Provided by: sdf_2.001+1-9_all bug

NAME

       sdfget - Documentation Extraction Utility

PURPOSE

       sdfget extracts documentation embedded in source code.

USAGE

        usage  : sdfget [-h[help]] [-o[out_ext]]
                [-l[log_ext]] [-O[out_dir]]
                [-f formatting_filename] [-g[get_rule]]
                [-r[rpt_file]] [-s scope] [-i]
                [-v[verbose]] file ...
       purpose: extract documentation embedded in source code
       version: 2.000    (SDF 2.001)

       The options are:

        Option       Description
        -h           display help on options
        -o           output file extension
        -l           log file extension
        -O           output to input file's (or explicit) directory
        -f           filename to use when formatting the output
        -g           rule to use to get documentation
        -r           report file
        -s           scope of documentation to be extracted
        -i           only output lines not extracted
        -v           verbose mode

DESCRIPTION

       The -h option provides help. If it is specified without a parameter, a brief description
       of each option is displayed. To display the attributes for an option, specify the option
       letter as a parameter.

       By default, generated output goes to standard output. To direct output to a file per input
       file, use the -o option to specify an extension for output files. If the -o option is
       specified without a parameter, an extension of out is assumed.

       Likewise, error messages go to standard error by default. Use the -l option to create a
       log file per input file. If the -l option is specified without a parameter, an extension
       of log is assumed.

       By default, generated output and log files are created in the current directory. Use the
       -O option to specify an explicit output directory.  If the -O option is specified without
       a parameter, the input file's directory is used.

       The -f option can be used to specify a filename to use when formatting the output. This is
       useful when the text is coming from the standard input stream.

       The get-rule nominates the formatting of the embedded documentation to be extracted. All
       currently defined get-rules assume the documentation is in comment blocks in one of the
       following formats:

        >>section_title1::
        text of section 1, line 1
        text of section 1, line ..

        >>section_title2::
        text of section 2, line 1
        text of section 2, line ..
        >>END::

        >>section_title3:: text of section 3

       The first form is most commonly used. In this format, the text in a section extends until
       the end of the current "comment block" or the start of the next section, whichever comes
       first. The second form (i.e. explicitly specifying where the section ends) is useful if
       you wish to add some normal comments (i.e. non-documentation) which you do not want
       extracted. If the text is short, the third form can be used.  Regardless of the format, if
       a section is found which is already defined, the text of the section is concatenated onto
       the existing text. This permits the documentation for each entity to be specified
       immediately above where it is defined in the source code.

       The -g option specifies the get-rule to use. The available get-rules differ on the prefix
       expected at the front of each line as shown below.

        Rule                              Prefix
        perl                              #
        cpp                               //
        c                                 * or /*
        fortran                           c (with 5 preceding spaces)
        eiffel                            --
        bat                               rem

       Within C code, a trailing space is required after the characters above. For other
       languages, a trailing space is optional. Within FORTRAN code, the "c" character must be
       preceded by exactly 5 spaces.  For other languages, zero or more whitespace characters are
       permitted before the characters above.

       For example, embedded documentation within C code looks like:

        /* >>Purpose::
         * This library provides a high level interface
         * to commonly used network services.
         */

       If the -g option is not specified, perl is the default get-rule. If the -g option is
       specified without a parameter, the extension in lowercase of the filename (or the
       formatting filename if the text is coming from standard input) is used to guess the
       get_rule as shown below.

        Rule                              Extensions
        cpp                               cpp, c++, cc, hpp, hpp, h, java, idl
        c                                 c
        fortran                           fortran, for, f77, f
        eiffel                            eiffel, ada
        bat                               bat, cmd

       A report filename can be specified using the -r option. If the name doesn't include an
       extension, sdg is assumed. Reports provide a mechanism for:

       •   selectively extracting sections, and

       •   rudimentary reformatting (e.g. to SDF)

       If no report is specified, all sections are output in the following format:

        section_title1
        section_text1

        section_title2
        section_text2

       If -r is specified on its own, default.sdg is assumed. This report selects the set of
       sections (within the SDF documentation standards) which form the user documentation and
       formats them into SDF. Details on the report format are specified below. Reports are
       searched for in the current directory, then in the stdlib directory within SDF's library
       directory.

       The -s option can be used to specify the scope of the documentation to be extracted. (This
       is an experimental feature and may change so most users should avoid using it.)

       The -i option outputs only those lines which the get-rule did not match. This option is
       useful for extracting non-documentation from a file to give just the code.

       Note: The -r option is ignored if -i is specified.

       The -v option enables verbose mode. This is useful for seeing which rule is being used for
       each file.

EXAMPLES

       To extract the user documentation from a SDF application written in C++ (xyz, say) and
       save it into xyz.sdf:

             sdfget -gcpp -r -osdf xyz.cpp

LIMITATIONS AND FUTURE DIRECTIONS

       It would be nicer if the get-rule was always guessed from the filename extension but
       changing the default from perl could break existing scripts. Therefore, get-rule guessing
       must be explicitly enabled by specifging the -g option without a parameter.