tools/cxref/README.man

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