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