path: root/doc/tools/src2html1.4a/src2html.1

.TH src2html 1L "June 1994"
.SH NAME
src2html \- Hyperlink a C source code tree  using HTML, Version 1.3-alpha

.SH SYNOPSIS
.B src2html
[
.I \-na
] [
.I \-nl
] [
.I \-d debug_level
]
.I configuration_file

.SH DESCRIPTION

.B 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.

.B 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
.I configuration file,
a query document is used so that symbols can be located by an index query
as well as following the hyperlinks.

.SH OPTIONS
The
.I 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.
.PP
By default,
.B src2html
produces html pages for each category of C symbols. If there are more than
50 in each category,
.B src2html
then further subdivides the symbols on a first-letter basis, making HTML
documents for each letter.
.PP
If the
.I -nl
flag is set, no first-letter HTML documents will ever be produced.
Similarly,
.B src2html
creates a top-level document with category links. If the
.I -na
flag is set, no top-level category links will be produced.

.SH CONFIGURATION FILE

.B src2html
takes as an argument a
.I 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:
.P
.IP "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.
.P
.IP "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.
.P
.IP "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.
.P
.IP "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'.
.P
.IP "set Headers header_dir"
.B 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 `.'.
.P
.IP "set Formdir form_dir"
If set, this tells
.B src2html
that the active HTML document which can
perform index lookups for the source tree is located in this
directory. If not set,
.B src2html
will not put query boxes in the
HTML documents created. This line is optional, and there is no
default value.
.P
.IP "dir directory comments_about_the_dir"
This line may appear may times, and tells
.B 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.

.SH DIRECTORY STRUCTURE

.B 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:
.PP
.nf
# 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
.fi
.PP
Three directories containing C source will be processed,
.nf
	/usr/src/sys/kern,
	/usr/src/sys/sys and
	/usr/src/sys/i386/isa
.fi

The resulting marked up source code will be placed in
.nf
	/usr/local/WWW/sys/newsrc/kern,
	/usr/local/WWW/sys/newsrc/sys and
	/usr/local/WWW/sys/newsrc/i386/isa
.fi
respectivey.
.PP
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.

.SH HEADER FILES

.B 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.
.PP
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.
.PP
Once
.B src2html
has completed, the header files may be removed. However,
you may wish to keep them in case you ever need to re-run
.B src2html
on the same source tree.

.SH SEARCH SCRIPT

During execution,
.B 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.
.PP
If the Formdir is set in the configuration file,
.B src2html
will configure the HTML code produced to use the search script
.I 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
.I src2html.cgi
file into the Formdir in the httpd hierachy before the query functionality
can be used.
.PP
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.

.SH EXAMPLE SOURCE TREE

The output from
.B src2html
for the full FreeBSD 2.0.5 kernel source directory can be browsed
from the Web page http://minnie.cs.adfa.oz.au/FreeBSD-srctree/FreeBSD.html.

.SH BUGS AND SHORTCOMINGS

.B 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.
.PP
Ideally,
.B 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).
.PP
.B 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.

.SH SEE ALSO
.PD
ctags-new(1L), httpd(1L), perl(1L)

.SH AUTHOR
.PD
Warren Toomey   wkt@cs.adfa.oz.au