ctoohtml: a c/C++ to HTML filter

Version 1.3

This c/C++ to HTML filter came out of several desires/needs:

The desire to automatically take c or C++ code and add HTML anchors so that hyperlinks within the code or from other documents can point to specific points (e.g. to function or data type definitions).
The desire to automatically generate hyperlinks from within the code (e.g. a function call) to the point at which the element is defined (the function implementation).
Do all this without placing any additional requirements on the programmer (ie the programmer should just write C++).
Do this quick so I can get on with my real work.

Why another filter?

There are already several programs out there for C++ to HTML 'conversion' (c++2html, c++2html, cxx2html, and ctohtml). In general, the above requirements are not satisfied - the first 3 either operate only on header files or their use requires work on the programmer's part; the latter (ctohtml) comes the closest, but is mimimal.

Because the c**2html name is already heavily overloaded, I call mine ctoohtml.

Usage: ctoohtml [-<parm>[<value>]]* <sourcefile>+

For each sourcefile (e.g. foo.c), a corresponding HTML file is generated (foo.c.html).

Within each html file:

Every tag (struct or class defintion, #define, and function definition) is anchored, so that it may be referenced externally.
All references to the tags within the source files are hyperlinked to the corresponding locations.

Other Features

HTML markup may be inserted directly into the C or C++ code. Instead of using '<' and '>' markup indicators, use '[<' and '>]'.
A file named files.html is generated with a list of all source files. Use the -t option to control the title of this file.
A file named tags.all.html is generated that contains a sorted list of all tags found in the source files. Use the -a option to set the title of this file.
A file named tags.file.html is generated that contains the same information as tags.all.html, except the tags are sorted by source file. Use the -f option to set the title of this file.
Supports NSL (Neural Simulation Language) RUN_MODULE and INIT_MODULE constructs. Use the -n option to activate this mode.

Command Line Parameters

    Parameter	Description
    ---------   ----------------------------------------------------
	a	Title/Header for the tag index (tags.all.html)
				default = "All Tags Found in Source Files"

	C	Indicates that .c and .h files are C++ and not c.
				default = assumes c

	d	Debug mask
				default = 0

	f	Title/Header for the tag index sorted by source file 
      				(tags.file.html)
				default = "Tags Sorted By Source File"

	h	Arbitrary string used for the hyperlink defined by 'p'
				default = "Project Description"

	n	Activates support for NSL (Neural Simulation Language)

	p	Arbitrary URL that points to a project description
				This hyperlink is placed at the top of each
    				source file.
				no default 

	t	Title/Header for the source file index (files.html)
				default = "Source File Index"

	z	Destination directory for the html files.
				default = local directory.

Debug Mask

      Mask	Meaning
      -----	------------------------------------------------
	1	Display list of tags.
	2	NSL debugging flag.
	4	Reports the identity and type of tags that are found
			in the TAGS file.
	8	Don't delete temporary TAGS file.

Note that masks may be ORed together.

Example Usage

ctoohtml -C -n \
   -p"file://localhost/home/mensa/af0a/notepad/projects/hfsp/index.html"\
   -h"RS Model V4.0" -zhtml *.c *.h

This call to ctoohtml processes all local .c and .h files:

-C indicates that this is C++.
-n turns on special processing for NSL.
-p"file:..." defines the project URL that is placed at the top of each source file.
-h"RS Model..." defines the text header to be used at the top of each source file.
-zhtml tells ctoohtml to put the results in the directory html/

In-Source Directives

Source files may also contain special directives understood by ctoohtml (at this time there is only one, though):

[DEFINE DESCRIPTION = <strg>]

where <strg> is a string that describes the contents of the file. This string is used in generating the source index file (files.html) - each file that is listed in the index is accompanied with its description (if one is defined).

Development History

Assumptions

Overloaded tags occur in separate files.
Tag names are alphanumeric [a-zA-Z_0-9], and in cases of class destructor functions, may start with a '~'.

Caveats

The perl code is still pretty messy.
Runs pretty slow for large files (7000 lines of code takes about 30 minutes on a sparc IPX) (I refer you to requirement #4).
Input files cannot be specified using the standard unix "~" designator.

Requirements

perl-4.0 (no guarantees for 5.0)
etags (from the gnu emacs version 19.22 or better)

Grabbing and Installation

Grab Version 1.3
Edit files ctoohtml and ctoohtml.pl so that they point to the location of perl and etags on your local machine.
Filter code!

Bug Reports

Bug reports may be sent to af0a@robotics.usc.edu. They will be carefully considered and most likely (but politely) ignored until November or December.

Version 1.2.1

Jerome Chouinard from Ecole Polytechnique de Montreal has expanded Version 1.2 to handle:

incremental processing of a set of files.
separate indices for libraries.

My plan is to incorporate these new features in V 2. For the time being, however, his original changes are available here:

Jerome's notes on the changes that have been made.
ctoohtml.v.1.2.1
Extensive documentation by Jerome (in French).

Note that some of the parameters have changed and that this version expects a very explicit file structure. If you want the version that corresponds to the documentation below, then you should download v.1.3 (I do not provide tech support for v.1.2.1).

Most recent version of this document.

Andrew H. Fagg
University of Southern California
Computer Science Department
Robotics Research Laboratory and Center for Neural Engineering