# 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:

- All context clauses
- Unit header
- If the unit is a package:
  - All exceptions (including renames)
  - All constants
  - All variables
  - A type index containing all types and their primitive operations (the latter only for (tagged) record types, private types, and types derived from those). The primitive operations list is fully cross- referenced and ordered by newly defined, overridden, and inherited operations.
  - Any other items

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 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. See below for more comments. Only one `-P` option may be given.
`-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 or info messages. Synonym to `-w0`.
`-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`.
`-wi`
  Sets the warning level of AdaBrowse. i may be one of the following:

  `0`, or `e` | print only error messages.
  `1`, or `w` | print warnings and errors.
  `2`, or `i`, or `a` | print all messages.

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

There must be at least either a `-f` or a `-P` option on the command line.

### 4.1. 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. Note that contrary to configuration files, string handling for finding comment starts is not done, and line continuations also are not allowed.

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 than 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 HTML file for that unit is placed into that directory unless overridden by a `-o` option. Note that if the unit spec contains a path, you'll most probably also have to set a `-T` or `-I` option, unless you do happen to have the ASIS information available directly (i.e., a tree file for the unit in the current directory; but that's not exactly typical).

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

### 4.2. The Project Manager

#### 4.2.1 Introduction

AdaBrowse compiled with and for GNAT with the GNAT sources available has built-in support for the GNAT project manager. The executables distributed at the original download location always come with project manager support. If you intend to build AdaBrowse from the sources, see below.

What does "GNAT project manager support" mean? First, AdaBrowse has a "`-P`" command line option; its argument is a project file name. If given this option, AdaBrowse reads the project file and extracts information from it:

- If the project file contains a variable called "`ADABROWSE_TREE_DIR`" and its value is a single string, AdaBrowse assumes this to be a directory specification relative to the project file's directory where to look for tree files and generate tree files in. (This variable is a work-around for the project manager not having a `Tree_Dir` attribute.) If there is no such variable, or if it happens to be equal to the object directory, AdaBrowse issues an error message. AdaBrowse will never use the object directory specified in the project file to avoid accidentally overwriting an existing `*.ali` file belonging to an object file. See below for more information.
- If the project file contains a variable called "`ADABROWSE_OUTPUT`" and its value is a single string, AdaBrowse assumes this string to be a directory specification where to write the generated files to. The directory is assumed to be relative to the directory of the project file the variable is found in.
- If the project file contains a variable called "`ADABROWSE_CONFIGURATIONS`", AdaBrowse assumes it to contain the file names of AdaBrowse configuration files. The value can be either a single string or a string list. Again, file names are taken to be relative to the directory the project file is in. AdaBrowse processes all the configuration files in the order given. When processing a configuration file, the current directory is set to the directory of the project file. Hence any relative file references from within a configuration file will be relative to that directory, too. If there is no such variable in the project file, the project file extended by this project (if any) is searched. (In a way, projects inherit this variable when extending.)
- If there is no "`-f`" option on the command line, AdaBrowse assumes all the unit specifications of all the units in the project are to be processed.
- When given a project file, AdaBrowse unconditionally changes the compile command used to create tree files (if needed) to "`gnat compile -c -gnatc -gnatt`", and passes it the project file (and any `-X` options), too. Thus the compiler has the environment it needs (e.g. configuration pragmas defined in a project file).

There must be either a `-f` or a `-P` option on the command-line. You can also specify both, e.g. to process only a subset of the files in a project.

AdaBrowse fully supports naming schemes as defined in project files.

#### Hints on using GNAT, the Project Manager, and AdaBrowse

AdaBrowse does not add a new package for itself to the project file syntax. I would have very much liked to do that; however, the other project-aware GNAT tools issue warnings for such a package. I also cannot define new attributes for the project. Hence the somewhat crude way of using special variable names. If the GNAT project manager ever changes such that it doesn't warn about unknown packages, I may change this. But until then, we'll have to live with this.

When using the GNAT project manager for your build process and for AdaBrowse, you should be aware of the following:

ASIS-for-GNAT has, at least up to version 3.16a, a problem if tree files have been generated with `-gnatt`, but without `-gnatc` on the command line. If it loads such tree files, or a set of such files, it may fail hard with the craziest exceptions. AdaBrowse tries to compensate for that and to give at least a descriptive error message.

However, when using project files, this means that you cannot just add `-gnatt` to your `Default_Switches ("ada")` in the `Compiler` package in your project files and have everything work fine. The problem is that typically, you won't specify the `-gnatc` in a project file: after all, you want to build real applications! As a result, ASIS-for-GNAT and thus AdaBrowse cannot work with these tree files.

You also don't want to recompile (for AdaBrowse) things already compiled, because you'd define the options as `-gnatc -gnatt`. If that happens, GNAT will overwrite possibly existing `*.ali` files in the project's object directory, which is probably not a good idea, given that such existing `*.ali` files "belong" to the object files.

AdaBrowse therefore insists on the variable `ADABROWSE_TREE_DIR` being defined, and its value being different from the object directory specified in the project file. AdaBrowse then creates a temporary project file used to compile files (if necessary) with the `ADABROWSE_TREE_DIR` as the object directory. In this way, files created through AdaBrowse are kept separate from files created by your normal build scripts. As a side-effect, AdaBrowse will not remove `*.adt` files it generated (as it does normally, when not using a project file) because it considers this `ADABROWSE_TREE_DIR` "its own". By not deleting the tree files, they remain available for future re-use.

### 4.3. Index generation

Index generation is active when AdaBrowse is told to process several units, and the output does not go to `stdout` (when the `-o-` option has been given).

There are several options controlling index generation:

`-i` or `-is`
  Switches on generation of a unit index.
`-p`
  Switches on generation of a subprogram index.
`-t`
  Switches on generation of a type index.

All these options take an optional filename as a parameter. If a filename follows, the index will be written to that file (or to `stdout`, if the filename happens to be "`-`"). If no filename is given, some default name is chosen.

All these options are actually maintained only for backwards compatibility reasons. As of V4.0, indices are defined primarily through configuration file entries, not on the command line. In order not to break existing scripts using command line options of earlier AdaBrowse versions, these options are still available.

AdaBrowse assumes it will process several units in the following cases:

- In file input mode (`-f @file_name` or `-f-`.
- When using a project file (`-P project_file_name`).
- When the `-all` option is given.

If no filename is given, or it doesn't contain a path, it depends upon the setting of other options where the index will be placed:

- In file input mode, if a `-o` option is given, it must specify a directory. All HTML files, including the index, will be put into that directory.
- If no `-o` option is given, but the first unit spec contains a path, the index is put into the directory designated by that path.
- If not in file input mode, but the `-all` option has been given, the `-o` option may specify a file name. The index is put into the directory designated by the path part of that file name (the current directory, if the filename doesn't contain a path).
- If using a project file, the indices are written into the `ADABROWSE_OUTPUT` directory.
- Otherwise, this index is put in the current directory.

If a filename containing a path is given, the index will be placed into that file in the given directory. If the filename contains only a path, AdaBrowse will use that path and create an index named "`index.html`" in the designated directory.

If a `-x` option is given (inhibiting overwriting of existing HTML files) and a file exists already in the place where AdaBrowse wants to put the index, no index will be generated and AdaBrowse will issue a warning. It'll also warn if it cannot generate an index for any other reasons, but will otherwise continue processing.

Note that if you give a filename to the `-i` option that starts with the letter "`s`", you must have a white space between the option and the filename, otherwise it will be recognized as a `-is` option. Also, if the filename starts with "`-`", there mustn't be any whitespace between the option and the filename, for if there is, AdaBrowse will assume the filename to be the next option and handle it as such (options all start with "`-`"), and not as a filename.

The same caveat also applies to the `-p` option, if you want the subprogram index to go to a file named "`rivate`": there must be a blank, otherwise, the whole thing will be recognized as the `-private` option. (Admittedly this is a rather pathological case, but it's mentioned here for completeness.)

For a full description of indices in AdaBrowse, see section 5.5, "Indexing".

### 4.4. Directory and File Names

Since V.1.1, there may or may not be white space between the `-c`, `-f`, `-o`, `-s`, `-P`, `-I`, and `-T` options and the filename or directory or URL.

Unfortunately, the directories given in the `-T` options must not contain white space. This is due to a limitation of the ASIS-for-GNAT implementation which cannot handle that. AdaBrowse checks for that and issues an error message if the directory name does contain white space.

In the `-I` option, AdaBrowse does allows white space, and it also correctly re-quotes such an argument when it passes it along to the compiler if it tries to compile a file when ASIS reports inconsistencies or cannot find a tree file. (Re-quoting means: "enclose the argument, which contains white space, by double quotes and insert a backslash before any double quote originally in the argument".)

Hence, if the compiler can handle directory and file name arguments containing white space, everything will work ok. The only problem is that the gcc driver that comes with GNAT gets confused, so with GNAT, do not use file or directory names containing white space. (It appears that the gcc driver doesn't re-quote the arguments when it passes them along to the gnat1 executable.)

This is not a problem with AdaBrowse, it is a problem with GNAT (and gcc). With other compilers, it might work.

Note that `-I` options are only passed along to the compiler, never to ASIS.

The filenames given in the `-c` and `-o` options may contain directory information, and they may contain blanks. These names are used only by AdaBrowse itself, and they are handled correctly.

### 4.5. Option History

The options `-a`, `-all`, `--all`, and `-I` have been introduced in V1.01.

The options `-q` and `-x` have been introduced in V1.1.

The file input mode, the `-i` and `-is` options, and also the possibility to give a directory to the `-o` option have been introduced in V1.3.

The subprogram and type indices as well as the associated options `-p` and `-t` have been introduced in V1.5.

The `-g` option, which enables cross-reference generation to items from the standard library, has been introduced in V2.11.

The `-l` and `-G` options have been introduced in V3.0.

The `-private` option has been added in V3.2.

The `-P` option has been added in V4.0. The indexing options `-i`, `-is`, `-p`, and `-t` have become obsolete in V4.0; they are superseded by the new indexing mechanism (but they are still supported).

### 4.6. Examples

Some examples, all using the sample files in directory `.\simple_test`: (All examples assume a clean slate; if you try these one after another, be sure to remove all `*.adt`, `*.ali`, and `*.html` files in between! Also, all examples assume the current directory is the adabrowse directory. And finally, all these examples are for Windows NT/2k, but I think Unix-people will understand them.)

1. Generate all tree files, then run AdaBrowse on them:

       cd .\simple_test
       for %i in (*.ads) do gcc -c -gnatc -gnatt -I.. %i
       for %i in (*.adt) do ..\adabrowse -c..\simple_test.cfg -f %i

2. Let AdaBrowse generate the tree files:

       for %i in (.\simple_test\*.ads) do adabrowse -I.\simple_test -I. -c .\simple_test.cfg -f %i

3. Use a directory listing:

       dir /b .\simple_test\*.ads > simple_test.lst
       adabrowse -I.\simple_test -I. -c simple_test.cfg -f @simple_test.lst

   (The `dir` command produces a list of filenames (without the "`.\simple_test\`"). The HTML files therefore end up in the directory `adabrowse_1.32`.)
4. Ditto, but using the Cygwin "`ls`" command, and reading directly from `stdin`:

       ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -I.\simple_test -I. -c simple_test.cfg -f-

   (The Cygwin "`ls`" uses "/", not "\", and generates a listing of filenames that start with "`./simple_test/`". The Cygwin "`sed`" command then replaces all "/" by "\" in that output. The HTML files are put in directory `.\simple_test`.)
   Note that on Unix systems, you won't need the "`sed`" command: AdaBrowse uses '\' as directory separator on Windows systems, but '/' on Unix systems. (And I guess it'll use ':' on MacOS, for it just uses whatever `GNAT.Os_Lib` considers the directory separator.)
5. As example 4, but we want the output in some other directory, and we want an index, too:

       mkdir Testing
       ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -I.\simple_test -I. -c simple_test.cfg -f- -o .\Testing\ -i

   (The HTML files are placed in the new directory `.\Testing`.)
6. As example 5, but we assume we already have all the tree files (we generate them first); the index shall be structured and be written to file "`toc.html`". The example assumes we still have the subdirectory `.\Testing`:

       cd .\simple_test
       for %i in (*.ads) do gcc -c -gnatc -gnatt -I.. %i
       cd ..
       ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -T.\simple_test -c simple_test.cfg -f- -o .\Testing\ -is toc.html

   (The HTML files are placed in the directory `.\Testing`; the index is in `.\Testing\toc.html`. Also note that this way of using AdaBrowse is likely to be the fastest way, for all tree files already exist, and AdaBrowse can open one single ASIS context for them all. Context opening and closing is slow in ASIS-for-GNAT, and seems to incur memory leaks.)

## 5. Configuration Files

AdaBrowse is highly configurable. On the one hand, you can use style sheets to customize some presentation aspects. On the other hand, you can control directly how AdaBrowse generates HTML in the first place through configuration files. In these configuration files, you can also exclude certain units from the HTML generation process, specify URL prefixes for cross-references to certain units, and suppress cross-references to certain units.

This section describes the syntax of configuration files and in further subsections some of the simpler entries that you can use to customize the behavior of AdaBrowse. The entries controlling the formatting of Ada comments and related issues are (because of their complexity) described in the following chapters on Descriptions, User-Defined HTML Mark-Up, Environment Variable Substitution, and Advanced Description Formatting.

### 5.1. Syntax of Configuration Files

A configuration file is a text file containing lines that are either empty (zero or more whitespace characters) or that contain a key definition of the form

        key = value

Key names are case insensitive, whitespace around the key and the value is ignored. If a key is not defined, AdaBrowse supplies a sensible default value. (In fact, you can run AdaBrowse without configuration files at all, and the output will be rendered reasonably by Netscape and MS IE.)

You can use as many configuration files as you like; they are processed in the order of the corresponding `-c` options on the command line. In general, definitions in files processed later overwrite earlier definitions. The few exceptions from this rule are mentioned explicitly in the key descriptions below.

Any text on a line following the first '#' that is not within a string (i.e., not within text enclosed by single (') or double quotes ("), or the backquote character (`)) up to the end of the line is taken as a comment and ignored. E.g.

        Some_Key = hello 'world #', a nice day # and a comment

