One of the most difficult tasks in creating extensive hypertext is generating the initial documents and providing an easy way to link to them. The doctext [(ref doctext)] program can be used to generate versions of Unix-style man pages from the C source code of routines. This program can generate nroff (for using man and xman), LaTeX (for generating printed manuals), and HTML. For the HTML to be useful, there must be an easy way to create links to the generate documents. This section describes how to do that; doctext itself is documented in [(ref doctext)].
To generate HTML man pages of a collection of source files in
/home/me/foo,
do the following:
cd
mkdir www
mkdir www/man3
cd foo
doctext -html -index ../foo.cit \
-indexdir http://www.mcs.anl.gov/me/foo/www/man3 \
-mpath ../www/man3 *.[ch]
cd ..
This puts the HTML files into the directory www/man3 and the index (in
the correct format for -mapman) into file foo.cit. Once you are
sure that the files are correct, you can move them into the Web area with
cp -r www /mcs/www/home/me(assuming that /mcs/www corresponds to http://www.mcs.anl.gov in the -indexdir argument).
To generate an HTML listing of the routines, you can execute the following
script, with, of course, the appropriate text:
#! /bin/sh
echo '<TITLE>Web pages for My Routines</TITLE>' >> www/index.html
echo '<H1>Web pages for My Routines</H1>' >> www/index.html
echo '<H2>My Routines</H2>' >> www/index.html
echo '<MENU>' >> www/index.html
ls -1 www/man3 | \
sed -e 's%^\(.*\).html$$%<LI><A HREF="man3/\1.html">\1</A>%g' \
>> www/index.html
echo '</MENU>' >> www/index.html
If you have only a few routines to document, you can dispense with the second
directory level above (the man3). However, you might find it valuable
to follow (at least loosely) the Unix man-page format, with commands and
installation instructions in man1 and routines spread across
man1 to man8.