mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2025-12-05 15:15:44 +00:00
245 lines
7.8 KiB
Groff
245 lines
7.8 KiB
Groff
.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
|