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