Documentation for C++ and Beyond

Writing documentation for a large ``C++'' project without a proper tool can be a daunting task. Unable to find a tool I liked, I decided to write my own, based on the following guidelines:

d4c&b main objective is to let you write both user guide (i.e system documentation) and source documentation, and easily cross reference between the two.

d4c&b generates an on-line document. Currently only HTML is supported, but since it's underlying language is a variant of texinfo, other output formats (from the same source) are possible.

d4c&b output is not fancy, and will not impress your manager. However, if it's a matter of font, size, or color, you might find a configuration option to change it. Personally, I find d4c&b mix of text, mathematical equations and simple figures [1] adequate, but your mileage may vary.

After reading the rest of this page, I suggest you take a quick stroll in src/d4cab to get a feeling what d4c&b output for ``C++'' looks like. Then read doc on how to write d4c&b documentation, and finally have a look at some of the source itself.

Netscape setup for reading d4c&b pages

To view equations and special symbols, You need to fool Netscape into believing the symbols font is an iso8859-1 font. On Unix, you can try copying fonts.alias to your `fonts.alias' file, or create a new `fonts.alias' file in some local directory dir and add `xset fp+ dir' to your `.xinitrc' file.

Make sure document specific fonts are enabled. In my Netscape, it is under Edit|Preferences|Fonts.

If that doesn't work, try Enabling Symbol Fonts in Netscape under X for other suggestions.

d4c&b version (pre alpha)

d4c&b is only in it's early stages, but is useful even in this initial form.

Do not let the presence of a configure script lull you into a false sense of security. d4c&b has only been tested on one operating system (Solaris 2.6) and one compiler (gcc 2.95).

An irritating g++ bug

Unfortunately, a bug in gcc/egcs libio results in an d4c&b infinite loop. While I reported this bug several time since Aug, 1997, and I included the simple fix, nothing was done.

d4c&b will use a workaround when this bug is detected, but if you have access to gcc, you might as well fix it.

Obtaining d4c&b

Right now, you will have to download using the cvs access at SourceForge Logo

Compiling and installing d4c&b

Assuming you want to install everything in one place.

  1. Install modified flex

    From the top dirsctory,

    d4cab> cd packages/flex-2.5.4
    d4cab/packages/flex-2.5.4> configure --prefix=target-directory
    d4cab/packages/flex-2.5.4> gmake install
    d4cab/packages/flex-2.5.4> gmake distclean
    
  2. Install tth

    d4cab> cd packages/tth_C
    d4cab/packages/tth_C> gmake
    d4cab/packages/tth_C> mv tth target-directory/bin
    
  3. Compile and Install d4c&b

    d4cab> cd d4cab
    d4cab/d4cab> autoconf
    d4cab/d4cab> setenv ...
    d4cab/d4cab> configure args --prefix=target-directory
    d4cab/d4cab> gmake
    
    You can have a look at the top `GNUmakefile' as an example.

  4. Generate d4c&b documentation as a test

    d4cab/d4cab> gmake docdirs
    d4cab/d4cab> gmake docregendirs
    
    The second run is needed only the first time, since the makefiles are set to generate documentation on a per directory basis, so a second run is required to resolve the cross references.

    Later I might add a makefile target which will require just one pass.


1. via a modified TKdraw and the tcl plugin