"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/misc/auto-man-page/README.auto-man-page-handling" (29 Jul 2021, 6091 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Rules:
    2 =====
    3 
    4 + Provide a version-controlled list of all bin programs to be
    5   processed for the "auto-man" documentation feature:
    6 
    7     auto-man-progs.txt
    8 
    9 + In the auto-man list each bin program name will be listed followed
   10   on the same line by the source file which provides it, e.g.,
   11 
   12     burst    ./src/burst/burst.c
   13 
   14 + Each bin source file must have one instance each of the following
   15   string variables:
   16 
   17   const char usage[]     = "...."; /* mandatory: used for the SYNOPSIS
   18                                       section of the man page */
   19   const char optstring[] = "";     /* mandatory for use with bu_getopt
   20                                       (if it is used) */
   21 
   22   Note the strings must either (1) be fully contained on one line or
   23   (2) adhere to the following format:
   24 
   25     const char usage[] =
   26        "Usage: %s ... first line...\n"
   27        " ... second line...\n"
   28        "... more lines if needed\n";
   29 
   30   The ending semicolon may follow on a line by itself.
   31 
   32   There must be no embedded newlines nor may the end-of-line escape be
   33   used.  An ending newline is required for each line.
   34 
   35   There must be nothing preceding the variable on its
   36   beginning line (except a 'static' qualifier is allowed).
   37 
   38   The program name may be manually entered or one string format
   39   specification ('%s') entered for print statement use in the program.
   40 
   41   Valid examples:
   42   --------------
   43 
   44     static const char usage[] = "Usage: %s input.g\n";
   45 
   46     const char usage[] =
   47       "Usage: fbserv port_num\n"
   48       "  (for a stand-alone daemon)\n"
   49       ;
   50 
   51   Invalid example:
   52   ---------------
   53 
   54     const char usage[] = "\
   55 Usage: %s port_num\n\
   56 	  (for a stand-alone daemon)\n\
   57 ";
   58 
   59 + Other man page inputs come from one or more specially-formatted
   60   ordinary C-style comment blocks (Doxygen-style comments beginning
   61   with '/**' or '/*!' are completely ignored).
   62 
   63   Each such block is divided into one or more parts beginning with a
   64   unique keyword ending with a colon ('partname:'; but see 'opt:' later)
   65   which identifies a section to appear in the man page.
   66 
   67   The block must begin with the following format or it will be ignored:
   68 
   69   - Immediately following the opening '/*' must be one or more white
   70     space characters (newlines allowed) followed by one keyword
   71     followed by on or more white-space characters followed by its
   72     description (its 'value').  Note the description must exist (i.e.,
   73     its value must be at least one printable character).
   74 
   75   - A blank line inside a part description results in a new paragraph.
   76 
   77   - The part name must be lower-case alpha characters, and it may have
   78     underscores.  The part name will be translated into upper case and
   79     underscores into spaces in the man page.
   80 
   81   - Following the mandatory first part may be more unique parts.
   82 
   83   - A description ends when the next part keyword is found or the the
   84     comment block ends.
   85 
   86   - Embedded asterisks surrounded by white space are ignored (to allow
   87     for the decorated comment style).
   88 
   89   - All the part descriptions may use valid DocBook code.
   90 
   91   Some part names are mandatory and some parts have default values.
   92   All part names must be unique except the 'opt:' part which may
   93   appear as many times as there are options.  Note option names follow
   94   the 'opt:' keyword and they must be unique.  Furthermore, the list
   95   of options in the comment blocks must exactly match the option in
   96   the optstring if it appears in the file.
   97 
   98   Each option (keyword 'opt:') must be described in one of three
   99   possible formats:
  100 
  101      opt: -c [N] description of this option and its optional arg N
  102      opt: -a <Z> description of this option and its mandatory arg Z
  103      opt: -d  description of this option which has no args
  104 
  105   'opt:' note: there must be no spaces inside the brackets ([] and
  106   <>).  If spaces are needed, use underscores which will then be
  107   translated to spaces in the man page.
  108 
  109   Following is an example of such a comment block (partially
  110   decorated):
  111 
  112   /*
  113    * section1:  description
  114    *
  115    *  more description but this follows a blank line so it begins a
  116       new para
  117 
  118    another_section: description ...
  119 
  120    ...
  121 
  122    opt: optiona description
  123 
  124    another para for optiona
  125 
  126    opt: optiond ...
  127 
  128   */
  129 
  130 + Mandatory parts:
  131 
  132     purpose: ...brief description for NAME section...
  133 
  134     description: some words, should give user a good idea of how and why
  135          to use the program
  136 
  137       ...this will appear in the DESCRIPTION section
  138 
  139     opt: option
  140 
  141       ... one for each option (if any), all will be put in an OPTIONS
  142           section
  143 
  144 + Default parts (user may override by explicitly providing them):
  145 
  146     copyright: YYYY
  147 
  148       where YYYY is the beginning copyright year (default is 1984).
  149 
  150     diagnostics:
  151 
  152       default: Error messages are intended to be self-explanatory.
  153 
  154     authors:
  155 
  156       default:  BRL-CAD Team
  157 
  158     bug_reports:
  159 
  160       default:  Reports of bugs or problems should be submitted via
  161                 electronic mail to <devs@brlcad.org>.
  162 
  163 + Optional but desirable parts:
  164 
  165     see_also:
  166 
  167       ...list of man pages only (with sections),
  168       semicolon- or white-space-separated, no other embellishments...
  169 
  170     other_refs:
  171 
  172       ...list of other references, if any,
  173       semicolon-separated, no other embellishments...
  174 
  175     ...both lists will go in the SEE ALSO section...
  176 
  177 Processing:
  178 ==========
  179 
  180 A C++ program (version controlled) will be used to parse the source
  181 files (defined in the file 'auto-man-progs.txt') and, after successful
  182 parsing, a complete docbook file in man format will be written to file
  183 "progname.xml" in directory:
  184 
  185   ./doc/docbook/system/man1/en/
  186 
  187 Assumptions:
  188 ===========
  189 
  190 + C++-style comments are ignored unless they are inside a C-style
  191   comment in which case they are treated as ordinary text.
  192 
  193 + No more than one C-style comment or partial comment is on a line.
  194 
  195 + Mandatory string variables ('usage' and 'optstring') begin and
  196   end on a line with no other C/C++ objects.
  197 
  198 Working example:
  199 ===============
  200 
  201 See file "${BRLCAD_SOURCE_ROOT}/src/util/fix_polysolids.c" for an
  202 example of some of the features described above.