will set `Some_Key` to the value "`hello 'world #', a nice day`". Note that the first '#' doesn't start the comment, as it is inside a string.

If a line ends with a backslash (\), this indicates a line contuation: the next line is appended to the line containing the backslash, and the backslash itself is removed. If a line contains both a line continuation marker and a comment, the line continuation must come before the comment. E.g.

        Compile = gcc # the compiler to use \
                  -c -gnatc -gnatt

will set the compile command to "`gcc`" and then issue an error message for the second line, but

        Compile = gcc \ # The compiler to use
                  -c -gnatc -gnatt

works fine and sets the compile command to "`gcc -c -gnatc -gnatt`". Note that if you absolutely want to define a key whose value has to end in a backslash, you need to write a two backslashes and make sure an empty line follows, as in

        Some_Key = something\\

        # Rest of the configuration file...

Line continuations and trailing comments have been introduced in V 1.3.

Important note: comments and line continuations only are effecitive outside strings. Strings in a config file are written using the Ada convention: delimiter characters embedded within the string value must be doubled. AdaBrowse allows three string delimiters: the single quote ('), the double quote ("), and the backquote (`). This is true even in places where normally other conventions apply, e.g. in commands to be run! Hence, a `sed` command to replace all double quotes has to be written as

        sed -e"s/\""/\&quot;/g" ...

in a configuration file, even though on the command line of your favorite shell, you'd just write

        sed -e"s/\"/\&quot;/g" ...

The above applies to configuration file parsing in general. Normally, strings will occur in a configuration file at the following places (if at all):

- In `Format` keys.
- In commands to be run (the values of `User_Tag.XYZ.Execute` or `User_Tag.XYZ.Set` keys, or in the value of a `Compile` key, or in an `execute` filter).
- In an `enclose` filter.
- In the value of `Index_Title` keys.
- Anywhere you can meaningfully give some HTML tag: HTML tag attribute values may be quoted. Although in this case, the strings should not contain embedded delimiters anyway, as this would be invalid HTML.

In the first four cases, AdaBrowse de-quotes strings by replacing any double occurrences of the delimiter character within the string by a single occurrence of that character. In the last case, it doesn't do that: you should write valid HTML tags in the first place! (If some tag attribute absolutely needs to contain a delimiting character, use a named character entity: write `<SOME_TAG some_attribute="foo &quot;bar&quot;">`; the HTML standard requires browsers to replace character entities in attribute values. For the single quote, the character entity is `&#39;`, the double quote is `&quot;`, and the backquote is `&#96;`.)

### 5.2 File Inclusion

Include_File
  New in V2.0.
  AdaBrowse includes the file given by the key's value into the current configuration file at the place the `Include_File` key appears. The included file also had better be a configuration file. AdaBrowse does environment variable substitution on the value first. If the value is empty, the key definition is ignored.
  Recursive inclusion is not allowed.

### 5.3 Compilation

Compile
  This key has been introduced in V1.01, and modified in V2.0.
  Defines a command to be executed if initially opening the unit through ASIS failed. If this command isn't the empty string, AdaBrowse excecutes it to try to generate the necessary info for ASIS, and then re-tries opening the given unit through ASIS.
  The default is "`gcc -c -gnatc -gnatt`". The command must accept GNAT-style `-I` options (including `-I-`), giving directories to search for source files. For this to work with files not in the current directory, you must also pass the appropriate `-I` options to AdaBrowse.
  If the command is the empty string, AdaBrowse does not try to produce ASIS-information, it just reports that it cannot handle the given unit.
  The default setting will call GNAT, and cause the creation of a tree file (`*.adt`) and a `*.ali` file in the current directory. Both files will bedeleted again by AdaBrowse once they're no longer needed.
  As of V2.0, AdaBrowse performs environment variable substitution on the value of this key.

### 5.4 HTML-related

The value of these keys is placed verbatim into the generated HTML output at predefined places.

Char_Set
  Introduced in V1.2.
  If defined, AdaBrowse will generate a line
  `<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=value">`
  in the `<HEAD>` section of the generated HTML file. By default, this is set to "ISO-8859-1", which is Latin-1.
  This key is also used for the index.
Style_Sheet
  Introduced in V1.0, modified in V2.0.
  Defines a URL. If defined, AdaBrowse generates a line containing a link to the key's value in the `<HEAD>` section:
  `<LINK REL="stylesheet" HREF="value" TYPE="text/css">`
  It follows that the value should be a URL relative to the final location where you'll put the generated HTML file, which may be different from the location where you generate them!
  If the value is empty, no such link is generated.
  This key is also used for the index. AdaBrowse does environment variable substitution on the value first.
  Note that AdaBrowse put a default style sheet directly into the generated HTML files using a `<STYLE>` element in the `<HEAD>` section. Your own style sheet defined by this key or with the "`-s`" option on the command-line may override these default style definitions.
Body
  Defines the `<BODY>` tag to use. Also used for the index.
Title.Before, Title.After
  Define what AdaBrowse puts around the page title (not the `<TITLE>` entry in the `<HEAD>` section, but the first title in the body). Also used for the index.
Sub_Title.Before, Sub_Title.After
  Define what AdaBrowse puts around subtitles (such as "Dependences", "Header", and so on).
Keyword.Before, Keyword.After
  Define what AdaBrowse puts around keywords (such as "`package`", "`type`", and so on).
Attribute.Before, Attribute.After
  Define what AdaBrowse puts around attributes (such as "`'Class`", "`'Read`", and so on).
Definition.Before, Definition.After
  Define what AdaBrowse puts around definitions, i.e. names of an entity being declared (such as the identifier "`My_Type`" in "`type My_Type is private;`").
Comment.Before, Comment.After
  Define what AdaBrowse puts around comments (before the opening "`--`" and at the end of the line) that end up in-line in the generated output.
Literal.Before, Literal.After
  Define what AdaBrowse puts around character and string literals.

### 5.5. Indexing

As of version 4.0, AdaBrowse supports fully user-defineable indices. An index has a name (an identifier) and is defined by a file name, a title, and a rule telling adabrowse what kinds of items to include in the index.

#### 5.5.1. Index Definition

Indices are defined through the `Index.<Identifier> keys, where the identifier defines the index name.`

Index.<Identifier>.File_Name
  Defines the file name where the index shall be written to. A possible extension is ignored. HTML output automatically appends the extension "html", while XML output includes the index in the global file `adabrowse.xml` anyway. If the file name is a single dash, the index will be written to `stdout`. If no file name is defined, it defaults to the name of the index itself, i.e. to the `Identifier`.
Index.<Identifier>.Title
  Gives the index an explicit title. AdaBrowse is smart enough to figure out meaningful titles for simple indices itself (e.g., if there are only compilation units in an index, it'll choose "Unit Index" as the default title). However, it is not smart enough to generate titles for complicated indices, say, an index of all variables and functions whose (return) type was a controlled type. If no title is given and none can be figured out, "Index" is used.
Index.<Identifier>.Rule
  Gives a rule: a boolean expression on items that defines which items are to be included in the index. We'll discuss rules shortly.
Index.<Identifier>.Structured
  The value of this key may be either `True` or `False` (the default). If `True`, which actually only makes sense if the index contains only compilation units, the index will use indentation to show parent-child relations between items.
Index.<Identifier>.Empty
  Defines a text that AdaBrowse will write in place of a "real" index entry if the index does not contain any entries. Defaults to "Nothing.".

AdaBrowse performs environment variable substitution on all these keys' values.

#### 5.5.2. Index Rules

Rules are boolean expression built from built-in predicates, operators, and user-defined functions. AdaBrowse evaluates the rule of an index for any item it encounters and adds the item to an index only if the rule of the index evaluates to `true`.

Expressions have the following syntax:

       Expression := Expr [;].
       Expr       := OR_Term {(or|xor) OR_Term}.
       OR_Term    := AND_Term {and AND_Term}.
       AND_Term   := EQ_Term {(=|/=) EQ_Term}.
       EQ_Term    := STR_Term {@ STR_Term}.
       STR_Term   := Term {& Term}.
       Term       := [not] Factor.
       Factor     := ( Expr ) |
                     Identifier |
                     String_Literal.

The syntax of identifiers and string literals is as in Ada. Parsing (as well as string comparisons and the `@` prefix operator) is case insensitive.

The identifier of a `Factor` shall resolve to either a user-defined function name (see the description of the `Rule` key below), or be one of the predefined predicate names.

Note that this syntax is a bit different from the Ada one:

- It allows mixing different logical operators. All binary operators (including the logical ones `and`, `or`, and `xor`) are left-associative.
- Mixing logical operators is possible because `and` has higher precedence than `or` and `xor`, and because of left-associativity.

Parentheses can be used to override the normal precedences. The equality operators `=` and `/=` can compare either two boolean expressions, or two string expressions. String comparisons are case insensitive. The `&` is the string concatenation operator. The `@` binary operator takes two string arguments and returns a boolean value; it is `True` if the right argument is a prefix of the left one.

An expression may or may not have a terminating semicolon.

Example:

          A and B or C = D and E = F & G = H

is the same as

          (A and B) or ((C = D) and ((E = (F & G)) = H))

#### 5.5.3. Predefined Predicates

AdaBrowse comes with a large set of predefined predicates. They can be classified in general predicates useful for determining the broad class of an item, plus type predicates that return `True` for particular classes of types. Finally, there are two built-in function for getting the name of an item, and the boolean constants.

General predicates:

child
  Is `True` for all child units.
constant
  Is `True` for all constants and named numbers.
entry
  Is `True` for all entry declarations (of both tasks and protected types or objects).
exception
  Is `True` for all exception declarations (including renamings).
function
  Is `True` for all function declarations (including protected functions and renamings, instantiations, and generic declarations).
generic
  Is `True` for all generic declarations.
instance
  Is `True` for all instantiations of generics.
package
  Is `True` for all packages, including generics, renamings, and instantiations).
pragma
  Is `True` for all pragmas.
private
  Is `True` for all items declared in the private part of the enclosing package, task, or protected type (or object).
procedure
  Is `True` for all procedure declarations (including protected procedures and renamings, instantiations, and generic declarations).
representation
  Is `True` for all representation clauses.
separate
  Is `True` for all separate items. Note that AdaBrowse will never encounter a separate item because it only processes unit specs!
subprogram
  Equivalent to the expression `function or procedure`.
subtype
  Is `True` for all subtype declarations.
type
  Is `True` for all type declarations (but not subtype declarations!).
unit
  Is `True` for all compilation units.
variable
  Is `True` for all object declarations (variables, but also single task and protected obejct declarations).

Predicates on types: these apply to type (and subtype) declarations, object declarations (where they work on the type of the object), and to functions (applying to the return type). These predicates basically mirror the type classes of Ada as shown in the refernce manual; see RM 3.2(12). However, there are a few extra predicates, such as `class_wide` or `controlled`. (The order given here also follows RM 3.2(12), with the extra predicates at the end.)

elementary
  Is `True` for all elementary types.
scalar
  Is `True` for all scalar types.
discrete
  Is `True` for all discrete types.
enum
  Is `True` for all enumeration types.
integral
  Is `True` for all integral types.
signed
  Is `True` for all signed integer types.
modular
  Is `True` for all modular types.
real
  Is `True` for all real types.
float
  Is `True` for all floating-point types.
fixed
  Is `True` for all fixed-point types.
ordinary_fixed
  Is `True` for all ordinary fixed-point types.
decimal_fixed
  Is `True` for all decimal fixed-point types.
numeric
  Is `True` for all numeric types. Equivalent to the expression `integral or real`.
access
  Is `True` for all access types.
access_object
  Is `True` for all access-to-object types.
access_subprogram
  Is `True` for all access-to-subprogram types.
composite
  Is `True` for all composite types.
array
  Is `True` for all array types (both constrained and unconstrained).
record
  Is `True` for all record types.
tagged
  Is `True` for all tagged record types.
limited
  Is `True` for all limited types, including task and protected types.
controlled
  Is `True` for all controlled types, i.e. types derived from one of the two types declared in package `Ada.Finalization`.
class_wide
  Is `True` for all class-wide types.
private_type
  Is `True` for all private types, including private extension declarations.
protected
  Is `True` for all protected objects and types, but also for all declarations within.
task
  Is `True` for all single tasks and task types, but also for entry declarations in tasks.

Miscellaneous predicates:

abstract
  Is `True` for all abstract types and subprograms.
aliased
  Is `True` for all aliased objects.
formal
  Is `True` for all generic formal declarations.
incomplete
  Is `True` for all incomplete types and for deferred constant declarations.

Constants:

false
  Is always `False`.
true
  Is (guess what?) always `True`.

Built-in functions returning strings:

name
  Returns the simple name of the item as a string.
full_name
  Returns the fully qualified name of the item as a string.

Note that `elementary /= not composite`: there are types that are neither elementary nor composite, such as private types.

#### 5.5.4. User-Defined Functions

Besides these built-in predicates, you can also define your own rule functions with the `Rule` key:

Rule.<Identifier>
  Defines a named function. Wherever this name appears in a subsequent expression, it is replaced by the defining expression. (In this sense, the name "function" is actually wrong; it's more like a macro.)
  Example: `Rule.entries_of_tasks = entry and not protected`

#### 5.5.5. Index Keys and Index Options

Versions of AdaBrowse prior to V4.0 only had the command line options (plus the few obsolete keys mentioned below) to define indices. These options still exist, they are now defined in terms of the new indexing keys:

`-i [file_name]` or `-is [file_name]`
  Defines a unit index named "Units". Equivalent to the index keys

        Index.Units.File_Name  = index (default) or file_name
        Index.Units.Title      = Unit Index
        Index.Units.Rule       = unit

  If the option `-is` is used, an additional key

        Index.Units.Structured = True

  is also defined.
`-p [file_name]`
  Defines a subprogram index named "Subprograms". Equivalent to the index keys

        Index.Subprograms.File_Name = procidx (default) or file_name
        Index.Subprograms.Title     = Subprogram Index
        Index.Subprograms.Rule      = subprogram and not protected

`-t [file_name]`
  Defines a type index named "Types". Equivalent to the index keys

        Index.Types.File_Name = typeidx (default) or file_name
        Index.Types.Title     = Type Index
        Index.Types.Rule      = type or subtype

The command line options can coexist with the new `Index` keys, and it is possible to redefine in a configuration file the indices defined by the command line options.

#### 5.5.6. An Example

In this example, we'll define an index of exceptions, but only those declared in public parts and that are not renamings.

      Index.My_Exceptions.File_Name = ex_idx
      Index.My_Exceptions.Title     = Public Exceptions
      Index.My_Exceptions.Rule      = exception and not (private or renaming);

#### 5.5.7. Other Indexing Keys

The following key has been carried over from earlier AdaBrowse versions. It allows the user to define special cross-reference formats for indices in HTML.

Index_XRef
  Defines a portion of a `<A HREF="">` tag to be used when AdaBrowse generates an index. AdaBrowse generates `<A HREF="somewhere.html"` then inserts the value, and then emits a single "`>`".
  This is useful if the index is finally to be used within a web page containing frames. For instance, with the definition
  `Index_XRef = TARGET="main"`
  AdaBrowse will generate cross references in the index that look like
  `<A HREF="somepackage.html" TARGET="main">SomePackage</A>`
  The default value of this key is the empty string.
  This key is used for all indices, but only for HTML output.

The following keys are obsolete; they are maintained only to ensure backwards compatibility with versions of AdaBrowse prior to V4.0.

Index_Title
  Defines the title of an index. The general format of this key is `Index_Title[.Index_Spec]`, where `Index_Spec` is one of `Unit_Index`, `Type_Index`, or `Procedure_Index`. If no `Index_Spec` is given, the key applies to the unit index to maintain compatibility with AdaBrowse versions earlier than 1.5.
  The default titles are "Unit Index" (not "Package Index", because subprograms also may be library units) for the unit index, "Type Index" for the type index, and "Subprogram Index" for the subprogram index.
  Examples:
  `Index_Title = My Subsystem`
    Sets the title for the unit index to "My Subsystem". Equivalent to `Index.Units.Title = My Subsystem`.
  `Index_Title.Unit_Index = My Subsystem`
    Ditto. Equivalent to `Index.Units.Title = My Subsystem`.
  `Index_Title.Type_Index = My Types`
    Sets the title for the type index to "My Types".
    Equivalent to `Index.Types.Title = My Types`.

### 5.6. Cross-References

(New in V1.1)

By default, AdaBrowse will generate cross-references to other units based on the assumption that the other units' HTML files will be in the same directory as the final place for the current unit's HTML file. However, this may not always be adequate.

Consider a shop that runs several projects, all using a set of common core components. The core components' descriptions are on a Web server in the intranet at URL "`http://intranet.shop.com/core/doc/ref_manual/`".

You are working in project X (which uses the core components), and are to place your project's HTML docu at "`http://intranet.shop.com/X/specs/`".

Therefore, the HTML files you generate must prefix all cross references to a core component with either "`http://intranet.shop.com/core/doc/ref_manual/`" or, in this particular case, "`../../core/doc/ref_manual/`".

Or maybe, for some reason, you don't want any cross-references to certain components at all.

AdaBrowse has some keys which allow you to define exactly this behavior:

Path.<Full_Unit_Name_Prefix>
  Modified in V2.0.
  If defined, prepend the value to any cross-reference to a unit whose full unit name (starting with a root library unit name) has a prefix that matches `<Full_Unit_Name_Prefix>`. If several `<Full_Unit_Name_Prefix>`es match, the longest match wins. Matching is case-insensitive. Note that you specify a unit name prefix, not a file name prefix. I.e., you'd write "`Core.Os`", not "`core-os`".
  Several `Path` keys may be defined. If two `<Full_Unit_Name_Prefix>`es are identical (except for casing), the later definition wins.
  `<Full_Unit_Name_Prefix>` must not be empty, i.e. a definition like
  `Path. = ...`
  is illegal.
  AdaBrowse does environment variable substitution on the value. The value (after environment variable substitution) may be empty, in which case AdaBrowse does not prefix cross-references to matching units.
  Example:

      Path.Cor  = http://intranet.shop.com/core_old/doc/rm/
      Path.Core = ../../core/doc/ref_manual/
      Path.BC   = http://intranet.shop.com/booch_components/rm/

  If AdaBrowse wants to generate a cross-reference to a unit `CORE.OS` now, it'll check the list of pathes given and in this case, it'll generate the cross-reference to "`../../core/doc/ref_manual/core-os.html`". Note that the first path also matches, but "`Core`" is a longer match than "`Cor`". However, for a cross-reference to `COROLD.EXTERNAL`, the first path will match (whereas the second one won't as "`core`" is not a matching prefix), and the cross-reference will be generated to the URL "`http://intranet.shop.com/core_old/doc/rm/corold-external.html`".
No_XRef = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}
  If defined, tells AdaBrowse never to generate cross-references to Units whose full name has a prefix matching one of the given unit name prefixes, unless a unit that would be thus excluded from cross-reference generation is explicitly included by a `XRef` key (see below). Matching is case-insensitive. White space around unit name prefixes is ignored, and so are empty unit name prefixes.
  Multiple `No_XRef` keys may be defined. The set of prefixes considered is the union of all `No_XRef` keys' values. The value may be empty, in which case the key definition has no effect.
  Matching is case-insensitive.
  Example:

      No_XRef = Core.Os ,,  , BC.Support
      No_XRef = , Co ,

  The set of prefixes is "`Co`", "`Core.Os`", "`BC.Support`".
XRef = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}
  (New in V2.12.) This is the exact opposite of `No_XRef`. Cross-references to units matching one of the prefixes defined by `XRef` keys are always generated, even if the unit name would otherwise be excluded from cross-reference generation by a `No_XRef` key. I.e., `XRef` keys define exceptions to the set of units defined by `No_XRef` keys.
Exclude = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}
  Same syntax as `No_XRef`. Defines a set of units for which no HTML files shall ever be generated. This is useful in particular in conjuction with the `-a` option: if your package in project X uses something from `Core`, AdaBrowse would normally also generate a HTML file for the core packages. But that's probably not what you want.
  If the value is empty, all previous definitions of that key are reset, i.e., the set of units to exclude is (again) the empty set.
  Multiple `Exclude` keys may be defined, the set of excluded units is the union of all keys' values (except for the empty value, see above).
  Example:

  `Exclude = Core, BC`

  If the unit you give in the (mandatory) `-f` option is excluded, AdaBrowse issues an error message.
  Note: cross-references to a unit suppressed by an `Exclude` key will still be generated unless the unit is also suppressed by a `No_XRef` key.
  Also note that AdaBrowse excludes by default all units from the Ada 95 standard library. (It only handles what ASIS calls "`An_Application_Unit`".)
