Many files in the FSW group's mechanized documentation system contain lines of the form #DDF .... Hand-edited data files (e.g., YAML) use these lines to describe themselves. Scripts use these lines to describe both themselves and the file sets they generate (sometimes indirectly, as in the case of cmap and png files).

The bin/ddf_y2d script collects these lines (stripping off the identifying #DDF prefix) and dumps them into a_ddf/file_sets.yml. It then loads the file, along with e_etc/ddf.yml (a global specification file), as a set of Perl data structures. These structures are used to generate data flow diagrams and a_ddf/makevile, a subsidiary makefile.

The prefix aside, these lines are encoded in YAML format. Thus, white space is critical, tabs are disallowed, etc. The following discussion assumes an understanding of YAML, concentrating on the things that make these entries unusual.

path entries

These entries begin with a path tag, indicating the relative path of the file (set) from the base directory (e.g., $FSW/web). A typical entry might include several tags, including:

• desc and type - used in Legend tables, etc.

• include - if present, specify file sets that are included (e.g., by an shtml file).

• inp_c and out_c - if present, specify the input and output file sets to be used in both the graph generation and makefile use.

• inp_g and out_g - if present, specify file sets to be shown as inputs and outputs, respectively, for a script.

• inp_m and out_m - if present, specify file sets to be used in makefile generation.

  Most output files are handled by file_update(), which will not write the file unless something in it has changed or the file_update environment variable is set to force. Consequently, inp_m and out_m generally refer to a_etc/exit_<script> files, which are updated if the script exits normally.

• label - used to label the icons in diagrams.

• shape - may be used to select the icon shape (e.g., octagon).

Here is a typical path entry. Brace-containing strings expand into sets of variations (e.g., e_etc/con.yml, e_etc/def_int.yml, a_cir/*_*_*.shtml).

    #DDF    - path:     'bin/con_y2d'
    #DDF      desc:     'create diagrams for Constituent relationships'
    #DDF      label:    'con_y2d'
    #DDF      type:     'Perl script'
    #DDF      inp_g:    |
    #DDF        a_etc/{con,pkg_use,tag_sum,use_tree}.yml
    #DDF        e_etc/{def_{con,int},package}.yml
    #DDF      out_g:    |
    #DDF        a_cir/*_*_*.{dot,inc,shtml}
    #DDF        a_con/*_*.{dot,shtml}
    #DDF        a_pnp/Pack_*_con.inc
    #DDF      out_m:    'a_etc/exit_con_y2d'
    

patt entries

These entries, each of which will expand into one or more path entries, begin with patt tags. The expansion is controlled by the number of values in the exts (file extensions) tag. If an extension contains a colon, the remainder of the value is used to generate the URL for the icon's imagemap (e.g., a_cir/Con_CCSDS_rad750.cmap).

Any include tags in a patt entry are matched up with the corresponding ext tags. If an include tag begins with "*:", it is considered to match all exts. The shtml and yml extensions are not included in generated label tags.

    #DDF    - patt:     'a_cir/*_*_*'
    #DDF      desc:     'Package-specific Constituent relationships'
    #DDF      include:  'shtml:a_cir/*_*_*.{cmap,inc,png}'
    #DDF      exts:     '{cmap,dot,inc,png,shtml}:Con_CCSDS_rad750'
    

The expansion of the entry above would contain several path entries, including:

    #DDF    - path:     'a_cir/*_*_*.dot'
    #DDF      desc:     'Package-specific Constituent relationships'
    #DDF      label:    '*_*_*.dot'
    #DDF      url:      'a_cir/Con_CCSDS_rad750.dot'

    #DDF    - path:     'a_cir/*_*_*.shtml'
    #DDF      desc:     'Package-specific Constituent relationships'
    #DDF      label:    '*_*_*'
    #DDF      include:  'a_cir/*_*_*.{cmap,inc,png}'
    #DDF      url:      'a_cir/Con_CCSDS_rad750.shtml'