AdaBrowse

Ada 95 Sources

Abstract
AdaBrowse is a javadoc-like HTML generator for Ada 95 library unit specifications. It can also generate XML output; a DTD is included in the distribution. It is free software; distributed under the terms of the GNU General Public License.

AdaBrowse has been developed on Windows NT/2k and is known to run on Windows NT/2k/XP and Unices.

Download
AdaBrowse 4.0.3 (Sources and executable for GNAT 3.15p on Windows NT/2k/XP; 1423kB)
AdaBrowse 4.0.3 (Sources and executable for GNAT 3.16a on Windows NT/2k/XP; 1427kB)
AdaBrowse 4.0.3 (Sources and executable for GNAT 5.01a on Windows NT/2k/XP; 1492kB)

Latest sources only (325kB)

For systems other than Windows NT/2k/XP, or compilers other than GNAT 3.15p or 3.16a (or 5.03a), download the source tarball and build AdaBrowse from the sources. See the User's Guide for information on how to build AdaBrowse from the sources. Note that AdaBrowse will not work with the FSF GNAT in gcc 3.x because there is no ASIS implementation for that compiler. (See also below.)

The distribution comes in all cases with an extensive User's Guide explaining just about everything about AdaBrowse as well as a couple of sample files that you can use to generate your first HTML documentation. It also includes instructions on how and where to submit bug reports.

You may also use the feedback page to send your comments to me.

Warning: HTML files generated by AdaBrowse 3.0 (and later) are not compatible with files generated by earlier versions of AdaBrowse. AdaBrowse 3.0 (and later) uses both the line and the column number to generate cross-references, whereas earlier versions used only the line number. If you absolutely need to maintain compatibility with files generated by earlier versions of AdaBrowse, use the new -l option.

Note that the 3.16a AdaBrowse executable will tell you after "adabrowse -v" that it was actually an AdaBrowse 4.0.2 for "ASIS 2.0.R for GNAT 5.00 (20030120)". That's OK, it works well with GNAT 3.16a. Also see below.


Description

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.

If AdaBrowse is told to process several units, it can even generate a master index page containing links to all generated HTML documentation files.

AdaBrowse is Copyright © 2002 by Thomas Wolf. It is free software and is distributed under the terms of the GNU General Public License (GPL).

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).

Optionally, AdaBrowse can also generate XML output. The XML generated contains all the structure, syntax coloring and cross-reference information contained in the HTML. The generated XML files are well suited for further processing (e.g. translation into your preferred document format such as docbook or texinfo). A DTD for the generated XML is included in the distribution and also available here at the URL http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/xml/adabrowse_1_1.dtd.

As an example of what AdaBrowse can do, take a look at the on-line documentation of my Util subsystem. (This documentation uses frames; try a no-frame version here.)

As another example, you can download the complete HTML reference of the Ada 95 standard library, including the GNAT additions (237kB). This set of HTML files has been generated using AdaBrowse 2.12 from the GNAT 3.14p standard library sources.


Synopsis

   adabrowse (-h | -help | --help | -?)
   adabrowse {-v | -version | --version | -f file_name | -a | -all | --all |
              -c file_name | -s URL | -o file_name | -q | -x | -g |
              (-i | -is | -p | -t) [filename] | (-I | -T) directory |
              -G (html [xml] | xml [html]) | -l | -private | --private |
              -P file_name | -X name=[value]}

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).

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

-f filename
Required: 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 should use this option only if you have HTML documentation generated by earlier AdaBrowse versions and somehow cannot re-generate that documentation. However, the recommended usage is never to use this option and to regenerate possibly already existing HTML documentation.

Note that HTML generated with "-l" is not compatible with HTML generated without "-l"! Also, HTML generated by AdaBrowse 3.0 and beyond is compatible with HTML generated by AdaBrowse 2.13 and earlier only if the "-l" option is given.

Usage of this option generates a warning message on stderr.

