FILES: cxref-1.2.tgz
       cxref-1.1-1.2.diff.gz

SIZE: 218334 & 41319 Bytes

FORMAT: gzipped tar file of C source code

COPYRIGHT: Andrew M. Bishop (amb@gedanken.demon.co.uk)
           distributed under GPL.

LOCATION: /pub/unix/tools

DESCRIPTION: Cxref - C program cross-referencing & documentation tool (UNIX)

SUPERSEDES: cxref-1.0.tgz          (please delete).
            cxref-1.1.tgz          (please delete).
            cxref-1.0-1.1.diff.gz  (please delete).


    C Cross Referencing & Documenting tool. Version 1.2 - cxref
    ===========================================================

Produce LaTeX or HTML documentation including cross-references from C program
source code.

Works for ANSI C, including a few gcc extensions.


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 documentation is produced for each of the following:

Files            - A comment that applies to the whole file.
Functions        - A comment for the function, including a description of
                   each of the arguments and the return value.
Variables        - A comment for each of a group of variables and/or
                   individual variables.
#include         - A comment for each included file.
#define          - A comment for each pre-processor symbol definition, and
                   for macro arguments.
Type definitions - A comment for each defined type and for each element of a
                   structure or union type.

Any or all of these comments can be present in suitable places in the
source code.


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.

Includes extensive README and FAQ with details and examples on how to use the
program.


New for version 1.2
-------------------

A FAQ is provided with common questions and answers and provide help.

Major revision of parsing code, especially for function definitions.
Labeled statements do not need a ';' (e.g. default in switch statement).
Better handling of traditional style function definitions
Variables declared extern within a function recognised and referenced.
Numerous minor bugs in parsing corrected.

Line number and file name information available in case of parse error.
Parse errors are handled gracefully, the program does not just exit.

Create sub-directories of the output directory as needed.
Better handling of include pathnames in cxref-cpp, for subdirectories.

Added a cxref.sty LaTeX style file instead of at the top of the main file.
The output files are not compatible with Version 1.1 output files.
******** cxref Version 1.2 must be used on all sources files to update ********
******** them and cxref.tex and cxref.html updated to the new format.  ********


Availability
------------

This program has been tested on the following systems:
Linux 1.[123].x, SunOS 4.1.x, Solaris 2.x, HPUX 10.x

The complete version 1.2
  cxref-1.2.tgz, 218334 Bytes, a gzipped tar file of C source code.

An upgrade from version 1.1
  cxref-1.1-1.2.diff.gz, 41319 Bytes, a gzipped file of differences.
  (requires GNU patch to apply.)

Available from ftp.demon.co.uk in the /pub/unix/unix/tools directory
(to be re-organised to /pub/unix/tools in the future).


Author & Copyright
------------------

This program is copyright Andrew M. Bishop (amb@gedanken.demon.co.uk)
and distributed under GPL.

I would like also to thank the many people who have e-mailed me after
versions 1.0 & 1.1 were released, for finding bugs and reporting them.
