diff options
Diffstat (limited to 'doc/tools/src2html1.4a/src2html.1')
| -rw-r--r-- | doc/tools/src2html1.4a/src2html.1 | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/doc/tools/src2html1.4a/src2html.1 b/doc/tools/src2html1.4a/src2html.1 new file mode 100644 index 0000000000..7401859ca8 --- /dev/null +++ b/doc/tools/src2html1.4a/src2html.1 @@ -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 |