home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / GENMAN.ZIP / README < prev    next >
Text File  |  1993-03-13  |  7KB  |  207 lines
  1.         Genman Version 2.0
  2.  
  3. The purpose of the genman.awk program is to generate man page style
  4. documentation about a C++ class from its include file.
  5.  
  6. Features include:
  7.     a) Outputs either troff -man input data or plain human readable text.
  8.     b) The output is in a consistent format which is independent of
  9.        the format used in the include file.
  10.     c) Requires minimal modifications to include files.
  11.     d) Adding support for other types of output such as latex
  12.        or HP LaserJet II should be simple.
  13.     e) Public domain.
  14.  
  15. The distribution includes the following files:
  16.     README         This file.
  17.     genman.awk     The awk program that generates the document.
  18.     genman         A shell script to make it easier to use awk.
  19.     genman.tpl     A template to use to create include files.
  20.     strloc.h       An example include file.
  21.     strloc.cxx     An example source file.
  22.     strloc.man     The output of the command "genman strloc.h"
  23.     gmtime.c       A program that prints the modify time of a file.
  24.  
  25.  
  26. Example usage:
  27.     genman strloc.h > strloc.man
  28.         or
  29.     awk -f genman.awk strloc.h > strloc.man
  30.  
  31. Genman.awk scans the specified include file for various keywords and
  32. collects all of the information associated with them.  It then outputs
  33. the data in an order it thinks is reasonable.  Then if any source
  34. files where specified with the "// .FILE" keyword it scans them for
  35. descriptions of functions and outputs the descriptions.
  36.  
  37. Genman.awk scans for the following "genman" keywords in the specified
  38. include file.  Each of these keywords must start in the first column.
  39.     // .NAME
  40.     // .LIBRARY
  41.     // .HEADER
  42.     // .INCLUDE
  43.     // .FILE
  44.     // .SECTION
  45.  
  46. Genman.awk scans for the following "C++" keywords in the specified
  47. include file.  Each of these keywords must start in the first column.
  48.     #define
  49.     #include
  50.     const
  51.     typedef
  52.     enum
  53.     struct
  54.     class
  55.     extern
  56. Genman.awk discards all input not associated with one of the above
  57. keywords.
  58.  
  59. // .NAME
  60.     This keyword is used to specify the sentence that appears
  61.     in the NAME section of the man page.  The first word of the
  62.     sentence also appears in the upper corners of the man page.
  63.     Example:
  64.         // .NAME foo - a class to manage foo objects
  65.  
  66.     If this keyword does not appear in the include file then
  67.     one is made up from the include filename and some question marks.
  68.  
  69. // .LIBRARY
  70.     This keyword is used to specify the word that appears in the
  71.     upper corners of the man page between the parens.  In a real
  72.     man page this is the section indicator such as 3 or 3s.  I
  73.     use it as a library indicator.
  74.     Example:
  75.         // .LIBRARY base
  76.  
  77.     If this keyword does not appear in the include file then
  78.     the word "c++" is used.
  79.  
  80. // .HEADER
  81.     This keyword is used to specify the sentence that appears
  82.     on the top line of the man page, centered.  In a real man
  83.     page this is a description of the type of functions provided.
  84.     Example:
  85.         // .HEADER c++ library functions
  86.  
  87.     If this keyword does not appear in the include file then
  88.     the word "C++" is used.
  89.  
  90. // .INCLUDE
  91.     The first line of the SYNOPSIS section is always
  92.         #include <filename>
  93.     where filename is the name of the include file specified to
  94.     genman.  This can be overridden using the // .INCLUDE
  95.     keyword.
  96.     Example:
  97.         // .INCLUDE base/foo.h
  98.  
  99. // .FILE
  100.     This keyword is used to specify the names of the source
  101.     files for the class described in the include file.
  102.     After processing the include file specified to genman,
  103.     all files specified with the // .FILE keyword are scanned.
  104.     When it finds the line:
  105.         // Description:
  106.     in a source file it starts saving the lines that follow up to
  107.     the first line that contains an open curley brace.  Lines that
  108.     begin with // are considered part of the description of the
  109.     function.  Non-blank lines that do not begin with // are
  110.     considered to be part of the function definition.  Also
  111.     commented lines that end in a colon are discarded.
  112.     The function descriptions found are outputted in the SUMMARY
  113.     section.
  114.     Example:
  115.         // .FILE strloc.cxx
  116.         // .FILE strloc.h
  117.     If the include file contains inline functions then it should
  118.     also be specified as a source file.  Do not declare inline
  119.     functions with the class declaration.  Break them out and use
  120.     the inline keyword.
  121.  
  122. // .SECTION
  123.     Because genman.awk discards everything including text not
  124.     associated with one of the keywords, a keyword is needed
  125.     to output paragraphs of text.  Use the // .SECTION keyword
  126.     to do this.  All non-blank lines that begin with // in the
  127.     first column are part of the section.  A blank line terminates
  128.     the section.  In traditional man pages there is usually at
  129.     least a "DESCRIPTION" section and very often others like,
  130.     "CAVEATS", "BUGS", and "AUTHORS".
  131.     Example:
  132.         // .SECTION Description
  133.         // The foo class manages lists of widgets using neural
  134.         // networks.  Blah blah blah...
  135.  
  136. #define
  137.     All #define macros are placed under the section heading of
  138.     "DEFINED MACROS".
  139. #include
  140.     All #include files are placed under the section heading of
  141.     "INCLUDED FILES".
  142. const
  143.     All const variables are placed under the section heading of
  144.     "CONSTANTS".
  145. typedef
  146.     All type definitions are placed under the section heading of
  147.     "TYPE DEFINITIONS".
  148. enum
  149.     All enum definitions are placed under the section heading of
  150.     "ENUMERATIONS".
  151. struct
  152.     All structure declarations are placed under the section heading of
  153.     "STRUCTURES".
  154. class
  155.     All class declarations are placed under the section heading of
  156.     "SYNOPSIS".
  157. extern
  158.     All externs are placed under the section heading of
  159.     "SYNOPSIS" after any classes.
  160.  
  161. Genman.awk works with gawk 2.10beta on Unix and mks awkl.exe on MS-DOS.
  162.  
  163. Genman.awk uses "ls -l" by default to get the modify time of the file.
  164. The problem with ls(1) is that it prints out the time of day instead
  165. of the year for recently modified files.  The source code gmtime.c is
  166. included which when compiled takes a single argument which is a
  167. filename and prints to stdout the modify time of the file in the
  168. format, "mmm dd, yyyy".  Use the "-s" option of the genman shell
  169. script to use this program instead of ls(1) to get the modify time of
  170. the file.
  171.  
  172. Genman.awk generates human readable text output by default.  Use
  173. the "-t" option of the genman shell script to generate troff format.
  174.  
  175. The genman shell script also includes a "-o" switch to specify the
  176. output file.
  177.  
  178. KNOWN PROBLEMS
  179.  
  180.     If tabs are used to line up end of line comments in the
  181.     include file then the comments will probably not be perfectly
  182.     aligned in the output.  This is because the indentation is
  183.     changed in the output.  A workaround is to use spaces instead
  184.     of tabs.
  185.  
  186. FUTURE WORK
  187.  
  188.     Write an awk routine that converts a line with tabs in it to
  189.     spaces.  This can be used to fix the problem mentioned above.
  190.  
  191.     Move the device specific routines into separate files and use
  192.     multiple -f options to get the desired output.
  193.  
  194.     Write a device driver that generates latex input.
  195.  
  196.     Write a device drive that generates HP LaserJet II input.
  197.  
  198.     Need a set of include files that test all of the features.
  199.  
  200. I am interested in any bug fixes or enhancement requests that people
  201. might have for this program.
  202.  
  203. Bob Mastors
  204. Epoch Systems, Westboro MA (508) 836-4711 x317 (voice)
  205.                            (508) 836-4884 (fax)
  206. {uunet!epochsys, harvard!cfisun!palladium}!mastors
  207.