AdaBrowse
AdaBrowse |
|
For systems other than Windows NT/2k/XP, or compilers other than GNAT 3.15p or 3.16a (or 5.03a), download the source tarball and build AdaBrowse from the sources. See the User's Guide for information on how to build AdaBrowse from the sources. Note that AdaBrowse will not work with the FSF GNAT in gcc 3.x because there is no ASIS implementation for that compiler. (See also below.)
The distribution comes in all cases with an extensive User's Guide explaining just about everything about AdaBrowse as well as a couple of sample files that you can use to generate your first HTML documentation. It also includes instructions on how and where to submit bug reports.
You may also use the feedback page to send your comments to me.
Warning: HTML files generated by AdaBrowse 3.0 (and later) are not
compatible with files generated by earlier versions of AdaBrowse. AdaBrowse 3.0 (and
later) uses both the line and the column number to generate cross-references,
whereas earlier versions used only the line number. If you absolutely need to maintain
compatibility with files generated by earlier versions of AdaBrowse, use the new
-l option.
Note that the 3.16a AdaBrowse executable will tell you after "adabrowse -v" that it was actually an AdaBrowse 4.0.2 for "ASIS 2.0.R for GNAT 5.00 (20030120)". That's OK, it works well with GNAT 3.16a. Also see below.
AdaBrowse produces a fully cross-referenced HTML rendering of Ada 95 specs
(no bodies) similar to what javadoc does for Java sources. AdaBrowse is a
command-line utility; it has no graphical user interface.
AdaBrowse is highly configurable through command-line options, style sheets, and configuration files.
AdaBrowse completely takes apart the source code and produces a HTML documentation containing:
For each item, AdaBrowse also tries to extract comments from the source and uses them to produce a description of the item. Which comments are to be taken for which items can be configured in a configuration file.
If AdaBrowse is told to process several units, it can even generate a master index page containing links to all generated HTML documentation files.
AdaBrowse is Copyright © 2002 by Thomas Wolf. It is free software and is distributed under the terms of the GNU General Public License (GPL).
AdaBrowse is not a pretty-printer! Any source chunks in the generated HTML retain the formatting as in the source file (except for cross-referencing and syntax coloring).
Optionally, AdaBrowse can also generate XML output. The XML generated contains all the
structure, syntax coloring and cross-reference information contained in the HTML. The
generated XML files are well suited for further processing (e.g. translation into your
preferred document format such as docbook or texinfo). A
DTD
for the generated XML is included in the distribution and also available here at the
URL http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/xml/adabrowse_1_1.dtd.
As an example of what AdaBrowse can do, take a look at the
on-line documentation of my
Util subsystem. (This documentation
uses frames; try a no-frame version here.)
As another example, you can download the complete HTML reference of the Ada 95 standard library, including the GNAT additions (237kB). This set of HTML files has been generated using AdaBrowse 2.12 from the GNAT 3.14p standard library sources.
adabrowse (-h | -help | --help | -?)
adabrowse {-v | -version | --version | -f file_name | -a | -all | --all |
-c file_name | -s URL | -o file_name | -q | -x | -g |
(-i | -is | -p | -t) [filename] | (-I | -T) directory |
-G (html [xml] | xml [html]) | -l | -private | --private |
-P file_name | -X name=[value]}
The following options are available in AdaBrowse:
-h, -?, -help, --help
-a, -all, --all
-f option, but also for all application units on which it
depends semantically (transitive closure of "with"es and
parent units).-c filename
-c options may be given; the files are processed
the given order and may overwrite earlier config settings.-f filename
-f option may be given.-g
Standard". Note: This can also be set by a configuration file key
"Refs_To_Standard". The later definition wins.-G output_formats
-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).
-G" option is given, AdaBrowse behaves as if "-G html" were
given; i.e., by default, AdaBrowse generates only HTML output.
-i [filename]
-all option
is set and the output does not go to stdout.
filename is given, the index is written to that file (or to stdout, if the
filename is "-").
-is [filename]
-i, but generates an index using indentation for child units.-l
-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.
stderr.
-o filename
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.
stdout.
-p [filename]
-i, but generates a subprogram index over all units
processed.-P filename
-P option may be given. Note: if AdaBrowse has project manager support,
it writes its version with a lower-case 'p' appended when invoked with -v.-private, --private
-q
-s URL
-s option can be overwritten by a later -c option, if the
configuration file defines the key "Style_Sheet".-t [filename]
-i, but generates a global type index over all units
processed.-v, -version, --version
stderr.-x
-a option.)-X name=[value]
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
-I options may be given.-T directory
-T options may be given.
-f option
The -f option has three different formats:
-" 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- ...")
@", 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.
The first two cases are called the "file input mode" of AdaBrowse. The file may contain empty lines and comments (starting with the first "#" on a line and extending up to the end of the line), which are ignored.
In all three cases, a unit spec is a filename that may contain a path; a
possible suffix is ignored. Note that a unit spec is a file name; in other
words, you give test-gen, or test-gen.ads, and not
Test.Gen. The reason is simply that for most shell scripting languages,
it is easier to work with filenames that to massage them into unit names (e.g. by
replacing dashes by dots). Also, if you have krunched file names, there is no simple
connection between the file name and the unit name.
If a unit spec contains a path, the output file for that unit is placed into
that directory unless overridden by a -o option.
In file input mode, the -o option (if given at all) may either be
"-" (in
which case all output goes to stdout) or specify a directory, but must not
specify a file.
AdaBrowse assumes a GNAT-like naming scheme for source and HTML files. It also
assumes that there is one library unit per file. As of V1.4, AdaBrowse can handle
krunched file names in the -f option, provided it can find
a source file, and it has the extension ".ads". If so, AdaBrowse opens and parses
the source file to extract the unit name, instead of deriving it directly from
the file name. Note that generated files always have names based on the unit
name, not the original file name: i.e., output file names will never be krunched.
Generated HTML files always have the suffix ".html" (not ".htm").
If AdaBrowse is told to process several units (i.e., in
file input mode or if the -all option has been given),
the -i, -is, -p, or -t options enable
index generation, unless the output goes to stdout, i.e. the
-o- option has been given.
The unit index contains cross-references to all units processed. The type and subprogram indices contain cross-references to all types or procedures and functions in all units processed. All three indices can also be customized through entries in a configuration file.
-i generates a plain unit index, whereas -is generates a
structured unit index in which child units are indented. Indices always are sorted
alphabetically.
For the full version history, see the online User's Guide.
AdaBrowse is an ASIS application and as such tied closely to the version of the ASIS library it uses.
The prebuilt executables have been created with GNAT 3.15p/3.16a and ASIS-for-GNAT 3.15p/3.16a. Any AdaBrowse executable created with a GNAT and ASIS-for-GNAT with versions <= 3.15p (and including the GNATPRO versions 3.15a and 3.15a1) will only work with this precise GNAT compiler version, i.e. the one used to compile AdaBrowse itself.
As of GNAT 3.16a, the picture has changed. ASIS-for-GNAT 3.16a no longer does this strict version check but (in its default mode) only requires that the tree file be compatible. However, it has changed the tree format slightly: it now contains in the first four bytes the tree version number. (Previous versions of GNAT did not store that version number at all.) As a result, the 3.16a version of AdaBrowse should work with any GNAT with a version >= 3.16a unless ACT changes the tree version number. (The 3.16a AdaBrowse won't work with a GNAT 3.15p precisely because the tree file format has changed. But it might well work with a GNAT 3.16a1 or even a GNAT 5.00 - just give it a try! But if you have any of these compilers, you're probably a paying customer of ACT anyway and can thus get an ASIS-for-GNAT for your compiler version and then re-build AdaBrowse.)
AdaBrowse can be rebuilt from the sources for GNAT versions >= 3.14p. Although I tested AdaBrowse only on Windows NT and 2000, its only OS-dependency concerns the format of file names. It should run without changes on Unix platforms, too. Just rebuild it from the sources.
AdaBrowse will not work with the FSF GNAT in gcc 3.x. The 3.15p AdaBrowse fails because it has not been compiled with the FSF GNAT (and cannot be, as there is no ASIS implementation for the FSF GNAT). The 3.16a AdaBrowse fails because the FSF GNAT still creates tree files without the tree-version. (And maybe there are other differences between the tree files generated by GNAT 3.16a and the FSF GNAT...)
Thanks to David J.A. Koogler for suggesting implementing a master index generation. (And also for his extensive testing!) He also gave the initial idea for the user-defineable HTML mark-up.
|
 Copyright © 2002-2005 by
Thomas Wolf.
TW, Apr 28, 2005 |
|