cBook - C language file formatter for BookMaster by Patrick Mueller (c) Copyright International Business Machines Corporation 1993. All rights Reserved. ---------------------------------------------------- What is cBook? ---------------------------------------------------- cBook is a program which will take a number of c and h files as input and create a BookMaster file. The BookMaster file will contain the contents of the input files that have been marked up so various parts are highlighted, and a cross reference. A global cross reference can be generated which contains a list of all the functions called within the c files. A file level cross reference can be generated for every input file. A file that includes links for BookManager can also be created. BookMaster is an IBM mainframe (CMS and MVS) document formatting system. ---------------------------------------------------- cBook invocation and options ---------------------------------------------------- When cBook is invoked, it examines the command line for file names and options. The file names may contain wildcards. Running cBook with no file names or with a ? as the first parameter will write some brief help to standard output. 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 CBOOK environment variable. Command line options override environment variable options. A typical invocation of cBook might be cbook *.c *.h > project.scr This invocation will include all c and h files, use any options set in the CBOOK environment variable, and write the output to the file project.scr. Note: it is possible to create extremely large BookMaster documents with cBook. 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. If the string that you want to use needs spaces, and ends up getting interpreted by SCRIPT, you can use &rbl. instead of the space (the SCRIPT symbol for a required blank). Since the & symbol is special on OS/2, you will need to escape this character when you set the environment variable by prefixing the & with a ^). Before you try to script and print a 500-page monster reference, try running it on just two or three files, to see if everything (font size, highlighting, etc.) is to your liking. After everything is the way you want it, remember your settings (you may want to set the CBOOK environment variable in your CONFIG.SYS file), and let'er rip on the 500-page monster. Save the trees!!! Valid options are: -a[*|1|2] cross reference table type Two cross reference table types are available. Type 1 is the 'classic' style, from previous versions of cBook. Type 2 is an alternate style which should be used when a the cross reference tables become too large, and BookMaster complains about splitting rows. The default value of this option, *, will use type 1 tables unless it it appears that your tables will have problems with BookMaster, in which case type 2 tables will be used. -b[+|-|#] enable/disable/set bracketing level Use -b+ to have all levels of braces within file bracketed. Use -b-to cause no bracketing. Use -b# to cause brackets to be generated for only the first # levels. For example, -b3 will cause only braces nested 3 deep or less to have bracketing placed around them. -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 whether function definition and usage are valid within the file, and to determine sorting order. Note that the 'extension' is considered the next after the first '.' in the name, up to the last character, or next '.' in the name. -ec1:xlat1,.. translate character c1 to string xlat1, etc. This option can be used to handle special characters within your files. For example, to translate the + character to :plus. in the output, you should use the option -e+:&plus. -f[+|-] enable/disable folio-by-chapter page numbering Cause pages numbers to be generated in a form chapter number-page number, so that each chapter number resets the page number. To get normal serial page number, using -f-. -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 next string after the first '.' in the name, up to the last character, or next '.' in the name. -i[+|-] create/don't create an imbeddable file Use of the -i+ option will create a BookMaster file without the userdoc and prolog tags, so the output file will be able to be imbedded within another BookMaster document. -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. 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. -l#### set head level for function/reserved/comment/preproc The default is -l2315. Four numbers must be specified, and must be between 0 and 9. -m[+|-] Generate BookManager source. This option implies -x-. You may want to use -n0 also. -n# separate line numbers from lines with # spaces. When 0 is specified, no line numbers are generated. -ofile output written to file. Without this option, output is written to stdout. -p[+|-] enable/disable best-fit page break at functions -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, ... -uarbitrary_text set security level This string will be used as the security banner for the file. -w[*|#] set width for :xmp. tag This option is used with the width= attribute of the :xmp. tags and controls the size of the font used to print the files. The default of 128 causes files to be printed in a fairly small font. Using -w* will cause the width of the longest line in the file to be used as the width (10 is added to the longest length). -x[+|-|*] enable/disable/only cross reference The -x* option will not produce a listing of the source files. -ypath path to use for temporary files A copy of each input file read is created during the a cBook run. By default, these copies are created in your current directory. This option allows you to specify a different location for the temp files. You should specify a directory name, with a backslash following the name. -z# function name size Controls the relative size of functions within the text. The default is -z2 which makes the functions 2 points bigger than the rest of the text. Use -z0 to make functions the same size as the rest of the text. -? display online help The default options are -a* -b+ -cc -f+ -hh -i- -l2315 -n2 -p+ -stn -t4 -w128 -x+ -z2 ---------------------------------------------------- cBook processing ---------------------------------------------------- cBook is a two-pass translator. It reads each file two times before generating an output file. The first pass expands tabs, inserts bracketing characters in the input file, and builds the function cross reference information. A copy of the input file with these changes is written to a temporary file. The second pass creates the output file by inserting highlighting tags in the copies of the input files and printing the cross reference. cBook is designed to be a fairly robust c tokenizer. It understands valid C constructs, including c++ // comments. cBook 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 cBook The definition of 'normal' function usage and definition for cBook 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). cBook treats preprocessor statements as whitespace, so if brace levels get out of synch because of preprocessor statements, cBook 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 cBook: { 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 }