Include = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}
  (New in V2.12) This is the exact opposite of `Exclude`. HTML files are always generated for units matching one of the prefixes defined by `Include` keys, even if the unit name would otherwise be excluded from cross-reference generation by an `Exclude` key. I.e., `include` keys define exceptions to the set of units defined by `Exclude` keys.
  Do not confuse this key with the `Include_File` key, which is for including another configuration file into the current one.
Refs_To_Standard = (True | False)
  (New in V2.11.) If this key is set to `True`, AdaBrowse will generate cross-references to items from the Ada 95 standard library or the compiler's run-time library, unless such units are excluded from cross-reference generation explicitly using a `No_XRef` key. If it is set to `False` (the default), AdaBrowse won't generate such cross-references. In both cases, AdaBrowse will never generate cross-references to items from the implicit package `Standard`.

AdaBrowse does longest prefix matching for the `[No_]XRef` and the `Exclude` or `Include` keys. This makes it possible to define precisely which units are to be included, and which ones are to be excluded. For instance,

       Exclude = System., System.Address_To_Access_Conversions.
       Include = System.Address_To_Access_Conversions

has the following effect:

1. exclude all children and further descendents from package `System`. That's the "`Exclude = System.`" part. Note the period: it doesn't exclude `System` itself!
2. include the package `System.Address_To_Access_Conversions` and all its children and further descendents. That's the `Include` key.
3. exclude again any descendents of `System.Address_To_Access_Conversions` again. That's the second prefix in the `Exclude` key's value.

As a result, there will exactly two packages from the `System` subsystem be included: `System` itself, and `System.Address_To_Access_Conversions`. All other packages in this subsystem are excluded.

> Versions of AdaBrowse prior to V2.13 did shortest prefix matching on these unit prefixes. This made sense when there were no `Include` or `XRef` keys, but since their introduction in V2.12, shortest prefix matching isn't exactly useful anymore; longest prefix matching actually is much more useful.

