AdaBrowse User's Guide

AdaBrowse is a HTML generator for Ada 95: it automatically generates HTML documentation from Ada 95 library unit specs, similar to what javadoc does for Java, except that AdaBrowse is much more versatile and powerful. It can even generate XML output in addition to HTML documentation.

Copyright © 2002-2003 by Thomas Wolf <twolf@acm.org>.
AdaBrowse is distributed under the GPL (the GNU General Public License, see "License" below).

Contents

1. What it does

AdaBrowse produces a fully cross-referenced HTML rendering of Ada 95 specs (no bodies) similar to what javadoc does for Java sources. AdaBrowse is a command-line utility; it has no graphical user interface.

AdaBrowse is highly configurable through command-line options, style sheets, and configuration files.

AdaBrowse completely takes apart the source code and produces a HTML documentation containing:

For each item, AdaBrowse also tries to extract comments from the source and uses them to produce a description of the item. Which comments are to be taken for which items can be configured in a configuration file.

As of V3.0, AdaBrowse not only can generate HTML documentation, but also XML output. The XML output contains all the information contained in the HTML, including structure, indices, and cross-references.

AdaBrowse is not a pretty-printer! Any source chunks in the generated HTML retain the formatting as in the source file (except for cross-referencing and syntax coloring). To get the best results, the source should not contain tabs. (I use an editor that de-tabs any source file when it saves it by replacing all tabs by the appropriate number of spaces.)

AdaBrowse does a few things that could be considered some very weak form of pretty printing, though:

  1. It prints all keywords in lowercase. I chose lowercase because I felt that the combination of all uppercase and bold face in the HTML was simply too much. Lowercase letters look much better in boldface, they're not that heavy.

  2. It capitalizes all attribute defining identifiers such as "Storage_Size" in "for X'Storage_Size use ...", or "Write" in "My_Type'Write (...)".

  3. Whenever possible, it uses the defining name in place of the identifier that references it. I.e., the source

    TYPE My_Type IS NEW natural;

X : my_Type;
    is rendered in the generated HTML as

    type My_Type is new Natural;

X : My_Type;
    As a result, the generated HTML should have consistent casing of all identifiers.

However, it does not re-indent things, and it preserves the original line breaks in source code chunks.

BTW, AdaBrowse is called "AdaBrowse" and not "adadoc" because there was already an open-source project on SourceForge with the latter name.

2. Version History

The version history of AdaBrowse can be found here.

3. How to use it

AdaBrowse is an ASIS-based application. You need GNAT 3.15p if you intend to use the pre-built executable in the distribution! (If you have some other GNAT version >= 3.14p, you may rebuild simply from the sources as described below.)

There are two ways to use AdaBrowse:

  1. Call AdaBrowse for your spec: adabrowse -f <filename> (and any other options as needed, in particular -I if the file is not in the current directory or depends on other units whose sources are not in the current directory!) If no tree file for the given unit exists, AdaBrowse will try to generate one.

or

  1. Generate the tree files for the specs you want to process by calling gcc -c -gnatc -gnatt <filename> (with the appropriate -I options, if needed.)

  2. Call AdaBrowse for these specs: adabrowse -f <filename> (and any other options, as needed [look in particular at -T!]).

AdaBrowse generates HTML files by default in the current directory.

AdaBrowse doesn't care whether the tree files have been produced from specs or bodies: since the tree file of a body always also contains the information on the spec, it can work with either.

4. Options

The following options are available in AdaBrowse:

-h, -?, -help, --help
Writes a comprehensive help text.

-a, -all, --all
Optional: Generate HTML not only for the unit given in the -f option, but also for all application units on which it depends semantically (transitive closure of "with"es and parent units).

Note that this option processes only the application units in the transitive closure even if the "-g" option is also given; it does not process any "with"ed standard library unit. This also means that if the unit given is a standard library unit, the "-all" option has no effect. This behavior is intentional: you'll normally generate HTML for the standard library once by processing all standard library units explicitly, and you don't want to re-generate HTML for these units each time one of your application unit "with"es a standard library unit.

-c filename
Optional: Defines a configuration file for the HTML generator. Multiple -c options may be given; the files are processed in the given order and may overwrite earlier config settings.

-f filename
Gives the filename (*.ads) of the spec to process. This filename may contain a path! See below for more comments. Only one -f option may be given.

-g
Optional: If set, AdaBrowse also generates cross-references to items from library units in the standard and run-time packages, except for items from the implict package "Standard". Note: This can also be set by a configuration file key "Refs_To_Standard". The later definition wins.

-G output_formats
Optional; new in V3.0: specify the output formats AdaBrowse shall generate. The "-G" option must be followed by one or more output format names, given as separate arguments. Recognized output format names are html and xml (case insensitive).

If no "-G" option is given, AdaBrowse behaves as if "-G html" were given; i.e., by default, AdaBrowse generates only HTML output.

-i [filename]
Optional: If set, AdaBrowse will generate a package index if it runs in "file input mode" (see below) or the -all option is set and the output does not go to stdout.

If a filename is given, the index is written to that file (or to stdout, if the filename is "-").

-is [filename]
Optional: same as -i, but generates an index using indentation for child units.

-l
Optional; new in V3.0: make AdaBrowse generate cross-references in HTML output using only the line number. This is what earlier versions of AdaBrowse (up to and including V2.13) always did. As of V3.0, cross-references are constructed taking into account both line and column number of an item. You