cdg.l

reads a set of C-source files and generates a two-column listing of those sources

.TH CDG L "14\ Jan\ 1996" "Release\ 1.0"
.UC 4
.SH NAME
CDG \- A C Documentation Generator.
.SH SYNOPSIS
.B cdg
\fIlistfile\fP
[ \fItagfile\fP ]
.SH DESCRIPTION
Cdg is a program that produces two-column listings with numbered lines and
three-column cross reference tables in landscape mode on suitable printers.
Lines in the source files that were wider than 80 characters are broken at
position 80 with a backslash added in position 81. Tabs are expanded into
spaces. Trailing spaces and tabs are ignored.
.PP
The cross reference table lists for each name the line-numbers where that
name is used. Line-numbers where the name gets defined or declared are output
in bold-face (or otherwise highlighted, depending on the capabilities of
the printer).  \fBCdg\fP sends the formatted output to \fIstdout\fP.
.br
The format of the output was inspired on the format used in
"Source Code and Commentary on UNIX level 6" by John Lions.
.SH FORMAT OF THE LISTFILE
The \fIlistfile\fP is a plain ASCII file that consists of four parts:
.TP
Identification of the output (3 lines)
This text will be appear on the footer of every output page. These lines
can be used for copyright messages and/or to identify the product to which
the source files belong. The first two lines may have a length of up to 180
characters, the third may have a length of no more than 156 characters
because the current date and time are printed after that.
.TP
Types for the cross reference table (optional, one line)
This line describes what types of words must be cross referenced,
see below at \fISelecting types for cross reference table\fP.
.TP
Names to exclude (any number of lines)
Each of these lines lists one word that must be excluded from the cross
reference table. Each of these lines consist of a dash followed by one word.
.TP
Names of the source files (any number of lines)
Any number of lines, each containing the name of a source file to be included
in the documentation.
.PP
An example \fIlistfile\fP for the sources of the \fBcdg\fP program looks
like this:
.br
CDG is a C-source Documentation Generator.
.br
CDG used on it's own sources yields this document.
.br
CDG is distributed under the GNU GPL conditions.
.br
Makefile
.br
cdg.h
.br
main.c
.br
page.c
.br
y.tab.h
.br
parse.c
.br
scan.h
.br
scan.l
.PP
An example \fIlistfile\fP (very similar to this one) is included in the
distribution of \fBcdg\fP.
.SH OPTIONS
.TP
\fItagfile\fP
Preserve the list of all identifiers in a file named \fItagfile\fP.
.SH SELECTING TYPES FOR CROSS REFERENCE TABLE
This is done with a line in the \fIlistfile\fP. This line consists of the
symbol \fB+\fP followed by letters which indicate types of identifiers to
be included in the cross reference table. Default is all types, except
parameters in extern function declarations. The types are:
.TP
\fBT\fP
Names that are typedef-d.
.TP
\fBt\fP
Names that are types.
.TP
\fBF\fP
Names of functions being defined.
.TP
\fBC\fP
Names of function being called.
.TP
\fBD\fP
Names of identifiers being declared.
.TP
\fBR\fP
Names of identifiers being referenced (used).
.TP
\fBd\fP
Names of parameters in an extern function declaration.
.TP
\fBM\fP
Macro names being defined.
.TP
\fBm\fP
Names being referenced in a preprocessor directive.
.TP
\fBN\fP
Constant being defined in an enum list.
.TP
\fBE\fP
Names of extern variables.
.SH SUPPORTED PRINTERS
Three types of output-device are currently supported.
The actual type is determined at compile-time.
Adding support for other printers should not be very
difficult for programmers with sufficient determination.
.TP
\fBPostScript\fP tm
Adobe's page makeup language. This can be printed on PostScript printers
and with the use of the \fBgs(1)\fP program on many other devices. An
attempt is made to activate duplex (double-sided) printing.
.TP
\fBHP-LaserJet\fP
Should work on most HP laser printers. This has been tested on the
LaserJet IID and the LaserJet IIISi printer. On printers that are equipped
with the right gears and rollers (this is an option on some models) duplex
(double-sided) printing is activated.
.TP
\fBHP-DeskJet\fP
Works on the DeskJet 500 printer but not on many later models.
It also gives good (preview) results when displayed with recent versions
of the \fBless(1)\fP program in very wide (180 column) xterm windows.
\fBLess\fP version 290 is recent enough.
.SH FORMAT OF THE TAGFILE
The \fItagfile\fP consists of one line for each name that was found in the
source listings. The order in which the names appear is identical to the
order in which the parser found them in the source files. If a word appears
several times on one source line, it will appear several times in the
\fItagfile\fP (but only once in the cross reference table). Each line in
the \fItagfile\fP consists of 3 fields separated by a tab character.
.TP
\fBlinenumber\fP
The line number (where the name can be found in the source listings part of
the output of \fBcdg\fP). The \fBlinenumber\fP occupies 6 positions; leading
spaces are used.
.TP
\fBtype\fP
The type of the object that the name refers to (see the list in the section
\fISelecting types for cross reference table\fP above).
.TP
\fBname\fP
The name of the object (truncated to 80 characters).
.SH LIMITATIONS
.TP
\fB-\fP
Only files with names ending on \fB.c\fP, or \fB.h\fP are cross-referenced.
However, other files will be included in the listing.
.TP
\fB-\fP
All source files must have balanced braces, parentheses and brackets. Certain
constructions with \fB#ifdef\fP, \fB#else\fP and \fB#endif\fP that violate
this restriction should be rewritten anyway. If the \fBindent(1L)\fP program
likes the source files, there is a good chance that \fBcdg\fP will like them
too.
.TP
\fB-\fP
The number of lines in the listing section must be less than 999.900
(the number of lines in each individual file is rounded up to the
next multiple of 50), because no linenumber may exceed 6 digits and no
page number may exceed 4 digits.
.TP
\fB-\fP
Identifiers longer than 58 characters will be truncated in the cross reference
listing. Identifiers longer than 80 characters which are identical in the
first 80 characters are treated as one and the same for the cross
reference table.
.TP
\fB-\fP
The method used to identify the type of a word is not perfect. This is
caused by the fact that the parser examines each file separately and
does not examine any #include-d files, nor learn any type-names. There is
(at least) one case where the parser can not be sure whether a word is an
identifier or a type. In
.br
\fB(\fP\fIword\fP\fB) - \fP\fIexpression\fP
.br
the parser will assume that \fIword\fP is a type and the minus is the negation
operator. The other solution (not taken) is that \fIword\fP is a parenthesized
expression (where the parentheses are apparently redundant) and the minus is
the subtraction operator. For the cross reference table the choice is
irrelevant (provided that both types are included or both are excluded).
If you use the \fItagfile\fP option to preserve the list of identifier tags
you should be aware of this problem.
.TP
\fB-\fP
All filenames must be no longer than 41 characters and may not contain spaces,
tabs, etc.
.TP
\fB-\fP
The C-parser of \fBcdg\fP treats ANSI C-prototypes exactly like function
definitions; there is currently no way to exclude only the C-prototypes
from the cross reference table.
.TP
\fB-\fP
All identifiers appear in the \fItagfile\fP, even those that should be excluded
according to the \fIlistfile\fP. However for each excluded word there is
an extra entry at the beginning of the \fItagfile\fP of type \fBX\fP and
with linenumber \fB0\fP.
.TP
\fB-\fP
Printer selection must be done at compile-time.
.TP
\fB-\fP
A4-size paper is assumed for all printers except PostScript.
.TP
\fB-\fP
To sort the identifier tags \fBcdg\fP invokes the \fBsort(1)\fP program.
Therefore \fBsort\fP must be in the search-path. This use of an external
program will make it a bit harder to port \fBcdg\fP to other operating systems.
.SH FILES
All the files mentioned here are automatically removed when the program exits,
except the \fItagfile\fP if an alternate name was specified on the command
line.
.TP
/tmp/cdgL*
The source listing (with numbered, broken lines). Each source file
is preceded by one line that contains a dash followed the name of the
next source file, two spaces and the modify-date and -time of the file.
.TP
/tmp/cdgT*
The list of all identifier tags (unless overridden by the \fItagfile\fP
option).
.TP
/tmp/cdgS*
The sorted list of all identifier tags.
.SH REVISION HISTORY
The initial version (0.0) was written by Peter Knoppers
<[e-mail]> during the Xmas holidays of December 1995,
except for the lexical scanner which was derived from a public domain
C-parser written 10 years earlier by Scott Lee.
.br
Adding PostScript and HP-LaserJet printer output and fixing some errors
in the recognition of enums increased the version number to 1.0 in
January 1996.
.br
In August 1996 version 1.1 was made public. This version fixed a few
bugs in the parse and the scanner. Support for US Letter sized paper
was added (but only for PostScript printers). An attempt is made to
activate double-sided printing on PostScript printers. This may not
work for all PostScript printers.
.SH DISTRIBUTION
The most recent version of \fBcdg\fP can be found through a link on Peter
Knoppers' WWW home-page which is (currently) located at URL:
.br
http://cardit.et.tudelft.nl/~knop
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.