home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 19 Printer / 19-Printer.zip / CPOST.ZIP / cpost.doc < prev    next >
Text File  |  1993-03-05  |  18KB  |  441 lines
  1.  
  2.  
  3.             cPost - C language file formatter for PostScript
  4.  
  5.                            by Patrick Mueller
  6.  
  7.  
  8.    (c) Copyright International Business Machines Corporation 1993.
  9.    All rights Reserved.
  10.  
  11. ----------------------------------------------------
  12. What is cPost?
  13. ----------------------------------------------------
  14.  
  15. cPost is a program which will take a number of c and h files as input
  16. and create a PostScript file.  The PostScript file will contain the
  17. contents of the input files that have been marked up so that various
  18. parts are highlighted.
  19.  
  20. ----------------------------------------------------
  21. cPost invocation and options
  22. ----------------------------------------------------
  23.  
  24. When cPost is invoked, it examines the command line for file names and
  25. options.  The file names may contain wildcards.  Running cPost with no
  26. file names or with a ? as the first parameter will write some brief help
  27. to standard error.
  28.  
  29. Options are blank delimited 'words' which begin with a '-'.  The case of
  30. the character following the - is not significant.  Options may be placed
  31. before, after or in between file names.  If the same option is specified
  32. more than once on the command line, only the last option is used.
  33. Options may also be specified in the CPOST environment variable.
  34. Command line options override environment variable options.
  35.  
  36. A typical invocation of cPost might be
  37.  
  38.    cpost *.c *.h > project.ps
  39.  
  40. This invocation will include all c and h files, use any options
  41. set in the CPOST environment variable, and write the output to the
  42. file 'project.ps'.
  43.  
  44. Note that the options used in the environment variable are used as-is,
  45. which means that quote processing which is normally done on the OS/2
  46. commandline parameters is not done on environment variable values.
  47. Thus, it is not possible to use an option which has a value which
  48. includes spaces.
  49.  
  50. You may also use a list file to determine the files to process.
  51. The list file is just a plain text file that contains the names of
  52. other files in it.  Prepend the list file name with a '@' when you
  53. use it on the command line.  The list file can contains any number
  54. of file names.  They can be entered on one line apiece, or multiple
  55. names can be on one line as long as they are separated with white
  56. space.  Blank lines, and lines that begin with a '#' character
  57. are ignored.  If a '@-' is given on the command line, file names
  58. to process will be read from stdin.
  59.  
  60. Valid options are:
  61.  
  62.     -b[+|-]
  63.     enable/disable bracketing level
  64.  
  65.        Use -b+ to have all levels of braces within file bracketed.  Use
  66.        -b- to cause no bracketing.
  67.  
  68.     -cext1,ext2,...
  69.     treat files with extension ext1 and ext2 as C files
  70.  
  71.        For example, -cc,y,sqc will cause files with 'extensions' c, y,
  72.        and sqc (case insensitive) to be considered c files.  This
  73.        information is used to determine sorting order.  Note that the
  74.        'extension' is considered the text after the first '.' in the
  75.        name, up to the last character, or next '.' in the name.
  76.  
  77.     -d[+|-]
  78.     enable/disable duplex
  79.  
  80.        Duplex processing causes two things to happen:  the header1 proc
  81.        is used for odd number pages, and the header2 proc is used for
  82.        even number pages; and a blank page will be printed for files
  83.        that end on an odd numbered page.  If duplexing is not on, the
  84.        header1 proc is used for both even and odd pages, and extra blank
  85.        pages will not be printed.  The header1 and header2 procs may be
  86.        customized with the -i option.
  87.  
  88.     -hext1,ext2,...
  89.     treat files with extension ext1 and ext2 as H files
  90.  
  91.        For example, -hh,rh,sqh will cause files with 'extensions' h, rh,
  92.        and sqh (case insensitive) to be considered h files.  This
  93.        information is used to determine whether function definition and
  94.        usage are valid within the file, and to determine sorting order.
  95.        Note that the 'extension' is considered the text after the
  96.        first '.' in the name, up to the last character, or next '.' in
  97.        the name.
  98.  
  99.     -ifile1;file2;...
  100.     imbed PostScript files into the output file
  101.  
  102.        This option is used to redefine fonts, margins and headers for
  103.        your document.  Multiple files can be imbedded - they will be
  104.        imbedded in the order specified.  See Customization below.
  105.  
  106.     -kkey1,key2,...
  107.     treat key1, key2, etc as reserved words
  108.  
  109.        In addition to the ANSI reserved words, the following are
  110.        considered reserved (SAA extensions):  _Packed, _System,
  111.        _Optlink, _Far16, _Cdecl, _Pascal.  If one of the keys specified
  112.        is 'c++', the following tokens will be considered reserved words:
  113.        catch, class, delete, friend, inline, new, operator, private,
  114.        protected, public, template, this, throw, try, virtual.  To make
  115.        additional words reserved, use the -k option.  For instance,
  116.        -kNULL,FILE adds NULL and FILE as reserved words.  This option is
  117.        used merely to control the highlighting of the tokens.
  118.  
  119.        You may also use a file that contains the keywords.  To do this,
  120.        prepend a '@' to the filename, and use that as a key on the -k
  121.        option.  The contents of the file should be in the same format
  122.        as list files, described above, except keywords are enclosed in
  123.        the file, and not filenames.
  124.  
  125.     -n#
  126.     separate line numbers from lines with # spaces.
  127.  
  128.        When 0 is specified, no line numbers are generated.
  129.  
  130.     -ofileName
  131.     output written to the file named fileName.
  132.  
  133.        Without this option, output is written to stdout.
  134.  
  135.     -p[+|-]
  136.     enable/disable best-fit page break at functions
  137.  
  138.        When this option is enabled, functions that can fit on a page by
  139.        themselves will be printed on a single page.  Basically this means
  140.        that page ejects occur between functions.  But if multiple
  141.        functions do fit on a page, they will be printed on a page
  142.        together.
  143.  
  144.     -rfile1;file2;...
  145.     replace default PostScript procedures with those in another file
  146.  
  147.        This option is used to replace the PostScript procedures
  148.        generated by cPost with your own.  This is for power-users
  149.        who think they can produce nicer looking output than I can!
  150.        See customization below.
  151.  
  152.     -snt or -stn
  153.     sort files by name/type or type/name
  154.  
  155.        When sorting by type, the files are first sorted by whether they
  156.        are c, h, or neither (see -c and -h options), and then by the
  157.        actual extension.  All sorting is done in a case insensitive
  158.        manner.
  159.  
  160.     -t#
  161.     expand tabs to # columns
  162.  
  163.        The default is 4, which causes the characters immediately
  164.        following tab characters to be placed in columns 5, 9, 13, ...
  165.  
  166.     -xx,y
  167.     coordinates to with translate for page
  168.  
  169.        This option is provided to help bridge the difference between
  170.        PostScript printers.  Because the printable area on printers is
  171.        different, you might create a set of margin and header
  172.        definitions that print fine on one printer, but are clipped on
  173.        another printer.  This option inserts a translate operation into
  174.        the PostScript file before a page is written to, to offset the
  175.        printing by a certain amount.  For example, -x0,18 would be used
  176.        to move the printout on the page up 1/4 inch.  The units must be
  177.        given in points (72 points/inch).
  178.  
  179.     -ypath
  180.     path to use for temporary files
  181.  
  182.        A copy of each input file read is created during the cPost run.
  183.        By default, these copies are created in your current directory.
  184.        This option allows you to specify a different location for the
  185.        temporary files.
  186.  
  187.     -?
  188.     display online help
  189.  
  190.  
  191. The default options are
  192.  
  193.     -b+ -d- -cc -hh -n2 -p+ -stn -t4 -x0,0
  194.  
  195. ----------------------------------------------------
  196. Customizing cPost output
  197. ----------------------------------------------------
  198.  
  199. Customization of the cPost output is done by including additional
  200. PostScript code in the output file, and optionally not adding some of
  201. the PostScript code normally written by cPost.  The code you add must be
  202. valid PostScript code - it is not checked or processed by cPost at all.
  203. The output of cPost can be used as a starting point for creating new
  204. code.  For an introduction to PostScript, see the "blue book" -
  205. PostScript Language Tutorial and CookBook, ISBN 0-201-10179-3.  That's
  206. all I used as a reference when writing cPost.
  207.  
  208. Three options allow the use of alternate PostScript code:
  209.  
  210.    -i option
  211.    -----------------
  212.  
  213.       The -i option allows files containing PostScript code to be
  214.       imbedded into the output file, after the default fonts, page size,
  215.       margins, and header procedures have been set.  The code included
  216.       can reset any of these values.  The values that may be reset are:
  217.  
  218.          /nFontName  - font name for normal text
  219.          /kFontName  - font name for keywords
  220.          /iFontName  - font name for identifiers
  221.          /fFontName  - font name for functions
  222.          /dFontName  - font name for functions in function definitions
  223.          /cFontName  - font name for comments
  224.          /pFontName  - font name for preprocessor directives
  225.          /lFontName  - font name for line numbers
  226.  
  227.          /nFontSize  - font size for normal text
  228.          /kFontSize  - font size for keywords
  229.          /iFontSize  - font size for identifiers
  230.          /fFontSize  - font size for functions
  231.          /dFontSize  - font size for functions in function definitions
  232.          /cFontSize  - font size for comments
  233.          /pFontSize  - font size for preprocessor directives
  234.          /lFontSize  - font size for line numbers
  235.  
  236.          /pLength    - page length
  237.          /pWidth     - page width
  238.  
  239.          /lMargin    - margin: left
  240.          /rMargin    - margin: right
  241.          /tMargin    - margin: top
  242.          /bMargin    - margin: bottom
  243.  
  244.          /header1    - procedure for header/footer on odd and even pages
  245.                        (no duplex) or odd pages (duplex)
  246.          /header2    - procedure for header/footer on even pages (duplex)
  247.  
  248.       For instance, to change the font used for functions to Helvetica,
  249.       create a file with the following line:
  250.  
  251.          /fFontName /Helvetica            def % font name for functions
  252.  
  253.       The /headerX procedures are used for the header and footer of a page.
  254.       header1 is called for all pages when not printing duplex, and called
  255.       for odd pages when printing duplex.  header2 is not called at all
  256.       when not printing duplex, and called for even pages when printing
  257.       duplex.  The following variables are available to the header
  258.       procedures:
  259.  
  260.          - margin sizes (lMargin, rMargin, tMargin, bMargin)
  261.          - page sizes   (pLength, pWidth)
  262.          - size of line number information (lineNoWidth)
  263.          - name of the current file (fileName)
  264.          - page number (pageNum)
  265.          - date/time of file (fileDateTime)
  266.          - date cPost run (printDate)
  267.          - last C function defined, up to bottom of the current page
  268.  
  269.       The page and margin sizes need to be expressed in real world
  270.       coordinates.  This can either be points (the native unit within
  271.       PostScript) or in inches, centimeters, or millimeters, using the
  272.       Inch, Cm, and Mm procedures defined at the beginning of the
  273.       output file.  See the default cPost output for use of the Inch
  274.       procedure.
  275.  
  276.       An example alternate set of header definitions is provided in the
  277.       file sample.ips.  This file prints the header like the default
  278.       header provided by cPost, except that it provides one line of text
  279.       across the top of the page, for company logos, security banners, etc.
  280.       Directions on how to customize it are provided as PostScript comments
  281.       within the file.
  282.  
  283.       See the output of cPost for the default settings of the the values
  284.       described above.
  285.  
  286.  
  287.    -r option
  288.    -----------------
  289.  
  290.       The -r option is used to replace the PostScript procedures
  291.       normally written to the output file with your own.  If more
  292.       customization than the header and footer areas is needed, this
  293.       is the way to do it.  None of the procedures written by cPost
  294.       are written to the output file.  Instead, the contents of
  295.       the files specified are written.  You will need to study the
  296.       existing PostScript procedures so that you can understand the
  297.       format of the formatted C code.  The format is fairly
  298.       straight-forward.  Note that any files specified with -i
  299.       option are written before (immediately before) those specified
  300.       with the -r option.
  301.  
  302.  
  303.    -w option
  304.    -----------------
  305.       The -w option is used to 'wrap' PostScript code around the cPost
  306.       output.  This would be useful if you had some PostScript code
  307.       you could wrap around an existing file to change the output in
  308.       some way. such as producing 2-up output.
  309.  
  310.  
  311. Note that cPost ALWAYS writes a %! header line FIRST to the output
  312. file, as well as commentary on the invocation, and some of the
  313. runtime option settings.
  314.  
  315. ----------------------------------------------------
  316. cPost processing
  317. ----------------------------------------------------
  318.  
  319. cPost is a two-pass translator.  It reads each file two times
  320. while generating the output file.  The first pass expands tabs
  321. and inserts bracketing characters in the input file.  A copy of
  322. the input file with these changes is written to a temporary file.
  323. The second pass writes the PostScript version of each of the input
  324. files to the output file.
  325.  
  326. ----------------------------------------------------
  327. anomolies
  328. ----------------------------------------------------
  329.  
  330. cPost is designed to be a fairly robust c tokenizer.  It understands
  331. valid C constructs, including c++ // comments.  cPost also attempts
  332. to recognize C function usage and definitions within C files.  It
  333. handles 'normal' function usage and definition well, but will not
  334. recognize functions defined or used in unusual ways.  For instance,
  335. the function usage
  336.  
  337.    (malloc)(10);
  338.  
  339. will not be recognized by cPost.
  340.  
  341. The definition of 'normal' function usage and definition for cPost
  342. is:
  343.  
  344. - function names can be followed by any amount of whitespace, comments,
  345.   and preprocessor statements, followed immediately by a left
  346.   parenthesis.
  347.  
  348. - functions are only defined and used in c files, not h files (see
  349.   the -c and -h options for more information).
  350.  
  351. - function definition vs. function usage is primarily determined by the
  352.   nested brace level.  If there are nested braces when the function
  353.   name is found, the function is a function usage; otherwise, it is a
  354.   function definition (a check is done to see if it's a function
  355.   prototype as well).
  356.  
  357. Macros that take arguments will be printed as if they were function
  358. invocations.
  359.  
  360. It is possible for cPost to misinterpret things as functions, such as
  361. complex variable and typedef definitions, and mangling of the C language
  362. such as:
  363.  
  364.    #define LT <
  365.    if ( 2 LT (x + 2))
  366.  
  367. In this case, cPost will misinterpret LT as a function.  Just as well,
  368. since you should not be committing these attrocities in the first place.
  369.  
  370. cPost treats preprocessor statements as whitespace, so if brace
  371. levels get out of synch because of preprocessor statements, cPost
  372. will not generate correct bracketing characters, and will misinterpret
  373. function definitions and function usages.  For example, the following
  374. code chunk will not format properly with cPost:
  375.  
  376.       {
  377.       i = 1;
  378.    #if defined(SOMETHING)
  379.       j = 2;
  380.       }
  381.    #else
  382.       j = 3;
  383.       }
  384.    #endif
  385.  
  386. The following form should be used instead:
  387.  
  388.       {
  389.       i = 1;
  390.    #if defined(SOMETHING)
  391.       j = 2;
  392.    #else
  393.       j = 3;
  394.    #endif
  395.       }
  396.  
  397. cPost also currently does not handle preprocessor statements absolutely
  398. correctly.  It treats anything on a line after a preprocessor token as
  399. part of the preprocessor line.  The following line will be printed in
  400. the preprocessor font
  401.  
  402.    #define X 5   /* define X to be 5 */
  403.  
  404. It should really print the comment part in the comment font.
  405.  
  406. ----------------------------------------------------
  407. history
  408. ----------------------------------------------------
  409.  
  410. version  1.2 - Feb 17 1993
  411.    - fix to make 'i' and 'd' fonts work (for good this time!)
  412.    - change Courier-Italic to Courier-Oblique
  413.  
  414. version  1.1 - Feb 15 1993
  415.    - fix tab handling problem (thanks to Art Roberts for this)
  416.    - fix to make 'i' and 'd' fonts work
  417.    - don't echo command line parameters into output file anymore
  418.    - allow '@' file specs for -k and file names.
  419.  
  420. version  1.0 - Feb  2 1993
  421.    - a few bug fixes, a few added diagnostics
  422.    - function definitions (can) now use different font than other
  423.      function tokens (usage and prototype).
  424.    - font for identifiers separated from 'n'ormal text
  425.    - added the -r option and -w option
  426.  
  427. version  0.3 - Jan 18 1993
  428.  
  429.    - configuration via imbed files with -i options
  430.    - all options added (most from cBook)
  431.    - added linefeed at end of file to prevent last line from not being
  432.      processed
  433.  
  434. version  0.2
  435.  
  436.    - lots of little fixes
  437.  
  438. version  0.1
  439.  
  440.    - initial version
  441.