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