To simplify using cxref on existing source code, there is now a shell script that will call the C compiler and then call cxref to process the source file. This means that it can be used as a drop in replacement for CC in Makefiles and the like.

Usage: cxref-cc [usual cc options]

The name of the source file is extracted from the list of options as well as the `-D*', `-I*', `-U*' flags and when the C compiler exits succesfully cxref will be called. The name of the C compiler to use is controlled by the CXREFCC environment variable, or if this is not set then the CC environment variable, or failing this just gcc.

Using this script requires the use of a `.cxref' configuration file to contain the options since there is nowhere to put the options on the command line for the C compiler.

This will only cross-reference and document the C source files since they are the only ones that are compiled, but it will make sure that they are cross-referenced with the correct options etc.

These command line arguments can also be put into a file named `.cxref' instead of on the command line. When cxref is run the arguments to the program are interpreted in the following order.

(1) Those on the command line. (2) Those in the `.cxref' file in the current directory. (3) Those in the `.cxref' file in the source tree root specified by `-R'.

This means that in a multi-directory source tree, each sub-directory can have a `.cxref' file containing just the line `-R..' or appropriate. The main directory can have a `.cxref' file containing the remainder of the options. This removes completely the need to have any options on the command line apart from the source file names.

The format of the `.cxref' file is any number of lines, each one containing a single command line argument (equivalent to one of the argv). The only options that cannot be used are the names of source files themselves and the `-delete' option. Blank lines are ignored and lines starting with a '#' are comments.

The documentation for the program is produced from comments in the code that are appropriately formatted. The cross referencing comes from the code itself and requires no extra work.

The special comments are `/**** ****/' (for a file) and `/*++++ ++++*/' (for a data object) any number of `*' or `+' can be used inside of the standard `/*' and `*/' comment delimiters in the comments, they are ignored.

If a comment line starts with whitespace and is followed by `+html+' then the rest of the line is included only in the HTML output, and is not processed so it can include HTML markup, `-html-' means that the rest of the line is included in all except the HTML output. The same also applies to the other output formats, `+none+' can be used for lines not to appear in any output. The exception to this is that the raw output does not do any checking and will output all lines.

In any situation where a comment follows a `,', `;' or `)' separated only by spaces and tabs, the comment is pushed to before the punctuation to apply to object there.

The program is implemented using a full ANSI C grammar parser with some GCC extensions, this means that the style of the code is unimportant, only the content and comments.

The cross referencing is performed for the following items

Files The files that the current file is included in (even when included via other files).

#includes Files included in the current file. Files included by these files etc.

Variables The location of the definition of external variables. The files that have visibility of global variables. The files / functions that use the variable.

Functions The file that the function is prototyped in. The functions that the function calls. The functions that call the function. The files and functions that reference the function. The variables that are used in the function.

Each of these items is cross referenced in the output.

The cross referencing uses files `cxref.variable', `cxref.function', `cxref.include' and `cxref.typedef' in the output directory. These are a complete list of the function and variable usage in the program and could be used to generate a function call hierarchy or variable usage diagram for example. Two cxref passes of each file is needed, the first to build up the cross referencing files and the second to use them.

(The file names are different if the `-N' option is used.)

The default LaTeX output is a file for each of the source files with one extra file `cxref.tex' that includes each of the other files. This is to allow a makefile to only update the changed files (although the references may require all of the files to be checked again). When the cxref.tex file has been written it can be modified by the user, any new files that are added are added at the end of the source code section, the rest of the file being unchanged.

The index is written to a file called `cxref.apdx.tex' and cxref.tex is updated to refer to it.

Also written out are three LaTeX style files `page.sty', `fonts.sty' and `cxref.sty'. These set up the page to use a smaller margin and smaller fonts to allow more to appear on a page and also define the new commands for typesetting the cxref output.

(The file names `cxref.tex' and `cxref.apdx.tex' are different if the `-N' option is used.)

The default HTML output is a file for each of the source files with one extra file `cxref.html' that includes each of the other files. This is to allow a makefile to only update the changed files (although the references may require all of the files to be checked again). When the cxref.html file has been written it can be modified by the user, any new files that are added are added at the end before the table of contents, the rest of the file being unchanged.

The index is written to a file called `cxref.apdx.html' and cxref.html is updated to refer to it.

(The file names `cxref.html' and `cxref.apdx.html' are different if the `-N' option is used.)

The HTML output uses the HTML 4.01 standard and all pages validate correctly.

Rich Text Format is a fairly low level page description format devised by Microsoft. It is not a well defined and easy to understand standard as are the other formats, but it is popular for document exchange.

There is a single output file for each of the source files and an index file.

Since SGML is a meta-language it is necessary to define the layout elements as well as provide the information. The cxref output uses the LinuxDoc document format and is designed for use with the SGMLtools programs (http://www.sgmltools.org/).

There is a single output file for each of the source files and an index file.