cPost - C language file formatter for PostScript by Patrick Mueller (c) Copyright International Business Machines Corporation 1993. All rights Reserved. ---------------------------------------------------- What is cPost? ---------------------------------------------------- cPost is a program which will take a number of c and h files as input and create a PostScript file. The PostScript file will contain the contents of the input files that have been marked up so that various parts are highlighted. ---------------------------------------------------- cPost invocation and options ---------------------------------------------------- When cPost is invoked, it examines the command line for file names and options. The file names may contain wildcards. Running cPost with no file names or with a ? as the first parameter will write some brief help to standard error. Options are blank delimited 'words' which begin with a '-'. The case of the character following the - is not significant. Options may be placed before, after or in between file names. If the same option is specified more than once on the command line, only the last option is used. Options may also be specified in the CPOST environment variable. Command line options override environment variable options. A typical invocation of cPost might be cpost *.c *.h > project.ps This invocation will include all c and h files, use any options set in the CPOST environment variable, and write the output to the file 'project.ps'. Note that the options used in the environment variable are used as-is, which means that quote processing which is normally done on the OS/2 commandline parameters is not done on environment variable values. Thus, it is not possible to use an option which has a value which includes spaces. You may also use a list file to determine the files to process. The list file is just a plain text file that contains the names of other files in it. Prepend the list file name with a '@' when you use it on the command line. The list file can contains any number of file names. They can be entered on one line apiece, or multiple names can be on one line as long as they are separated with white space. Blank lines, and lines that begin with a '#' character are ignored. If a '@-' is given on the command line, file names to process will be read from stdin. Valid options are: -b[+|-] enable/disable bracketing level Use -b+ to have all levels of braces within file bracketed. Use -b- to cause no bracketing. -cext1,ext2,... treat files with extension ext1 and ext2 as C files For example, -cc,y,sqc will cause files with 'extensions' c, y, and sqc (case insensitive) to be considered c files. This information is used to determine sorting order. Note that the 'extension' is considered the text after the first '.' in the name, up to the last character, or next '.' in the name. -d[+|-] enable/disable duplex Duplex processing causes two things to happen: the header1 proc is used for odd number pages, and the header2 proc is used for even number pages; and a blank page will be printed for files that end on an odd numbered page. If duplexing is not on, the header1 proc is used for both even and odd pages, and extra blank pages will not be printed. The header1 and header2 procs may be customized with the -i option. -hext1,ext2,... treat files with extension ext1 and ext2 as H files For example, -hh,rh,sqh will cause files with 'extensions' h, rh, and sqh (case insensitive) to be considered h files. This information is used to determine whether function definition and usage are valid within the file, and to determine sorting order. Note that the 'extension' is considered the text after the first '.' in the name, up to the last character, or next '.' in the name. -ifile1;file2;... imbed PostScript files into the output file This option is used to redefine fonts, margins and headers for your document. Multiple files can be imbedded - they will be imbedded in the order specified. See Customization below. -kkey1,key2,... treat key1, key2, etc as reserved words In addition to the ANSI reserved words, the following are considered reserved (SAA extensions): _Packed, _System, _Optlink, _Far16, _Cdecl, _Pascal. If one of the keys specified is 'c++', the following tokens will be considered reserved words: catch, class, delete, friend, inline, new, operator, private, protected, public, template, this, throw, try, virtual. To make additional words reserved, use the -k option. For instance, -kNULL,FILE adds NULL and FILE as reserved words. This option is used merely to control the highlighting of the tokens. You may also use a file that contains the keywords. To do this, prepend a '@' to the filename, and use that as a key on the -k option. The contents of the file should be in the same format as list files, described above, except keywords are enclosed in the file, and not filenames. -n# separate line numbers from lines with # spaces. When 0 is specified, no line numbers are generated. -ofileName output written to the file named fileName. Without this option, output is written to stdout. -p[+|-] enable/disable best-fit page break at functions When this option is enabled, functions that can fit on a page by themselves will be printed on a single page. Basically this means that page ejects occur between functions. But if multiple functions do fit on a page, they will be printed on a page together. -rfile1;file2;... replace default PostScript procedures with those in another file This option is used to replace the PostScript procedures generated by cPost with your own. This is for power-users who think they can produce nicer looking output than I can! See customization below. -snt or -stn sort files by name/type or type/name When sorting by type, the files are first sorted by whether they are c, h, or neither (see -c and -h options), and then by the actual extension. All sorting is done in a case insensitive manner. -t# expand tabs to # columns The default is 4, which causes the characters immediately following tab characters to be placed in columns 5, 9, 13, ... -xx,y coordinates to with translate for page This option is provided to help bridge the difference between PostScript printers. Because the printable area on printers is different, you might create a set of margin and header definitions that print fine on one printer, but are clipped on another printer. This option inserts a translate operation into the PostScript file before a page is written to, to offset the printing by a certain amount. For example, -x0,18 would be used to move the printout on the page up 1/4 inch. The units must be given in points (72 points/inch). -ypath path to use for temporary files A copy of each input file read is created during the cPost run. By default, these copies are created in your current directory. This option allows you to specify a different location for the temporary files. -? display online help The default options are -b+ -d- -cc -hh -n2 -p+ -stn -t4 -x0,0 ---------------------------------------------------- Customizing cPost output ---------------------------------------------------- Customization of the cPost output is done by including additional PostScript code in the output file, and optionally not adding some of the PostScript code normally written by cPost. The code you add must be valid PostScript code - it is not checked or processed by cPost at all. The output of cPost can be used as a starting point for creating new code. For an introduction to PostScript, see the "blue book" - PostScript Language Tutorial and CookBook, ISBN 0-201-10179-3. That's all I used as a reference when writing cPost. Three options allow the use of alternate PostScript code: -i option ----------------- The -i option allows files containing PostScript code to be imbedded into the output file, after the default fonts, page size, margins, and header procedures have been set. The code included can reset any of these values. The values that may be reset are: /nFontName - font name for normal text /kFontName - font name for keywords /iFontName - font name for identifiers /fFontName - font name for functions /dFontName - font name for functions in function definitions /cFontName - font name for comments /pFontName - font name for preprocessor directives /lFontName - font name for line numbers /nFontSize - font size for normal text /kFontSize - font size for keywords /iFontSize - font size for identifiers /fFontSize - font size for functions /dFontSize - font size for functions in function definitions /cFontSize - font size for comments /pFontSize - font size for preprocessor directives /lFontSize - font size for line numbers /pLength - page length /pWidth - page width /lMargin - margin: left /rMargin - margin: right /tMargin - margin: top /bMargin - margin: bottom /header1 - procedure for header/footer on odd and even pages (no duplex) or odd pages (duplex) /header2 - procedure for header/footer on even pages (duplex) For instance, to change the font used for functions to Helvetica, create a file with the following line: /fFontName /Helvetica def % font name for functions The /headerX procedures are used for the header and footer of a page. header1 is called for all pages when not printing duplex, and called for odd pages when printing duplex. header2 is not called at all when not printing duplex, and called for even pages when printing duplex. The following variables are available to the header procedures: - margin sizes (lMargin, rMargin, tMargin, bMargin) - page sizes (pLength, pWidth) - size of line number information (lineNoWidth) - name of the current file (fileName) - page number (pageNum) - date/time of file (fileDateTime) - date cPost run (printDate) - last C function defined, up to bottom of the current page The page and margin sizes need to be expressed in real world coordinates. This can either be points (the native unit within PostScript) or in inches, centimeters, or millimeters, using the Inch, Cm, and Mm procedures defined at the beginning of the output file. See the default cPost output for use of the Inch procedure. An example alternate set of header definitions is provided in the file sample.ips. This file prints the header like the default header provided by cPost, except that it provides one line of text across the top of the page, for company logos, security banners, etc. Directions on how to customize it are provided as PostScript comments within the file. See the output of cPost for the default settings of the the values described above. -r option ----------------- The -r option is used to replace the PostScript procedures normally written to the output file with your own. If more customization than the header and footer areas is needed, this is the way to do it. None of the procedures written by cPost are written to the output file. Instead, the contents of the files specified are written. You will need to study the existing PostScript procedures so that you can understand the format of the formatted C code. The format is fairly straight-forward. Note that any files specified with -i option are written before (immediately before) those specified with the -r option. -w option ----------------- The -w option is used to 'wrap' PostScript code around the cPost output. This would be useful if you had some PostScript code you could wrap around an existing file to change the output in some way. such as producing 2-up output. Note that cPost ALWAYS writes a %! header line FIRST to the output file, as well as commentary on the invocation, and some of the runtime option settings. ---------------------------------------------------- cPost processing ---------------------------------------------------- cPost is a two-pass translator. It reads each file two times while generating the output file. The first pass expands tabs and inserts bracketing characters in the input file. A copy of the input file with these changes is written to a temporary file. The second pass writes the PostScript version of each of the input files to the output file. ---------------------------------------------------- anomolies ---------------------------------------------------- cPost is designed to be a fairly robust c tokenizer. It understands valid C constructs, including c++ // comments. cPost also attempts to recognize C function usage and definitions within C files. It handles 'normal' function usage and definition well, but will not recognize functions defined or used in unusual ways. For instance, the function usage (malloc)(10); will not be recognized by cPost. The definition of 'normal' function usage and definition for cPost is: - function names can be followed by any amount of whitespace, comments, and preprocessor statements, followed immediately by a left parenthesis. - functions are only defined and used in c files, not h files (see the -c and -h options for more information). - function definition vs. function usage is primarily determined by the nested brace level. If there are nested braces when the function name is found, the function is a function usage; otherwise, it is a function definition (a check is done to see if it's a function prototype as well). Macros that take arguments will be printed as if they were function invocations. It is possible for cPost to misinterpret things as functions, such as complex variable and typedef definitions, and mangling of the C language such as: #define LT < if ( 2 LT (x + 2)) In this case, cPost will misinterpret LT as a function. Just as well, since you should not be committing these attrocities in the first place. cPost treats preprocessor statements as whitespace, so if brace levels get out of synch because of preprocessor statements, cPost will not generate correct bracketing characters, and will misinterpret function definitions and function usages. For example, the following code chunk will not format properly with cPost: { i = 1; #if defined(SOMETHING) j = 2; } #else j = 3; } #endif The following form should be used instead: { i = 1; #if defined(SOMETHING) j = 2; #else j = 3; #endif } cPost also currently does not handle preprocessor statements absolutely correctly. It treats anything on a line after a preprocessor token as part of the preprocessor line. The following line will be printed in the preprocessor font #define X 5 /* define X to be 5 */ It should really print the comment part in the comment font. ---------------------------------------------------- history ---------------------------------------------------- version 1.2 - Feb 17 1993 - fix to make 'i' and 'd' fonts work (for good this time!) - change Courier-Italic to Courier-Oblique version 1.1 - Feb 15 1993 - fix tab handling problem (thanks to Art Roberts for this) - fix to make 'i' and 'd' fonts work - don't echo command line parameters into output file anymore - allow '@' file specs for -k and file names. version 1.0 - Feb 2 1993 - a few bug fixes, a few added diagnostics - function definitions (can) now use different font than other function tokens (usage and prototype). - font for identifiers separated from 'n'ormal text - added the -r option and -w option version 0.3 - Jan 18 1993 - configuration via imbed files with -i options - all options added (most from cBook) - added linefeed at end of file to prevent last line from not being processed version 0.2 - lots of little fixes version 0.1 - initial version