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

   src2html - Hyperlink a C source code tree using HTML, Version 1.3-alpha

             Warren Toomey      wkt@cs.adfa.oz.au       June 1995


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.


REQUIREMENTS

You will need:

        + Perl 4.x
        + a standard Unix sort(1) command.
        + a mkdir(1) that supports recursive creation of directories.
          src2html is configured to use `mkdir -p' to do this.
        + an egrep(1) if you're going to use the search facility.
        + httpd(1) if you're going to use the search facility.
        + Ctags-new, which is bundled with src2html, and a C compiler
          to compile it.


INSTALLATION

Extract the src2html archive, including the Ctags-new and Example directories;
you probably have already done that. Go into the Ctags-new directory and make
ctags-new. This should be very straight-forward.

Install ctags-new and src2html in a directory on your path, make them
executable and install their man pages as well. If your mkdir(1) uses a
different option to -p, edit src2html to fix this.

If you want to use the search facility, you need to install src2html.cgi
in your httpd script directory, and edit it to reflect the root of your
HTML documents, as set in DirectryRoot in conf/srm.conf.

Make sure that ctags-new, src2html and src2html.cgi are executable, and
that the latter two can find the Perl interpreter. Installation is complete.


USING SRC2HTML

Using src2html is pretty straight-forward. Print out and read the man page
before trying anything. In the FreeBSD directory I have included the config
file and header files for my src2html conversion of the FreeBSD-2.0.5 source
tree; read the man page and FreeBSD/FreeBSD.s2h in tandem. The root document of
this HTML tree is at http://minnie.cs.adfa.oz.au/FreeBSD-srctree/FreeBSD.html.


COMMENTS AND QUESTIONS

Surprisingly, src2html is reasonably fast even on large source trees. This was
my first Perl program, so it could probably be made faster and smaller. I've
placed comments in the source to give you an idea of what each section does. If
you have any questions or comments, please email them to me at
wkt@cs.adfa.oz.au. Now that it's finished I'm not that keen on overhauling it
etc. I consider it as a good prototype. Getting inter-source hyperlinks done
would be great, but I really don't want to write a C parser myself.

Cheers,
        Warren Toomey