home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / C / CPG.ZIP / CPG.DOC < prev    next >
Encoding:
Text File  |  1987-04-10  |  6.8 KB  |  196 lines
  1.  
  2.      cpg(1)                                                     cpg(1)
  3.  
  4.  
  5.  
  6.      NAME
  7.           cpg - C source listing formatter
  8.  
  9.      SYNOPSIS
  10.           cpg [ -t tabstop ] [ file... ]
  11.  
  12.      DESCRIPTION
  13.           CPG is a C language source listing  formatter.   It  employs
  14.           certain  triggers  to  perform  its  formatting.  Those same
  15.           triggers may be used to  extract  in-line  documentation  to
  16.           create documentation.  At the end of the listing produced by
  17.           CPG is a table  of  contents  of  all  files  and  functions
  18.           contained  in the current listing.  The table of contents is
  19.           sorted alphabetically by function and file.
  20.  
  21.           The listing produced by CPG includes on  each  line  a  line
  22.           number.  On each line containing any braces ({}), there will
  23.           also be  a  nesting  level  indicator.   The  nesting  level
  24.           indicator  includes a number (the current nesting level) and
  25.           a directional character.  The directional characters are:
  26.  
  27.           >     The nesting level increased on this line
  28.  
  29.           <     The nesting level decreased on this line
  30.  
  31.           *     The nesting level changed both ways, with a net change
  32.                 of zero
  33.  
  34.           The triggers that CPG recognizes are itemized  below.   Each
  35.           must appear in column 1.
  36.  
  37.           <formfeed>
  38.                A formfeed will cause a new page to be started  with  a
  39.                full header.
  40.  
  41.           /*F filename *<anything>
  42.                The file name may be specified in a comment preceding a
  43.                descriptive  header  block.  The filename argument must
  44.                be delimited by asterisks in the trigger.  The filename
  45.                will  appear  in  all  page  headings  up  to  the next
  46.                filename trigger or the next file.  A filename  comment
  47.                block must be terminated by the endofblock trigger (see
  48.                below).  This trigger will  print  as  a  line  in  the
  49.                listing.   This  trigger causes the start of a new page
  50.                (form feed) in the listing, with printing of  the  page
  51.                header including the current file name.
  52.  
  53.           /*H funcname *<anything>
  54.                The  function  name  may  be  specified  in  a  comment
  55.                preceding  a  descriptive  header  block.  The funcname
  56.                argument must be delimited by asterisks in the trigger.
  57.                The funcname will appear in all page headings up to the
  58.  
  59.  
  60.  
  61.      Page 1                                          (printed 4/10/87)
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.      cpg(1)              UNIX 5.0 (Benetics Local)              cpg(1)
  69.  
  70.  
  71.  
  72.                next funcname trigger or the  next  file.   A  funcname
  73.                comment  block  must  be  terminated  by the endofblock
  74.                trigger (see below).  This trigger will print as a line
  75.                in the listing.  This trigger causes the start of a new
  76.                page (form feed) in the listing, with printing  of  the
  77.                page header including the current function name.
  78.  
  79.           /*E*/
  80.                This is the endofblock trigger.  Everything between the
  81.                last  filename  or  funcname trigger and the endofblock
  82.                trigger will be passed straight through by CPG  without
  83.                evaluation  of  nesting  levels,  comments,  or  quoted
  84.                strings.  Thus, a header block is treated as  one  long
  85.                comment  by  CPG.  This trigger will print as a line in
  86.                the listing.
  87.  
  88.           /*P*/
  89.                This is a page eject trigger.  It will not print in the
  90.                listing,   but  will  be  counted  for  line  numbering
  91.                purposes.  This trigger causes the page heading, title,
  92.                and  subtitle  to  be  reprinted based on their current
  93.                values (see title and subtitle below).
  94.  
  95.           /*S <text> */
  96.                This  is  the  subtitle  trigger.   It  determines  the
  97.                contents  of  the second title line on the page header.
  98.                All characters after the initial space and  up  to  but
  99.                not  including  the  following  asterisk (required) are
  100.                included as part of the subtitle.   This  trigger  will
  101.                not  print  in the listing but will be counted for line
  102.                numbering purposes.
  103.  
  104.           /*T <text> */
  105.                This is the title trigger.  It determines the  contents
  106.                of  the  first  title  line  on  the  page header.  All
  107.                characters after the initial space and up  to  but  not
  108.                including   the   following   asterisk  (required)  are
  109.                included as part of the title.  This trigger  will  not
  110.                print  in  the  listing  but  will  be counted for line
  111.                numbering purposes.
  112.  
  113.         Options
  114.           -t tabstop  The tabstop argument to the -t option  specifies
  115.                       how  to expand tabs.  The expansion is performed
  116.                       automatically with a tabstop of  8  if  none  is
  117.                       specified.
  118.  
  119.         Arguments
  120.           file        Any number of file names may be specified on the
  121.                       command  line  (within  limits  set by whichever
  122.                       shell is used).  Each file will be formatted and
  123.                       its  name added to the table of contents.  If no
  124.  
  125.  
  126.  
  127.      Page 2                                          (printed 4/10/87)
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.      cpg(1)              UNIX 5.0 (Benetics Local)              cpg(1)
  135.  
  136.  
  137.  
  138.                       file names are  specified,  CPG  will  read  the
  139.                       standard input.
  140.  
  141.      FILES
  142.           /tmp/toc_XXXXXX     temporary file for building the table of
  143.                               contents.
  144.  
  145.      SEE ALSO
  146.           dtab(1), nl(1), pr(1), sort(1)
  147.  
  148.      NOTES
  149.           This tool was developed at Benetics Corporation.
  150.  
  151.           A side note: CPG also properly processes comments  in  shell
  152.           scripts and makefiles.  These comments are correctly handled
  153.           when the comment character (# or :) is  the  first  nonblank
  154.           character  on  a line.  In order to facilitate documentation
  155.           of shell scripts, CPG recognizes the sequences #{ and #}  as
  156.           the  beginning  and ending of nesting, and treats them as it
  157.           does in C program sources.  Thus lengthy for, if, while, and
  158.           case statements may be more clearly documented as to nesting
  159.           levels, particulary in shell scripts.
  160.  
  161.      AUTHOR
  162.           Steven M. List
  163.           Benetics Corporation
  164.           Mountain View, CA.
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.      Page 3                                          (printed 4/10/87)
  193.  
  194.  
  195.  
  196.