If the `-a` option is given to AdaBrowse, it will try to generate HTML files for all parent units of the given unit, as well as for the transitive closure of all "with"ed units and their parents. However, it will skip any unit in this set that is either excluded by an `Exclude` key, or for that no cross- references are generated anyway due to a `No_XRef` definition. AdaBrowse will issue a warning for each skipped unit to `stderr`. (If, in addition to `-a`, also `-x` was given, it'll also skip the unit if the corresponding HTML file already exists, and it'll also warn about that.)

(Of course, if warnings are suppressed with the `-q` option, AdaBrowse will not issue these warnings.)

### 5.7. General Usage Hints

The file `sample.cfg` gives the default settings AdaBrowse uses anyway if no configuration is used. In this default setting AdaBrowse generates valid HTML 4.01. However, if you redefine some keys inconsistently in a configuration file, AdaBrowse may generate invalid HTML. An example would be to define

        Keyword.Before = <EM>
        Keyword.After  = </STRONG>

or

        Comment.Before = <EM>
        Comment.After  =

or (especially catastrophic)

        Body = <!--

Thus, be careful to define your values properly! Or use the default settings. AdaBrowse does not check whether or not the values defined make any sense.

Note that the style sheet to use can be defined on the command line (with the `-s` option) or in a configuration file (with the Style_Sheet key). The later definition wins.

### 5.8. A More Elaborate Example

This example shows how to generate a useful HTML reference of the standard library of your compiler. The example assumes your compiler is GNAT, and its standard library is at a place designated by an environment variable called `GNAT_LIB_SRCS`. On my machine for instance, `GNAT_LIB_SRCS` would have the value `x:\gnat\lib\gcc-lib\pentium-mingw32msv\2.8.1\adainclude`.

First, create a directory where you want the generated HTML to go:

       mkdir ./std_lib_html

Then create a configuration file `./std_lib_html/std.cfg` with the following contents:

       # Sample configuration file for creating a HTML docu for the standard lib.

       # Do not generate cross refs to any child of System. Note the period at the end: we
       # don't exclude System itself!
       No_XRef = System.

       # But do generate cross-refs to the standard children
       XRef    = System.Address_To_Access_Conversions, System.Machine_Code, System.RPC
       XRef    = System.Storage_Elements, System.Storage_Pools

       # The above combination of No_XRef and XRef excludes all GNAT-specific children
       # of package System.

       # Now the same with Exclude and Include keys:
       Exclude = System.
       Include = System.Address_To_Access_Conversions, System.Machine_Code, System.RPC
       Include = System.Storage_Elements, System.Storage_Pools

Then, execute the following commands (assuming Win NT/2k, but on Unix, it would be very similar):

       cd .\std_lib_html
       for %i in (%GNAT_LIB_SRCS%\*.ads) do gcc -c -gnatc -gnatg -gnatt -I%GNAT_LIB_SRCS% -I- %i
       ls -1 *.adt | sed -e"s@/@\\@g" | adabrowse -I%GNAT_LIB_SRCS% -c std.cfg -g -f- -is -t -p
       del *.adt *.ali

Note the "`-g`" option! Also note that the above configuration file excludes only the GNAT specific children of `System`, but it doesn't exclude GNAT-specific additions to e.g. the `Ada` or `Interfaces` subsystem.

On my machine, the above execution of AdaBrowse takes about one minute and generates 205 HTML files (using GNAT 3.15p).

## 6. Descriptions

This section describes how AdaBrowse associates Ada 95 comments with declarations to generate HTML descriptions. It also gives an introduction to how AdaBrowse formats the HTML descriptions.

Advanced topics on user-defined HTML mark-up and on how to fine tune or even completely change the formatting process are described in their own sections following this basic introduction.

### 6.1. Finding Descriptions

Since V1.1, AdaBrowse can extract comments from the source and generate HTML descriptions for items from them automatically. You configure which comments are to be taken for which items through the `Description` keys explained below. For instance, you can tell AdaBrowse whether you generally put comments for a subprogram before or after the subprogram declaration.

This section only describes how AdaBrowse associates Ada comments with certain Ada entities. For information on how to control the formatting of the HTML descriptions generated from these comments, see below.

#### 6.1.1. Description Definitions

The keys that tell AdaBrowse where to find the comments to create the descriptions of an entity from all start with "`Description.`" and all take a list written as comma-separated values as their argument. Legal list element values are:

Before (Number)
  Take the comment above the entity to build the description from. There may be at most `Number` empty lines between the last comment line and the beginning of the entity. If no number is given, this means "any number of empty lines". If the `Number` is zero, there mustn't be any empty lines between the entity and the comment. The search for the comment starts at the beginning of the item and goes backward.
  Examples:
  `Description.Subprogram = Before (3)`
    Tells AdaBrowse that the description for a subprogram declaration can be found in a comment textually above the declaration, separated from the declaration by at most 3 empty lines.
  `Declaration.Subprogram = Before`
    The same, but the search for the comment is not limited to a particular number of empty lines.
After (Number)
  Ditto, but AdaBrowse goes looking for a comment below the entity. The search starts at the end of the item and goes forward.
Inside (Number)
  This value is allowed only for the "containers" (see below). It tells AdaBrowse that the descriptive comment is inside the entity, separated by at most 'Number' empty lines from the end of the header. The search goes forward. (An exception are library units, see the corresponding keys below.)
  It can be applied to (generic) package declarations, task (type) declarations, and protected object and type declarations.
  The header of each of these constructs is defined by AdaBrowse to end at the end of the "`is`":
  `package XYZ is`
  `generic ... package XYZ is`
  `task (type) XYZ (Discriminants) is`
  `protected (type) XYZ (Discriminants) is`
None
  Tells AdaBrowse not to try to find any descriptive comment for the entity.

In any case, search for a descriptive comment stops and comes up empty if either

- a comment already taken as the description of some other entity is hit, or
- a line containing any non-comment is hit.

If a comment is found, all comment-only lines directly adjacent until one of the above two conditions (or the beginning or end of the file) is met belong to that descriptive comment.

AdaBrowse recognizes the following description keys:

Description.Context_Clause
  For the context clauses of a library unit. "Before" means "before the first context clause" and "After" means "after the last context clause". default setting is "`After (1)`".
Description.Clause
  For interior "`use`" and "`use type`" clauses. Default setting is "`After (1)`".
Description.Subprogram
  For subprogram, generic subprogram, entry, and entry family declarations.
Description.Renaming
  For (generic) subprogram and package renamings. If not set explicitly, defaults to Description.Subprogram.
Description.Instantiation
  For generic instantiations (subprograms or packages). If not set explicitly, defaults to Description.Subprogram.
Description.Constant
  Applies to (deferred) constants and named numbers.
Description.Exception
  For exception declarations including exception renamings.
Description.Pragma
  For pragmas.
Description.Rep_Clause
  For representation clauses.
Description.Type
  For all types except task and protected types.
Description.Object
  For all variable declarations and object renamings.
Description.Container
  A global key for all "containers", i.e., (generic) package declarations that are not renamings, task (type) declarations, and declarations of protected objects and types.
Description.Task
  For tasks and task types. If not set explicitly, defaults to Description.Container.
Description.Protected
  For protected objects and types. Defaults to Description.Container.
Description.Package
  For nested (generic) packages. Defaults to Description.Container.
Description.Library
  For all library units. Here, "Before" means "before the context clauses", "Inside" means "between the context clauses and the beginning of the header" and "After" means "after the declaration" for library unit sub subprograms and renamings and "Inside, after the package header" for library unit (generic) packages.
  If "Inside" is specified, the search for the comment starts at the beginning of the header, and the search goes backwards. It is thus possible to have

      Description.Context_Clause = After
      Description.Library = Inside

      with Ada.Text_IO;
      -- This comment is taken for the context clauses

      -- This comment is taken to build the package description
      package XYZ is
         ...

  The empty line between these two comments is crucial! Without this empty line, both Ada comment lines would be considered part of the same descriptive comment and be taken for the package description. (See below.)
Description.Library_Subprogram
  For (generic) library subprograms. Defaults to Description.Library.
Description.Library_Package
  For (generic) library packages. Defaults to Description.Library.
Description.Library_Renaming
  For library unit (generic) renamings. Defaults to Description.Library.
Description.Library_Instantiation
  For library units that are instantiations of other generic units. Defaults to Description.Library.

#### 6.1.2. How AdaBrowse maps Ada Comments to Descriptions

Determining which comment belongs to which entity works as follows:

Generally, for finding a description, AdaBrowse considers all specified locations in the order they appear in the list of the key.

AdaBrowse starts with the library unit and tries to find a descriptive comment for it. If it finds one, it associates that comment with the library unit.

Next, it considers the context clauses and associates any description it finds with them (as a whole).

Then, if the library unit is a package, it goes through all declarations and pragmas inside the visible part of the package in the order of their appearance and tries to find descriptions.

If for some entities a list and not just a single value was given, AdaBrowse then makes another pass following exactly the same rules and tries to find additional descriptions (that have not yet been assigned to an entity), using the remaining location definitions in the entity's key definition.

Nested containers, that is, (generic) package declarations, task (type) declarations, and protected object and type declarations are handled similarly whenever the container is encountered.

The default values, which mirror my own style, are as follows:

Description.Context_Clause | = After (1)
Description.Clause | = After (1)
Description.Subprogram | = After (1)
Description.Renaming | = After (1)
Description.Instantiation | = After (1)
Description.Constant | = After (1)
Description.Exception | = After (1)
Description.Pragma | = After (1)
Description.Rep_Clause | = After (1)
Description.Type | = After (1), Before
Description.Object | = After (1)
Description.Container | = Before, Inside
Description.Task | = Before, Inside
Description.Protected | = Before, Inside
Description.Package | = Before, Inside
Description.Library | = Before, After
Description.Library_Subprogram | = Before, After
Description.Library_Package | = Before, After
Description.Library_Renaming | = Before, After
Description.Library_Instantiation | = Before, After

### 6.2. Basic Description Formatting

A description for some declaration is thus a sequence of Ada 95 comments. These comments appear in the order the locations were given in the `Description` key definitions, not in the order they appeared in the original Ada 95 source.

If the first line of a comment of a description contains the comment prefix and then dashes only, it is removed and likewise for the last line. Next, the comment prefix is removed from all lines in the comments of the descriptions, and any trailing "`--`" (for box comments) is also removed. The comment prefix is normally "`--`" (of course), but more elaborate prefixes can be defined; see below. Then, any trailing white-space is removed. What remains is the content of the description.

This description content is then processed in various ways (which you can define, see below) and then written to the generated HTML file. Logically, if the comments contain HTML tags, these will end up in the generated HTML file. Hence you can use HTML mark-up to format your Ada 95 comments.

#### 6.2.1. Default Formatting

By default, HTML comments within Ada comments (started by "`<!--`" and extending up to the next "`-->`") are suppressed completely; they are not written into the generated HTML file at all. HTML special characters in Ada comments are automatically replaced by the corresponding named character entity, e.g. a "<" in an Ada comment will be written as "`&lt;`" into the HTML file. (Unless, of course, the "<" is the opening of an HTML tag.) Characters beyond the 7-bit ASCII range (like e.g. "ü") are replaced by numeric character entities, in this case by "`&#252;`".

Empty Ada comment lines (i.e., starting with "`--`" and then followed by white-space only (and possibly a terminating "`--`")) cause new paragraphs to be started, so it is in general not necessary to put `<P>` tags in your comments.

