Handle Boolean tags safely.

[tangerine.git] / tools / cxref / README.tex

% This LaTeX file generated by cxref (and then edited by hand).
% cxref program README (c) Andrew M. Bishop 1995,96,97,98,99.

\documentclass{report}
\usepackage{doc/fonts,doc/page,doc/cxref}
\pagestyle{myheadings}

\begin{document}

% Contents (Optional, either here or at end)

%\markboth{Contents}{Contents}
%\tableofcontents

\chapter{C Cross Referencing \& Documenting tool. Version 1.5 - cxref}

A program that can automatically generate documentation and cross references for
a C program.

The input is any C program with appropriate comments and the output is \LaTeX ,
HTML, RTF or SGML files.

\section{Program Options}

The name of the program is cxref.

\smallskip

\begin{tabular}{ll}
Usage: {\tt cxref} & \\
& {\tt filename [ ... filename]} \\
& {\tt [-Odirname] [-Nbasename] [-Rdirname]} \\
& {\tt [-all-comments] [-no-comments]} \\
& {\tt [-verbatim-comments] [-block-comments]} \\
& {\tt [-xref[-all][-file][-func][-var][-type]]} \\
& {\tt [-warn[-all][-comment][-xref]]} \\
& {\tt [-index[-all][-file][-func][-var][-type]]} \\
& {\tt [-raw]} \\
& {\tt [-latex209|-latex2e]} \\
& {\tt [-html20|-html32][-src]} \\
& {\tt [-rtf]} \\
& {\tt [-sgml]} \\
& {\tt [-Idirname] [-Ddefine] [-Udefine]} \\
& {\tt [-CPP cpp\_program] [-- cpp\_arg [ ... cpp\_arg]]} \\
\end{tabular}
\begin{tabular}{ll}
Usage: {\tt cxref} & \\
& {\tt filename [ ... filename] -delete} \\
& {\tt [-Odirname] [-Nbasename] [-Rdirname]} \\
\end{tabular}

\begin{list}{}{\leftmargin=1in \labelwidth=2.5in}
\item[{\tt filename}]
The name of the file to document, any number of files may be
documented at a time.
\item[{\tt -delete}]
The files named are to be deleted from the output directory and
their entries in the cross reference database and main output
files are to be removed.
\item[{\tt -Odirname}]
The name of a directory to use for the output \LaTeX files and
the location of the cross reference files that are created.
\item[{\tt -Nbasename}]
The name to use for the first part of the output and cross
reference files instead of cxref, the file extensions remain
the same.
\item[{\tt -Rdirname}]
When the source files are in more than one directory, set
dirname to the name of the root directory of the source tree
(use relative path if easier e.g. ``-R../..'').  This will then
run cxref from that root directory and the ``-Odirname'' must be
relative to that directory.
\item[{\tt -all-comments}]
In case you think that the existing comments might work,
(see below for description of special comments).
{\it[Danger! This option can produce weird results.]}
\item[{\tt -no-comments}]
Ignores all comments, useful if you just want the cross
references and not the documentation.
\item[{\tt -verbatim-comments}]
When the comments that you have in the code are formatted
in a predetermined style that you want to preserve on the
output, this option will force them not to be reformatted.
{\it[Note, this is for file and function comments only.]}
\item[{\tt -block-comments}]
When the comments in the program are formatted in the ``block''
style (with a leading ``*'' character on every line), this option
will remove that character from the output.
{\it[Works for a single ``*'', ``+'', ``|'' or ``:'' on each line.]}
\item[{\tt -xref}]
Produce cross referencing information (see below).
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]    All cross references.
\item[{\tt -file}]   Cross references for files.
\item[{\tt -func}]   Cross references for functions.
\item[{\tt -var}]    Cross references for variables.
\item[{\tt -type}]   Cross references for types.
\end{list}
\item[{\tt -warn}]
Produce warnings, the options must be concatenated together:
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]       All warnings.
\item[{\tt -comment}]   Warn of missing comments.
\item[{\tt -xref}]      Warn of missing cross references.
\end{list}
\item[{\tt -index}]
Produce a cross reference index, the options must be
concatenated together:
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]    All indexes.
\item[{\tt -file}]   Index of files.
\item[{\tt -func}]   Index of functions.
\item[{\tt -var}]    Index of variables.
\item[{\tt -type}]   Index of types.
\end{list}
\item[{\tt -raw}]
Produce a raw form of output, not really of much use except
with -warn.
\item[{\tt -latex209}]
Produce a LaTeX file to document each of the source files and
also an extra file that includes each of these files.  (Using
the LaTeX version 2.09 format.)
\item[{\tt -latex2e}]
Produce the LaTeX file described above for use with the
LaTeX2e version of LaTeX.
\item[{\tt -html20}]
Produce an HTML file to document each of the source files and
a main file to reference each of these files.  (using the HTML
2.0 standard, no tables).
\item[{\tt -html32}]
Produce the HTML file described above but using HTML 3.2.
\item[{\tt -html20-src}]
Produce the HTML v2.0 output and a HTML version of the source
file with links into it.
\item[{\tt -html32-src}]
Produce the HTML v3.2 output and a HTML version of the source
file with links into it.
\item[{\tt -rtf}]
Produce a Rich Text Format (RTF) file to document the source
file.
\item[{\tt -sgml}]
Produce an SGML file to document the source file.  (Using the
LinuxDoc DTD).
\item[{\tt -Idirname}]
GCC option to specify the path for include files.
\item[{\tt -Ddefine}]
GCC option to define a pre-processor symbol.
\item[{\tt -Udefine}]
GCC option to undefine a pre-processor symbol.
\item[{\tt -CPP program}]
The name of the program to use instead of the compile time
default. The program must be able to perform all of the actions
that ``gcc -E -C -dD'' does to work.  If the program takes
arguments then the whole thing needs to be in quotes so that it
is interpreted as a single argument to cxref.
\item[{\tt-- arg ... arg}]
Extra arguments to be passed to the pre-processor can be placed
after the ``--'' separator.
\end{list}

