home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / CBOOK.ZIP / cbook.doc < prev    next >
Text File  |  1993-01-30  |  11KB  |  290 lines
  1.  
  2.  
  3.             cBook - C language file formatter for BookMaster
  4.  
  5.                            by Patrick Mueller
  6.  
  7.  
  8.    (c) Copyright International Business Machines Corporation 1993.
  9.    All rights Reserved.
  10.  
  11. ----------------------------------------------------
  12. What is cBook?
  13. ----------------------------------------------------
  14.  
  15. cBook is a program which will take a number of c and h files as
  16. input and create a BookMaster file.  The BookMaster file will contain
  17. the contents of the input files that have been marked up so various
  18. parts are highlighted, and a cross reference.  A global cross reference
  19. can be generated which contains a list of all the functions called
  20. within the c files.  A file level cross reference can be generated for
  21. every input file.  A file that includes links for BookManager can
  22. also be created.
  23.  
  24. BookMaster is an IBM mainframe (CMS and MVS) document formatting system.
  25.  
  26. ----------------------------------------------------
  27. cBook invocation and options
  28. ----------------------------------------------------
  29.  
  30. When cBook is invoked, it examines the command line for file names
  31. and options.  The file names may contain wildcards.  Running cBook
  32. with no file names or with a ? as the first parameter will write some
  33. brief help to standard output.
  34.  
  35. Options are blank delimited 'words' which begin with a '-'.
  36. The case of the character following the - is not significant.
  37. Options may be placed before, after or in between file names.  If the
  38. same option is specified more than once on the command line, only the
  39. last option is used.  Options may also be specified in the CBOOK
  40. environment variable.  Command line options override environment
  41. variable options.
  42.  
  43. A typical invocation of cBook might be
  44.  
  45.    cbook *.c *.h > project.scr
  46.  
  47. This invocation will include all c and h files, use any options
  48. set in the CBOOK environment variable, and write the output to the
  49. file project.scr.
  50.  
  51. Note: it is possible to create extremely large BookMaster
  52. documents with cBook.
  53.  
  54. Note that the options used in the environment variable are used as-is,
  55. which means that quote processing which is normally done on the OS/2
  56. commandline parameters is not done on environment variable values.
  57. Thus, it is not possible to use an option which has a value which
  58. includes spaces.  If the string that you want to use needs spaces, and
  59. ends up getting interpreted by SCRIPT, you can use &rbl. instead of the
  60. space (the SCRIPT symbol for a required blank).  Since the & symbol is
  61. special on OS/2, you will need to escape this character when you set the
  62. environment variable by prefixing the & with a ^).
  63.  
  64. Before you try to script and print a 500-page monster reference, try
  65. running it on just two or three files, to see if everything (font size,
  66. highlighting, etc.) is to your liking.  After everything is the way you
  67. want it, remember your settings (you may want to set the CBOOK
  68. environment variable in your CONFIG.SYS file), and let'er rip on the
  69. 500-page monster.  Save the trees!!!
  70.  
  71. Valid options are:
  72.  
  73.     -a[*|1|2]
  74.     cross reference table type
  75.  
  76. Two cross reference table types are available.  Type 1 is the 'classic'
  77. style, from previous versions of cBook.  Type 2 is an alternate style
  78. which should be used when a the cross reference tables become too large,
  79. and BookMaster complains about splitting rows.  The default value of
  80. this option, *, will use type 1 tables unless it it appears that your
  81. tables will have problems with BookMaster, in which case type 2 tables
  82. will be used.
  83.  
  84.     -b[+|-|#]
  85.     enable/disable/set bracketing level
  86.  
  87. Use -b+ to have all levels of braces within file bracketed.
  88. Use -b-to cause no bracketing.
  89. Use -b# to cause brackets to be generated for only the first # levels.
  90. For example, -b3 will cause only braces nested 3 deep or less to have
  91. bracketing placed around them.
  92.  
  93.     -cext1,ext2,...
  94.     treat files with extension ext1 and ext2 as C files
  95.  
  96. For example, -cc,y,sqc will cause files with 'extensions' c, y,
  97. and sqc (case insensitive) to be considered c files.  This information
  98. is used to determine whether function definition and usage are valid
  99. within the file, and to determine sorting order.  Note that the
  100. 'extension' is considered the next after the first '.' in the name,
  101. up to the last character, or next '.' in the name.
  102.  
  103.     -ec1:xlat1,..
  104.     translate character c1 to string xlat1, etc.
  105.  
  106. This option can be used to handle special characters within your files.
  107. For example, to translate the + character to :plus. in the output, you
  108. should use the option
  109. -e+:&plus.
  110.  
  111.     -f[+|-]
  112.     enable/disable folio-by-chapter page numbering
  113.  
  114. Cause pages numbers to be generated in a form chapter number-page
  115. number, so that each chapter number resets the page number.  To get
  116. normal serial page number, using -f-.
  117.  
  118.     -hext1,ext2,...
  119.     treat files with extension ext1 and ext2 as H files
  120.  
  121. For example, -hh,rh,sqh will cause files with 'extensions' h, rh,
  122. and sqh (case insensitive) to be considered h files.  This information
  123. is used to determine whether function definition and usage are valid
  124. within the file, and to determine sorting order.  Note that the
  125. 'extension' is considered the next string after the first '.' in the name,
  126. up to the last character, or next '.' in the name.
  127.  
  128.     -i[+|-]
  129.     create/don't create an imbeddable file
  130.  
  131. Use of the -i+ option will create a BookMaster file without the
  132. userdoc and prolog tags, so the output file will be able to be
  133. imbedded within another BookMaster document.
  134.  
  135.     -kkey1,key2,...
  136.     treat key1, key2, etc as reserved words
  137.  
  138. In addition to the ANSI reserved words, the following are considered
  139. reserved (SAA extensions):  _Packed, _System, _Optlink, _Far16, _Cdecl,
  140. _Pascal.  To make additional words reserved, use the -k option.  For
  141. instance, -kNULL,FILE adds NULL and FILE as reserved words.  This option
  142. is used merely to control the highlighting of the tokens.
  143.  
  144.     -l####
  145.     set head level for function/reserved/comment/preproc
  146.  
  147. The default is -l2315.  Four numbers must be specified, and must
  148. be between 0 and 9.
  149.  
  150.     -m[+|-]
  151.     Generate BookManager source.
  152.  
  153. This option implies -x-.  You may want to use -n0 also.
  154.  
  155.     -n#
  156.     separate line numbers from lines with # spaces.
  157.  
  158. When 0 is specified, no line numbers are generated.
  159.  
  160.     -ofile
  161.     output written to file.
  162.  
  163. Without this option, output is written to stdout.
  164.  
  165.     -p[+|-]
  166.     enable/disable best-fit page break at functions
  167.  
  168.     -snt or -stn
  169.     sort files by name/type or type/name
  170.  
  171. When sorting by type, the files are first sorted by whether they
  172. are c, h, or neither (see -c and -h options), and then by the
  173. actual extension.  All sorting is done in a case insensitive manner.
  174.  
  175.     -t#
  176.     expand tabs to # columns
  177.  
  178. The default is 4, which causes the characters immediately following
  179. tab characters to be placed in columns 5, 9, 13, ...
  180.  
  181.     -uarbitrary_text
  182.     set security level
  183.  
  184. This string will be used as the security banner for the file.
  185.  
  186.     -w[*|#]
  187.     set width for :xmp. tag
  188.  
  189. This option is used with the width= attribute of the :xmp. tags and
  190. controls the size of the font used to print the files.  The default of
  191. 128 causes files to be printed in a fairly small font.  Using -w* will
  192. cause the width of the longest line in the file to be used as the width
  193. (10 is added to the longest length).
  194.  
  195.     -x[+|-|*]
  196.     enable/disable/only cross reference
  197.  
  198. The -x* option will not produce a listing of the source files.
  199.  
  200.     -ypath
  201.     path to use for temporary files
  202.  
  203. A copy of each input file read is created during the a cBook run.  By
  204. default, these copies are created in your current directory.  This
  205. option allows you to specify a different location for the temp files.
  206. You should specify a directory name, with a backslash following the
  207. name.
  208.  
  209.     -z#
  210.     function name size
  211.  
  212. Controls the relative size of functions within the text.  The default
  213. is -z2 which makes the functions 2 points bigger than the rest of
  214. the text.  Use -z0 to make functions the same size as the rest of
  215. the text.
  216.  
  217.     -?
  218.     display online help
  219.  
  220.  
  221. The default options are
  222.  
  223.     -a* -b+ -cc -f+ -hh -i- -l2315 -n2 -p+ -stn -t4 -w128 -x+ -z2
  224.  
  225. ----------------------------------------------------
  226. cBook processing
  227. ----------------------------------------------------
  228.  
  229. cBook is a two-pass translator.  It reads each file two times
  230. before generating an output file.  The first pass expands tabs, inserts
  231. bracketing characters in the input file, and builds the function cross
  232. reference information.  A copy of the input file with these changes is
  233. written to a temporary file.  The second pass creates the output file by
  234. inserting highlighting tags in the copies of the input files and
  235. printing the cross reference.
  236.  
  237. cBook is designed to be a fairly robust c tokenizer.  It understands
  238. valid C constructs, including c++ // comments.  cBook also attempts
  239. to recognize C function usage and definitions within C files.  It
  240. handles 'normal' function usage and definition well, but will not
  241. recognize functions defined or used in unusual ways.  For instance,
  242. the function usage
  243.  
  244.    (malloc)(10);
  245.  
  246. will not be recognized by cBook
  247.  
  248. The definition of 'normal' function usage and definition for cBook
  249. is:
  250.  
  251. - function names can be followed by any amount of whitespace, comments,
  252.   and preprocessor statements, followed immediately by a left
  253.   parenthesis.
  254.  
  255. - functions are only defined and used in c files, not h files (see
  256.   the -c and -h options for more information).
  257.  
  258. - function definition vs. function usage is primarily determined by the
  259.   nested brace level.  If there are nested braces when the function
  260.   name is found, the function is a function usage; otherwise, it is a
  261.   function definition (a check is done to see if it's a function
  262.   prototype as well).
  263.  
  264. cBook treats preprocessor statements as whitespace, so if brace
  265. levels get out of synch because of preprocessor statements, cBook
  266. will not generate correct bracketing characters, and will misinterpret
  267. function definitions and function usages.  For example, the following
  268. code chunk will not format properly with cBook:
  269.  
  270.       {
  271.       i = 1;
  272.    #if defined(SOMETHING)
  273.       j = 2;
  274.       }
  275.    #else
  276.       j = 3;
  277.       }
  278.    #endif
  279.  
  280. The following form should be used instead:
  281.  
  282.       {
  283.       i = 1;
  284.    #if defined(SOMETHING)
  285.       j = 2;
  286.    #else
  287.       j = 3;
  288.    #endif
  289.       }
  290.