AdaBrowse uses a simplified parsing of Ada comments to determine what is an HTML tag. It considers anything starting with a "<" followed by a character or a "/" and a character up to the next ">" that is not within a """-delimited string a HTML tag. This works pretty well in practice, but may fail in some circumstances:

- If you have an Ada comment like "`-- This function returns True iff 10<a`", AdaBrowse thinks the "`<a`" was the start of a HTML tag. To avoid this, write your comment as "`-- This function returns True iff 10 < a`", which looks nicer anyway. (Note that this particular case causes troubles even if AdaBrowse knew all the legal HTML tags exactly, and therefore I chose to use a simplified parsing only: nothing would be gained by an exact parsing, but it would make AdaBrowse slower.)
- The same problem occurs in an Ada comment like "`-- Author: <somebody@somewhere.org>`": AdaBrowse will treat the whole e-mail address as a HTML tag. Either omit the "<" and ">" around the e-mail address, or write them as "`&lt;`" and "`&gt;`", or make sure there's a space following the "<" as in "`-- Author: < somebody@somewhere.org >`".

#### 6.2.2. A Shortcut for the `<CODE>`-Tag

I also found that the most often used HTML tag in Ada 95 comments tends to be `<CODE>`. Since I personally find it rather cumbersome to have to type this so often and I also think it interferes with the readability of the Ada comments in the Ada source, AdaBrowse offers a more readable short-hand notation for most uses of the `<CODE>`-tag: Any pair of "`@` without white-space in between is replaced by "`<CODE>`" and "`</CODE>`", respectively. Hence the Ada comment

    This function returns @True@ iff 10 < @a@

will be written as

    This function returns <CODE>True</CODE> iff 10 < <CODE>a</CODE>

into the HTML file, and will be rendered as

This function returns `True` iff 10 < `a`

The "`@`"-pair handling is intended to catch and simplify the most common uses of the `<CODE>`-tag, but it cannot replace all uses of `<CODE>`.

The above is sufficient for most simple needs, and AdaBrowse provides sensible default settings such that well-written comments are rendered nicely when the generated HTML file is displayed. However, for more advanced needs, AdaBrowse provides two more ways to control the formatting process precisely to nearly any level desired:

1. User-defined HTML mark-up can be used to define your own tags that are macro-expanded. There are even ways to define tags that include other files, or that call an external command and replace the tag by the command's output. This is described in detail in the section on user-defined HTML mark-up.
2. Format instructions allow you to define exactly how AdaBrowse shall format a comment. You may define special prefixes and format instructions that apply to all Ada 95 comments that start with those prefixes (for instance, you could make any comments beginning with "`--!`" to be written in a <PRE> block). You may also redefine how AdaBrowse formats comments in general by defining your own format instructions for the standard prefix "`--`". AdaBrowse offers several powerful built-in format instructions, but also allows you to send the whole description content to some external command for formatting. All this is described in the section on advanced description formatting.

However, for your first experiments, just use the default settings. As a next step, I suggest trying out the "`@`"-pair replacement. Once you've had some experience with AdaBrowse, you'll probably start using user-defined tags for newly written source code. Format instructions are mainly useful if you have special formatting needs, or if you need to generate HTML documentation for legacy code containing textually formatted comments.

## 7. User-Defined Mark-Up

As of V2.0, AdaBrowse supports user-defined HTML mark-up elements. By default, AdaBrowse replaces any user-defined HTML tag in a comment that is formatted according to the tag's definition.

### 7.1. Basic Syntax

A user-defined HTML element is defined by keys of the form `User_Tag.<TAG_IDENTIFIER>`. `<TAG_IDENTIFIER>` must be an identifier, which in AdaBrowse has the syntax

        Identifier = Letter { Letter | Digit | '_' }.
        Letter     = 'A' .. 'Z' | 'a' ..'z'.
        Digit      = '0' .. '9'.

This is the same syntax as for Ada 95 identifiers, except that it allows multiple underscores in a row as well as trailing underscores.

To define a container element, the syntax is

        User_Tag.<TAG_IDENTIFIER>.Before = Definition
        User_Tag.<TAG_IDENTIFIER>.After  = Definition

Both the "`.Before`" and the "`.After`" must be present. If one or the other is missing, AdaBrowse will issue an error message. The "`.Before`" definition replaces any occurrence of the opening tag, and the "`.After`" definition replaces occurrences of the closing tag.

To define a non-container element, use the syntax

        User_Tag.<TAG_IDENTIFIER> = Definition

i.e. without either "`.Before`" or "`.After`". In both cases, the key is case insensitive, both in the configuration file and also in the comments where the user-defined tags are used. Both container and non-container elements can be individually switched on or off:

        User_Tag.<TAG_IDENTIFIER>.Enabled = (True | False)

By default, all user-defined HTML elements are enabled. If an element is disabled, it is completely suppressed. If a container element is disabled, all its content also is suppressed.

### 7.2. A Simple Example

Consider the following configuration file:

        User_Tag.COPYRIGHT.Before = <BLOCKQUOTE><STRONG>Copyright (c)
        User_Tag.COPYRIGHT.After  = </STRONG></BLOCKQUOTE>

        User_Tag.AUTHOR = Thomas Wolf

An Ada comment like

        --  <COPYRIGHT> 2002 by <AUTHOR></COPYRIGHT>

will thus be written to the generated HTML file as:

    <BLOCKQUOTE><STRONG>Copyright (c) 2002 by Thomas Wolf</STRONG></BLOCKQUOTE>

and will be rendered as

> Copyright (c) 2002 by Thomas Wolf

Note how the non-container element "AUTHOR" works like a variable!

The same effect can also be achieved with the configuration file

        User_Tag.COPYRIGHT.Before = <BLOCKQUOTE><STRONG>Copyright (c)
        User_Tag.COPYRIGHT.After  = by <Author></STRONG></BLOCKQUOTE>

        User_Tag.AUTHOR = Thomas Wolf

and the Ada comment

        --  <COPYRIGHT> 2002 </COPYRIGHT>

This latter example also shows that user-defined tags can be defined in terms of other user-defined tags: AdaBrowse performs macro substitution of user-defined tags. Of course, recursion between user-defined tags is not allowed. If AdaBrowse detects a recursive definition of user-defined tags during tag expansion, such as

        User_Tag.RECURSIVE   = <NOT_ALLOWED>
        User_Tag.NOT_ALLOWED = <RECURSIVE>

it issues an error message and terminates.

### 7.3. Advanced User-Defined Variables

A user-defined non-container HTML element acts like a variable (or more precisely, a macro): it is simply replaced by its definition, and references inside that definition to yet other user-defined HTML elements also are replaced.

AdaBrowse offers some more advanced ways to set such user-defined variables (all these definitions define non-container HTML elements):

`User_Tag.<TAG_IDENTIFIER>.Include = File_Name`
  Replaces any occurrence of `<TAG_IDENTIFIER>` by the verbatim contents of the file `File_Name`. If the file cannot be found or read, AdaBrowse issues a warning and replaces the tag by the empty string. Within `File_Name`, AdaBrowse performs environment variable substitution!
  Note that AdaBrowse does not parse the file in any way, so inside the included file, AdaBrowse's user-defined HTML elements are not available; the file should contain standard HTML only. Also, it is good, prudent practice to make the file self-contained in the sense that it should close all container elements it has opened. Otherwise, the HTML file generated by AdaBrowse may become hopelessly garbled.
  If the file name is empty, no file inclusion occurs, and the tag is replaced by the empty string.
`User_Tag.<TAG_IDENTIFIER>.Execute = Command`
  For each occurrence of `<TAG_IDENTIFIER>`, AdaBrowse runs the `Command` and replaces the tag by the entire output of the command. Note that the command had better not read from `stdin`, and it also had better return. If the command blocks (does not return), so will AdaBrowse! Within the `Command`, AdaBrowse performs environment variable substitution.
  The command's output is placed verbatim into the generated HTML file, so again, no user-defined HTML elements are available.
  If the command is empty, no command is run and the tag is replaced by the empty string.
`User_Tag.<TAG_IDENTIFIER>.Set = Command`
  As the `Execute` selector, but the command is run only once upon the first occurrence of `<TAG_IDENTIFIER>`. The variable is set to the first line (limited to 1000 characters) of the command's output. Then, this and any subsequent occurrences of the tag are replaced by this value. Since these replacements are then normal tag replacements, AdaBrowse does parse the value and expand any contained references to other user-defined HTML elements! Within the `Command`, AdaBrowse performs environment variable substitution.
  If the command is empty, no command is run and the tag is replaced by the empty string.
`User_Tag.<TAG_IDENTIFIER>.Variable = ...`
  As a normal non-container definition of the form `User_Tag.<TAG_IDENTIFIER>` (without selector), but AdaBrowse performs environment variable substitution on the value.

### 7.4. Parameters of User-Defined Tags

(Introduced in V2.1)

User-defined HTML tags may also have parameters. AdaBrowse considers anything after the tag identifier in an opening tag up to the closing "`>`" the parameters of the tag. This is similar to standard HTML (where parameters are called "attributes"). Consider e.g.

        <A HREF="http://www.somewhere.org/" TARGET="_top">

In AdaBrowse's terms, this tag has two parameters: one has the name `HREF` and the value `http://www.somewhere.org/`, and the other one is named `TARGET` and has the value `_top`.

Parameters of user-defined tags work in exactly the same way. Any valid parameter has a name, and is defined using an equal sign followed by the value. If the value is quoted (a double quote sign (`"`) follows the equal sign immediately), the enclosing quotes are stripped off. Note that there mustn't be any white space between the equal sign and the parameter name or the value!

Parameters make only sense if they can be referenced in some way and the referenced parameter inserted in some way in the user-defined key's expansion at macro substitution time. The syntax for parameter references is similar to the syntax used for environment variable references as explained below, except that the initial character introducing a reference is not the "`$`" sign but the "`%`" sign. Of course, indirect and recursive references for parameters don't make much sense and therefore are not allowed.

At macro substitution time, any parameter reference in the definition of a user-defined HTML tag is replaced by the value of the corresponding parameter. The following examples show how this can be used:

- Define an HTML tag that includes any file given:

      User_Tag.INCLUDE_ANY.Include = %File

  A tag `<INCLUDE_ANY FILE="../somefile.html">` will then be replaced by the contents of file `../somefile.html`. Another tag `<INCLUDE_ANY FILE="other.html">` will be replaced by the contents of file `other.html`. And an `INCLUDE_FILE` tag that doesn't have a parameter named `File` will be silently ignored, since references to undefined parameters are replaced by the empty string.
- Pass parameters to an external command:

      User_Tag.RUN_IT.Execute = some_program %Params

  A tag `<RUN_IT PARAMS="-I.. -I../something -q -x">` will then run the command "`some_program -I.. -I../something -q -x`" and replace the tag with the output of this command.
- Pass on some parameters to other tags (standard or user-defined):

      User_Tag.MY_TAG.Before = <SPAN %{Class:+Class="%Class"}>
      User_Tag.MY_TAG.After  = </SPAN>

  A fragment like `<MY_TAG CLASS="something">Text</MY_TAG>` will then be replaced by `<SPAN Class="something">Text</SPAN>`. Note that the value of `%Class` is just `something` (without the quotes, see above)! Occurrences of `MY_TAG` without a `Class` parameter will expand into a `SPAN` tag without parameters. (That's the definition of the "`:+`" operator used in this example, see below for more information.)

Because the form used in the last example ("`%{Param:+Param="%Param"}`") is so common, the syntax `%{!Param}` is used as an abbreviation for this. (In other words, the syntax of indirect references is redefined (or misused) to expand to the name of the parameter, followed by an equal sign and the value of the parameter within quotes if the parameter exists, and the empty string otherwise.)

The special parameter name `%` is defined to denote all parameters of the user-defined HTML tag. I.e., a reference of the form "`%%`" or "`%{%}`" is replaced by whatever followed the tag identifier up to the closing "`>`" sign. Example:

        User_Tag.MY_TAG.Before = <SPAN %%>
        User_Tag.MY_TAG.After  = </SPAN>

effectively defines `MY_TAG` as an alias for `SPAN`.

Note an important difference between the substitution of tag parameters and the substitution of environment variables: environment variables are replaced when the configuration file is read, whereas tag parameters (logically) are replaced when an occurrence of the user-defined tag is found in an Ada comment and is to be rendered as HTML.

## 8. Environment Variable Substitution

Environment variable substitution occurs when the declaration in the configuration file is read and can thus never interfere with the later macro substitution of user-defined HTML mark-up.

### 8.1. Syntax and Semantics

AdaBrowse uses for environment variable substitution a syntax very similar to that of the GNU `bash` shell. An environment variable has a name, which is an identifier as defined above. A simple reference to an environment variable has the form

        $Identifier

and is replaced as a whole (including the '`$`' sign) by the variable's value or by the empty string if no such environment variable is defined.

More interesting are the complex variable references, which have the syntax

        Value         = any string, maybe containing environment variable references.
        Operator      = :- | :+.
        Reference     = ${Variable_Name[Operator[Value]]}.
        Variable_Name = Value | !Identifier.

In all forms, `Variable_Name` can have one of three formats:

- An identifier: expands to the empty string if no such environment variable is defined, and to the variable's value otherwise.
- A '`!`' and an identifier: expands the identifier as above, but then takes the result of this expansion as the name of another environment variable, which is then expanded. This is known as indirect expansion, and is limited to one level of indirection only.
- Some arbitrary string that may contain embedded references to environment variables: environment variable substitution is performed on the whole thing, and the resulting value is taken to be the name of an environment variable, which is then expanded. This recursive expansion is unknown in `bash`, and it is done for as many levels as specified.

The semantics of these forms is as follows:

`${Variable_Name}`
  Is identical to the simple form of references `$Identifier` except that it also allows indirect and recursive expansion.
`${Variable_Name:-Value}`
  Is replaced by the result of `${Variable_Name}` unless that result is empty, in which case it is replaced by the expansion of `Value`.
`${Variable_Name:+Value}`
  Is replaced by the expansion of `Value` if the result of `${Variable_Name}` is non-empty, or the empty string otherwise. (`:+` is the inverse of `:-`.)

Indirect expansion using the '`!`' character is supported only to keep the syntax as close to the one used by `bash` as possible. It is actually superfluous and can be replaced by the more powerful (and, so I think, simpler because more regular) recursive expansion: "`${!Some_Name}`" is identical to "`${${Some_Name}}`" or "`${$Some_Name}`".

In the operators `:-` and `:+`, the '`:`' is actually optional. It appears that it is optional in `bash` (although the manual doesn't say so), and I have therefore chosen to make it optional in AdaBrowse, too.

Within configuration files, AdaBrowse also supports two special "environment" variables named '`@`' and '`$`'.

`@`
  Is always defined and evaluates to the path component of the complete filename AdaBrowse used to open the file. This path has a trailing directory separator ('`\`' on Windows or '`/`' on Unix), unless we're on Windows and the path is a relative path on some other drive (as in "`C:some_file.cfg`"). If the filename has no path, "`$@`" is substituted by "`.\`" or "`./`", respectively.
`$`
  Also is always defined and evaluates to the raw filename (without path, if any) of the complete filename AdaBrowse used to open the file. I.e. "`$$`" or "`${$}`" is substituted by the filename of the configuration file.

The `@` variable is useful to refer to other files relative to the place the configuration file is at, rather than relative to the current directory from which AdaBrowse was invoked. Whether the `$` variable is useful at all I do not know :-), but it seemed only consistent to provide that, too. Note that "`$@$$`" gives the complete filename of the configuration file, whereas "`$@\$$`" won't expand the "`$$`" because the backslash escapes the '`$`' sign introducing the variable reference.

AdaBrowse performs environment variable substitution on the values of the following keys:

- `Compile`,
- `Include_File`,
- `Path....`,
- `Style_Sheet`, and
- `User_Tag....` with selectors "`.Execute`", "`.Include`", "`.Set`", "`.Variable`", and (new in V2.1) "`.Enabled`".

To include a literal dollar sign '`$`' in any of these keys' values, escape it with a backslash and write "`\$`". If, for some reason, you want to have a backslash immediately before a variable reference, and do not want to escape the dollar sign, escape the backslash by writing two backslashes before the dollar. The sequence "`\\`" immediately followed by a variable reference is replaced by a single backslash and the substitution of the reference. I.e., "`${SOME_PATH}\${SOME_FILE}`" won't do what is expected, but "`${SOME_PATH}\\${SOME_FILE}`" will (and there will be one backslash between the two variable substitutions).

### 8.2. Some Examples

- Include a configuration file, but only if a variable giving a prefix of its path is set:

      Include_File = ${PATH_TO_FILE:+$PATH_TO_FILE\file.cfg}

- To include the current date:

      User_Tag.Date.Set = date /t

  (or whatever the equivalent on Unix would be).
- To supply a default path, if an environment variable that should be set isn't:

      User_Tag.GMGPL.Include = ${ADABROWSE_HOME:-.}\gmgpl.html

- To specify a file relative to the location of the configuration file the key is in:

      User_Tag.XYZ.Include = $@some_file.html

- To enable a user-defined tag depending on the setting of some environment variable:

      User_Tag.SOME_TAG.Enabled = ${SOME_VAR:-False}

  Note that in this example, the environment variable `SOME_VAR`, if defined, must have one of the values "`True`" or "`False`"; otherwise an error will occur because the "`.Enabled`" selector is defined to accept only these two definitions. If the environment variable is not defined (or defined as the empty string), the "`:-`" operator makes this be treated as `False`.

## 9. Advanced Description Formatting

This section describes in detail how AdaBrowse formats Ada comments to generate descriptions for items. You can configure how AdaBrowse performs this formatting to a great extent, in fact, it is even possible to replace the built-in formatting completely.

### 9.1. Structure of a Description

As mentioned above, a description is a sequence of comments AdaBrowse extracts from the source file. In this section, I will refine this basic definition a little bit by introducing blocks.

#### 9.1.1. Comment Blocks and Prefixes

A comment block is any sequence of consecutive Ada 95 comment lines that start with the same prefix. When AdaBrowse formats a description, it goes through all comments of the description, and within each comment, through all blocks and formats the blocks according to the format instructions defined for the prefix of the lines in each block.

The default prefix is "`--`", so by default any Ada 95 comment forms one block. Additional prefixes for splitting a comment into blocks are defined by the configuration key `Format`:

        Format.<Prefix> = Format_Instruction

`<Prefix>` is a string, which must start with "`--`". AdaBrowse issues an error if the string doesn't start with "`--`". Any consecutive comment lines (beginning with the "`--`" in the Ada source) that start with the same prefix belong to one comment block. If several prefixes match, the longest match wins.

As with most configuration keys, later definitions of a format for the same prefix override earlier definition for that prefix. A definition of a "`Format`" key with an empty right-hand side (i.e., only white space in the value after the "`=`") removes the comment prefix and any format instructions previously defined for it, except in the case of the standard prefix "`--`" (which cannot be removed) where such an empty definition reverts to the default formatting.

The prefix "`--`" is predefined as if a key "`Format."--" = ...`" was defined as the very first configuration key. This definition defines the default formatting AdaBrowse uses, and it can be redefined by an explicit definition of the configuration key `Format."--"`. Such later redefinition can be removed by defining the configuration key with an empty value, which makes AdaBrowse use the built-in default formatting as already mentioned above.

The Format Instruction for a given prefix defines how the content of a particular comment block is to be formatted. Note that if you use several prefixes, it would be a very good idea to make sure that all comment blocks are self-contained, i.e. that no HTML entities cross blocks. This is a direct consequence of AdaBrowse's formatting process, which formats block after block. Obviously, this can get misdirected if blocks are not self-contained.

To show how different format instructions for different blocks can be used, consider the following example:

| Assume our Ada sources contain not only normal Ada comments starting with "`--`", but also comment lines starting with "`--!`" that shall somehow be formatted specially, for instance these lines might contain sample code. We can now define a comment prefix
        Format."--!" = some format instructions
to make AdaBrowse format any such comment lines e.g. by including them verbatim in a `<PRE></PRE>` block. (I'll soon explain how to write such a format instruction below.) As a result, a comment like
        ------------------------------------------------------
        --  This is an example usage of procedure @Foo@:
        --
        --!   declare
        --!      X : Integer := 42;
        --!   begin
        --!      Foo (X);
        --!   end;
        --
        --  Note that @X@ must not be zero!
        ------------------------------------------------------
will be split into three blocks:
        --  This is an example usage of procedure @Foo@:
        --
        --!   declare
        --!      X : Integer := 42;
        --!   begin
        --!      Foo (X);
        --!   end;
        --
        --  Note that @X@ must not be zero!
The first and the last block will be formatted according to the default rules (we didn't redefine `Format."--"`), whereas the middle block will be formatted according to our own rules. Note that to just have something enclosed in `<PRE></PRE>` tags, a special format is maybe overkill: in new sources, you could just as well directly enclose the example code in `<PRE></PRE>` tags yourself. However, if you have legacy code, you may not want to modify it to produce HTML documentation, or you may want to do more complex formatting. In these cases, the format instructions come in handy.

### 9.2. User-Defined Formatting

This section explains how to define format instructions for comment blocks.

#### 9.2.1. Format Instructions

AdaBrowse recognizes the following format instructions, which define how it should format the content of a comment block:

`swallow`
  Swallow the block, i.e. replace it by an empty string. The whole block will not appear at all in the generated HTML file.
`entities`
  AdaBrowse puts the whole content of the block as-is into the generated HTML file. It doesn't parse the HTML, but blindly replaces all special characters (such as "`<`" or "`"`", or characters beyond the 7-bit ASCII range) by named character entities. Note that if the block does contain HTML mark-up, this will effectively disable the mark-up (because all "`<`" characters will be replaced by `&lt;`, even if they started a HTML tag). This filter is intended primarily for legacy code where it is known that comments do not contain any HTML mark-up.
  Note that because the `entities` filter blindly replaces special characters, it should come before any filter that inserts or modifies tags. To replace special characters without affecting existing HTML mark-up, use the `plain` filter instead!
`plain`
  AdaBrowse replaces special characters by character entities, e.g. all quotes not within a tag are replaced by `&quot;`; any "`<`" that doesn't belong to a tag is replaced by `&lt;`, and so on. The difference to the `entities` filter is that this filter does parse the HTML mark-up and preserves it.
`hr [strip | replace]`
  Defines how AdaBrowse shall handle comment lines that contain only the prefix followed by dashes. Such lines may occur within a description (the global processing only strips the first and last line of a whole comment if they contain only dashes, but not interior comment lines). Possible values for `hr` are:
  `strip`
    Replace such separator lines by an empty line.
  `replace`
    Replace separator lines by `<HR>`.

  If only "`hr`" appears (i.e., without "`strip`" or "`replace`" following), the default behavior is `strip`.

`strip_comments`
  Removes all HTML-comments.
`enclose (string, string)`
  AdaBrowse encloses the whole block by prefixing it with the first string and appending the second string. Typically, the strings will contain HTML mark-up, and if `enclose` is followed (in a pipe) by `expand`, they may even contain user-defined HTML mark-up.
  AdaBrowse does not verify that the two strings correspond in any way, so if you define nonsense parameters such as `enclose ("<!--", "")`, you will get nonsense HTML output. Typically, the first string will contain some container-opening tags, and the second one the corresponding closing tags in the right order. Both strings must be present (even though they may be empty). Embedded double quotes in a string must be doubled as in Ada 95.
`pre`
  AdaBrowse encloses the whole block in `<PRE></PRE>` tags, i.e. `pre` is short-hand for `enclose ("<PRE>", "</PRE>")`.
`expand`
  AdaBrowse performs macro replacement of user-defined HTML entities as described above.
`unknown_tags [all | standard]`
  AdaBrowse converts all references to unknown HTML entities (i.e., unknown tags) to text by replacing all special characters, notably the opening `<` and the closing `>`, by character entities. In other words, "`<UNKNOWN>`" becomes "`&lt;UNKNOWN&gt;`".
  The optional parameter defines whether the filter considers only the standard HTML 4.01 tags as known (`unknown_tags standard`), or whether user-defined tags also shall be considered as known (`unknown_tags all`). Default is `standard`, i.e., any remaining user-defined tags will be replaced by their text equivalent.
`shortcut`
  AdaBrowse replaces all occurrences of pairs of "`@`" without whitespace in between by `<CODE>` and `</CODE>`, respectively, as described above.
`para`
  AdaBrowse assumes that an empty content line indicates a new paragraph and inserts `<BR>` or `<P>` tags as appropriate.
  This format instruction is smart: it won't change anything inside `<PRE>` blocks, and it also will never insert `<BR>` or `<P>` tags where they would be illegal (such as directly inside a `<UL>`).
`lines`
  AdaBrowse tries to maintain the original line structure of the Ada comment by replacing all white space outside HTML tags by `&nbsp;` and adding a `<BR>` at each end-of-line outside HTML tags, unless the line already ended in a `<BR>`.
  This format instruction will only do this wherever such processing is allowed. E.g., it won't change anything in a `<PRE>` block (because there, it is unnecessary), and also won't do anything if the last tag was e.g. `<UL>` (because inside an unordered list, the only tag allowed is `<LI>`). Inside each `<LI>`, however, it will transform the text.
`standard`
  This is a shortcut for the pipe "`expand | strip_comments | unknown_tags standard | hr strip | para | shortcut | plain`", which defines the standard formatting AdaBrowse uses by default.
`execute [end-of-line] (command)`
  This is the most powerful format instruction. It tells AdaBrowse to run the `command` to format a comment block, passing the block on the command's `stdin`. AdaBrowse reads the command's output (`stdout`) and treats that as the result of the formatting.
  The optional `end-of-line` specification may be useful if the command assumes an end-of-line convention other than the one normally used on your operating system. (This happens for instance for me when I use the Cygwin utilities on Windows; Cygwin `sed` wants single LFs, whereas the normal end-of-line marker on Windows in CR-LF, which apparently confuses `sed`. I do not know whether this is "normal" or some installation problem on my machine, but anyway AdaBrowse has a way to get around such difficulties.)
  To properly handle such pathological cases, you can define precisely what end-of-line convention AdaBrowse shall use for the input to the `command`. Possible values of `end-of-line` are `CR`, `CRLF`, and `LF`. By default, AdaBrowse uses whatever is the standard convention on the operating system it runs on.
  The closing parenthesis of an `execute` filter is defined to be the next right parenthesis ("`)`") not within a string (delimited by ", ', or the backquote `; embedded string delimiters are assumed to be escaped by a backslash) and on the same nesting level, where the nesting level is given by the nesting of parenthesized pieces of text enclosed by round parentheses ("`(`" and "`)`") or curly braces ("`{`" and "`}`").
  If the `command` is empty or contains only whitespace, AdaBrowse issues an error. It also issues an error and terminates if the command fails for any reason.

The parsing of format instructions always is case insensitive, e.g. all of "`STANDARD`", "`standard`", "`StAnDaRd`", or any other combination of upper and lower case letters is recognized as the format instruction `standard`.

All of these format instruction except `entities` and `execute` skip any HTML comments they encounter. Hence, `expand` will not expand user-defined tags inside HTML comments, `para` will not do anything inside an HTML comment, and so on. However, any command called by an `execute` instruction will have to deal with HTML comments as it sees fit.

#### 9.2.2. Pipes

All these format instructions are filters that transform their input in some way to produce output. As a consequence, combining these is possible using the "`|`" pipe operator. It's an infix, left-associative operator. The syntax of a pipe is

        Pipe = Format_Instruction | Pipe "|" Format_Instruction.

And the semantics is that the output of the left operand is piped into the input of the right operand. The output of the pipe is the output of its right operand, and the input to a pipe becomes the input of its left operand. Note that grouping by parentheses is not allowed in a pipe, and would be superfluous anyway.

Note that in the `expand` filter, most user-defined HTML tags are expanded recursively, i.e., if their expansion contains further user-defined tags, these are expanded in turn. However, this is not the case for user-defined tags defined using the "`.Include`" or the "`.Execute`" selectors. If you want to use user-defined tags in the results of such mark-up definitions, you should define a format instruction that has several `expand` filters in a row. E.g. the format instruction

    Format."--" = expand | standard

would in a first step expand all user-defined HTML tags, and then (because `standard` contains an `expand` filter) expand all remaining user-defined tags again. Note that any user-defined tags remaining after the first `expand` filter must have come from an expansion of an "`.Include`" or "`.Execute`" tag.

If you use the `execute` filter, make sure that the command does terminate! If the called command blocks, AdaBrowse will block, too.

Some combinations of format instructions within a pipe make no sense. For instance, after a `pre` filter, `para`, `lines`, or `standard` don't make much sense because both `para` and `lines` leave anything within a `<PRE>` block untouched. The combination of `para` followed by `lines` or `pre` within the same pipe also is pretty useless. You also should make sure that any "`hr replace`" filter appears before an eventual "`para`" filter, otherwise the result may not be what you expect. AdaBrowse does not check for such bizarre combinations, so make sure you understand what each filter does, and write sensible pipes! Otherwise, the final result may become hopelessly garbled.

Also note that AdaBrowse does not try to correct already invalid HTML stemming from the Ada comments. So, if your HTML is incorrect to begin with, all bets are off as to what the final result will be, and whether and if so, how it will be rendered by a browser.

#### 9.2.3. The Default Formatting

The standard formatting is defined by

    Format."--" = expand | strip_comments | unknown_tags standard | hr strip | para | shortcut | plain

which is the same as

    Format."--" = standard

You can redefine this standard formatting by overriding the key `Format."--"` explicitly in a configuration file.

#### 9.2.4. An Example

As an example of an `execute` filter, consider how a simple look-alike of the `lines` filter could be implemented using `sed`:

    Format."--!" = execute (sed -e"s/^\(.*\)<BR>$/\1/" \
                                -e"s/[[:blank:]]/\&nbsp;/g" \
                                -e"s/^\(.*\)$/\1<BR>/") | \
                   plain

The first `sed` expression removes any trailing `<BR>` to avoid inadvertantly doubling `<BR>`s. The second expression replaces all white space by `&nbsp;`, and the third finally appends a `<BR>` to each line. That's more or less what the predefined `lines` filter does, except that this definition assumes that there are no HTML tags in the input (the `lines` filter is smarter: it only replaces whitespace and only adds `<BR>` in text outside HTML tags).

If the above `execute` filter does not work for you, you're probably on Windows and are using the Cygwin `sed`. In that case, you should instruct AdaBrowse explicitly not to use the host end-of-line indicator (which would be CR-LF), but the Unix format, which is a single LF. In that case, you should use the format instruction

    Format."--!" = execute lf (sed -e"s/^\(.*\)<BR>$/\1/" \
                                   -e"s/[[:blank:]]/\&nbsp;/g" \
                                   -e"s/^\(.*\)$/\1<BR>/") | \
                   plain

Note that due to the way configuration files are read, we might also write this definition with embedded comments:

    Format."--!" = execute (sed -e"s/^\(.*\)<BR>$/\1/" \      # Remove existing <BR>s
                                -e"s/[[:blank:]]/\&nbsp;/g" \ # Replace whitespace
                                -e"s/^\(.*\)$/\1<BR>/") | \   # Add <BR>s
                   plain

The comments are removed before any further processing, and the command to be run is in all three cases

    sed -e"s/^\(.*\)<BR>$/\1/" -e"s/[[:blank:]]/\&nbsp;/g" -e"s/^\(.*\)$/\1<BR>/"

Redefining the formatting for the standard comment prefix may be useful for processing legacy sources that don't use HTML markup for formatting in the comments. Some possibilities to get reasonably looking HTML output without modifying such sources are:

- `Format."--" = hr strip | entities | lines`, or
- `Format."--" = entities | enclose ("<DIV CLASS=""LineStructure"">", "</DIV>") | hr strip`, with a style definition in the style sheet like

          DIV.LineStructure {
            white-space : pre
          }

- `Format."--" = entities | pre | hr strip`, which also uses a monospaced (non-proportional) font.

Note, however, that the CSS 2 standard allows conforming user-agents (browsers) to ignore the `white-space` property! Hence the second example may or may not produce the desired result.

Also note that the `entities` filter must come before the `enclose` filter; otherwise, it would replace e.g. the "`<PRE>`" inserted by the `enclose` filter by "`&lt;PRE&gt;`", and thus the tag would not be interpreted by a browser but rather be displayed!

## 10. XML Output

As of version 3.0, AdaBrowse can also generate XML output in addition to HTML output. This opens the door for generating other document formats than HTML: just translate the XML into your favorite format, e.g. `docbook` or `texinfo`. This saves you the need to write your own Ada parser if you'd like to have e.g. a `docbook` documentation instead of HTML: you just need to write a `docbook` generator that takes the AdaBrowse XML as input, which should be relatively simple, given that there are numerous XML parsers available. And it saves me the trouble of having to provide built-in generators for any odd format.

Some publicly available XML parser tool kits are e.g. XML/Ada (for Ada 95), or Xerces (Java, C++, Perl), and there are many others. It might even be possible to use XSLT stylesheets to transform the AdaBrowse-generated XML into other formats; for this, you'd need an XSLT processor such as Xalan (Java) or `xsltproc` (C). (I recommend the latter: it is small, fast, and works. You'll also need `libxml2`; a Windows port of `xsltproc` also exists: download `libxml`, `libxslt`, and `iconv`.) Another suggestion is the Saxon/Ælfred (Java). If you work on Windows, also be sure to get Markus Hoenicka's excellent guide to setting up an SGML/XML editing and publishing system on Windows NT.

The generated XML complies to the XML 1.0 DTD included in the distribution. This DTD is also available at the URL `http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/xml/adabrowse_2_0.dtd`. It is thus possible to process the generated XML using any odd off-the-shelf XML 1.0 compliant XML parser. I do not claim that this DTD was a prime example of how a DTD should be written; it has been developed in a rather ad-hoc fashion. However, it captures all the necessary information and complies to XML 1.0, and thus (hopefully) fulfills its intended purpose, namely to serve as an intermediary representation for generating other document formats than HTML.

You switch on XML generation using the "`-G`" option giving the output format name "`xml`". It is possible to generate only XML using "`-G xml`", or to generate both HTML and XML at the same time using "`-G xml html`".

The XML output generates one single file containing the XML for all units processed. This file is has a default file name of "adabrowse.xml" in file input mode and of the name of the input unit with extension "xml" if only one file is being processed and is written to:

- If the `-o` option specifies a file name: to that file, with extension "`xml`".
- If the `-o` option specifies only a path: to a file named as specified above in the given directory.
- If the `-o` option specifies `stdout`: to `stdout`.
- If no `-o` option at all is given: to a file named as specified above in the current directory.

This XML file contains all the information contained in the HTML file: it mirrors the exact structure of the HTML, and includes all cross-references. Descriptions are already grouped together with the item they belong to. The XML newly (since V4.0) also does contain the indices.

Descriptions are not processed in any way (i.e.; all filter definitions are ignored) except for replacing all special characters by their character entities. Hence there is no replacement of user-defined tags or other automatic formatting: the XML contains the raw comments. If you use user-defined tags and so on, your XML-to-whatever translator will have to deal with them.

There are no implicit formatting assumptions in the XML (as e.g. in the `PRE` in HTML). All lines are represented by an XML element `LINE`, both in source excerpts and descriptions.

XML generation ignores the following options: `-l` (cross-references in XML always have both the line and the column number), and `-s`.

XML generation honors the following configuration file keys: `Compile`, `Char_Set`, all the `Description.*` keys, all the `Index` and `Rule` keys, `Exclude`, `Include`, `Include_File`, `No_XRef`, `XRef`, and `Refs_To_Standard`. All other configuration file keys have no effect on the generation of XML (but they are still parsed, and if incorrect, may cause error messages to be generated).

## 11. Rebuilding from sources for a GNAT version

### 11.1 Why does AdaBrowse work only with a specific GNAT version?

AdaBrowse uses ASIS to produce precise cross-references in the generated HTML and to extract semantic information. The ASIS-for-GNAT library is specific to a particular GNAT version, and therefore, all ASIS applications also are specific to the GNAT version the ASIS library used is for.

AdaBrowse won't work with the FSF GNAT contained in gcc 3.x, because there is no ASIS implementation for that compiler. See also below.

### 11.2 Rebuilding

AdaBrowse works ok with versions of GNAT >= 3.14p. To rebuild AdaBrowse from the sources, follow these steps:

1. Get ASIS-for-GNAT for your GNAT version.
2. Apply the following corrections to the ASIS-for-GNAT you got:

   GNAT version | Correction to make in ASIS-for-GNAT:
   --- | ---
   3.14p | Get the version string of your GNAT compiler by compiling something with the options `gcc -c -gnatv`. GNAT writes its version string (e.g. "`3.14p (20010503)`"). Open the ASIS source file `./gnat/gnatvsn.ads` and make sure that the `GNAT_Version_String` there is exactly the same. (When I downloaded ASIS-for-GNAT 3.14p, there was a blank missing.) If the strings differ, change `gnatvsn.ads` to match what GNAT wrote. If you fail to make this correction, the ASIS libraray will not work at all (it'll always report an inconsistency between the compiler version and the ASIS library version.)
   3.15p | No corrections needed.
   3.16a | No corrections needed.
   3.16a1 5.01a | Remove line #295 from file `./asis/a4g-contt-pd.adb` (the one reading "`Result_Unit_Id_List := Nil_Unit_Id_List;`"). Without this correction, the "`-all`" option of AdaBrowse will not work; ASIS-for-GNAT will always raise a `CONSTRAINT_ERROR`!

3. Install ASIS-for-GNAT.
4. Make sure the path to your ASIS-for-GNAT installation is in `ADA_INCLUDE_PATH` and `ADA_OBJECTS_PATH`.
5. Run the make file by typing `make` in the adabrowse directory.

The above procedure will produce an AdaBrowse without support for the GNAT project manager. If you have GNAT 3.15p or later, you may rebuild an AdaBrowse with project manager support as follows:

1. Get, correct and install ASIS-for-GNAT for your GNAT version.
2. Make sure the path to your ASIS-for-GNAT installation is in `ADA_INCLUDE_PATH` and `ADA_OBJECTS_PATH`.
3. Get the compiler sources for your GNAT version and put them into a directory, e.g. `C:\gnat-3.15p-src\`. Do not include this directory in the `ADA_INCLUDE_PATH`!
4. Set the environment variable `GNATSRC` to the directory in which the compiler sources are. (Note that the sources are in a subdirectory `src/ada`, so you'd have to set it to `C:\gnat-3.15p-src\src\ada` in the above case.)
5. Go to the directory where you had unpacked the AdaBrowse source distribution and type `make`.

Steps 4 and 5 can also be combined by simply changing to the directory where you had unpacked the AdaBrowse source distribution and typing the command

       make GNATSRC=C:/gnat-3.15p-src/src/ada

(You can use forward slashes even on Windows.)

Do not include the GNAT source directory in `ADA_INCLUDE_PATH`! Because the GNAT source distribution contains both the compiler and the library sources, this will screw up things completely unless you know exactly what you're doing. The typical outcome is that you will no longer be able to link because "system.ads has been modified".

The make file is smart enough; so just leave any such issues to the makefile. It knows what it's doing, if you permit me the anthropomorphism. Just tell it where the GNAT sources are by setting `GNATSRC` (it's smart, but it can't read your mind :-), and then let it do its job.

If this does not configure AdaBrowse to use the project manager, then either the environment variable `GNATSRC` was set wrongly, or your compiler doesn't have a project manager, or it is a compiler newer than GNAT 3.16a and has an incompatible project manager, or the make file incorrectly figured out the location of the installed ASIS library.

If any of these things happen, the make file will produce an AdaBrowse without project manager support. You'll have to figure out yourself what went wrong.

I have tested the make file using GNU make 3.79.1 on Windows 2k and with GNU make 3.77 on Windows NT; it may fail with other versions of GNU make or with other make utilities or on other operating systems (though I believe it should work fine on Linux, too). If the make file fails and doesn't build any executable named "adabrowse", the source distribution can, as a last resort, also be compiled using the commands

       make adabrowse

or

       gcc -c -O2 util-nl.c
       gnatmake -O2 adabrowse -largs -lasis

Both will build an AdaBrowse using "gcc" as the default compiler name and not having project manager support.

If the make fails, and you're sure you did everything correctly, I'd like to know about it so that I can try to figure out what went wrong and correct the make file. See "Reporting Bugs" below. I'll need to know your operating system, make version, GNAT version, ASIS version, AdaBrowse version, the command you used to run the make file, and your complete environment (all environment variables and their values), and a valid e-mail address of yours.

(Although, if you're using the ancient GNU make 3.77, I'd much rather you upgrade to GNU make 3.79.1. Version 3.77 has just too many bugs, and I don't know why it is in the GNAT 3.15p distribution. 3.79.1 has been out for quite some time... Windows users can get an executable of an up-to-date GNU make (3.79.1 or 3.80, although I have no idea how stable the 3.80 version is -- I don't have it, and I didn't test with it) from the MinGW site.)

## 12. Rebuilding from sources for other compilers (not GNAT)

The procedure is basically the same:

1. Get and install an ASIS implementation for your compiler.
2. Verify that the compiler can find and use the ASIS library.
3. Watch out for implementation-defined ASIS features used in AdaBrowse:
   - GNAT-specific pragmas `License` on all units. These may cause compilation warnings when compiled with some compiler other than GNAT.
   - Implementation-defined options passed to `Asis.Ada_Environments.Associate` in file `adabrowse.adb`.
   - ASIS-for-GNAT-specific exception handling in `adabrowse.adb`.
   - AdaBrowse uses `GNAT.Os_Lib` in a few places. You'll need to replace that as appropriate in files `util-pathes.adb` and in `ad-file_ops.ad[bs]`.
   - Make sure package `AD.Projects.Impl` is a renaming of `AD.Projects.Impl_No`. (Your compiler most probably doesn't come with the GNAT project manager, I suppose.)
4. Build the adabrowse application.

If it doesn't work, you're on your own. I cannot maintain or support versions of AdaBrowse except the one I distribute myself. (If it doesn't work due to some bug in your ASIS implementation, and you can find a simple work-around, and that work-around doesn't break the latest version of AdaBrowse for GNAT, I'm willing to incorporate your bug fix. But otherwise, I won't deal with such problems.)

## 13. Testing

I have tested AdaBrowse with ASIS-for-GNAT 3.15p and 3.16a, using the test files in subdirectory ./simple_test and a large (some 56 ada specs) subsystem containing a pretty complex data structure library of mine. (The Generic Ada Library GAL, of which some files are included in this distribution. I'll publish that when I have done some more testing.).

For these tests, I have checked the generated HTML with Netscape 4.76, MS IE 5.0, and Mozilla 1.4, and it is rendered reasonably by all three.

I have also run AdaBrowse over the following, large libraries:

- adabindx 0.7.2,
- the ASIS-for-GNAT 3.14p sources,
- a subset (all the `as[go]c*.ads`) of Corey Minyard's ASL (asl-1.4),
- Simon Wright's Booch Components (bc-20010819),
- Matthew Heaney's charles (20020228),
- RR Software's CLAW 1.3 Introductory Edition,
- GtkAda 2.0.0,
- Mats Weber's components (except those files GNAT 3.14p failed or crashed upon),
- Ted Dennison's OpenToken 3.0b,
- J. Carter's pragmarc (from 01-DEC-2001),
- Stephen Leake's SAL 1.03,
- TASH 8.3.2a,
- Gautier de Montmollin's UnzipAda 0.9,
- Stephen Leake's Windex 1.06,
- The complete Ada 95 standard library and the run-time library of GNAT, and
- XML/Ada 0.7.1.

AdaBrowse handles all of these without problems, and I didn't see any obvious problems in a cursory inspection of some of the generated HTML files. All of the generated files have been checked to comply to the "HTML 4.01 Transitional" DTD.

Version 3.0 of AdaBrowse is the result of a major rewrite of the complete output part of AdaBrowse. It has been regression tested by comparing it against the output of V2.13 for all the above test subsystems. The only differences found are either small layout improvements of V3.0 over V2.13, or are due to the improved cross-reference generation of V3.0 for implicitly inherited items and items from instantiations of nested generics, which actually came out wrong in V2.13.

The new indices of V4.0 have been cross-checked against the old indices of V3.4.2; no significant differences were found.

The new XML output of V3.4 (and also of V4.0) has been verified to comply to the DTD contained in the distribution using Xerces 2.0.0.

## 14. Known Problems

1. If AdaBrowse runs an external command, and that command does not terminate, AdaBrowse will be blocked, too.
2. Both Netscape and MS IE sometimes produce an extra line at the end of a preformatted block. I.e. the HTML fragment

   `<PRE>`This is some code.`</PRE>` Followed by other text.

   is rendered as

       This is some code.
   Followed by other text.

   As a result, most code chunks put into the generated HTML page have such a trailing empty space, which sometimes makes the layout a bit awkward.
   This is a problem with the browsers' rendering of HTML. There's nothing whatsoever in the HTML 4.0 spec that would justify this empty space. But there's also nothing I can do about it.
3. If you use the `-all` option, comments after a library-level subprogram or generic instantiation or generic renaming are found only for the top unit but not for the other units. This is due to a problem in ASIS-for-GNAT, which somehow doesn't seem to give access to these source lines.
4. ASIS-for-GNAT only finds the "known child units" if their tree files exist and can be found. Hence, if you let AdaBrowse generate the tree files on the fly, you'll generally not see any known child units. However, if you generate the tree files for all units and then run AdaBrowse, ASIS will find them, and AdaBrowse can generate a meaningful section for the known child units.
5. In some rare cases, AdaBrowse may fail to generate completely accurate cross-references. This is caused by bugs in ASIS-for-GNAT, in particular in the area of formal packages. I do my best to work around these bugs and try hard to generate cross-references that point at least to the correct file, but in some cases, the source position returned by ASIS is bogus, and there's nothing I can do about that. However, these cases are so rare that you'll most probably not even notice them. If you notice wrong or missing cross-references, check the HTML source generated. If it contains a comment just before the suspicious place saying something about an ASIS failure, the cross-reference is wrong or missing because of a known ASIS problem, and it's no use reporting this as a bug.
6. Not really a problem, but I've been asked whether I'd produce a version of AdaBrowse for Ada 83. No, I won't, for I have neither an Ada 83 compiler nor an Ada 83 ASIS implementation. However, GNAT has an option `-gnat83` which makes it compile using the Ada 83 rules. If it still can generate tree files when this option is set, and if ASIS-for-GNAT can work with such tree files, then AdaBrowse also will work. (I didn't try it!) Hence I see no pressing need for a special Ada 83 version of AdaBrowse.
7. AdaBrowse won't work (yet) with the FSF GNAT in gcc-3.1. The problem is that there is currently no ASIS implementation for that compiler. Since AdaBrowse uses ASIS, there needs to be an ASIS for the FSF GNAT to make AdaBrowse work with it. Once there'll be such an ASIS, it'll be a simple matter of recompiling AdaBrowse to get it to work with the FSF GNAT. (I do not know what ACT's plans in that respect are. I hope they'll put their ASIS-for-GNAT into the FSF CVS tree once gcc-3.1 has stabilized and is out. If they don't, I fear somebody will have to write an ASIS implementation for the FSF GNAT.)
8. Not a problem: I've been asked whether I'd agree to have AdaBrowse put into the FSF CVS repository (and, supposedly, into the FSF GNAT distribution). I have no objections, but again, there needs to be an ASIS for the FSF GNAT first.

## 15. License

AdaBrowse is copyright © 2002-2003 by Thomas Wolf `<twolf@acm.org>`.

AdaBrowse is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

AdaBrowse is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License with this distribution; see file GPL.txt. If not, write to the `Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA` or try the URL http://www.gnu.org/licenses/gpl.html.

Some of the sources (all the `gal*.ad?`) files are part of a not-yet-released library of mine; these are subject to the "GNAT modified GPL" (GMGPL), which is the GPL but explicitly allows using these units without causing such use to make the using executable automatically fall under the GPL.

All the `util*.ad?` files are an extract of my `Util` subsystem available at the URL http://home.tiscalinet.ch/t_wolf/tw/ada95/util/. These, too, are covered by the GMGPL.

## 16. Reporting Bugs and Enhancements

Send bug reports and enhancement propsals to `<twolf@acm.org>`. Use a subject line containing the text "AdaBrowse".

For bug reports, I need:

- Your complete system setup: OS, GNAT version, ASIS-for-GNAT version, AdaBrowse version, settings of environment variables such as `ADA_INCLUDE_PATH` and `ADA_OBJECTS_PATH`.
- The complete sources on which the problem is shown. Preferrably reduced to the minimum necessary and in gnatchop format! (Not the AdaBrowse sources [I have those :-)], but the ones you tried to run AdaBrowse on!)
  If the error occurs on sources from a publicly available, downloadable library, you may also just send me a link to the download location and tell me which file causes troubles.
  I can also handle .zip, .tar.gz, .gz, and .bz2 files. Any other funny compression or encoding will not be accepted.
- Any configuration files and style sheets used.
- The exact command and/or shell script you used for calling AdaBrowse.
- All output produced by AdaBrowse: HTML files, error and warning messages on `stderr`, etc.
- A clear, precise, and comprehensible description of the error (what you think is wrong) in English (or, if you prefer, in German or French).
- A valid e-mail address of yours, so that I can contact you if necessary.

I can only maintain the AdaBrowse version I distribute myself. See above for AdaBrowse adapted to work with other compilers.