forked from Imagelibrary/rtems
New files
This commit is contained in:
Joel Sherrill
244
doc/tools/src2html1.4a/src2html.1
Normal file
244
doc/tools/src2html1.4a/src2html.1
Normal file
@@ -0,0 +1,244 @@
|
||||
.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
|
||||
Reference in New Issue
Block a user