tools/cxref/README

   1           C Cross Referencing & Documenting tool. Version 1.5 - cxref
   2           ===========================================================
   3
   4 A program that can automatically generate documentation and cross references for
   5 a C program.
   6
   7 The input is any C program with appropriate comments and the output is LaTeX,
   8 HTML, RTF or SGML files.
   9
  10 --------------------------------------------------------------------------------
  11 ------------------------------- Program Options --------------------------------
  12 --------------------------------------------------------------------------------
  13
  14 The name of the program is cxref.
  15
  16 Usage: cxref filename [ ... filename]
  17              [-Odirname] [-Nbasename] [-Rdirname]
  18              [-all-comments] [-no-comments]
  19              [-verbatim-comments] [-block-comments]
  20              [-xref[-all][-file][-func][-var][-type]]
  21              [-warn[-all][-comment][-xref]]
  22              [-index[-all][-file][-func][-var][-type]]
  23              [-raw]
  24              [-latex209|-latex2e]
  25              [-html20|-html32][-src]
  26              [-rtf]
  27              [-sgml]
  28              [-Idirname] [-Ddefine] [-Udefine]
  29              [-CPP cpp_program] [-- cpp_arg [ ... cpp_arg]]
  30
  31 Usage: cxref filename [ ... filename] -delete
  32              [-Odirname] [-Nbasename] [-Rdirname]
  33
  34
  35 filename        The name of the file to document, any number of files may be
  36                 documented at a time.
  37
  38 -delete         The files named are to be deleted from the output directory and
  39                 their entries in the cross reference database and main output
  40                 files are to be removed.
  41
  42 -Odirname       The name of a directory to use for the output latex files and
  43                 the location of the cross reference files that are created.
  44
  45 -Nbasename      The name to use for the first part of the output and cross
  46                 reference files instead of cxref, the file extensions remain
  47                 the same.
  48
  49 -Rdirname       When the source files are in more than one directory, set
  50                 dirname to the name of the root directory of the source tree
  51                 (use relative path if easier e.g. `-R../..').  This will then
  52                 run cxref from that root directory and the `-Odirname' must be
  53                 relative to that directory.
  54
  55 -all-comments   In case you think that the existing comments might work,
  56                 (see below for description of special comments).
  57                 [Danger! This option can produce weird results.]
  58
  59 -no-comments    Ignores all comments, useful if you just want the cross
  60                 references and not the documentation.
  61
  62 -verbatim-comments   When the comments that you have in the code are formatted
  63                 in a predetermined style that you want to preserve on the
  64                 output, this option will force them not to be reformatted.
  65                 [Note, this is for file and function comments only.]
  66
  67 -block-comments When the comments in the program are formatted in the `block'
  68                 style (with a leading `*' character on every line), this option
  69                 will remove that character from the output.
  70                 [Works for a single `*', `+', `|' or `:' on each line.]
  71
  72 -xref           Produce cross referencing information (see below).
  73                 -all    All cross references.
  74                 -file   Cross references for files.
  75                 -func   Cross references for functions.
  76                 -var    Cross references for variables.
  77                 -type   Cross references for types.
  78
  79 -warn           Produce warnings, the options must be concatenated together:
  80                 -all       All warnings.
  81                 -comment   Warn of missing comments.
  82                 -xref      Warn of missing cross references.
  83
  84 -index          Produce a cross reference index, the options must be
  85                 concatenated together:
  86                 -all    All indexes.
  87                 -file   Index of files.
  88                 -func   Index of functions.
  89                 -var    Index of variables.
  90                 -type   Index of types.
  91
  92 -raw            Produce a raw form of output, not really of much use except
  93                 with -warn.
  94
  95 -latex209       Produce a LaTeX file to document each of the source files and
  96                 also an extra file that includes each of these files.  (Using
  97                 the LaTeX version 2.09 format.)
  98 -latex2e        Produce the LaTeX file described above for use with the
  99                 LaTeX2e version of LaTeX.
 100
 101 -html20         Produce an HTML file to document each of the source files and
 102                 a main file to reference each of these files.  (using the HTML
 103                 2.0 standard, no tables).
 104 -html32         Produce the HTML file described above but using HTML 3.2.
 105 -html20-src     Produce the HTML v2.0 output and a HTML version of the source
 106                 file with links into it.
 107 -html32-src     Produce the HTML v3.2 output and a HTML version of the source
 108                 file with links into it.
 109
 110 -rtf            Produce a Rich Text Format (RTF) file to document the source
 111                 file.
 112
 113 -sgml           Produce an SGML file to document the source file.  (Using the
 114                 LinuxDoc DTD).
 115
 116 -Idirname       GCC option to specify the path for include files.
 117 -Ddefine        GCC option to define a pre-processor symbol.
 118 -Udefine        GCC option to undefine a pre-processor symbol.
 119
 120 -CPP program    The name of the program to use instead of the compile time
 121                 default. The program must be able to perform all of the actions
 122                 that `gcc -E -C -dD' does to work.  If the program takes
 123                 arguments then the whole thing needs to be in quotes so that it
 124                 is interpreted as a single argument to cxref.
 125
 126 -- arg ... arg  Extra arguments to be passed to the pre-processor can be placed
 127                 after the `--' separator.
 128
 129 --------------------------------------------------------------------------------
 130 ----------------------- C Compiler Replacement cxref-cc ------------------------
 131 --------------------------------------------------------------------------------
 132
 133 To simplify using cxref on existing source code, there is now a shell script
 134 that will call the C compiler and then call cxref to process the source file.
 135 This means that it can be used as a drop in replacement for CC in Makefiles and
 136 the like.
 137
 138 Usage: cxref-cc [usual cc options]
 139
 140 The name of the source file is extracted from the list of options as well as the
 141 `-D*', `-I*', `-U*' flags and when the C compiler exits succesfully cxref will
 142 be called.  The name of the C compiler to use is controlled by the CXREFCC
 143 environment variable, or if this is not set then the CC environment variable, or
 144 failing this just gcc.
 145
 146 Using this script requires the use of a `.cxref' configuration file to contain
 147 the options since there is nowhere to put the options on the command line for
 148 the C compiler.
 149
 150 This will only cross-reference and document the C source files since they are
 151 the only ones that are compiled, but it will make sure that they are
 152 cross-referenced with the correct options etc.
 153
 154 --------------------------------------------------------------------------------
 155 ----------------------- Cxref configuration File .cxref ------------------------
 156 --------------------------------------------------------------------------------
 157
 158 These command line arguments can also be put into a file named `.cxref' instead
 159 of on the command line.  When cxref is run the arguments to the program are
 160 interpreted in the following order.
 161
 162 1) Those on the command line.
 163 2) Those in the `.cxref' file in the current directory.
 164 3) Those in the `.cxref' file in the source tree root specified by `-R'.
 165
 166 This means that in a multi-directory source tree, each sub-directory can have a
 167 `.cxref' file containing just the line `-R..' or appropriate.  The main
 168 directory can have a `.cxref' file containing the remainder of the options.
 169 This removes completely the need to have any options on the command line apart
 170 from the source file names.
 171
 172 The format of the `.cxref' file is any number of lines, each one containing a
 173 single command line argument (equivalent to one of the argv).  The only options
 174 that cannot be used are the names of source files themselves and the `-delete'
 175 option.  Blank lines are ignored and lines starting with a '#' are comments.
 176
 177 --------------------------------------------------------------------------------
 178 ------------------------ Program Documentation Comments ------------------------
 179 --------------------------------------------------------------------------------
 180
 181 The documentation for the program is produced from comments in the code that are
 182 appropriately formatted.  The cross referencing comes from the code itself and
 183 requires no extra work.
 184
 185 The special comments are `/**** ****/' (for a file) and `/*++++ ++++*/' (for a
 186 data object) any number of `*' or `+' can be used inside of the standard `/*'
 187 and `*/' comment delimiters in the comments, they are ignored.
 188
 189 If a comment line starts with whitespace and is followed by `+html+' then the
 190 rest of the line is included only in the HTML output, and is not processed so it
 191 can include HTML markup, `-html-' means that the rest of the line is included in
 192 all except the HTML output.  The same also applies to the other output formats,
 193 `+none+' can be used for lines not to appear in any output.  The exception to
 194 this is that the raw output does not do any checking and will output all lines.
 195
 196 In any situation where a comment follows a `,', `;' or `)' separated only by
 197 spaces and tabs, the comment is pushed to before the punctuation to apply to
 198 object there.
 199
 200 The program is implemented using a full ANSI C grammar parser with some GCC
 201 extensions, this means that the style of the code is unimportant, only the
 202 content and comments.
 203
 204 --------------------------------------------------------------------------------
 205 ------------------------- Automated Comment Insertion --------------------------
 206 --------------------------------------------------------------------------------
 207
 208 To simplify the insertion of comments that will be parsed by cxref, the file
 209 cxref.el provides a number of Emacs lisp functions.  To use them add the line
 210 `(load "cxref")' to your `.emacs' file or type `M-x load-file cxref.el' from
 211 within Emacs.
 212
 213 The functions and key bindings are:
 214
 215 Control-C Control-F - Adds file comments, a /** **/ header at the top of the
 216                       file and if it is a .h file then it also adds a #ifndef,
 217                       #define at the beginning and #endif at the end to stop
 218                       multiple inclusions.
 219
 220 Control-C f         - Adds comments to a function, the cursor must be on the
 221                       line containing the start of the function definition when
 222                       this function is called.  The /*+ ... +*/ comment that is
 223                       added is of the header type (see the examples) not inline.
 224
 225 Control-C v         - Adds a leading comment to the variable or other definition
 226                       on the current line.
 227
 228 Control-C e         - Adds a trailing comment at the end of the line.
 229
 230 Control-C i         - Adds an inline comment that is ignored by cxref.
 231
 232 --------------------------------------------------------------------------------
 233 -------------------------------- C Preprocessor --------------------------------
 234 --------------------------------------------------------------------------------
 235
 236 To improve the output that is available a modified version of the GNU CPP V2.7.2
 237 is supplied (named cxref-cpp).
 238
 239 This modified C preprocessor allows for a finer control over some features of
 240 the preprocessing that are not important for a compiler.  In a standard
 241 preprocessor, the preprocessor directives are intended for use only by the
 242 preprocessor, so passing the information through is not important.
 243
 244 With cxref-cpp, there are two features that are different to the standard GNU
 245 CPP:
 246
 247 1) The #include directives from the file are output in the same way as the
 248    #defines are output.  An extra flag has been added to cpp to do this, '-dI',
 249    it works in the same way as the existing '-dD' flag for #defines.
 250
 251 2) Comments trailing a #include or a #define are dropped with GNU CPP even if -C
 252    is used. This is not important while compiling but is useful for documenting.
 253
 254 --------------------------------------------------------------------------------
 255 ------------------------------ Cross Referencing -------------------------------
 256 --------------------------------------------------------------------------------
 257
 258 The cross referencing is performed for the following items
 259
 260 Files           - The files that the current file is included in
 261                   (even when included via other files).
 262
 263 #includes       - Files included in the current file.
 264                 - Files included by these files etc.
 265
 266 Variables       - The location of the definition of external variables.
 267                 - The files that have visibility of global variables.
 268                 - The files / functions that use the variable.
 269
 270 Functions       - The file that the function is prototyped in.
 271                 - The functions that the function calls.
 272                 - The functions that call the function.
 273                 - The files and functions that reference the function.
 274                 - The variables that are used in the function.
 275
 276 Each of these items is cross referenced in the output.
 277
 278 The cross referencing uses files `cxref.variable', `cxref.function',
 279 `cxref.include' and `cxref.typedef' in the output directory.
 280 These are a complete list of the function and variable usage in the program and
 281 could be used to generate a function call hierarchy or variable usage diagram
 282 for example.
 283 Two cxref passes of each file is needed, the first to build up the cross
 284 referencing files and the second to use them.
 285
 286 (The file names are different if the `-N' option is used.)
 287
 288 --------------------------------------------------------------------------------
 289 --------------------------------- LaTeX Output ---------------------------------
 290 --------------------------------------------------------------------------------
 291
 292 The default LaTeX output is a file for each of the source files with one extra
 293 file `cxref.tex' that includes each of the other files.  This is to allow a
 294 makefile to only update the changed files (although the references may require
 295 all of the files to be checked again).  When the cxref.tex file has been written
 296 it can be modified by the user, any new files that are added are added at the
 297 end of the source code section, the rest of the file being unchanged.
 298
 299 The index is written to a file called `cxref.apdx.tex' and cxref.tex is updated
 300 to refer to it.
 301
 302 Also written out are three LaTeX style files `page.sty', `fonts.sty' and
 303 `cxref.sty'.  These set up the page to use a smaller margin and smaller fonts to
 304 allow more to appear on a page and also define the new commands for typesetting
 305 the cxref output.
 306
 307 (The file names `cxref.tex' and `cxref.apdx.tex' are different if the `-N'
 308 option is used.)
 309
 310 The two different forms of LaTeX output are selected by using the -latex209 or
 311 the -latex2e options.  These select between two sets of output that can be used
 312 with those two different versions of LaTeX.
 313
 314 --------------------------------------------------------------------------------
 315 --------------------------------- HTML Output ----------------------------------
 316 --------------------------------------------------------------------------------
 317
 318 The default HTML output is a file for each of the source files with one extra
 319 file `cxref.html' that includes each of the other files.  This is to allow a
 320 makefile to only update the changed files (although the references may require
 321 all of the files to be checked again).  When the cxref.html file has been
 322 written it can be modified by the user, any new files that are added are added
 323 at the end before the table of contents, the rest of the file being unchanged.
 324
 325 The index is written to a file called `cxref.apdx.html' and cxref.html is
 326 updated to refer to it.
 327
 328 (The file names `cxref.html' and `cxref.apdx.html' are different if the `-N'
 329 option is used.)
 330
 331 The two different forms of HTML output are selected by using the -html20 or the
 332 -html32 options.  These select between two sets of output that comply with the
 333 HTML 2.0 and 3.2 definitions, they differ in their use of tables.
 334
 335 --------------------------------------------------------------------------------
 336 --------------------------------- RTF Output -----------------------------------
 337 --------------------------------------------------------------------------------
 338
 339 Rich Text Format is a fairly low level page description format devised by
 340 Microsoft.  It is not a well defined and easy to understand standard as are the
 341 other formats, but it is popular for document exchange.
 342
 343 There is a single output file for each of the source files and an index file.
 344
 345 --------------------------------------------------------------------------------
 346 --------------------------------- SGML Output ----------------------------------
 347 --------------------------------------------------------------------------------
 348
 349 Since SGML is a meta-language it is necessary to define the layout elements as
 350 well as provide the information.  The cxref output uses the LinuxDoc document
 351 format and is designed for use with the SGMLtools programs
 352 (http://www.sgmltools.org/).
 353
 354 There is a single output file for each of the source files and an index file.
 355
 356 --------------------------------------------------------------------------------
 357 --------------------------- Example Special Comments ---------------------------
 358 --------------------------------------------------------------------------------
 359
 360 See the `README.c' file, to see that the comments are indeed seen in the code,
 361 run `cxref README.c -raw', the comments are indicated in chevrons `<<< >>>'.
 362
 363 --------------------------------------------------------------------------------
 364 ----------------------------- Further Information ------------------------------
 365 --------------------------------------------------------------------------------
 366
 367 There is a list of frequently asked questions and their answers for the cxref
 368 program in the FAQ file.  A list of improvements planned for future versions of
 369 the program are listed in the file TODO.
 370
 371 More up-to-date information can be found on the World Wide Web at the cxref
 372 homepage, reached via the author's homepage http://www.gedanken.demon.co.uk/.
 373
 374 If you wish to submit bug reports or other comments about the program then email
 375 the author amb@gedanken.demon.co.uk and put cxref in the subject line.
 376
 377 --------------------------------------------------------------------------------
 378 ----------------------------- Author and Copyright -----------------------------
 379 --------------------------------------------------------------------------------
 380
 381 The cxref program was written by Andrew M. Bishop in 1995,96,97,98,99.
 382
 383 The cxref program is copyright Andrew M. Bishop 1995,96,97,98,99.
 384
 385 The cxref-cpp program is copyright Free Software Foundation, Inc.
 386
 387 The cxref and cxref-cpp programs can be freely distributed according to the
 388 terms of the GNU General Public License (see the file `COPYING').