source: rtems/doc/tools/src2html1.4a/src2html.1 @ 52461c5

4.104.114.84.95
Last change on this file since 52461c5 was 52461c5, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 14, 1998 at 4:03:45 PM

New files

  • Property mode set to 100644
File size: 7.8 KB
Line 
1.TH src2html 1L "June 1994"
2.SH NAME
3src2html \- Hyperlink a C source code tree  using HTML, Version 1.3-alpha
4
5.SH SYNOPSIS
6.B src2html
7[
8.I \-na
9] [
10.I \-nl
11] [
12.I \-d debug_level
13]
14.I configuration_file
15
16.SH DESCRIPTION
17
18.B src2html
19is a program which takes a C source tree and creates a set of
20HTML hypertext documents that allows the most important symbols in the
21source tree to be found easily. As well, a HTML version of the source
22tree is created, with the symbols given in bold font where they are defined
23in the source.
24
25.B src2html
26finds and hyperlinks the following C symbols: Preprocessor defines
27and macros, C functions, global variables, structs, unions, enums and typedefs.
28If defined in the
29.I configuration file,
30a query document is used so that symbols can be located by an index query
31as well as following the hyperlinks.
32
33.SH OPTIONS
34The
35.I debug level
36was used when debugging the program, and its only use is
37to assure the user that something is actually happening, especially for large
38source trees. The highest debug level of 3 is not particularly verbose.
39.PP
40By default,
41.B src2html
42produces html pages for each category of C symbols. If there are more than
4350 in each category,
44.B src2html
45then further subdivides the symbols on a first-letter basis, making HTML
46documents for each letter.
47.PP
48If the
49.I -nl
50flag is set, no first-letter HTML documents will ever be produced.
51Similarly,
52.B src2html
53creates a top-level document with category links. If the
54.I -na
55flag is set, no top-level category links will be produced.
56
57.SH CONFIGURATION FILE
58
59.B src2html
60takes as an argument a
61.I configuration file
62which describes the directories in a source tree to process, and
63where to place the resulting HTML documents. Lines beginning with a #
64sign are ignored, as are blank lines. The following lines have special meaning:
65.P
66.IP "set Srctree source_tree"
67Set the root of the tree where the original source is kept, e.g
68/usr/src/sys. Do not leave a trailing slash on the tree name.
69This line must appear in the configuration file.
70.P
71.IP "set Htmlroot html_tree"
72Set the root of the tree where HTML documents are normally kept.
73This is the same as DocumentRoot in the httpd(1L) configuration.
74Again, do not leave a trailing slash on the tree name.
75This line must appear in the configuration file.
76.P
77.IP "set Htmldir html_dir"
78Set the directory within Htmlroot where the HTML documents for this
79tree will be placed.
80Again, do not leave a trailing slash on the tree name.
81This line must appear in the configuration file.
82.P
83.IP "set Newsrctree new_source_tree"
84Set the directory within the Htmltree where the marked up source code
85is placed, e.g src. This allows the source to be kept separate from the
86`pointer' documents which point at the source; see the next section for
87more details. This line is optional, and the default value of
88Newsrctree is `newsrc'.
89.P
90.IP "set Headers header_dir"
91.B src2html
92allows information to be placed at the beginning of the HTML
93documents created, e.g to describe the contents of a particular
94subdirectory. Files containing this information are kept in this
95directory. This line is optional, and the default value of
96Headers is `.'.
97.P
98.IP "set Formdir form_dir"
99If set, this tells
100.B src2html
101that the active HTML document which can
102perform index lookups for the source tree is located in this
103directory. If not set,
104.B src2html
105will not put query boxes in the
106HTML documents created. This line is optional, and there is no
107default value.
108.P
109.IP "dir directory comments_about_the_dir"
110This line may appear may times, and tells
111.B src2html
112to process
113source files in the directory Srctree/dir. This allows only particular
114sections of the source tree to be marked up. The comments after the
115directory are placed in the top-level HTML document to explain
116what that directory contains.
117
118.SH DIRECTORY STRUCTURE
119
120.B src2html
121expects to be given a source tree to process, and it produces
122a new tree with HTML documents. The configuration file should have a suffix
123of `.s2h', although this is strictly not needed.
124
125As an example, consider the following configuration file named BSD.s2h:
126.PP
127.nf
128# Comments
129set Srctree /usr/src/sys
130set Htmltree /usr/local/WWW
131set Htmldir sys
132set Newsrctree newsrc                           # Comments here too
133set Headers /home/staff/warren/sys_headers
134set Formdir /cgi
135dir kern        The core OS routines: processes, scheduling, syscalls
136dir sys         Widely used C-language include files
137dir i386/isa    Device drivers for peripherals on the ISA bus
138.fi
139.PP
140Three directories containing C source will be processed,
141.nf
142        /usr/src/sys/kern,
143        /usr/src/sys/sys and
144        /usr/src/sys/i386/isa
145.fi
146
147The resulting marked up source code will be placed in
148.nf
149        /usr/local/WWW/sys/newsrc/kern,
150        /usr/local/WWW/sys/newsrc/sys and
151        /usr/local/WWW/sys/newsrc/i386/isa
152.fi
153respectivey.
154.PP
155The directory /usr/local/WWW/sys will itself contain a set of pointer
156documents which point to the source code documents on a per-directory,
157per-symbol-type and per-first-letter basis (and combinations of the
158above). One file, BSD.html (named from the configuration file name), is the
159root of the hyperlinks, and the entire source tree can be browsed from this
160one document.
161
162.SH HEADER FILES
163
164.B src2html
165creates a root HTML document, and HTML documents for each directory
166named in the configuration file. Textual information can be placed in the
167head of these documents to describe the contents of the tree/directory,
168give references etc. The files that hold this information are kept in the
169Headers directory. Taking the above configuration file as an example,
170
171        /home/staff/warren/sys_headers/BSD.hdr
172        /home/staff/warren/sys_headers/kern.hdr
173        /home/staff/warren/sys_headers/sys.hdr
174        /home/staff/warren/sys_headers/i386.isa.hdr
175
176can hold the information to be placed in the head of the appropriate
177documents. Note that if a directory name has a slash as given in the
178configuration file, the name of the header file has a dot instead.
179.PP
180Header files are placed `as is' into the head of the document, and thus
181can contain HTML markup commands. Any and all header files are optional;
182if the file does not exist, nothing will be placed in the head of the
183appropriate HTML document.
184.PP
185Once
186.B src2html
187has completed, the header files may be removed. However,
188you may wish to keep them in case you ever need to re-run
189.B src2html
190on the same source tree.
191
192.SH SEARCH SCRIPT
193
194During execution,
195.B src2html
196builds a ctags directory in Htmltree and places
197the output of ctags-new(1L) on the source tree directories in this place.
198This information is needed if a search script is also requested.
199.PP
200If the Formdir is set in the configuration file,
201.B src2html
202will configure the HTML code produced to use the search script
203.I src2html.cgi
204to search for symbols in the source tree. This script
205conforms to the cgi query format as used by httpd(1). You must move the
206supplied
207.I src2html.cgi
208file into the Formdir in the httpd hierachy before the query functionality
209can be used.
210.PP
211Again, from the example configuration file above,
212/usr/local/httpd/cgi/src2html.cgi is where to place the script, if the
213httpd hierachy is kept in /usr/local/httpd.
214
215.SH EXAMPLE SOURCE TREE
216
217The output from
218.B src2html
219for the full FreeBSD 2.0.5 kernel source directory can be browsed
220from the Web page http://minnie.cs.adfa.oz.au/FreeBSD-srctree/FreeBSD.html.
221
222.SH BUGS AND SHORTCOMINGS
223
224.B src2html
225uses the ctags-new(1L) program, which does not correctly parse C variable
226declarations and function pointer usage. Someone should rewrite this in Perl.
227.PP
228Ideally,
229.B src2html
230should include hyperlinks within each source file,
231but this is difficult given C's scoping rules, and would need a more
232sophisticated parser than ctags(1L).
233.PP
234.B src2html
235looks at all files in the named source directories, including
236files that don't end in .c and .h. This may be construed as a feature.
237
238.SH SEE ALSO
239.PD
240ctags-new(1L), httpd(1L), perl(1L)
241
242.SH AUTHOR
243.PD
244Warren Toomey   wkt@cs.adfa.oz.au
Note: See TracBrowser for help on using the repository browser.