Copyright © 2002-2005 by Thomas Wolf.
TW, Nov 18, 2003
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 AT acm DOT org>.
AdaBrowse is distributed under the GPL (the GNU General Public License, see
"License" below).
-f Option
<CODE>-Tag
AdaBrowse produces a fully cross-referenced HTML rendering of Ada 95 specs (no bodies) similar to what javadoc does for Java sources. AdaBrowse is a command-line utility; it has no graphical user interface.
AdaBrowse is highly configurable through command-line options, style sheets, and configuration files.
AdaBrowse completely takes apart the source code and produces a HTML documentation containing:
For each item, AdaBrowse also tries to extract comments from the source and uses them to produce a description of the item. Which comments are to be taken for which items can be configured in a configuration file.
As of V3.0, AdaBrowse not only can generate HTML documentation, but also XML output. The XML output contains all the information contained in the HTML, including structure, indices, and cross-references.
AdaBrowse is not a pretty-printer! Any source chunks in the generated HTML retain the formatting as in the source file (except for cross-referencing and syntax coloring). To get the best results, the source should not contain tabs. (I use an editor that de-tabs any source file when it saves it by replacing all tabs by the appropriate number of spaces.)
AdaBrowse does a few things that could be considered some very weak form of pretty printing, though:
Storage_Size"
in "for X'Storage_Size use ...", or "Write" in
"My_Type'Write (...)".
TYPE My_Type IS NEW natural; X : my_Type; |
type My_Type is new Natural; X : My_Type; |
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.
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:
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
gcc -c -gnatc -gnatt <filename> (with the appropriate -I options, if
needed.)
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.
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).
-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
-c options may be given; the files are processed in
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.-private, --private
-q
-w0.-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.-wi
0, or e | print only error messages. |
1, or w | print warnings and errors. |
2, or i, or a | print all messages. |
-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.
There must be at least either a -f or a -P option on the command line.
-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. 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").
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:
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.
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.
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.)
-f" option on the command line, AdaBrowse assumes all
the unit specifications of all the units in the project are to be processed.
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.
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.
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
-p
-t
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:
-f @file_name or -f-.
-P project_file_name).
-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:
-o option is given, it must specify a directory.
All HTML files, including the index, will be put into that directory.
-o option is given, but the first unit spec contains a path, the
index is put into the directory designated by that path.
-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).
ADABROWSE_OUTPUT
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".
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.
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).
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.)
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
for %i in (.\simple_test\*.ads) do adabrowse -I.\simple_test -I. -c .\simple_test.cfg -f %i
dir /b .\simple_test\*.ads > simple_test.lst adabrowse -I.\simple_test -I. -c simple_test.cfg -f @simple_test.lst
dir command produces a list of filenames (without the
".\simple_test\"). The HTML files therefore end up in the directory
adabrowse_1.32.)
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-
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.)
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.)
mkdir Testing ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -I.\simple_test -I. -c simple_test.cfg -f- -o .\Testing\ -i
.\Testing.)
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
.\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.)
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.
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/\""/\"/g" ...
in a configuration file, even though on the command line of your favorite shell, you'd just write
sed -e"s/\"/\"/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):
Format keys.
User_Tag.XYZ.Execute or
User_Tag.XYZ.Set keys,
or in the value of a Compile
key, or in an execute filter).
enclose filter.
Index_Title keys.
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 "bar"">;
the HTML standard requires browsers to replace character entities in attribute values.
For the single quote, the character entity is ', the double quote
is ", and the backquote is `.)
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.
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.
*.adt) and a *.ali file in the current directory.
Both files will bedeleted again by AdaBrowse once they're no longer needed.
The value of these keys is placed verbatim into the generated HTML output at predefined places.
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=value">
<HEAD> section of the generated HTML file. By default, this
is set to "ISO-8859-1", which is Latin-1.
<HEAD> section:
<LINK REL="stylesheet" HREF="value" TYPE="text/css">
<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> tag to use. Also used for the index.
<TITLE> entry
in the <HEAD> section, but the first title in the body). Also used for
the index.
package",
"type", and so on).
'Class",
"'Read", and so on).
My_Type" in "type My_Type is
private;").
--" and
at the end of the line) that end up in-line in the generated output.
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.
Indices are defined through the Index.<Identifier> keys, where the
identifier defines the index name.
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.
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.
AdaBrowse performs environment variable substitution on all these keys' values.
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:
and, or, and xor)
are left-associative.
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))
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:
True for all child units.
True for all constants and named numbers.
True for all entry declarations (of both tasks and protected
types or objects).
True for all exception declarations (including renamings).
True for all function declarations (including protected functions
and renamings, instantiations, and generic declarations).
True for all generic declarations.
True for all instantiations of generics.
True for all packages, including generics, renamings, and instantiations).
True for all pragmas.
True for all items declared in the private part of the
enclosing package, task, or protected type (or object).
True for all procedure declarations (including protected procedures
and renamings, instantiations, and generic declarations).
True for all representation clauses.
True for all separate items. Note that AdaBrowse will
never encounter a separate item because it only processes unit specs!
function or procedure.
True for all subtype declarations.
True for all type declarations (but not subtype declarations!).
True for all compilation units.
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.)
True for all elementary types.
True for all scalar types.
True for all discrete types.
True for all enumeration types.
True for all integral types.
True for all signed integer types.
True for all modular types.
True for all real types.
True for all floating-point types.
True for all fixed-point types.
True for all ordinary fixed-point types.
True for all decimal fixed-point types.
True for all numeric types. Equivalent to the expression
integral or real.
True for all access types.
True for all access-to-object types.
True for all access-to-subprogram types.
True for all composite types.
True for all array types (both constrained and unconstrained).
True for all record types.
True for all tagged record types.
True for all limited types, including task and protected types.
True for all controlled types, i.e. types derived from one of the
two types declared in package Ada.Finalization.
True for all class-wide types.
True for all private types, including private extension declarations.
True for all protected objects and types, but also for all declarations
within.
True for all single tasks and task types, but also for entry declarations
in tasks.
Miscellaneous predicates:
True for all abstract types and subprograms.
True for all aliased objects.
True for all generic formal declarations.
True for all incomplete types and for deferred constant declarations.
Constants:
False.
True.
Built-in functions returning strings:
Note that elementary /= not composite: there are types that
are neither elementary nor composite, such as private types.
Besides these built-in predicates, you can also define your own rule functions with the
Rule key:
Rule.entries_of_tasks = entry and not protected
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]
Index.Units.File_Name = index (default) or file_name Index.Units.Title = Unit Index Index.Units.Rule = unitIf the option
-is is used, an additional key
Index.Units.Structured = Trueis also defined.
-p [file_name]
Index.Subprograms.File_Name = procidx (default) or file_name Index.Subprograms.Title = Subprogram Index Index.Subprograms.Rule = subprogram and not protected
-t [file_name]
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.
Index.My_Exceptions.File_Name = ex_idx Index.My_Exceptions.Title = Public Exceptions Index.My_Exceptions.Rule = exception and not (private or renaming); |
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.
<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 ">".
Index_XRef = TARGET="main"
<A HREF="somepackage.html" TARGET="main">SomePackage</A>
The following keys are obsolete; they are maintained only to ensure backwards compatibility with versions of AdaBrowse prior to V4.0.
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.
Index_Title = My Subsystem
Index.Units.Title = My Subsystem.
Index_Title.Unit_Index = My Subsystem
Index.Units.Title = My Subsystem.
Index_Title.Type_Index = My Types
Index.Types.Title = My Types.
(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:
<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".
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. = ...
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/ |
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".
XRef key (see below).
Matching is case-insensitive. White space around unit name prefixes is
ignored, and so are empty unit name prefixes.
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.
No_XRef = Core.Os ,, , BC.Support No_XRef = , Co , |
Co", "Core.Os", "BC.Support".
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.
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.
Exclude keys may be defined, the set of excluded units
is the union of all keys' values (except for the empty value, see above).
Exclude = Core, BC |
-f option is excluded,
AdaBrowse issues an error message.
Exclude key will
still be generated unless the unit is also suppressed by a
No_XRef key.
An_Application_Unit".)
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.
Include_File key, which
is for including another configuration file into the current one.
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:
System.
That's the "Exclude = System." part. Note the period: it doesn't
exclude System itself!
System.Address_To_Access_Conversions and all
its children and further descendents. That's the Include key.
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 noIncludeorXRefkeys, 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.)
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.
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).
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.
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.
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:
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.
Description.Subprogram = Before (3)
Declaration.Subprogram = Before
is":
package XYZ isgeneric ... package XYZ istask (type) XYZ (Discriminants) isprotected (type) XYZ (Discriminants) isIn any case, search for a descriptive comment stops and comes up empty if either
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:
After (1)".
use" and "use type" clauses.
Default setting is "After (1)".
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 ... |
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 |
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.
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
"<" 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 "ü".
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:
-- 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.)
-- 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 "<" and ">", or make sure there's a space
following the "<" as in "-- Author: < somebody@somewhere.org >".
<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:
--!" 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.
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.
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.
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.
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
<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!
User_Tag.<TAG_IDENTIFIER>.Execute = Command
<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.
User_Tag.<TAG_IDENTIFIER>.Set = Command
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.
User_Tag.<TAG_IDENTIFIER>.Variable = ...
User_Tag.<TAG_IDENTIFIER>
(without selector), but AdaBrowse performs environment variable
substitution on the value.
(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:
User_Tag.INCLUDE_ANY.Include = %File |
<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.
User_Tag.RUN_IT.Execute = some_program %Params |
<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.
User_Tag.MY_TAG.Before = <SPAN %{Class:+Class="%Class"}>
User_Tag.MY_TAG.After = </SPAN>
|
<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.
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.
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:
!' 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.
bash, and it is done for as many levels as specified.
The semantics of these forms is as follows:
${Variable_Name}
$Identifier except that it
also allows indirect and recursive expansion.
${Variable_Name:-Value}
${Variable_Name} unless that result is empty,
in which case it is replaced by the expansion of Value.
${Variable_Name:+Value}
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 '$'.
@
\' 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.
$
$$" 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).
Include_File = ${PATH_TO_FILE:+$PATH_TO_FILE\file.cfg}
|
User_Tag.Date.Set = date /t |
User_Tag.GMGPL.Include = ${ADABROWSE_HOME:-.}\gmgpl.html
|
User_Tag.XYZ.Include = $@some_file.html |
User_Tag.SOME_TAG.Enabled = ${SOME_VAR:-False}
|
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.
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.
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.
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 " 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
------------------------------------------------------
-- 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:
The first and the last block will be formatted according to
the default rules (we didn't redefine
Note that to just have something enclosed in
|
This section explains how to define format instructions for comment blocks.
AdaBrowse recognizes the following format instructions, which define how it should format the content of a comment block:
swallow
entities
<" 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 <, 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.
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
"; any
"<" that doesn't belong to a tag is replaced by
<, 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]
hr
are:
strip
replace
<HR>.
If only "hr" appears (i.e., without "strip" or
"replace" following), the default behavior is strip.
strip_comments
enclose (string, string)
enclose is followed (in a pipe) by expand,
they may even contain user-defined HTML mark-up.
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
<PRE></PRE>
tags, i.e. pre is short-hand for
enclose ("<PRE>", "</PRE>").
expand
unknown_tags [all | standard]
< and the closing
>, by character entities. In other words, "<UNKNOWN>"
becomes "<UNKNOWN>".
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
@" without
whitespace in between by <CODE> and </CODE>,
respectively, as described above.
para
<BR> or <P> tags as
appropriate.
<PRE> blocks,
and it also will never insert <BR> or <P> tags where
they would be illegal (such as directly inside a <UL>).
lines
and
adding a <BR> at each end-of-line outside HTML tags, unless
the line already ended in a <BR>.
<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
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)
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.
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.)
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.
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 "}").
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.
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.
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.
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:]]/\ /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 , 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:]]/\ /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:]]/\ /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:]]/\ /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 "<PRE>", and thus the tag would not be interpreted by a browser but rather be
displayed!
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:
-o option specifies a file name: to that file, with
extension "xml".
-o option specifies only a path: to a file named
as specified above in the given directory.
-o option specifies stdout: to stdout.
-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).
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.
AdaBrowse works ok with versions of GNAT >= 3.14p. To rebuild AdaBrowse from the sources, follow these steps:
| 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 Open the ASIS source file 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
Without this correction, the " |
ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
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:
ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
C:\gnat-3.15p-src\. Do not include this
directory in the ADA_INCLUDE_PATH!
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.)
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.)
The procedure is basically the same:
License on all units. These may cause
compilation warnings when compiled with some compiler other than GNAT.
Asis.Ada_Environments.Associate in file
adabrowse.adb.
adabrowse.adb.
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].
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.)
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.)
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:
as[go]c*.ads) of Corey Minyard's ASL (asl-1.4),
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.
<PRE>This is some code.</PRE>Followed by other text. |
This is some code.Followed by other text. |
-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.
-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.
AdaBrowse is copyright © 2002-2003 by Thomas Wolf <twolf AT acm DOT 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.
Send bug reports and enhancement propsals to <twolf AT acm DOT org>. Use a subject
line containing the text "AdaBrowse".
For bug reports, I need:
ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
stderr, etc.
I can only maintain the AdaBrowse version I distribute myself. See above for AdaBrowse adapted to work with other compilers.
|
Copyright © 2002-2005 by Thomas Wolf.
TW, Nov 18, 2003 |