Welcome to ada2html, a tool developed by David A. Wheeler. Ada2html takes as input a set of Ada source files and generates (as output) a set of HTML (hypertext) files. These generated files are the Ada source files with a large number of hypertext links added to them, so users can walk around the Ada source using the hypertext links. The generated files also have Ada keywords bolded and comments italicized. You can view the resulting output using any HTML browser. For an example of the results, see program Small.
Ada2html requires Unix, perl, and gnatf to run. Gnatf is part of the freely-available GNAT Ada compiler. Unix is only required because of sorting commands, and might not be needed in a future version of this tool. You do not need any of those things to view the results, but you will need an HTML browser to view the results in the way they're intended.
Another, somewhat similar program, src2www by Michal Young. Src2www develops a nice index, but at the time of this writing it didn't generate the hypertext links between compilation units that ada2html does.
This is Version 1.4 of ada2html.
Limitations
Here are some known limitations:
- Currently the scripts are messy. - Currently these scripts leave some "junk" temporary files afterwards; they have ".tmp" extensions, so you can delete them later if you like. - Not enough testing has been done. It seems to work fine when I use the -s, -k and -c options, but for other circumstances I would check the results carefully. In my code, nearly all the top-level compilation units are packages; I have not tested very much other cases. - No master word index is generated yet, though a master list of compilation units IS generated. At this point it's not clear to me that creating a master index of all words is very helpful. The program CAN generate indices for each compilation unit, and as noted above it also generates a file listing all compilation units. - It's very inefficient (but acceptable for small programs on my Sparc). In particular it uses mass sorting that in many cases isn't needed; much of this sorting could be eliminated. Since this program is intended to run as a batch process, speed shouldn't be very important anyway. - If you use the "-k" (krunched) option, this program assumes that the generated HTML filenames won't overlap. A check for this would be appropriate, but currently is not performed. In the future this problem could be overcome by renaming generated files as strange names (f0000001.htm, etc). If you're worried about overlaps, consider using long filenames (and not using the -k "krunch" option). - Currently it can't generate the "home page" (should be an option) - Currently depends on Unix (i.e. sort), and that's not necessary. - Currently doesn't handle Ada 95 child packages nor separates specially. Some future version should add more links for these cases. - I haven't tested this on programs stored in multiple directories. If this causes you trouble, a work-around is to copy or link all files into a single directory and then generate the hypertext version. - Unreasonably formatted programs (for example, one word per line) won't work. Normally-formatted programs should be fine. A few programs assume "normal" formats (for example, the routine to determine the primary content of each file assumes that in the phrase "package body XXX" the name XXX is on the same line as "package body").
The Details
Ada2html takes the list of Ada source files given to it and generates corresponding HTML files for each one. It also generates a master list of compilation units and places that list in a file named "pkglist.html" (the -s option will drop that last "l"). The input Ada source files must follow the GNAT filename conventions, using krunching if you want krunched HTML filenames, and not using krunching if you don't want krunched HTML filenames. If you have Ada source files that don't follow GNAT filename conventions you can use the GNAT program "gnatchop" to create such files. If ada2html isn't given a list of files, it uses all the files ending in .ada, .adb, or .ads in the current directory. Ada2html supports the following options:
-c the following parameter is HTML text to include at the bottom of
every generated page; this is intended to permit connections
to a "central" page. By default no text like this is included.
-s "Short" file extensions - when generating HTML files, use ".htm"
instead of ".html" as the file extension.
-k "Krunched" filenames - use 8 characters or less for prefixes
of generated filenames. Usually -k and -s are used together.
Filenames are the first seven characters of the original source
file, plus the last character of the extension. For example,
small.adb => smallb.htm, occupant.ads => occupans.htm
Without krunching, filenames are the old name, underscore, last char.
small.adb => small_b.htm, occupant.ads => occupant_s.htm
-x Generate cross-reference files for each file
(otherwise cross-reference files aren't generated).
This generates filename prefixes ending in "i" (for specs) and
"j" (for bodies). This option is not well tested.
-m Mailto address - next parameter is a mailto address, presumably
of the author or a point of contact regarding the source files.
The default is "mailto:wheeler@ida.org".
-f ignore certain types of cross references if they are in the same
file (variables, etc). If you don't use this option, the results
may be distracting (there would be too many hypertext links to
items that aren't interesting because they're in the same file).
Installation
Usage
To use ada2html, run it from a command line in the following format:
ada2html [options]* [Ada_source_filenames]*
For example, cd to whatever directory contains the Ada source code with GNAT "krunched" filenames and type something like this:
ada2html -s -k -f -m "mailto:wheeler@ida.org" *.ad[bs]
Version Information
Version 1.4 fixes a bug noticed by Jacob Sparre Andersen (sparre@cats.nbi.dk) that in certain special cases caused a nontranslation of the special HTML characters <, >, and &. Version 1.3 added a link from every Ada compilation unit to the master package list that's also produced by this program. Version 1.2 fixed some minor spelling errors in the document. Version 1.1 made some minor improvements to this document and a few minor bug fixes to the distribution. The major change is that the Ada2html home page has changed slightly (it's now in a subdirectory of HBAP's tools directory). A "redirection" page is on HBAP so that users of version 1.0 will go to the correct place.
Legal Stuff
This software, "ada2html", is Copyright (C) 1995, 1996 David A. Wheeler (wheeler@ida.org). It is released under the terms of the FSF General Public License (GPL, also known as a "copyleft"), with the following additional requirement: All generated files must keep their acknowledgement that David A. Wheeler created ada2html and that ada2html was used to generate the HTML format. You may not change "ada2html" in a way that removes this acknowledgement, you may not remove this acknowledgement, and you may not grant anyone else permission to remove this acknowledgement. I'm letting you use ada2html for free, and in return I ask that you give me some credit.
At one time I required that people not submit anything generated by ada2html to the ARA for its Ada programming competition until/unless program Small won the ARA Ada programming competition. I required this because because I viewed ada2html as a "special advantage" in my submission to ARA's Ada programming competition. I originally created ada2html to improve my submission, and I didn't think it would be fair for others to use my own tools against me. program Small won the competition, so I have happily removed this requirement on the use of ada2html. This page was last modified on 21-March-1996.
David A. Wheeler (wheeler@ida.org)