\section{C Compiler Replacement cxref-cc}

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.

\section{Cxref configuration File}

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.

\begin{enumerate}
\item Those on the command line.
\item Those in the ``.cxref'' file in the current directory.
\item Those in the ``.cxref'' file in the source tree root specified by ``-R''.
\end{enumerate}

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.

\section{Program Documentation 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
the 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.

\section{Automated Comment Insertion}

To simplify the insertion of comments that will be parsed by cxref, the file
cxref.el provides a number of Emacs lisp functions.  To use them add the line
{\tt (load "cxref")} to your ``.emacs'' file or type {\tt M-x load-file cxref.el} from
within Emacs.

The functions and key bindings are:
\begin{list}{}{\leftmargin=1.3in \labelwidth=2.5in}
\item[{\it Control-C Control-F}]
Adds file comments, a /** **/ header at the top of the
file and if it is a .h file then it also adds a \#ifndef,
\#define at the beginning and \#endif at the end to stop
multiple inclusions.
\item[{\it Control-C f}]
Adds comments to a function, the cursor must be on the
line containing the start of the function definition when
this function is called.  The /*+ ... +*/ comment that is
added is of the header type (see the examples) not inline.
\item[{\it Control-C v}]
Adds a leading comment to the variable or other definition
on the current line.
\item[{\it Control-C e}]
Adds a trailing comment at the end of the line.
\item[{\it Control-C i}]
Adds an inline comment that is ignored by cxref.
\end{list}

\section{C Preprocessor}

To improve the output that is available a modified version of the GNU CPP V2.7.2
is supplied (named cxref-cpp).

This modified C preprocessor allows for a finer control over some features of
the preprocessing that are not important for a compiler.  In a standard
preprocessor, the preprocessor directives are intended for use only by the
preprocessor, so passing the information through is not important.

With cxref-cpp, there are two features that are different to the standard GNU
CPP:

\begin{enumerate}
\item
The \#include directives from the file are output in the same way as the
\#defines are output.  An extra flag has been added to cpp to do this, '-dI',
it works in the same way as the existing '-dD' flag for \#defines.
\item
Comments trailing a \#include or a \#define are dropped with GNU CPP even if -C
is used. This is not important while compiling but is useful for documenting.
\end{enumerate}

\section{Cross Referencing}

The cross referencing is performed for the following items
\begin{list}{}{\leftmargin=1in \labelwidth=1.5in}
\item[Files]
\begin{itemize}
\item The files that the current file is included in
(even when included via other files).
\end{itemize}
\item[\#includes]
\begin{itemize}
\item Files included in the current file.
\item Files included by these files etc.
\end{itemize}
\item[Variables]
\begin{itemize}
\item The location of the definition of external variables.
\item The files that have visibility of global variables.
\item The files / functions that use the variable.
\end{itemize}
\item[Functions]
\begin{itemize}
\item The file that the function is prototyped in.
\item The functions that the function calls.
\item The functions that call the function.
\item The files and functions that reference the function.
\item The variables that are used in the function.
\end{itemize}
\end{list}
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.

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

\section{\LaTeX Output}

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.

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

The two different forms of \LaTeX output are selected by using the {\it -latex209} or
the {\it -latex2e} options.  These select between two sets of output that can be used
with those two different versions of \LaTeX.

\section{HTML Output}

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.

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

The two different forms of HTML output are selected by using the {\it-html20} or the
{\it -html32} options.  These select between two sets of output that comply with the
HTML 2.0 and 3.2 definitions, they differ in their use of tables.

\section{RTF Output}

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.

\section{SGML Output}

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.

\section{Example Special Comments}

The file ``README.c'' is included at the end of this document to show that the
comments are indeed seen in the code, the result of running this through cxref
is also included.

\section{Further Information}

There is a list of frequently asked questions and their answers for the cxref
program in the FAQ file.  A list of improvements planned for future versions of
the program are listed in the file TODO.

More up-to-date information can be found on the World Wide Web at the cxref
homepage, reached via the author's homepage http://www.gedanken.demon.co.uk/.

If you wish to submit bug reports or other comments about the program then email
the author amb@gedanken.demon.co.uk and put cxref in the subject line.

\section{Author and Copyright}

The cxref program was written by Andrew M. Bishop in 1995,96,97,98,99.

The cxref program is copyright Andrew M. Bishop 1995,96,97,98,99.

The cxref-cpp program is copyright Free Software Foundation, Inc.

The cxref and cxref-cpp programs can be freely distributed according to the
terms of the GNU General Public License (see the file `COPYING').

\chapter{Example ``README.c''}

% What a hack to load a file into a verbatim section!
% I have also had to rename README.c.tex to README_c.tex
% so that \input{README.c} does not do \input{README.c.tex} instead.

\def\endverbatim{\input{README.c}\endtrivlist}
\begin{verbatim}
\end{verbatim}

\chapter{Cxref Output For ``README.c''}

% Begin-Of-Source-Files

\input{README_c.tex}

% End-Of-Source-Files

% Appendix

% Contents (Optional, either here or at beginning)

\markboth{Contents}{Contents}
\tableofcontents

\end{document}