adabrowse - Generate fully cross-referenced HTML rendering of Ada
95 specs
adabrowse [options] -f file
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
There are two ways to use adabrowse:
- 1.
- Call adabrowse for your spec: adabrowse -f file (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
gnatgcc -c -gnatc -gnatt file (with the appropriate
-I options, if needed.)
- 2.
- Call adabrowse for these specs: adabrowse -f file
(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.
- -h, -?, -help, --help
- Writes a comprehensive help text.
- -a, -all, --all
- 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 file
- 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 file
- 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
- 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 latter definition
wins.
- -G output_formats...
- 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).
- -i [file]
- 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 [file]
- Same as -i, but generates an index using indentation for child units.
- -l
- 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 [file]
- Define the output file name. If not set, the output goes to a file with
the name of the input and suffix .html. If file 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 [file]
- As -i, but generates a subprogram index over all units processed.
- -private, --private
- 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
- Quiet mode: do not issue warning or info messages. Synonym to -w0.
- -s URL
- 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 [file]
- As -i, but generates a global type index over all units processed.
- -version, --version
- 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
- If set, adabrowse never overwrites existing HTML files. (May be
useful in conjunction with the -a option.)
- -X name=value
- 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
- Define source paths for ASIS. Same semantics as for GNAT. Multiple
-I options may be given.
- -T directory
- Define paths for ASIS to search for tree files (*.adt). Multiple -T
options may be given.
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.)
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").
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). This
option is disabled in Debian.
- 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.
The Debian package of adabrowse does not have the Project
Manager feature; the command-line option -P project_file is
therefore disabled.
adabrowse and the accompanying documentation was written by
Thomas Wolf <twolf@acm.org>.
Ludovic Brenta <ludovic@ludovic-brenta.org> merely turned
part of the user's guide into this manual page for the Debian project.