src2www: Source code to web pages
(Last changed 25 June 1996)
Description:
These programs take source code as input, and produce formatted listings
in html. The provided scripts also produce alphabetical indexes of declarations,
within each file and for a set of files. They do not indent source code.
src2www produces web documents for Ada83, Ada95,
Ansi C, Csh scripts, and some simple C++.
See also src2fm for producing FrameMaker documents.
You may also want to browse a list of other
filters that produce html from source code, especially if you program
in C++.
Recent changes
Versions 0.9g&h of June 1996: A long-overdue enhancement with numerous fixes, plus support for embedded images in comments.
Try it
on your own source code
if your browser has file-upload capability as specified
in RFC 1867.
Index
Features:
- Keywords and comments are set off by fonts. Netscape users will also
see declarations in a larger font. The quality of formatting is severely
limited by HTML version 2, and will improve when CSS1 stylesheets are widely
supported.
- The provided scripts build alphabetical indexes of functions and classes
(for C) and functions, procedures, packages, tasks, and types (for Ada).
- Line numbering (every n lines, you specify n) in the
left margin.
Status:
Beta release --- some bugs fixed, but there are probably more.
See also known problems.
Requirements:
src2www runs on the Unix operating system; they have been tested on Sun
Sparcstations under Solaris2 (a SysVoid), and should run under other Unix
operating systems. I do not have resources to port src2fm to Mac, Windows/Dos,
VMS, or other non-Unix platforms at this time. I am happy to provide advice
and what help I can to anyone who wants to do their own port to a non-Unix
platform.
Building the binaries requires Gnu make, flex and gcc from FSF. The scripts
make heavy use of the new version of awk as described in the book, "The
Awk Programming Language." This version of awk is implemented by gawk
from FSF, and is also packaged as "nawk" or "v7awk"
with some Unix systems. The command named "awk" is often NOT
the new version. (A good Perl programmer could probably translate these
all to Perl in about an hour.)
Availability
This is free software. Full source code is available. The current version
is 0.9h. (Version numbers are synchronized with src2fm, but new versions
are not always released simultaneously). Changes occur irregularly but frequently
--- feedback from users typically results in at least some small improvements
or corrections within a week or two.
Version
0.9g, the almost current version. This is a source distribution. It doesn't properly title the global index page.
Version
0.9h, the really current version, it is just a small bug fix after 0.9g.
(I will remove 0.9g when I am sure the small bug fix didn't result in some bigger bug.) This is a source distribution.
Version
0.9e, an older version, just in case of problem with 0.9g.
Note: These are compressed tar files. Versions 0.9g and 0.9h are
compressed with Gnu zip, version 0.9e is compressed with the Unix
compress utility. A typical command for unpacking them on a Unix workstation is
zcat src2www-0.9g.src.tar.gz | tar xvf -
This source code has not been prepared for
dos/windows or mac environments.
Send mail to request a different version or configuration,
or to request help. I also appreciate a note just to tell me if you find
the software useful (or to tell me why you don't).
Bugs and problems
- Different versions of software tools (especially nawk) can cause unpredictable
results. (Gawk seems to be more consistent, but not everyone has it.) If
you get an error message indicating that awk doesn't understand the -v option,
your version of awk (or nawk) is too old and hypertext index generation
will not work.
- Version 0.9g has a new configuration scheme in which an awk script
rewrites the shell scripts. A buggy implementation of awk can really mess
things up now, and in alpha testing an old SunOS awk completely wiped out
the scripts. This particular bug now has a workaround, but I won't be surprised
if there are more.
Plans and wish list
- Use external cross-reference tools to produce cross-linking from uses
to definitions. Although this is a high priority, I want to do it in a way
that is not excessively bound to a particular language and cross-reference
tool. (See David Wheeler's ada2html tool for a language & compiler-dependent
solution.)
- Image maps for a graphical index based on file dependencies. There
is an internal version of this working now, but it is too fragile and crufty
to distribute yet. More sophisticated birds-eye and fish-eye views are also
in the works, but this is very experimental and it is not yet possible to
say when some useful map generators may be available for distribution.
- Use user-customizable style sheets, in place of the <PRE> tag
with presentational markup. This should happen within a few months, as both
Netscape and Microsoft have announced they will implement CSS1 stylesheets.
- Replace the hand-written flex front-ends with a higher level lexical
specification, in the spirit of vgrind and tgrind. This is important, but
definitely non-trivial; in fact the vgrind recognition rules are not quite
powerful enough for the job.
- Optionally map file names to 8+3 characters, for DOS-based servers
and some CD rom formats. (Now that even Windoze permits decent file names,
this is a low priority.)
Thanks to the following people for making
src2www better through their criticism, suggestions, and bug fixes:
- Sjoerd Zwart, Philips Semiconductors B.V.
- David Wheeler, Institue for Defense Analysis
- Peter Constantinidis, Sybase
- Umeed Kothavala, Purdue
Contact me
Please send email to michal@cs.uoregon.edu
- To let me know that you have obtained the software.
- To request help with obtaining, installing, or using the software,
or to make comments and suggestions, or to complain.
Michal
Young