tools/cxref/README.html

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