readme

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

If you can read this, you probably succeeded in unpacking the sources
of cdg, the C-source Documentation Generator.

WHAT CDG DOES.

Cdg reads a set of C-source files and generates a two-column listing
of those sources where all lines are numbered. After the listing part
comes a three-column cross-reference table which gives for each iden-
tifier a list of line-numbers where this identifier occurs in the
source listing part.

WHO NEEDS CDG ?

You could use cdg if:
- you are trying to understand how a software package written by
  someone else works and you find yourself searching all over the
  sources for places where certain identifiers are used or defined.
- you are creating documentation of a software package.

REQUIREMENTS.

Cdg expects to run on a UNIX-like operating system. Though it should
be possible to port it to other environments.
Cdg can generate output for PostScript (tm) printers, HP LaserJet
(tm ?) printers or HP DeskJet (tm ?) printers. Using the ghostscript
program you can print PostScript output on other popular printers.

COMPILING AND LINKING CDG

1: Edit the Makefile and select the type of output (PostScript, HP
   LaserJet, or HP DeskJet). With PostScript printers you can also
   use US Letter sized paper. The -WALL compiler option is for gcc,
   the GNU C-compiler. Remove this option if you use another
   C-compiler and correct the CC macro to contain the name of your
   C-compiler. You may also have to add an option to let your compiler
   accept ANSI-C prototypes. If your C compiler does not accept ANSI
   prototypes you'll have to do some editing in most source files...
2: Let the make program build cdg.
3: Test cdg with the command
	cdg listfile > outputfile
   in the directory where you unpacked the sources.
4: Print (or preview) the outputfile and check it out.
5: Install the cdg program and the manual page in a place where other
   users can use it too.
That's it.

CREATING DOCUMENTATION OF A PROJECT

You must write a listfile for the project. The simplest listfile
consists of three empty lines followed by the names of the files
that are part of your project, one filename per line. You can include
non-C files, but these will not be cross-referenced. The files will
be listed in the order that you put them in the listfile.
The next step is to run cdg with the name of the listfile as the only
argument. You must redirect the standard output to a file, or printer
or to the ghostscript program. On the standard error cdg prints its
actions and possibly some warnings as it progresses.

For more info consult the manual page.

IF SOMETHING DOES NOT WORK.

This is mostly guesswork...

The compiler complains about the -Wall option.
	The Makefile works for gcc, the GNU C-compiler. Other compilers
	may require the use of other options.

You get lots of errors.
	Check if your C-compiler accepts ANSI-C prototypes. Many
	compilers require a flag to accept prototypes.

There is an error compiling the file datestr.c.
	This file is created by make in a way that depends on the
	of the programs ls, tail and sed. If any of these programs
	is missing or incompatible with the version I used, you may
	need to fix the Makefile, or create datestr.c by hand.
	Datestr.c should contain one line of the form
		char makedatestring[] = "Jan 12 22:46";
	The date and time should be the current date and time (when
	you are compiling and linking cdg).

There is an error concerning the file scan.c.
	Scan.c is generated using the lex or flex program. If you
	edit scan.l, make will try to re-generate scan.c. For those
	unfortunate users that don't have a compatible lex or flex
	program, a copy of the scan.c file is included in the
	distribution. These users should not touch the lexical
	scanner definition file scan.l.

The cdg program aborts with some runtime error message.
	All runtime error messages are self-explanatory... At least
	that is what I hope...

Your printer does not like the output of the cdg program.
	If your printer is one of the types I used I would be very
	surprised. If your printer is of a different type, you'll
	need to edit the printer control strings in the file page.c.
	You'll need good documentation of your printer for this task.

The output is badly positioned on the paper.
	The printer control strings were tested using A4 size paper.
	If your paper has different dimensions, you'll have to edit
	the printer control strings to reflect this. I never use
	paper other than A4 in my printer.
	Determining the printer control strings is a time-consuming
	affair...

WHAT IF IT STILL DOES NOT WORK ?

Read the man page again, carefully.

Try to fix it yourself. If that does not work email me with the
details. I can't promise to fix your problems, but I'll give it a
try.

REVISION HISTORY.

Version 1.3:
Flex seems to have changed even more than I thought. This resulted in
wrong linenumbers.
Removed my own declaration from scan.h and re-generated scan.c.

Version 1.2:
Fixed imcompatibility with newer version (?) of lex.
Replaced a few declaration of errno and friends by include <errno.h>.
Updated my email and www-page addresses.

Version 1.1:
Added a few missing operate-and-assign operators to the parser.
Fixed faulty EOF detection in scan.h
Added parsing of quoted chars in function macro in scan.h. (Parsing
  a quoted doublequote caused an infinite loop.)
Fixed a systematic error in the use of the "input" macro in scan.h.
Minor code cleanup in cdg.c and cdg.h.
Changed URL in man page to reflect my change of WWW server.
Fixed two typos in the man page (thanks to Larry W. Virden)
Use duplex printing for HP (and possible other) PostScript printers
  (thanks to Larry W. Virden)
Added US Letter paper size support (only for PostScript printers)
  (thanks to Larry W. Virden)
Fixed another error (unintended assignment inside an if statement)
  in parse.c (thanks to Larry W. Virden)
Changed the footer text specified in the demo-"listfile"
Fiddled with some control codes for DeskJet printers...
15-july-1998: updated my own email and www-page addresses.

TO DO
- Printer control codes for US Letter on non-PostScript printers.
  (I don't have US Letter sized paper, someone else will have to
  figure this out, or supply me some US Letter paper.)
- Printer control codes that work for the DeskJet 500 AND on other
  models.

CONTACT INFORMATION.

If you
- have a suggestion to make cdg more portable or more useful
- find a new case where the parser of cdg incorrectly identifies the
  type of an indentifier
- want to express admiration :-)
please contact me by email or ordinary mail.
--
Peter Knoppers <[e-mail]>
Snail mail:	Prins Mauritsstraat 17
		2628 SR  Delft
		The Netherlands