NAME

src2html - Hyperlink a C source code tree using HTML, Version 1.3-alpha

SYNOPSIS

src2html [ -na ] [ -nl ] [ -d debug_level ] configuration_file

DESCRIPTION

src2html is a program which takes a C source tree and creates a set of HTML hypertext documents that allows the most important symbols in the source tree to be found easily. As well, a HTML version of the source tree is created, with the symbols given in bold font where they are defined in the source. src2html finds and hyperlinks the following C symbols: Preprocessor defines and macros, C functions, global variables, structs, unions, enums and typedefs. If defined in the configuration file, a query document is used so that symbols can be located by an index query as well as following the hyperlinks.

OPTIONS

The debug level was used when debugging the program, and its only use is to assure the user that something is actually happening, especially for large source trees. The highest debug level of 3 is not particularly verbose.

By default, src2html produces html pages for each category of C symbols. If there are more than 50 in each category, src2html then further subdivides the symbols on a first-letter basis, making HTML documents for each letter.

If the -nl flag is set, no first-letter HTML documents will ever be produced. Similarly, src2html creates a top-level document with category links. If the -na flag is set, no top-level category links will be produced.

CONFIGURATION FILE

src2html takes as an argument a configuration file which describes the directories in a source tree to process, and where to place the resulting HTML documents. Lines beginning with a # sign are ignored, as are blank lines. The following lines have special meaning:
set Srctree source_tree
Set the root of the tree where the original source is kept, e.g /usr/src/sys. Do not leave a trailing slash on the tree name. This line must appear in the configuration file.
set Htmlroot html_tree
Set the root of the tree where HTML documents are normally kept. This is the same as DocumentRoot in the httpd(1L) configuration. Again, do not leave a trailing slash on the tree name. This line must appear in the configuration file.
set Htmldir html_dir
Set the directory within Htmlroot where the HTML documents for this tree will be placed. Again, do not leave a trailing slash on the tree name. This line must appear in the configuration file.
set Newsrctree new_source_tree
Set the directory within the Htmltree where the marked up source code is placed, e.g src. This allows the source to be kept separate from the `pointer' documents which point at the source; see the next section for more details. This line is optional, and the default value of Newsrctree is `newsrc'.
set Headers header_dir
src2html allows information to be placed at the beginning of the HTML documents created, e.g to describe the contents of a particular subdirectory. Files containing this information are kept in this directory. This line is optional, and the default value of Headers is `.'.
set Formdir form_dir
If set, this tells src2html that the active HTML document which can perform index lookups for the source tree is located in this directory. If not set, src2html will not put query boxes in the HTML documents created. This line is optional, and there is no default value.
dir directory comments_about_the_dir
This line may appear may times, and tells src2html to process source files in the directory Srctree/dir. This allows only particular sections of the source tree to be marked up. The comments after the directory are placed in the top-level HTML document to explain what that directory contains.

DIRECTORY STRUCTURE

src2html expects to be given a source tree to process, and it produces a new tree with HTML documents. The configuration file should have a suffix of `.s2h', although this is strictly not needed. As an example, consider the following configuration file named BSD.s2h: 

# Comments
set Srctree /usr/src/sys
set Htmltree /usr/local/WWW
set Htmldir sys
set Newsrctree newsrc				# Comments here too
set Headers /home/staff/warren/sys_headers
set Formdir /cgi
dir kern        The core OS routines: processes, scheduling, syscalls
dir sys         Widely used C-language include files
dir i386/isa    Device drivers for peripherals on the ISA bus

Three directories containing C source will be processed, 

	/usr/src/sys/kern,
	/usr/src/sys/sys and
	/usr/src/sys/i386/isa
The resulting marked up source code will be placed in 
	/usr/local/WWW/sys/newsrc/kern,
	/usr/local/WWW/sys/newsrc/sys and
	/usr/local/WWW/sys/newsrc/i386/isa
respectivey.

The directory /usr/local/WWW/sys will itself contain a set of pointer documents which point to the source code documents on a per-directory, per-symbol-type and per-first-letter basis (and combinations of the above). One file, BSD.html (named from the configuration file name), is the root of the hyperlinks, and the entire source tree can be browsed from this one document.

HEADER FILES

src2html creates a root HTML document, and HTML documents for each directory named in the configuration file. Textual information can be placed in the head of these documents to describe the contents of the tree/directory, give references etc. The files that hold this information are kept in the Headers directory. Taking the above configuration file as an example, /home/staff/warren/sys_headers/BSD.hdr /home/staff/warren/sys_headers/kern.hdr /home/staff/warren/sys_headers/sys.hdr /home/staff/warren/sys_headers/i386.isa.hdr can hold the information to be placed in the head of the appropriate documents. Note that if a directory name has a slash as given in the configuration file, the name of the header file has a dot instead.

Header files are placed `as is' into the head of the document, and thus can contain HTML markup commands. Any and all header files are optional; if the file does not exist, nothing will be placed in the head of the appropriate HTML document.

Once src2html has completed, the header files may be removed. However, you may wish to keep them in case you ever need to re-run src2html on the same source tree.

SEARCH SCRIPT

During execution, src2html builds a ctags directory in Htmltree and places the output of ctags-new(1L) on the source tree directories in this place. This information is needed if a search script is also requested.

If the Formdir is set in the configuration file, src2html will configure the HTML code produced to use the search script src2html.cgi to search for symbols in the source tree. This script conforms to the cgi query format as used by httpd(1). You must move the supplied src2html.cgi file into the Formdir in the httpd hierachy before the query functionality can be used.

Again, from the example configuration file above, /usr/local/httpd/cgi/src2html.cgi is where to place the script, if the httpd hierachy is kept in /usr/local/httpd.

EXAMPLE SOURCE TREE

The output from src2html for the full FreeBSD 2.0.5 kernel source directory can be browsed from the Web page http://minnie.tuhs.org/FreeBSD-srctree/FreeBSD.html.

BUGS AND SHORTCOMINGS

src2html uses the ctags-new(1L) program, which does not correctly parse C variable declarations and function pointer usage. Someone should rewrite this in Perl.

Ideally, src2html should include hyperlinks within each source file, but this is difficult given C's scoping rules, and would need a more sophisticated parser than ctags(1L).

src2html looks at all files in the named source directories, including files that don't end in .c and .h. This may be construed as a feature.

SEE ALSO

ctags-new(1L), httpd(1L), perl(1L)

AUTHOR

Warren Toomey wkt@tuhs.org