-o filename
Optional: Define the output file name. If not set, the output goes to a file with the name of the input and suffix ".html". If filename specifies a directory (i.e., ends in a "\" on Windows or a "/" on Unix), all generated HTML files will be put into that directory. If the filename is "-", output is written to stdout. Only one -o option may be given.

A dash as the filename ("-") is allowed only if there is exactly one output format specified. If there are multiple output formats specified (e.g. both XML and HTML), output is not allowed to go to stdout.

-p [filename]
Optional: As -i, but generates a subprogram index over all units processed.

-P filename
Gives the filename (with or without the extension *.gpr) of the GNAT project file to process. Only one -P option may be given. Note: if AdaBrowse has project manager support, it writes its version with a lower-case 'p' appended when invoked with -v.

-private, --private
Optional: if given, AdaBrowse will also process the private parts of packages and task or protected declarations. (By default, it doesn't do so but replaces the private parts by a comment saying "Implementation defined".)

-q
Optional: "Quiet" mode: do not issue warning messages.

-s URL
Optional: Defines the URL to the style sheet the generated HTML file shall use. This URL should be relative to the final place where you will put the HTML files! Note that a -s option can be overwritten by a later -c option, if the configuration file defines the key "Style_Sheet".

-t [filename]
Optional: As -i, but generates a global type index over all units processed.

-v, -version, --version
Optional: Print version information of AdaBrowse to stderr.

-x
Optional: If set, AdaBrowse never overwrites existing HTML files. (May be useful in conjunction with the -a option.)

-X name=[value]
Optional: define an environment variable name with value value. The value supersedes any possibly already existing definition of name in the system's environment for this call to AdaBrowse. The new definition affects any configuration file processed subsequently and also the project file (if any). The name must not contain white space; if value contains white space, quote the whole definition as in -X"user=John Doe". There may or may not be white space between the "-X and the variable definition.

-I directory
Optional: Define source pathes for ASIS. Same semantics as for GNAT. Multiple -I options may be given.

-T directory
Optional: Define pathes for ASIS to search for tree files (*.adt). Multiple -T options may be given.

The -f option

The -f option has three different formats:

  1. If the filename is "-" or "@-", AdaBrowse reads the unit specs of the units to process from stdin, one unit per line, until EOF is encountered. Empty lines are skipped. (If you try this interactively, you'll have to signal EOF yourself. Otherwise, this may be useful if the input comes from a pipe, like in "ls -1 *.ads | adabrowse -f- ...")

  2. If the filename starts with "@", AdaBrowse doesn't consider it a unit spec, but as the name of a text file from which to read the unit names, one unit per line. Empty lines in the file are ignored.

  3. If neither applies, AdaBrowse uses the given filename as the unit spec.

The first two cases are called the "file input mode" of AdaBrowse. The file may contain empty lines and comments (starting with the first "#" on a line and extending up to the end of the line), which are ignored.

In all three cases, a unit spec is a filename that may contain a path; a possible suffix is ignored. Note that a unit spec is a file name; in other words, you give test-gen, or test-gen.ads, and not Test.Gen. The reason is simply that for most shell scripting languages, it is easier to work with filenames that to massage them into unit names (e.g. by replacing dashes by dots). Also, if you have krunched file names, there is no simple connection between the file name and the unit name.

If a unit spec contains a path, the output file for that unit is placed into that directory unless overridden by a -o option.

In file input mode, the -o option (if given at all) may either be "-" (in which case all output goes to stdout) or specify a directory, but must not specify a file.

AdaBrowse assumes a GNAT-like naming scheme for source and HTML files. It also assumes that there is one library unit per file. As of V1.4, AdaBrowse can handle krunched file names in the -f option, provided it can find a source file, and it has the extension ".ads". If so, AdaBrowse opens and parses the source file to extract the unit name, instead of deriving it directly from the file name. Note that generated files always have names based on the unit name, not the original file name: i.e., output file names will never be krunched.

Generated HTML files always have the suffix ".html" (not ".htm").

Index generation

If AdaBrowse is told to process several units (i.e., in file input mode or if the -all option has been given), the -i, -is, -p, or -t options enable index generation, unless the output goes to stdout, i.e. the -o- option has been given.

The unit index contains cross-references to all units processed. The type and subprogram indices contain cross-references to all types or procedures and functions in all units processed. All three indices can also be customized through entries in a configuration file.

-i generates a plain unit index, whereas -is generates a structured unit index in which child units are indented. Indices always are sorted alphabetically.

Version History

For the full version history, see the online User's Guide.

Supported Compilers

AdaBrowse is an ASIS application and as such tied closely to the version of the ASIS library it uses.

The prebuilt executables have been created with GNAT 3.15p/3.16a and ASIS-for-GNAT 3.15p/3.16a. Any AdaBrowse executable created with a GNAT and ASIS-for-GNAT with versions <= 3.15p (and including the GNATPRO versions 3.15a and 3.15a1) will only work with this precise GNAT compiler version, i.e. the one used to compile AdaBrowse itself.

As of GNAT 3.16a, the picture has changed. ASIS-for-GNAT 3.16a no longer does this strict version check but (in its default mode) only requires that the tree file be compatible. However, it has changed the tree format slightly: it now contains in the first four bytes the tree version number. (Previous versions of GNAT did not store that version number at all.) As a result, the 3.16a version of AdaBrowse should work with any GNAT with a version >= 3.16a unless ACT changes the tree version number. (The 3.16a AdaBrowse won't work with a GNAT 3.15p precisely because the tree file format has changed. But it might well work with a GNAT 3.16a1 or even a GNAT 5.00 - just give it a try! But if you have any of these compilers, you're probably a paying customer of ACT anyway and can thus get an ASIS-for-GNAT for your compiler version and then re-build AdaBrowse.)

AdaBrowse can be rebuilt from the sources for GNAT versions >= 3.14p. Although I tested AdaBrowse only on Windows NT and 2000, its only OS-dependency concerns the format of file names. It should run without changes on Unix platforms, too. Just rebuild it from the sources.

AdaBrowse will not work with the FSF GNAT in gcc 3.x. The 3.15p AdaBrowse fails because it has not been compiled with the FSF GNAT (and cannot be, as there is no ASIS implementation for the FSF GNAT). The 3.16a AdaBrowse fails because the FSF GNAT still creates tree files without the tree-version. (And maybe there are other differences between the tree files generated by GNAT 3.16a and the FSF GNAT...)


Credits

Thanks to David J.A. Koogler for suggesting implementing a master index generation. (And also for his extensive testing!) He also gave the initial idea for the user-defineable HTML mark-up.