File: adabrowse_ug.html

package info (click to toggle)
adabrowse 4.0.2-1
links: PTS
area: main
in suites: sarge
size: 2,316 kB
ctags: 253
sloc: ada: 29,761; makefile: 150; ansic: 4
file content (3749 lines) | stat: -rw-r--r-- 169,525 bytes
parent folder | download | duplicates (3)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>

<HEAD>
  <TITLE>AdaBrowse User's Guide</TITLE>
  <META NAME="description" CONTENT="AdaBrowse User's Guide">
  <LINK REL="stylesheet" HREF="gal.css" TYPE="text/css">
  <STYLE TYPE="text/css">
    UL.toc { list-style: none }
    PRE.small { font-size: smaller }
  </STYLE>
</HEAD>

<BODY BGCOLOR="#FFFFF4">

<TABLE WIDTH="100%" BORDER=0 CELLSPACING=0 CELLPADDING=5 CLASS="title">
<TR>
  <TD>
	<H1 ALIGN="CENTER">AdaBrowse User's Guide</H1>
  </TD>
</TR>
</TABLE>

<P>
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.
</P>

<P>
<STRONG>Copyright &copy; 2002-2003 by Thomas Wolf</STRONG> <CODE>&lt;twolf@acm.org&gt;</CODE>.<BR>
AdaBrowse is distributed under the GPL (the GNU General Public License, see
"<A HREF="#License">License</A>" below).
</P>


<HR>
<H2 CLASS="toc">Contents</H2>

<UL CLASS="toc">
  <LI>1.&nbsp;&nbsp;<A HREF="#About">What it does</A>
  <LI>2.&nbsp;&nbsp;<A HREF="#History">Version history</A>
  <LI>3.&nbsp;&nbsp;<A HREF="#Use">How to use it</A>
  <LI>4.&nbsp;&nbsp;<A HREF="#Options">Options</A>
      <UL CLASS="toc">
        <LI>4.1.&nbsp;&nbsp;<A HREF="#F_Option">The <CODE>-f</CODE> Option</A>
        <LI>4.2.&nbsp;&nbsp;<A HREF="#Projects">The Project Manager</A>
        <LI>4.3.&nbsp;&nbsp;<A HREF="#I_Option">Index Generation</A>
        <LI>4.4.&nbsp;&nbsp;<A HREF="#File_Names">Directory and File Names</A>
        <LI>4.5.&nbsp;&nbsp;<A HREF="#Opt_History">Option History</A>
        <LI>4.6.&nbsp;&nbsp;<A HREF="#Opt_Examples">Examples</A>
      </UL>
  <LI>5.&nbsp;&nbsp;<A HREF="#Config">Configuration Files</A>
      <UL CLASS="toc">
        <LI>5.1.&nbsp;&nbsp;<A HREF="#File_Syntax">Syntax of Configuration Files</A>
        <LI>5.2.&nbsp;&nbsp;<A HREF="#File_Incl">File Inclusion</A>
        <LI>5.3.&nbsp;&nbsp;<A HREF="#Compilation">Compilation</A>
        <LI>5.4.&nbsp;&nbsp;<A HREF="#HTML_Keys">HTML-related</A>
        <LI>5.5.&nbsp;&nbsp;<A HREF="#Index_Keys">Indexing</A>
            <UL CLASS="toc">
              <LI>5.5.1.&nbsp;&nbsp;<A HREF="#Index_Def">Index Definition</A>
              <LI>5.5.2.&nbsp;&nbsp;<A HREF="#Index_Rule">Index Rules</A>
              <LI>5.5.3.&nbsp;&nbsp;<A HREF="#Predef_Rule">Predefined Predicates</A>
              <LI>5.5.4.&nbsp;&nbsp;<A HREF="#Def_Func">User-Defined Functions</A>
              <LI>5.5.5.&nbsp;&nbsp;<A HREF="#Idx_Options">Index Keys and Index Options</A>
              <LI>5.5.6.&nbsp;&nbsp;<A HREF="#Idx_Example">An Example</A>
              <LI>5.5.7.&nbsp;&nbsp;<A HREF="#Idx_Keys_Old">Other Indexing Keys</A>
            </UL>
        <LI>5.6.&nbsp;&nbsp;<A HREF="#XRef_Keys">Cross-References</A>
        <LI>5.7.&nbsp;&nbsp;<A HREF="#General">General Usage Hints</A>
        <LI>5.8.&nbsp;&nbsp;<A HREF="#Std_Lib_HTML">A More Elaborate Example</A>
      </UL>
  <LI>6.&nbsp;&nbsp;<A HREF="#Descs">Descriptions</A>
      <UL CLASS="toc">
        <LI>6.1.&nbsp;&nbsp;<A HREF="#Find_Descs">Finding Descriptions</A>
            <UL CLASS="toc">
              <LI>6.1.1.&nbsp;&nbsp;<A HREF="#Comment_Def">Defining Description</A>
              <LI>6.1.2.&nbsp;&nbsp;<A HREF="#Extract_Descs">How AdaBrowse maps Ada Comments to Descriptions</A>
            </UL>
        <LI>6.2.&nbsp;&nbsp;<A HREF="#Format_Descs">Basic Description Formatting</A>
            <UL CLASS="toc">
              <LI>6.2.1.&nbsp;&nbsp;<A HREF="#Default_Format">Default Formatting</A>
              <LI>6.2.2.&nbsp;&nbsp;<A HREF="#Code_Shortcut">A Shortcut for the <CODE>&lt;CODE&gt;</CODE>-Tag</A>
            </UL>
      </UL>
  <LI>7.&nbsp;&nbsp;<A HREF="#userdef">User-Defined Mark-Up</A>
      <UL CLASS="toc">
        <LI>7.1.&nbsp;&nbsp;<A HREF="#basic_syntax">Basic Syntax</A>
        <LI>7.2.&nbsp;&nbsp;<A HREF="#userdef_example">A Simple Example</A>
        <LI>7.3.&nbsp;&nbsp;<A HREF="#userdef_advanced">Advanced User-Defined Variables</A>
        <LI>7.4.&nbsp;&nbsp;<A HREF="#userdef_params">Parameters of User-Defined Tags</A>
      </UL>
  <LI>8.&nbsp;&nbsp;<A HREF="#subst">Environment Variable Substitution</A>
      <UL CLASS="toc">
        <LI>8.1.&nbsp;&nbsp;<A HREF="#env_syntax">Syntax and Semantics</A>
        <LI>8.2.&nbsp;&nbsp;<A HREF="#env_examples">Some Examples</A>
      </UL>
  <LI>9.&nbsp;&nbsp;<A HREF="#Comment_Format">Advanced Description Formatting</A>
      <UL CLASS="toc">
        <LI>9.1.&nbsp;&nbsp;<A HREF="#General_Format">Structure of a Description</A>
            <UL CLASS="toc">
              <LI>9.1.1.&nbsp;&nbsp;<A HREF="#Comment_Block">Comment Blocks and Prefixes</A>
            </UL>
        <LI>9.2.&nbsp;&nbsp;<A HREF="#Userdef_Format">User-Defined Formatting</A>
            <UL CLASS="toc">
              <LI>9.2.1.&nbsp;&nbsp;<A HREF="#Format_Instruction">Format Instructions</A>
              <LI>9.2.2.&nbsp;&nbsp;<A HREF="#Format_Pipe">Pipes</A>
              <LI>9.2.3.&nbsp;&nbsp;<A HREF="#Standard_Format">The Default Formatting</A>
              <LI>9.2.4.&nbsp;&nbsp;<A HREF="#Example_Pipe">An Example</A>
            </UL>
      </UL>
  <LI>10.&nbsp;&nbsp;<A HREF="#XML">XML Output</A>
  <LI>11.&nbsp;&nbsp;<A HREF="#GNAT">Rebuilding from sources for GNAT</A>
  <LI>12.&nbsp;&nbsp;<A HREF="#Rebuild">Rebuilding from sources for another Ada 95 compiler</A>
  <LI>13.&nbsp;&nbsp;<A HREF="#Testing">Testing</A>
  <LI>14.&nbsp;&nbsp;<A HREF="#Problems">Known Problems</A>
  <LI>15.&nbsp;&nbsp;<A HREF="#License">License</A>
  <LI>16.&nbsp;&nbsp;<A HREF="#Bugs">Reporting Bugs and Enhancements</A>
</UL>

<HR>
<H2 CLASS="toc"><A NAME="About">1. What it does</A></H2>

<P>
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.
</P>
<P>
AdaBrowse is highly configurable through command-line options, style sheets,
and configuration files.
</P>
<P>
AdaBrowse completely takes apart the source code and produces a HTML
documentation containing:
</P>
<UL>
  <LI>All context clauses
  <LI>Unit header
  <LI>If the unit is a package:
      <UL>
        <LI>All exceptions (including renames)
        <LI>All constants
        <LI>All variables
        <LI>A type index containing all types and their primitive operations
           (the latter only for (tagged) record types, private types, and types
           derived from those). The primitive operations list is fully cross-
           referenced and ordered by newly defined, overridden, and inherited
           operations.
        <LI>Any other items
      </UL>
</UL>
<P>
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.
</P>
<P>
As of V3.0, AdaBrowse not only can generate HTML documentation, but also
<A HREF="#XML">XML output</A>.
The XML output contains all the information contained in the HTML, including structure,
indices, and cross-references.
</P>
<P>
AdaBrowse is <EM>not</EM> 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.)
</P>
<P>
AdaBrowse does a few things that could be considered some very weak form of
pretty printing, though:
</P>
<OL>
  <LI>It prints all keywords in lowercase. I chose lowercase because I felt that
      the combination of all uppercase <EM>and</EM> bold face in the HTML was simply
      too much. Lowercase letters look much better in boldface, they're not that
      heavy.
      <BR><BR>
  <LI>It capitalizes all attribute defining identifiers such as "<CODE>Storage_Size</CODE>"
      in "<CODE>for X'Storage_Size use ...</CODE>", or "<CODE>Write</CODE>" in
      "<CODE>My_Type'Write (...)</CODE>".
      <BR><BR>
  <LI>Whenever possible, it uses the defining name in place of the identifier
      that references it. I.e., the source<BR><BR>
      <TABLE BORDER=0><TR><TD>
<PRE>TYPE My_Type IS NEW natural;

X : my_Type;
</PRE></TD></TR></TABLE>

      is rendered in the generated HTML as<BR><BR>
      <TABLE BORDER=0><TR><TD>
<PRE><STRONG>type</STRONG> My_Type <STRONG>is new</STRONG> Natural;

X : My_Type;
</PRE></TD></TR></TABLE>

      As a result, the generated HTML should have consistent casing of all
      identifiers.
      <BR><BR>
</OL>
<P>
However, it does not re-indent things, and it preserves the original line
breaks in source code chunks.
</P>
<P>
BTW, AdaBrowse is called "AdaBrowse" and <EM>not</EM> "adadoc" because there was
already an open-source project on SourceForge with the latter name.
</P>

<HR>
<H2 CLASS="toc"><A NAME="History">2. Version History</A></H2>

The version history of AdaBrowse can be found <A HREF="versions.html">here</A>.

<HR>
<H2 CLASS="toc"><A NAME="Use">3. How to use it</A></H2>

<P>
AdaBrowse is an ASIS-based application. <EM>You need GNAT 3.15p if you intend
to use the pre-built executable in the distribution!</EM> (If you have some
other GNAT version &gt;= 3.14p, you may rebuild simply from the sources as
described <A HREF="#GNAT">below</A>.)
</P>
<P>
There are two ways to use AdaBrowse:
</P>
<OL>
  <LI>Call AdaBrowse for your spec: <CODE>adabrowse -f &lt;filename&gt;</CODE> (and any other
      options as needed, in particular <CODE>-I</CODE> 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.
      <BR><BR>
</OL>
<P>
<EM>or</EM>
</P>
<OL>
  <LI>Generate the tree files for the specs you want to process by calling
      <CODE>gcc -c -gnatc -gnatt &lt;filename&gt;</CODE> (with the appropriate <CODE>-I</CODE> options, if
      needed.)
      <BR><BR>
  <LI>Call AdaBrowse for these specs: <CODE>adabrowse -f &lt;filename&gt;</CODE> (and any other
      options, as needed [look in particular at <CODE>-T</CODE>!]).
      <BR><BR>
</OL>
<P>
AdaBrowse generates HTML files by default in the current directory.
</P>
<P>
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.
</P>

<HR>
<H2 CLASS="toc"><A NAME="Options">4. Options</A></H2>
<P>
The following options are available in AdaBrowse:
</P>
<DL>
   <DT><CODE>-h, -?, -help, --help</CODE>
   <DD>Writes a comprehensive help text.<BR><BR>

   <DT><CODE>-a, -all, --all</CODE>
   <DD>Optional: Generate HTML not only for the unit given in the
       <CODE>-f</CODE> option, but also for all application units on which it
       depends semantically (transitive closure of "with"es and parent units).
       <BR><BR>
       Note that this option processes only the <EM>application units</EM> in the
       transitive closure even if the "<CODE>-g</CODE>" 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 "<CODE>-all</CODE>" option has <EM>no effect</EM>.
       This behavior is <EM>intentional</EM>: you'll normally generate HTML for the standard
       library once by processing all standard library units explicitly, and you <EM>don't</EM>
       want to re-generate HTML for these units each time one of your application unit "with"es
       a standard library unit.
       <BR><BR>

   <DT><CODE>-c filename</CODE>
   <DD>Optional: Defines a <A HREF="#Config">configuration file</A> for the HTML generator.
       Multiple <CODE>-c</CODE> options may be given; the files are processed in
       the given order and may overwrite earlier config settings.<BR><BR>

   <DT><CODE><STRONG>-f filename</STRONG></CODE>
   <DD>Gives the filename (*.ads) of the spec to process.
       This filename may contain a path! See <A HREF="#F_Option">below</A> for more comments.
       Only one <CODE>-f</CODE> option may be given.<BR><BR>

   <DT><CODE>-g</CODE>
   <DD>Optional: If set, AdaBrowse also generates cross-references to items from library units
       in the standard and run-time packages, except for items from the implict package
       "<CODE>Standard</CODE>". Note: This can also be set by a configuration file key
       "<CODE>Refs_To_Standard</CODE>". The later definition wins.<BR><BR>

   <DT><CODE><A NAME="G_Option">-G output_formats</A>
   <DD>Optional; new in V3.0: specify the output formats AdaBrowse shall generate. The "<CODE>-G</CODE>"
       option must be followed by one or more <EM>output format names</EM>, given as separate arguments.
       Recognized output format names are <CODE>html</CODE> and <CODE>xml</CODE> (case insensitive).
       <BR><BR>
       If no "<CODE>-G</CODE>" option is given, AdaBrowse behaves as if "<CODE>-G&nbsp;html</CODE>" were
       given; i.e., by default, AdaBrowse generates only HTML output.
       <BR><BR>

   <DT><CODE>-i [filename]</CODE>
   <DD>Optional: If set, AdaBrowse will generate a package index if
       it runs in "file input mode" (see <A HREF="#I_Option">below</A>) or the <CODE>-all</CODE> option
       is set and the output does <EM>not</EM> go to <CODE>stdout</CODE>.
       <BR><BR>
       If a <CODE>filename</CODE> is given, the index is written to that file (or to <CODE>stdout</CODE>, if the
       <CODE>filename</CODE> is "<CODE>-</CODE>").
       <BR><BR>

   <DT><CODE>-is [filename]</CODE>
   <DD>Optional: same as <CODE>-i</CODE>, but generates an index using indentation for child units.<BR><BR>

   <DT><CODE>-l</CODE>
   <DD>Optional; new in V3.0: make AdaBrowse generate cross-references in HTML output using only the line
       number. This is what earlier versions of AdaBrowse (up to and including V2.13) always did. As of V3.0,
       cross-references are constructed taking into account both line and column number of an item. You should
       use this option only if you have HTML documentation generated by earlier AdaBrowse versions and somehow
       cannot re-generate that documentation. However, the recommended usage is never to use this option
       and to regenerate possibly already existing HTML documentation.
       <BR><BR>
       Note that HTML generated with "<CODE>-l</CODE>" is <EM>not</EM> compatible with HTML generated
       <EM>without</EM> "<CODE>-l</CODE>"! Also, HTML generated by AdaBrowse 3.0 and beyond is compatible
       with HTML generated by AdaBrowse 2.13 and earlier only if the "<CODE>-l</CODE>" option <EM>is</EM>
       given.
       <BR><BR>
       Usage of this option generates a warning message on <CODE>stderr</CODE>.
       <BR><BR>

   <DT><CODE>-o filename</CODE>
   <DD>Optional: Define the output file name. If not set, the output
       goes to a file with the name of the input and suffix ".html".
       If <CODE>filename</CODE> 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 <CODE>stdout</CODE>. Only one <CODE>-o</CODE> option may be given.
       <BR><BR>
	   A dash as the filename ("-") is allowed only if there is exactly one <A HREF="#G_Option">output
	   format</A> specified. If there are multiple output formats specified (e.g. both XML and HTML),
	   output is not allowed to go to <CODE>stdout</CODE>.
	   <BR><BR>

   <DT><CODE>-p [filename]</CODE>
   <DD>Optional: As <CODE>-i</CODE>, but generates a subprogram index over all units
       processed.<BR><BR>

   <DT><CODE><STRONG>-P filename</STRONG></CODE>
   <DD>Gives the filename (with or without the extension *.gpr) of the GNAT project file to process.
       See <A HREF="#Projects">below</A> for more comments. Only one <CODE>-P</CODE> option may be
       given.<BR><BR>

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

   <DT><CODE>-q</CODE>
   <DD>Optional: "Quiet" mode: do not issue warning or info messages. Synonym to <CODE>-w0</CODE>.<BR><BR>

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

   <DT><CODE>-t [filename]</CODE>
   <DD>Optional: As <CODE>-i</CODE>, but generates a global type index over all units
       processed.<BR><BR>

   <DT><CODE>-v, -version, --version</CODE>
   <DD>Optional: Print version information of AdaBrowse to <CODE>stderr</CODE>.<BR><BR>

   <DT><CODE>-w<EM>i</EM></CODE>
   <DD>Sets the warning level of AdaBrowse. <EM>i</EM> may be one of the following:
       <TABLE BORDER=0>
         <TR><TD><CODE>0</CODE>, or <CODE>e</CODE></TD><TD>print only error messages.</TD></TR>
         <TR><TD><CODE>1</CODE>, or <CODE>w</CODE></TD><TD>print warnings and errors.</TD></TR>
         <TR><TD><CODE>2</CODE>, or <CODE>i</CODE>, or <CODE>a</CODE></TD><TD>print all messages.</TD></TR>
       </TABLE>

   <DT><CODE>-x</CODE>
   <DD>Optional: If set, AdaBrowse never overwrites existing HTML
       files. (May be useful in conjunction with the <CODE>-a</CODE> option.)<BR><BR>

   <DT><CODE>-X name=[value]</CODE>
   <DD>Optional: define an environment variable <CODE>name</CODE> with value <CODE>value</CODE>. The value
       supersedes any possibly already existing definition of <CODE>name</CODE> 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 <CODE>name</CODE> must not contain white space; if <CODE>value</CODE>
       contains white space, quote the whole definition as in <CODE>-X"user=John Doe"</CODE>. There may or may
       not be white space between the "<CODE>-X</CODE> and the variable definition.<BR><BR>

   <DT><CODE>-I directory</CODE>
   <DD>Optional: Define source pathes for ASIS. Same semantics as
       for GNAT. Multiple <CODE>-I</CODE> options may be given.<BR><BR>

   <DT><CODE>-T directory</CODE>
   <DD>Optional: Define pathes for ASIS to search for tree files
       (*.adt). Multiple <CODE>-T</CODE> options may be given.
</DL>
<P>
There must be at least either a <CODE>-f</CODE> or a <CODE>-P</CODE> option on the command line.
</P>

<H3 CLASS="toc"><A NAME="F_Option">4.1. The <CODE>-f</CODE> option</A></H3>
<P>
  The <CODE>-f</CODE> option has three different formats:
</P>
<OL>
  <LI>If the filename is "<CODE>-</CODE>" or "<CODE>@-</CODE>", AdaBrowse reads the unit
      specs of the units to process from <CODE>stdin</CODE>, 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 "<CODE>ls -1 *.ads | adabrowse -f- ...</CODE>")
      <BR><BR>
  <LI>If the filename starts with "<CODE>@</CODE>", 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.
      <BR><BR>
  <LI>If neither applies, AdaBrowse uses the given filename as the unit spec.
</OL>
<P>
  The first two cases are called the "<EM>file input mode</EM>" of AdaBrowse. The file
  may contain empty lines and comments (starting with the first "<CODE>#</CODE>" on a line and
  extending up to the end of the line), which are ignored. Note that contrary to
  <A HREF="#Config">configuration files</A>, string handling for finding comment starts
  is <EM>not</EM> done, and line continuations also are <EM>not</EM> allowed.
</P>
<P>
  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 <CODE>test-gen</CODE>, or <CODE>test-gen.ads</CODE>, and not
  <CODE>Test.Gen</CODE>. 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.
</P>
<P>
  If a unit spec contains a path, the HTML file for that unit is placed into
  that directory unless overridden by a <CODE>-o</CODE> option. Note that if
  the unit spec contains a path, you'll most probably also have to set
  a <CODE>-T</CODE> or <CODE>-I</CODE> 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).
</P>
<P>
  In file input mode, the <CODE>-o</CODE> option (if given at all) may either be
  "<CODE>-</CODE>" (in which case all output goes to <CODE>stdout</CODE>) or specify
  a directory, but must not specify a file.
</P>
<P>
  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
  <EM>krunched</EM> file names in the <CODE>-f</CODE> 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.
</P>
<P>
  Generated HTML files always have the suffix ".html" (not ".htm").
</P>

<H3 CLASS="toc"><A NAME="Projects">4.2. The Project Manager</A></H3>

<H4><A NAME="Project_Intro">4.2.1 Introduction</A></H4>

<P>
  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
  <A HREF="http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/">original
  download location</A> always come with project manager support. If you intend to
  build AdaBrowse from the sources, see <A HREF="#GNAT">below</A>.
</P>
<P>
  What does "GNAT project manager support" mean? First, AdaBrowse has a "<CODE>-P</CODE>"
  command line option; its argument is a project file name. If given this option, AdaBrowse
  reads the project file and extracts information from it:
</P>
<UL>
  <LI>If the project file contains a variable called "<CODE>ADABROWSE_TREE_DIR</CODE>" 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
      <CODE>Tree_Dir</CODE> 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 <EM>never</EM> use the object directory specified in the project file to avoid
      accidentally overwriting an existing <CODE>*.ali</CODE> file belonging to an object
      file. See <A HREF="#prj_obj_dir">below</A> for more information.
      <BR><BR>
  <LI>If the project file contains a variable called "<CODE>ADABROWSE_OUTPUT</CODE>" 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.
      <BR><BR>
  <LI>If the project file contains a variable called "<CODE>ADABROWSE_CONFIGURATIONS</CODE>",
      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.)
      <BR><BR>
  <LI>If there is no "<CODE>-f</CODE>" option on the command line, AdaBrowse assumes all
      the unit specifications of all the units in the project are to be processed.
      <BR><BR>
  <LI>When given a project file, AdaBrowse unconditionally changes the compile command
      used to create tree files (if needed) to "<CODE>gnat compile -c -gnatc -gnatt</CODE>",
      and passes it the project file (and any <CODE>-X</CODE> options), too. Thus the
      compiler has the environment it needs (e.g. configuration pragmas defined in a
      project file).
</UL>
<P>
There must be either a <CODE>-f</CODE> or a <CODE>-P</CODE> option on the
command-line. You can also specify both, e.g. to process only a subset of the files
in a project.
</P>
<P>
AdaBrowse fully supports naming schemes as defined in project files.
</P>

<H4><A NAME="Project_Hints">Hints on using GNAT, the Project Manager, and AdaBrowse</A></H4>

<P>
AdaBrowse does <EM>not</EM> 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.
</P>
<P>
When using the GNAT project manager for your build process and for AdaBrowse, you
should be aware of the following:
</P>
<P>
<A NAME="prj_obj_dir">ASIS-for-GNAT</A> has, at least up to version 3.16a, a problem
if tree files have been generated with <CODE>-gnatt</CODE>, but <EM>without</EM>
<CODE>-gnatc</CODE> 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.
</P>
<P>
However, when using project files, this means that you <EM>cannot</EM> just add
<CODE>-gnatt</CODE> to your <CODE>Default_Switches ("ada")</CODE> in
the <CODE>Compiler</CODE> package in your project files and have everything
work fine. The problem is that typically, you <EM>won't</EM> specify the
<CODE>-gnatc</CODE> 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.
</P>
<P>
You also don't want to recompile (for AdaBrowse) things already compiled, because you'd
define the options as <CODE>-gnatc -gnatt</CODE>. If that happens, GNAT will overwrite
possibly existing <CODE>*.ali</CODE> files in the project's object directory, which is
probably not a good idea, given that such existing <CODE>*.ali</CODE> files "belong" to
the object files.
</P>
<P>
AdaBrowse therefore insists on the variable <CODE>ADABROWSE_TREE_DIR</CODE> 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 <CODE>ADABROWSE_TREE_DIR</CODE> 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 <EM>not</EM> remove
<CODE>*.adt</CODE> files it generated (as it does normally, when not using a project
file) because it considers this <CODE>ADABROWSE_TREE_DIR</CODE> "its own". By not
deleting the tree files, they remain available for future re-use.
</P>

<H3 CLASS="toc"><A NAME="I_Option">4.3. Index generation</A></H3>

<P>
  Index generation is active when AdaBrowse is told to process several units, and
  the output does not go to <CODE>stdout</CODE> (when the <CODE>-o-</CODE> option
  has been given).
</P>
<P>
  There are several options controlling index generation:
</P>
<DL>
  <DT><CODE>-i</CODE> or <CODE>-is</CODE>
  <DD>Switches on generation of a unit index.
  <DT><CODE>-p</CODE>
  <DD>Switches on generation of a subprogram index.
  <DT><CODE>-t</CODE>
  <DD>Switches on generation of a type index.
</DL>
<P>
All these options take an optional filename as a parameter. If a filename follows,
the index will be written to that file (or to <CODE>stdout</CODE>, if the filename
happens to be "<CODE>-</CODE>"). If no filename is given, some default name is chosen.
</P>
<P>
All these options are actually maintained only for backwards compatibility reasons.
As of V4.0, indices are defined primarily through <A HREF="#Index_Keys">configuration
file entries</A>, 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.
</P>
<P>
AdaBrowse assumes it will process several units in the following cases:
</P>
<UL>
  <LI>In file input mode (<CODE>-f @file_name</CODE> or <CODE>-f-</CODE>.
  <LI>When using a project file (<CODE>-P project_file_name</CODE>).
  <LI>When the <CODE>-all</CODE> option is given.
</UL>
<P>
<P>
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:
</P>
<UL>
  <LI>In file input mode, if a <CODE>-o</CODE> option is given, it must specify a directory.
      All HTML files, including the index, will be put into that directory.
      <BR><BR>
  <LI>If no <CODE>-o</CODE> option is given, but the first unit spec contains a path, the
      index is put into the directory designated by that path.
      <BR><BR>
  <LI>If not in file input mode, but the <CODE>-all</CODE> option has been given, the <CODE>-o</CODE>
      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).
      <BR><BR>
  <LI>If using a project file, the indices are written into the <CODE>ADABROWSE_OUTPUT</CODE>
      directory.
      <BR><BR>
  <LI>Otherwise, this index is put in the current directory.

</UL>
<P>
If a filename containing a path is given, the index will be placed into that file in the given
directory. If the filename contains <EM>only</EM> a path, AdaBrowse will use that path and create
an index named "<CODE>index.html</CODE>" in the designated directory.
</P>
<P>
If a <CODE>-x</CODE> 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.
</P>
<P>
Note that if you give a filename to the <CODE>-i</CODE> option that starts with the letter "<CODE>s</CODE>",
you <EM>must</EM> have a white space between the option and the filename, otherwise it will be recognized
as a <CODE>-is</CODE> option. Also, if the filename starts with "<CODE>-</CODE>", there <EM>mustn't</EM>
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 "<CODE>-</CODE>"), and not as a filename.
</P>
<P>
The same caveat also applies to the <CODE>-p</CODE> option, if you want the subprogram index to go to a file
named "<CODE>rivate</CODE>": there must be a blank, otherwise, the whole thing will be recognized as the
<CODE>-private</CODE> option. (Admittedly this is a rather pathological case, but it's mentioned here for
completeness.)
</P>
<P>
For a full description of indices in AdaBrowse, see section 5.5,
&quot;<A HREF="#Index_Keys">Indexing</A>&quot;.
</P>

<H3 CLASS="toc"><A NAME="File_Names">4.4. Directory and File Names</A></H3>

<P>
  Since V.1.1, there may or may not be white space between the <CODE>-c</CODE>, <CODE>-f</CODE>,
  <CODE>-o</CODE>, <CODE>-s</CODE>, <CODE>-P</CODE>, <CODE>-I</CODE>, and <CODE>-T</CODE> options
  and the filename or directory or URL.
</P>
<P>
  Unfortunately, the directories given in the <CODE>-T</CODE> 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 <EM>does</EM> contain white space.
</P>
<P>
  In the <CODE>-I</CODE> option, AdaBrowse <EM>does</EM> 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".)
</P>
<P>
  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, <EM>do not use file
  or directory names containing white space</EM>. (It appears that the gcc driver
  doesn't re-quote the arguments when it passes them along to the gnat1
  executable.)
</P>
<P>
  This is not a problem with AdaBrowse, it is a problem with GNAT (and gcc).
  With other compilers, it might work.
</P>
<P>
  Note that <CODE>-I</CODE> options are only passed along to the compiler, never to ASIS.
</P>
<P>
  The filenames given in the <CODE>-c</CODE> and <CODE>-o</CODE> options may contain directory
  information, and they may contain blanks. These names are used only by
  AdaBrowse itself, and they are handled correctly.
</P>

<H3 CLASS="toc"><A NAME="Opt_History">4.5. Option History</A></H3>

<P>
  The options <CODE>-a</CODE>, <CODE>-all</CODE>, <CODE>--all</CODE>, and <CODE>-I</CODE> have been introduced in V1.01.
</P>
<P>
  The options <CODE>-q</CODE> and <CODE>-x</CODE> have been introduced in V1.1.
</P>
<P>
  The file input mode, the <CODE>-i</CODE> and <CODE>-is</CODE> options, and also the possibility to
  give a directory to the <CODE>-o</CODE> option have been introduced in V1.3.
</P>
<P>
  The subprogram and type indices as well as the associated options <CODE>-p</CODE> and
  <CODE>-t</CODE> have been introduced in V1.5.
</P>
<P>
  The <CODE>-g</CODE> option, which enables cross-reference generation to items from the standard library,
  has been introduced in V2.11.
</P>
<P>
  The <CODE>-l</CODE> and <CODE>-G</CODE> options have been introduced in V3.0.
</P>
<P>
  The <CODE>-private</CODE> option has been added in V3.2.
</P>
<P>
  The <CODE>-P</CODE> option has been added in V4.0. The indexing options <CODE>-i</CODE>,
  <CODE>-is</CODE>, <CODE>-p</CODE>, and <CODE>-t</CODE> have become obsolete in V4.0; they
  are superseded by the new <A HREF="#Index_Keys">indexing mechanism</A> (but they are still
  supported).
</P>

<H3 CLASS="toc"><A NAME="Opt_Examples">4.6. Examples</A></H3>

<P>
  Some examples, all using the sample files in directory <CODE>.\simple_test</CODE>:
  (All examples assume a clean slate; if you try these one after another,
  be sure to remove all <CODE>*.adt</CODE>, <CODE>*.ali</CODE>, and
  <CODE>*.html</CODE> 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.)
</P>
<OL>
  <LI>Generate all tree files, then run AdaBrowse on them:
      <DIV>
<PRE CLASS="small">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
</PRE></DIV>

  <LI>Let AdaBrowse generate the tree files:
      <DIV>
<PRE CLASS="small">for %i in (.\simple_test\*.ads) do adabrowse -I.\simple_test -I. -c .\simple_test.cfg -f %i
</PRE></DIV>

  <LI>Use a directory listing:
      <DIV>
<PRE CLASS="small">dir /b .\simple_test\*.ads &gt; simple_test.lst
adabrowse -I.\simple_test -I. -c simple_test.cfg -f @simple_test.lst
</PRE></DIV>

      (The <CODE>dir</CODE> command produces a list of filenames (without the
       "<CODE>.\simple_test\</CODE>"). The HTML files therefore end up in the directory
       <CODE>adabrowse_1.32</CODE>.)
       <BR><BR>
  <LI>Ditto, but using the Cygwin "<CODE>ls</CODE>" command, and reading directly from
      <CODE>stdin</CODE>:
      <DIV>
<PRE CLASS="small">ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -I.\simple_test -I. -c simple_test.cfg -f-
</PRE></DIV>
      (The Cygwin "<CODE>ls</CODE>" uses "/", not "\", and generates a listing of filenames
       that start with "<CODE>./simple_test/</CODE>". The Cygwin "<CODE>sed</CODE>" command
       then replaces all "/" by "\" in that output. The HTML files are put in directory
       <CODE>.\simple_test</CODE>.)
       <BR><BR>
       Note that on Unix systems, you won't need the "<CODE>sed</CODE>" 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 <CODE>GNAT.Os_Lib</CODE>
       considers the directory separator.)
       <BR><BR>
  <LI>As example 4, but we want the output in some other directory, and
      we want an index, too:
      <DIV>
<PRE CLASS="small">mkdir Testing
ls -1 ./simple_test/*.ads | sed -e "s@/@\\@g" | adabrowse -I.\simple_test -I. -c simple_test.cfg -f- -o .\Testing\ -i
</PRE></DIV>

      (The HTML files are placed in the new directory <CODE>.\Testing</CODE>.)
      <BR><BR>
  <LI>As example 5, but we assume we already have all the tree files
      (we generate them first); the index shall be structured and be written to file "<CODE>toc.html</CODE>".
      The example assumes we still have the subdirectory <CODE>.\Testing</CODE>:
      <DIV>
<PRE CLASS="small">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
</PRE></DIV>

      (The HTML files are placed in the directory <CODE>.\Testing</CODE>; the index
      is in <CODE>.\Testing\toc.html</CODE>. 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.)
      <BR><BR>

</OL>

<HR>
<H2 CLASS="toc"><A NAME="Config">5. Configuration Files</A></H2>

<P>
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.
</P>
<P>
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
<A HREF="#Descs">Descriptions</A>, <A HREF="#userdef">User-Defined HTML Mark-Up</A>,
<A HREF="#subst">Environment Variable Substitution</A>, and
<A HREF="#Comment_Format">Advanced Description Formatting</A>.
<P>

<H3 CLASS="toc"><A NAME="File_Syntax">5.1. Syntax of Configuration Files</A></H3>

<P>
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
</P>
<PRE>    key = value</PRE>
<P>
Key names are case <EM>in</EM>sensitive, 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.)
</P>
<P>
You can use as many configuration files as you like; they are processed in
the order of the corresponding <CODE>-c</CODE> 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.
</P>
<P>
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 (&quot;), or the backquote
character (&#96;)) up to the end of the line is taken as a comment and ignored. E.g.
</P>
<PRE>    Some_Key = hello 'world #', a nice day # and a comment
</PRE>
<P>
will set <CODE>Some_Key</CODE> to the value "<CODE>hello 'world #', a nice day</CODE>". Note that the
first '#' doesn't start the comment, as it is inside a string.
</P>
<P>
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 <EM>before</EM> the comment. E.g.
</P>
<PRE>    Compile = gcc # the compiler to use \
              -c -gnatc -gnatt
</PRE>
<P>
will set the compile command to "<CODE>gcc</CODE>" and then issue an error message for
the second line, but
</P>
<PRE>    Compile = gcc \ # The compiler to use
              -c -gnatc -gnatt
</PRE>
<P>
works fine and sets the compile command to "<CODE>gcc           -c -gnatc -gnatt</CODE>".
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
</P>
<PRE>    Some_Key = something\\

    # Rest of the configuration file...
</PRE>
<P>
Line continuations and trailing comments have been introduced in V 1.3.
</P>
<P>
<STRONG>Important note:</STRONG> comments and line continuations only are effecitive
<EM>outside</EM> 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 (&quot;), and the backquote
(&#96;). This is true even in places where normally other conventions apply, e.g. in commands
to be run! Hence, a <CODE>sed</CODE> command to replace all double quotes has to be written
as
</P>
<PRE>    sed -e"s/\""/\&amp;quot;/g" ...
</PRE>
<P>
in a configuration file, even though on the command line of your favorite shell, you'd
just write
</P>
<PRE>    sed -e"s/\"/\&amp;quot;/g" ...
</PRE>
<P>
The above applies to configuration file parsing in general. Normally, strings will occur
in a configuration file at the following places (if at all):
</P>
<UL>
  <LI>In <CODE><A HREF="#Comment_Block">Format</A></CODE> keys.
  <LI>In commands to be run (the values of
      <CODE><A HREF="#userdef_advanced">User_Tag.XYZ.Execute</A></CODE> or
      <CODE><A HREF="#userdef_advanced">User_Tag.XYZ.Set</A></CODE> keys,
      or in the value of a <CODE><A HREF="#Compilation">Compile</A></CODE>
      key, or in an <CODE><A HREF="#Format_Instruction">execute</A></CODE> filter).
  <LI>In an <CODE><A HREF="#Format_Instruction">enclose</A></CODE> filter.
  <LI>In the value of <CODE><A HREF="#HTML_Keys">Index_Title</A></CODE> keys.
  <LI>Anywhere you can meaningfully give some HTML tag: HTML tag attribute values
      may be quoted. Although in this case, the strings should not contain embedded
      delimiters anyway, as this would be invalid HTML.
</UL>
<P>
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 <CODE>&lt;SOME_TAG some_attribute="foo &amp;quot;bar&amp;quot;"&gt;</CODE>;
the HTML standard requires browsers to replace character entities in attribute values.
For the single quote, the character entity is <CODE>&amp;#39;</CODE>, the double quote
is <CODE>&amp;quot;</CODE>, and the backquote is <CODE>&amp;#96;</CODE>.)
</P>

<H3 CLASS="toc"><A NAME="File_Incl">5.2  File Inclusion</A></H3>

<DL>
  <DT><STRONG>Include_File</STRONG>

  <DD>New in V2.0.
      <BR><BR>
      AdaBrowse includes the file given by the key's value into the current configuration
      file at the place the <CODE>Include_File</CODE> key appears. The included file also
      had better be a configuration file. AdaBrowse does
      <A HREF="#subst">environment variable substitution</A> on the value first. If the
      value is empty, the key definition is ignored.
      <BR><BR>
      Recursive inclusion is not allowed.
</DL>

<H3 CLASS="toc"><A NAME="Compilation">5.3  Compilation</A></H3>

<DL>
  <DT><STRONG>Compile</STRONG>

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

<H3 CLASS="toc"><A NAME="HTML_Keys">5.4  HTML-related</A></H3>

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

<DL>
  <DT><STRONG>Char_Set</STRONG>

  <DD>Introduced in V1.2.
    <BR><BR>
    If defined, AdaBrowse will generate a line
    <BR><BR>
    <CODE>&lt;META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=value"&gt;</CODE>
    <BR><BR>
    in the <CODE>&lt;HEAD&gt;</CODE> section of the generated HTML file. By default, this
    is set to "ISO-8859-1", which is Latin-1.
    <BR><BR>
    This key is also used for the index.
    <BR><BR>

  <DT><STRONG><A NAME="StyleSheet">Style_Sheet</A></STRONG>

  <DD>Introduced in V1.0, modified in V2.0.
    <BR><BR>
    Defines a URL. If defined, AdaBrowse generates a line containing
    a link to the key's value in the <CODE>&lt;HEAD&gt;</CODE> section:
    <BR><BR>
    <CODE>&lt;LINK REL="stylesheet" HREF="value" TYPE="text/css"&gt;</CODE>
    <BR><BR>
    It follows that the value should be a URL relative to the <EM>final</EM>
    location where you'll put the generated HTML file, which may be
    different from the location where you generate them!
    <BR><BR>
    If the value is empty, no such link is generated.
    <BR><BR>
    This key is also used for the index. AdaBrowse does
    <A HREF="#subst">environment variable substitution</A> on the value first.
    <BR><BR>
    Note that AdaBrowse put a default style sheet directly into the generated HTML
    files using a <CODE>&lt;STYLE&gt;</CODE> element in the <CODE>&lt;HEAD&gt;</CODE>
    section. Your own style sheet defined by this key or with the "<CODE>-s</CODE>"
    option on the command-line may override these default style definitions.
    <BR><BR>

  <DT><STRONG>Body</STRONG>

  <DD>Defines the <CODE>&lt;BODY&gt;</CODE> tag to use. Also used for the index.
      <BR><BR>

  <DT><STRONG>Title.Before, Title.After</STRONG>

  <DD>Define what AdaBrowse puts around the page title (not the <CODE>&lt;TITLE&gt;</CODE> entry
    in the <CODE>&lt;HEAD&gt;</CODE> section, but the first title in the body). Also used for
    the index.
    <BR><BR>

  <DT><STRONG>Sub_Title.Before, Sub_Title.After</STRONG>

  <DD>Define what AdaBrowse puts around subtitles (such as "Dependences",
    "Header", and so on).
    <BR><BR>

  <DT><STRONG>Keyword.Before, Keyword.After</STRONG>

  <DD>Define what AdaBrowse puts around keywords (such as "<CODE>package</CODE>",
      "<CODE>type</CODE>", and so on).
      <BR><BR>

  <DT><STRONG>Attribute.Before, Attribute.After</STRONG>

  <DD>Define what AdaBrowse puts around attributes (such as "<CODE>'Class</CODE>",
      "<CODE>'Read</CODE>", and so on).
      <BR><BR>

  <DT><STRONG>Definition.Before, Definition.After</STRONG>

  <DD>Define what AdaBrowse puts around definitions, i.e. names of an entity
    being declared (such as the identifier "<CODE>My_Type</CODE>" in "<CODE>type My_Type is
    private;</CODE>").
    <BR><BR>

  <DT><STRONG>Comment.Before, Comment.After</STRONG>

  <DD>Define what AdaBrowse puts around comments (before the opening "<CODE>--</CODE>" and
    at the end of the line) that end up in-line in the generated output.
    <BR><BR>

  <DT><STRONG>Literal.Before, Literal.After</STRONG>

  <DD>Define what AdaBrowse puts around character and string literals.
      <BR><BR>
</DL>

<H3 CLASS="toc"><A NAME="Index_Keys">5.5. Indexing</A></H3>

<P>
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.
</P>

<H4>5.5.1. <A NAME="Index_Def">Index Definition</A></H4>

<P>
Indices are defined through the <CODE>Index.&lt;<EM>Identifier</EM>&gt; keys, where the
identifier defines the index name.
</P>

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

<H4>5.5.2. <A NAME="Index_Rule">Index Rules</A></H4>

<P>
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 <CODE>true</CODE>.
</P>
<P>
Expressions have the following syntax:
</P>
<PRE>
   Expression := Expr [<B>;</B>].
   Expr       := OR_Term {(<B>or</B>|<B>xor</B>) OR_Term}.
   OR_Term    := AND_Term {<B>and</B> AND_Term}.
   AND_Term   := EQ_Term {(<B>=</B>|<B>/=</B>) EQ_Term}.
   EQ_Term    := STR_Term {<B>@</B> STR_Term}.
   STR_Term   := Term {<B>&</B> Term}.
   Term       := [<B>not</B>] Factor.
   Factor     := <B>(</B> Expr <B>)</B> |
                 Identifier |
                 String_Literal.
</PRE>
<P>
   The syntax of identifiers and string literals is as in Ada. Parsing (as well as string comparisons
   and the <CODE>@</CODE> prefix operator) is case <EM>in</EM>sensitive.
</P>
<P>
   The identifier of a <CODE>Factor</CODE> shall resolve to either a user-defined
   function name (see the description of the <CODE><A HREF="#Def_Func">Rule</A></CODE>
   key below), or be one of the <A HREF="#Predef_Rule">predefined predicate</A> names.
</P>
   <P>
   Note that this syntax is a bit different from the Ada one:
   </P>
   <UL>
     <LI>It allows mixing different logical operators. All binary
         operators (including the logical ones <CODE>and</CODE>, <CODE>or</CODE>, and <CODE>xor</CODE>)
         are <EM>left-associative</EM>.
     <LI>Mixing logical operators is possible because <CODE>and</CODE> has higher
         precedence than <CODE>or</CODE> and <CODE>xor</CODE>, and because of
         left-associativity.
   </UL>
   <P>
   Parentheses can be used to override the normal precedences. The equality
   operators <CODE>=</CODE> and <CODE>/=</CODE> can compare either two boolean expressions, or
   two string expressions. String comparisons are case insensitive. The <CODE>&</CODE>
   is the string concatenation operator. The <CODE>@</CODE> binary operator takes two string
   arguments and returns a boolean value; it is <CODE>True</CODE> if the right argument is a
   prefix of the left one.
   </P>
   <P>
   An expression may or may not have a terminating semicolon.
   </P>
   <P>
   Example:
   </P>
   <PRE>
      A and B or C = D and E = F & G = H
   </PRE>
   <P>
   is the same as
   </P>
   <PRE>
      (A and B) or ((C = D) and ((E = (F & G)) = H))
   </PRE>

<H4>5.5.3. <A NAME="Predef_Rule">Predefined Predicates</A></H4>

<P>
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 <CODE>True</CODE> for particular classes of types. Finally,
there are two built-in function for getting the name of an item, and the boolean
constants.
</P>
<P>
General predicates:
</P>
<DL>
  <DT><STRONG>child</STRONG>
  <DD>Is <CODE>True</CODE> for all child units.
  <DT><STRONG>constant</STRONG>
  <DD>Is <CODE>True</CODE> for all constants and named numbers.
  <DT><STRONG>entry</STRONG>
  <DD>Is <CODE>True</CODE> for all entry declarations (of both tasks and protected
      types or objects).
  <DT><STRONG>exception</STRONG>
  <DD>Is <CODE>True</CODE> for all exception declarations (including renamings).
  <DT><STRONG>function</STRONG>
  <DD>Is <CODE>True</CODE> for all function declarations (including protected functions
      and renamings, instantiations, and generic declarations).
  <DT><STRONG>generic</STRONG>
  <DD>Is <CODE>True</CODE> for all generic declarations.
  <DT><STRONG>instance</STRONG>
  <DD>Is <CODE>True</CODE> for all instantiations of generics.
  <DT><STRONG>package</STRONG>
  <DD>Is <CODE>True</CODE> for all packages, including generics, renamings, and instantiations).
  <DT><STRONG>pragma</STRONG>
  <DD>Is <CODE>True</CODE> for all pragmas.
  <DT><STRONG>private</STRONG>
  <DD>Is <CODE>True</CODE> for all items declared in the private part of the
      enclosing package, task, or protected type (or object).
  <DT><STRONG>procedure</STRONG>
  <DD>Is <CODE>True</CODE> for all procedure declarations (including protected procedures
      and renamings, instantiations, and generic declarations).
  <DT><STRONG>representation</STRONG>
  <DD>Is <CODE>True</CODE> for all representation clauses.
  <DT><STRONG>separate</STRONG>
  <DD>Is <CODE>True</CODE> for all separate items. Note that AdaBrowse will
      never encounter a separate item because it only processes unit specs!
  <DT><STRONG>subprogram</STRONG>
  <DD>Equivalent to the expression <CODE>function&nbsp;<B>or</B>&nbsp;procedure</CODE>.
  <DT><STRONG>subtype</STRONG>
  <DD>Is <CODE>True</CODE> for all subtype declarations.
  <DT><STRONG>type</STRONG>
  <DD>Is <CODE>True</CODE> for all type declarations (but not subtype declarations!).
  <DT><STRONG>unit</STRONG>
  <DD>Is <CODE>True</CODE> for all compilation units.
  <DT><STRONG>variable</STRONG>
  <DD>Is <CODE>True</CODE> for all object declarations (variables, but also
      single task and protected obejct declarations).
</DL>
<P>
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 <CODE>class_wide</CODE> or <CODE>controlled</CODE>.
(The order given here also follows RM 3.2(12), with the extra predicates at the end.)
</P>
<DL>
  <DT><STRONG>elementary</STRONG>
  <DD>Is <CODE>True</CODE> for all elementary types.
  <DT><STRONG>scalar</STRONG>
  <DD>Is <CODE>True</CODE> for all scalar types.
  <DT><STRONG>discrete</STRONG>
  <DD>Is <CODE>True</CODE> for all discrete types.
  <DT><STRONG>enum</STRONG>
  <DD>Is <CODE>True</CODE> for all enumeration types.
  <DT><STRONG>integral</STRONG>
  <DD>Is <CODE>True</CODE> for all integral types.
  <DT><STRONG>signed</STRONG>
  <DD>Is <CODE>True</CODE> for all signed integer types.
  <DT><STRONG>modular</STRONG>
  <DD>Is <CODE>True</CODE> for all modular types.
  <DT><STRONG>real</STRONG>
  <DD>Is <CODE>True</CODE> for all real types.
  <DT><STRONG>float</STRONG>
  <DD>Is <CODE>True</CODE> for all floating-point types.
  <DT><STRONG>fixed</STRONG>
  <DD>Is <CODE>True</CODE> for all fixed-point types.
  <DT><STRONG>ordinary_fixed</STRONG>
  <DD>Is <CODE>True</CODE> for all ordinary fixed-point types.
  <DT><STRONG>decimal_fixed</STRONG>
  <DD>Is <CODE>True</CODE> for all decimal fixed-point types.
  <DT><STRONG>numeric</STRONG>
  <DD>Is <CODE>True</CODE> for all numeric types. Equivalent to the expression
      <CODE>integral&nbsp;<B>or</B>&nbsp;real</CODE>.
  <DT><STRONG>access</STRONG>
  <DD>Is <CODE>True</CODE> for all access types.
  <DT><STRONG>access_object</STRONG>
  <DD>Is <CODE>True</CODE> for all access-to-object types.
  <DT><STRONG>access_subprogram</STRONG>
  <DD>Is <CODE>True</CODE> for all access-to-subprogram types.
      <BR><BR>

  <DT><STRONG>composite</STRONG>
  <DD>Is <CODE>True</CODE> for all composite types.
  <DT><STRONG>array</STRONG>
  <DD>Is <CODE>True</CODE> for all array types (both constrained and unconstrained).
  <DT><STRONG>record</STRONG>
  <DD>Is <CODE>True</CODE> for all record types.
  <DT><STRONG>tagged</STRONG>
  <DD>Is <CODE>True</CODE> for all tagged record types.
  <DT><STRONG>limited</STRONG>
  <DD>Is <CODE>True</CODE> for all limited types, including task and protected types.
  <DT><STRONG>controlled</STRONG>
  <DD>Is <CODE>True</CODE> for all controlled types, i.e. types derived from one of the
      two types declared in package <CODE>Ada.Finalization</CODE>.
  <DT><STRONG>class_wide</STRONG>
  <DD>Is <CODE>True</CODE> for all class-wide types.
  <DT><STRONG>private_type</STRONG>
  <DD>Is <CODE>True</CODE> for all private types, including private extension declarations.
  <DT><STRONG>protected</STRONG>
  <DD>Is <CODE>True</CODE> for all protected objects and types, but also for all declarations
      within.
  <DT><STRONG>task</STRONG>
  <DD>Is <CODE>True</CODE> for all single tasks and task types, but also for entry declarations
      in tasks.
</DL>
<P>
Miscellaneous predicates:
</P>
<DL>
  <DT><STRONG>abstract</STRONG>
  <DD>Is <CODE>True</CODE> for all abstract types and subprograms.
  <DT><STRONG>aliased</STRONG>
  <DD>Is <CODE>True</CODE> for all aliased objects.
  <DT><STRONG>formal</STRONG>
  <DD>Is <CODE>True</CODE> for all generic formal declarations.
  <DT><STRONG>incomplete</STRONG>
  <DD>Is <CODE>True</CODE> for all incomplete types and for deferred constant declarations.
</DL>
<P>
Constants:
</P>
<DL>
  <DT><STRONG>false</STRONG>
  <DD>Is always <CODE>False</CODE>.
  <DT><STRONG>true</STRONG>
  <DD>Is (guess what?) always <CODE>True</CODE>.
</DL>
<P>
Built-in functions returning strings:
</P>
<DL>
  <DT><STRONG>name</STRONG>
  <DD>Returns the simple name of the item as a string.
  <DT><STRONG>full_name</STRONG>
  <DD>Returns the fully qualified name of the item as a string.
</DL>

<P>
Note that <CODE>elementary&nbsp;/=&nbsp;<B>not</B>&nbsp;composite</CODE>: there are types that
are neither elementary nor composite, such as private types.
</P>

<H4>5.5.4. <A NAME="Def_Func">User-Defined Functions</A></H4>

<P>
Besides these built-in predicates, you can also define your own rule functions with the
<CODE>Rule</CODE> key:
</P>
<DL>
  <DT><STRONG>Rule.&lt;<EM>Identifier</EM>&gt;</STRONG>
  <DD>
    Defines a named function. Wherever this name appears in a subsequent expression, it
    is replaced by the defining expression. (In this sense, the name "function" is actually
    wrong; it's more like a <EM>macro</EM>.)
    <BR><BR>
    Example:
    <CODE>Rule.entries_of_tasks = entry and not protected</CODE>
    <BR><BR>
</DL>

<H4>5.5.5. <A NAME="Idx_Options">Index Keys and Index Options</A></H4>

<P>
Versions of AdaBrowse prior to V4.0 only had the command line options (plus the few
<A HREF="#Idx_Keys_Old">obsolete keys</A> mentioned below) to define indices. These
options still exist, they are now defined in terms of the new indexing keys:
</P>
<DL>
  <DT><CODE>-i&nbsp;[<EM>file_name</EM>]</CODE> or <CODE>-is&nbsp;[<EM>file_name</EM>]</CODE>
  <DD>Defines a unit index named "Units". Equivalent to the index keys
<PRE>
  Index.Units.File_Name  = index (default) or <EM>file_name</EM>
  Index.Units.Title      = Unit Index
  Index.Units.Rule       = unit
</PRE>
  If the option <CODE>-is</CODE> is used, an additional key
<PRE>
  Index.Units.Structured = True
</PRE>
  is also defined.
  <BR><BR>

  <DT><CODE>-p&nbsp;[<EM>file_name</EM>]</CODE>
  <DD>Defines a subprogram index named "Subprograms". Equivalent to the index keys
<PRE>
  Index.Subprograms.File_Name = procidx (default) or <EM>file_name</EM>
  Index.Subprograms.Title     = Subprogram Index
  Index.Subprograms.Rule      = subprogram and not protected
</PRE>

  <DT><CODE>-t&nbsp;[<EM>file_name</EM>]</CODE>
  <DD>Defines a type index named "Types". Equivalent to the index keys
<PRE>
  Index.Types.File_Name = typeidx (default) or <EM>file_name</EM>
  Index.Types.Title     = Type Index
  Index.Types.Rule      = type or subtype
</PRE>

</DL>
<P>
The command line options can coexist with the new <CODE>Index</CODE> keys, and it is
possible to redefine in a configuration file the indices defined by the command line
options.
</P>

<H4>5.5.6. <A NAME="Idx_Example">An Example</A></H4>

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

<TABLE BORDER=0><TR><TD CLASS="sample">
<PRE>
  Index.My_Exceptions.File_Name = ex_idx
  Index.My_Exceptions.Title     = Public Exceptions
  Index.My_Exceptions.Rule      = exception and not (private or renaming);
</PRE>
</TD></TR></TABLE>

<H4>5.5.7. <A NAME="Idx_Keys_Old">Other Indexing Keys</A></H4>

<P>
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.
</P>

<DL>
  <DT><STRONG>Index_XRef</STRONG>

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

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

<DL>

  <DT><STRONG>Index_Title</STRONG>

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

       <DD>Sets the title for the unit index to "My Subsystem".
       Equivalent to <CODE>Index.Units.Title = My Subsystem</CODE>.
       <BR><BR>

       <DT><CODE>Index_Title.Unit_Index = My Subsystem</CODE>

       <DD>Ditto. Equivalent to <CODE>Index.Units.Title = My Subsystem</CODE>.
       <BR><BR>

       <DT><CODE>Index_Title.Type_Index = My Types</CODE>

       <DD>Sets the title for the type index to "My Types".<BR>
           Equivalent to <CODE>Index.Types.Title = My Types</CODE>.
       <BR><BR>

     </DL>

</DL>

<H3 CLASS="toc"><A NAME="XRef_Keys">5.6. Cross-References</A></H3>

<P>
  (New in V1.1)
</P>
<P>
  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.
</P>
<P>
  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 "<CODE>http://intranet.shop.com/core/doc/ref_manual/</CODE>".
</P>
<P>
  You are working in project X (which uses the core components), and are to
  place your project's HTML docu at "<CODE>http://intranet.shop.com/X/specs/</CODE>".
</P>
<P>
  Therefore, the HTML files you generate must prefix all cross references to
  a core component with either "<CODE>http://intranet.shop.com/core/doc/ref_manual/</CODE>"
  or, in this particular case, "<CODE>../../core/doc/ref_manual/</CODE>".
</P>
<P>
  Or maybe, for some reason, you don't want any cross-references to certain
  components at all.
</P>
<P>
  AdaBrowse has some keys which allow you to define exactly this behavior:
</P>
<DL>
<DT><STRONG>Path.&lt;Full_Unit_Name_Prefix&gt;</STRONG>

<DD>Modified in V2.0.
    <BR><BR>
    If defined, prepend the value to any cross-reference to a unit whose full
    unit name (starting with a root library unit name) has a prefix that matches
    <CODE>&lt;Full_Unit_Name_Prefix&gt;</CODE>. If several
    <CODE>&lt;Full_Unit_Name_Prefix&gt;</CODE>es match, the
    longest match wins. Matching is case-insensitive. Note that you specify a
    <EM>unit name prefix</EM>, not a file name prefix. I.e., you'd write "<CODE>Core.Os</CODE>",
    <EM>not</EM> "<CODE>core-os</CODE>".
    <BR><BR>
    Several <CODE>Path</CODE> keys may be defined. If two <CODE>&lt;Full_Unit_Name_Prefix&gt;</CODE>es are
    identical (except for casing), the later definition wins.
    <BR><BR>
    <CODE>&lt;Full_Unit_Name_Prefix&gt;</CODE> must not be empty, i.e. a definition like
    <BR><BR>
    <CODE>Path. = ...</CODE>
    <BR><BR>
    is illegal.
    <BR><BR>
    AdaBrowse does <A HREF="#subst">environment variable substitution</A> on the value.
    The value (after environment variable substitution) may be empty, in which case
    AdaBrowse does not prefix cross-references to matching units.
    <BR><BR>
    Example:
    <BR><BR>
    <TABLE><TR><TD>
<PRE>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/
</PRE></TD></TR></TABLE>

      If AdaBrowse wants to generate a cross-reference to a unit <CODE>CORE.OS</CODE> now,
      it'll check the list of pathes given and in this case, it'll generate
      the cross-reference to "<CODE>../../core/doc/ref_manual/core-os.html</CODE>". Note
      that the first path also matches, but "<CODE>Core</CODE>" is a longer match than
      "<CODE>Cor</CODE>". However, for a cross-reference to <CODE>COROLD.EXTERNAL</CODE>, the first path
      <EM>will</EM> match (whereas the second one won't as "<CODE>core</CODE>" is not a matching
      prefix), and the cross-reference will be generated to the URL
      "<CODE>http://intranet.shop.com/core_old/doc/rm/corold-external.html</CODE>".
      <BR><BR>

<DT><STRONG><A NAME="No_XRef">No_XRef</A> = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}</STRONG>

<DD>If defined, tells AdaBrowse never to generate cross-references to Units
    whose full name has a prefix matching one of the given unit name prefixes,
    <EM>unless</EM> a unit that would be thus excluded from cross-reference generation
    is explicitly included by a <CODE>XRef</CODE> key (see <A HREF="#XRef">below</A>).
    Matching is case-insensitive. White space around unit name prefixes is
    ignored, and so are empty unit name prefixes.
    <BR><BR>
    Multiple <CODE>No_XRef</CODE> keys may be defined. The set of prefixes considered is
    the union of all <CODE>No_XRef</CODE> keys' values. The value may be empty, in which
    case the key definition has no effect.
    <BR><BR>
    Matching is case-insensitive.
    <BR><BR>
    Example:
    <BR><BR>
    <TABLE><TR><TD>
<PRE>No_XRef = Core.Os ,,  , BC.Support
No_XRef = , Co ,
</PRE></TD></TR></TABLE>

      The set of prefixes is "<CODE>Co</CODE>", "<CODE>Core.Os</CODE>", "<CODE>BC.Support</CODE>".
      <BR><BR>

<DT><STRONG><A NAME="XRef">XRef</A> = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}</STRONG>
<DD>(New in V2.12.) This is the exact opposite of <CODE><A HREF="#No_XRef">No_XRef</A></CODE>. Cross-references
    to units matching one of the prefixes defined by <CODE>XRef</CODE> keys are <EM>always</EM>
    generated, even if the unit name would otherwise be excluded from cross-reference generation
    by a <CODE>No_XRef</CODE> key. I.e., <CODE>XRef</CODE> keys define exceptions to the set of
    units defined by <CODE>No_XRef</CODE> keys.
    <BR><BR>

<DT><STRONG><A NAME="Exclude_Key">Exclude</A> = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}</STRONG>

<DD>Same syntax as <CODE><A HREF="#No_XRef">No_XRef</A></CODE>. Defines a set of
    units for which no HTML files shall ever be generated. This is useful in
    particular in conjuction with the <CODE>-a</CODE> option: if your package in project
    X uses something from <CODE>Core</CODE>, AdaBrowse would normally also generate a HTML
    file for the core packages. But that's probably not what you want.
    <BR><BR>
    If the value is empty, all previous definitions of that key are reset,
    i.e., the set of units to exclude is (again) the empty set.
    <BR><BR>
    Multiple <CODE>Exclude</CODE> keys may be defined, the set of excluded units
    is the union of all keys' values (except for the empty value, see above).
    <BR><BR>
    Example:
    <BR><BR>
    <TABLE><TR><TD><CODE>Exclude = Core, BC</CODE></TD></TR></TABLE>
    <BR>
    If the unit you give in the (mandatory) <CODE>-f</CODE> option is excluded,
    AdaBrowse issues an error message.
    <BR><BR>
    Note: cross-references to a unit suppressed by an <CODE>Exclude</CODE> key will
    still be generated unless the unit is also suppressed by a
    <CODE><A HREF="#No_XRef">No_XRef</A></CODE> key.
	<BR><BR>
    Also note that AdaBrowse excludes by default all units from
    the Ada 95 standard library. (It only handles what ASIS calls
    "<CODE>An_Application_Unit</CODE>".)
    <BR><BR>

<DT><STRONG>Include</A> = Full_Unit_Name_Prefix {"," Full_Unit_Name_Prefix}</STRONG>
<DD>(New in V2.12) This is the exact opposite of <CODE><A HREF="#Exclude_Key">Exclude</A></CODE>. HTML files are
    always generated for units matching one of the prefixes defined by <CODE>Include</CODE> keys,
    even if the unit name would otherwise be excluded from cross-reference generation
    by an <CODE>Exclude</CODE> key. I.e., <CODE>include</CODE> keys define exceptions to the set of
    units defined by <CODE>Exclude</CODE> keys.
    <BR><BR>
    Do not confuse this key with the <CODE><A HREF="#File_Incl">Include_File</A></CODE> key, which
    is for including another configuration file into the current one.
    <BR><BR>

<DT><STRONG>Refs_To_Standard = (True | False)</STRONG>

<DD>(New in V2.11.) If this key is set to <CODE>True</CODE>, 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 <CODE>No_XRef</CODE>
    key. If it is set to <CODE>False</CODE> (the default), AdaBrowse won't generate such
    cross-references. In both cases, AdaBrowse will never generate cross-references to items
    from the implicit package <CODE>Standard</CODE>.
    <BR><BR>

</DL>

<P>
   AdaBrowse does <EM>longest prefix matching</EM> for the <CODE>[No_]XRef</CODE> and the
   <CODE>Exclude</CODE> or <CODE>Include</CODE> keys. This makes it possible to define
   precisely which units are to be included, and which ones are to be excluded. For instance,
</P>
<TABLE BORDER=0><TR><TD CLASS="sample">
<PRE>
   Exclude = System., System.Address_To_Access_Conversions.
   Include = System.Address_To_Access_Conversions
</PRE>
</TD></TR></TABLE>
<P>
   has the following effect:
</P>
<OL>
  <LI> <EM>exclude</EM> all children and further descendents from package <CODE>System</CODE>.
       That's the "<CODE>Exclude = System.</CODE>" part. Note the period: it <EM>doesn't</EM>
       exclude <CODE>System</CODE> itself!
       <BR><BR>
  <LI> <EM>include</EM> the package <CODE>System.Address_To_Access_Conversions</CODE> and all
       its children and further descendents. That's the <CODE>Include</CODE> key.
  <LI> <EM>exclude</EM> again any descendents of <CODE>System.Address_To_Access_Conversions</CODE>
       again. That's the second prefix in the <CODE>Exclude</CODE> key's value.
</OL>
<P>
   As a result, there will exactly two packages from the <CODE>System</CODE> subsystem be
   included: <CODE>System</CODE> itself, and <CODE>System.Address_To_Access_Conversions</CODE>.
   All other packages in this subsystem are excluded.
</P>

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

<P>
  If the <CODE>-a</CODE> 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 <CODE>Exclude</CODE> key, or for that no cross-
  references are generated anyway due to a <CODE>No_XRef</CODE> definition. AdaBrowse will
  issue a warning for each skipped unit to <CODE>stderr</CODE>. (If, in addition to <CODE>-a</CODE>,
  also <CODE>-x</CODE> was given, it'll also skip the unit if the corresponding HTML file
  already exists, and it'll also warn about that.)
</P>
<P>
  (Of course, if warnings are suppressed with the <CODE>-q</CODE> option, AdaBrowse will
  not issue these warnings.)
</P>

<H3 CLASS="toc"><A NAME="General">5.7. General Usage Hints</A></H3>

<P>
  The file <CODE>sample.cfg</CODE> gives the default settings AdaBrowse uses anyway if no
  configuration is used. In this default setting AdaBrowse generates valid
  <A HREF="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01</A>. However, if you
  redefine some keys inconsistently in a configuration file, AdaBrowse may generate invalid
  HTML. An example would be to define
</P>
<PRE>
    Keyword.Before = &lt;EM&gt;
    Keyword.After  = &lt;/STRONG&gt;
</PRE>
<P>
  or
</P>
<PRE>
    Comment.Before = &lt;EM&gt;
    Comment.After  =
</PRE>
<P>
  or (especially catastrophic)
</P>
<PRE>
    Body = &lt;!--
</PRE>
<P>
  Thus, be careful to define your values properly! Or use the default
  settings. AdaBrowse does <EM>not</EM> check whether or not the values defined
  make any sense.
</P>
<P>
  Note that the style sheet to use can be defined on the command line (with
  the <CODE>-s</CODE> option) or in a configuration file (with the
  <A HREF="#StyleSheet">Style_Sheet</A> key). The later definition wins.
</P>

<H3 CLASS="toc"><A NAME="Std_Lib_HTML">5.8. A More Elaborate Example</A></H3>
<P>
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 <CODE>GNAT_LIB_SRCS</CODE>. On my machine for
instance, <CODE>GNAT_LIB_SRCS</CODE> would have the value
<CODE>x:\gnat\lib\gcc-lib\pentium-mingw32msv\2.8.1\adainclude</CODE>.
</P>
<P>
First, create a directory where you want the generated HTML to go:
</P>
<TABLE BORDER=0 WIDTH="100%"><TR>
  <TD CLASS="sample">
<PRE CLASS="small">
   mkdir ./std_lib_html
</PRE>
</TD></TR></TABLE>
<P>
Then create a configuration file <CODE>./std_lib_html/std.cfg</CODE> with the following contents:
</P>
<TABLE BORDER=0 WIDTH="100%"><TR>
  <TD CLASS="sample">
<PRE>
   # 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
   # <EM>don't</EM> exclude System itself!
   No_XRef = System.

   # But <EM>do</EM> 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

</PRE>
</TD></TR></TABLE>
<P>
Then, execute the following commands (assuming Win NT/2k, but on Unix, it would be very
similar):
<P>
<TABLE BORDER=0 WIDTH="100%"><TR>
  <TD CLASS="sample">
<PRE CLASS="small">
   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
</PRE>
</TD></TR></TABLE>
<P>
Note the "<CODE>-g</CODE>" option! Also note that the above configuration file excludes only
the GNAT specific children of <CODE>System</CODE>, but it doesn't exclude GNAT-specific
additions to e.g. the <CODE>Ada</CODE> or <CODE>Interfaces</CODE> subsystem.
</P>
<P>
On my machine, the above execution of AdaBrowse takes about one minute and generates 205 HTML files
(using GNAT 3.15p).
</P>

<HR>
<H2 CLASS="toc"><A NAME="Descs">6. Descriptions</A></H2>

<P>
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.
</P>
<P>
Advanced topics on <A HREF="#userdef">user-defined HTML mark-up</A> and on how
to fine tune or even completely change the <A HREF="#Comment_Format">formatting
process</A> are described in their own sections following this basic introduction.
</P>

<H3 CLASS="toc"><A NAME="Find_Descs">6.1. Finding Descriptions</A></H3>

<P>
  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 <CODE>Description</CODE> keys
  explained below. For instance, you can tell AdaBrowse whether you generally
  put comments for a subprogram before or after the subprogram declaration.
</P>
<P>
  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 <A HREF="#Comment_Format">below</A>.
</P>

<H4>6.1.1. <A NAME="Comment_Def">Description Definitions</A></H4>

<P>
  The keys that tell AdaBrowse where to find the comments to create the
  descriptions of an entity from all start with "<CODE>Description.</CODE>" and all take a
  list written as comma-separated values as their argument. Legal list element
  values are:
</P>
<DL>
  <DT><STRONG>Before (Number)</STRONG>

  <DD>Take the comment above the entity to build the description from. There
     may be at most <CODE>Number</CODE> 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 <CODE>Number</CODE> 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.
     <BR><BR>
     Examples:
     <BR><BR>
     <DL>
       <DT><CODE>Description.Subprogram = Before (3)</CODE>

       <DD>Tells AdaBrowse that the description for a subprogram declaration can
       be found in a comment textually above the declaration, separated from
       the declaration by at most 3 empty lines.
       <BR><BR>

       <DT><CODE>Declaration.Subprogram = Before</CODE>

       <DD>The same, but the search for the comment is not limited to a particular
       number of empty lines.
       <BR><BR>
     </DL>

  <DT><STRONG>After (Number)</STRONG>

  <DD>Ditto, but AdaBrowse goes looking for a comment below the entity. The
     search starts at the end of the item and goes forward.
     <BR><BR>

  <DT><STRONG>Inside (Number)</STRONG>

  <DD>This value is allowed only for the "containers" (see below). It tells
     AdaBrowse that the descriptive comment is inside the entity, separated
     by at most 'Number' empty lines from the end of the header. The search
     goes forward. (An exception are library units, see the corresponding
     keys below.)
     <BR><BR>
     It can be applied to (generic) package declarations, task (type) declarations,
     and protected object and type declarations.
     <BR><BR>
     The header of each of these constructs is defined by AdaBrowse to end at
     the end of the "<CODE>is</CODE>":
     <BR><BR>
     <CODE>package XYZ <STRONG>is</STRONG></CODE><BR><BR>

     <CODE>generic ... package XYZ <STRONG>is</STRONG></CODE><BR><BR>

     <CODE>task (type) XYZ (Discriminants) <STRONG>is</STRONG></CODE><BR><BR>

     <CODE>protected (type) XYZ (Discriminants) <STRONG>is</STRONG></CODE><BR><BR>

  <DT><STRONG>None</STRONG>

  <DD>Tells AdaBrowse not to try to find any descriptive comment for the entity.<BR><BR>
</DL>
<P>
  In any case, search for a descriptive comment stops and comes up empty if
  either
</P>
<UL>
  <LI>a comment already taken as the description of some other entity is
      hit, or
  <LI>a line containing any non-comment is hit.
</UL>
<P>
  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.
</P>
<P>
  AdaBrowse recognizes the following description keys:
</P>
<DL>
<DT><STRONG>Description.Context_Clause</STRONG>

<DD>For the context clauses of a library unit. "Before" means "before the
    first context clause" and "After" means "after the last context clause".
    default setting is "<CODE>After (1)</CODE>".
    <BR><BR>

<DT><STRONG>Description.Clause</STRONG>

<DD>For interior "<CODE>use</CODE>" and "<CODE>use type</CODE>" clauses.
    Default setting is "<CODE>After (1)</CODE>".
    <BR><BR>

<DT><STRONG>Description.Subprogram</STRONG>

<DD>For subprogram, generic subprogram, entry, and entry family declarations.
    <BR><BR>

<DT><STRONG>Description.Renaming</STRONG>

<DD>For (generic) subprogram and package renamings. If not set explicitly,
    defaults to Description.Subprogram.
    <BR><BR>

<DT><STRONG>Description.Instantiation</STRONG>

<DD>For generic instantiations (subprograms or packages). If not set
    explicitly, defaults to Description.Subprogram.
    <BR><BR>

<DT><STRONG>Description.Constant</STRONG>

<DD>Applies to (deferred) constants and named numbers.
    <BR><BR>

<DT><STRONG>Description.Exception</STRONG>

<DD>For exception declarations including exception renamings.
    <BR><BR>

<DT><STRONG>Description.Pragma</STRONG>

<DD>For pragmas.
    <BR><BR>

<DT><STRONG>Description.Rep_Clause</STRONG>

<DD>For representation clauses.
    <BR><BR>

<DT><STRONG>Description.Type</STRONG>

<DD>For all types except task and protected types.
    <BR><BR>

<DT><STRONG>Description.Object</STRONG>

<DD>For all variable declarations and object renamings.
    <BR><BR>

<DT><STRONG>Description.Container</STRONG>

<DD>A global key for all "containers", i.e., (generic) package declarations
    that are not renamings, task (type) declarations, and declarations of
    protected objects and types.
    <BR><BR>

<DT><STRONG>Description.Task</STRONG>

<DD>For tasks and task types. If not set explicitly, defaults to
    Description.Container.
    <BR><BR>

<DT><STRONG>Description.Protected</STRONG>

<DD>For protected objects and types. Defaults to Description.Container.
    <BR><BR>

<DT><STRONG>Description.Package</STRONG>

<DD>For nested (generic) packages. Defaults to Description.Container.
    <BR><BR>

<DT><STRONG>Description.Library</STRONG>

<DD>For all library units. Here, "Before" means "before the context clauses",
    "Inside" means "between the context clauses and the beginning of the
    header" and "After" means "after the declaration" for library unit sub
    subprograms and renamings and "Inside, after the package header" for library
    unit (generic) packages.
    <BR><BR>
    If "Inside" is specified, the search for the comment starts at the
    beginning of the header, and the search goes backwards. It is thus
    possible to have
    <BR><BR>
    <TABLE BORDER=0><TR><TD CLASS="sample">
<PRE>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
   ...
</PRE></TD></TR></TABLE>

    The empty line between these two comments is crucial! Without this empty
    line, both Ada comment lines would be considered part of the same
    descriptive comment and be taken for the package description.
    (See <A HREF="#Extract_Descs">below</A>.)
    <BR><BR>
<DT><STRONG>Description.Library_Subprogram</STRONG>

<DD>For (generic) library subprograms. Defaults to Description.Library.
    <BR><BR>

<DT><STRONG>Description.Library_Package</STRONG>

<DD>For (generic) library packages. Defaults to Description.Library.
    <BR><BR>

<DT><STRONG>Description.Library_Renaming</STRONG>

<DD>For library unit (generic) renamings. Defaults to Description.Library.
    <BR><BR>

<DT><STRONG>Description.Library_Instantiation</STRONG>

<DD>For library units that are instantiations of other generic units. Defaults to Description.Library.
    <BR><BR>
</DL>

<H4><A NAME="Extract_Descs">6.1.2. How AdaBrowse maps Ada Comments to Descriptions</A></H4>

<P>
  Determining which comment belongs to which entity works as follows:
</P>
<P>
  Generally, for finding a description, AdaBrowse considers all specified
  locations in the order they appear in the list of the key.
</P>
<P>
  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.
</P>
<P>
  Next, it considers the context clauses and associates any description it
  finds with them (as a whole).
</P>
<P>
  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.
</P>
<P>
  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.
</P>
<P>
  Nested containers, that is, (generic) package declarations, task (type)
  declarations, and protected object and type declarations are handled
  similarly whenever the container is encountered.
</P>
<P>
  The default values, which mirror my own style, are as follows:
</P>
<TABLE BORDER=0>
<TR><TD ALIGN=LEFT>Description.Context_Clause</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Clause</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Subprogram</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Renaming</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Instantiation</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Constant</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Exception</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Pragma</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Rep_Clause</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Type</TD><TD ALIGN=LEFT>= After (1), Before</TD></TR>
<TR><TD ALIGN=LEFT>Description.Object</TD><TD ALIGN=LEFT>= After (1)</TD></TR>
<TR><TD ALIGN=LEFT>Description.Container</TD><TD ALIGN=LEFT>= Before, Inside</TD></TR>
<TR><TD ALIGN=LEFT>Description.Task</TD><TD ALIGN=LEFT>= Before, Inside</TD></TR>
<TR><TD ALIGN=LEFT>Description.Protected</TD><TD ALIGN=LEFT>= Before, Inside</TD></TR>
<TR><TD ALIGN=LEFT>Description.Package</TD><TD ALIGN=LEFT>= Before, Inside</TD></TR>
<TR><TD ALIGN=LEFT>Description.Library</TD><TD ALIGN=LEFT>= Before, After</TD></TR>
<TR><TD ALIGN=LEFT>Description.Library_Subprogram</TD><TD ALIGN=LEFT>= Before, After</TD></TR>
<TR><TD ALIGN=LEFT>Description.Library_Package</TD><TD ALIGN=LEFT>= Before, After</TD></TR>
<TR><TD ALIGN=LEFT>Description.Library_Renaming</TD><TD ALIGN=LEFT>= Before, After</TD></TR>
<TR><TD ALIGN=LEFT>Description.Library_Instantiation</TD><TD ALIGN=LEFT>= Before, After</TD></TR>
</TABLE>

<H3 CLASS="toc"><A NAME="Format_Descs">6.2. Basic Description Formatting</A></H3>

<P>
  A <EM>description</EM> for some declaration is thus a sequence of Ada 95 <EM>comments</EM>.
  These comments appear in the order the locations were given in the <CODE>Description</CODE> key
  definitions, not in the order they appeared in the original Ada 95 source.
</P>
<P>
  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 "<CODE> --</CODE>" (for box comments) is also removed. The comment prefix is
  normally "<CODE>--</CODE>" (of course), but more elaborate prefixes can be defined; see
  <A HREF="#Comment_Format">below</A>. Then, any trailing white-space is removed. What remains
  is the <EM>content</EM> of the description.
</P>
<P>
  This description content is then processed in various ways (which you can define, see
  <A HREF="#Comment_Format">below</A>) 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.
</P>

<H4><A NAME="Default_Format">6.2.1. Default Formatting</A></H4>

<P>
  By default, HTML comments within Ada comments (started by "<CODE>&lt;!--</CODE>" and extending up to the
  next "<CODE>--&gt;</CODE>") 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 "&lt;" in an Ada comment will be written as
  "<CODE>&amp;lt;</CODE>" into the HTML file. (Unless, of course, the "&lt;" is the opening
  of an HTML tag.) Characters beyond the 7-bit ASCII range (like e.g. "&uuml;") are
  replaced by numeric character entities, in this case by "<CODE>&amp;#252;</CODE>".
</P>
<P>
  Empty Ada comment lines (i.e., starting with "<CODE>--</CODE>" and then followed by white-space
  only (and possibly a terminating "<CODE> --</CODE>")) cause new paragraphs to be
  started, so it is in general not necessary to put <CODE>&lt;P&gt;</CODE> tags in your comments.
<P>
  AdaBrowse uses a simplified parsing of Ada comments to determine what is an HTML tag.
  It considers anything starting with a "&lt;" followed by a character or a "/" and a character up
  to the next "&gt;" that is not within a &quot;&quot;&quot;-delimited string a HTML tag. This
  works pretty well in practice, but may fail in some circumstances:
</P>
<UL>
  <LI>If you have an Ada comment like "<CODE>--&nbsp;This&nbsp;function&nbsp;returns&nbsp;True&nbsp;iff&nbsp;10&lt;a</CODE>",
      AdaBrowse thinks the "<CODE>&lt;a</CODE>" was the start of a HTML tag. To avoid this, write your comment
      as "<CODE>--&nbsp;This&nbsp;function&nbsp;returns&nbsp;True&nbsp;iff&nbsp;10&nbsp;&lt;&nbsp;a</CODE>",
      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.)
      <BR><BR>
  <LI>The same problem occurs in an Ada comment like
      "<CODE>--&nbsp;Author:&nbsp;&lt;somebody@somewhere.org&gt;</CODE>": AdaBrowse will treat the
      whole e-mail address as a HTML tag. Either omit the "&lt;" and "&gt;" around the e-mail
      address, or write them as "<CODE>&amp;lt;</CODE>" and "<CODE>&amp;gt;</CODE>", or make sure there's a space
      following the "&lt;" as in "<CODE>--&nbsp;Author:&nbsp;&lt;&nbsp;somebody@somewhere.org&nbsp;&gt;</CODE>".
</UL>

<H4><A NAME="Code_Shortcut">6.2.2. A Shortcut for the <CODE>&lt;CODE&gt;</CODE>-Tag</A></H4>

<P>
  I also found that the most often used HTML tag in Ada 95 comments tends to be
  <CODE>&lt;CODE&gt;</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>&lt;CODE&gt;</CODE>-tag:
  Any <EM>pair</EM> of "<CODE>@</CODE> without white-space in
  between is replaced by "<CODE>&lt;CODE&gt;</CODE>" and "<CODE>&lt;/CODE&gt;</CODE>",
  respectively. Hence the Ada comment
</P>

<TABLE><TR><TD CLASS="sample"><PRE>
This function returns @True@ iff 10 &lt; @a@
</PRE></TD></TR></TABLE>

<P>
  will be written as
</P>

<TABLE><TR><TD CLASS="sample"><PRE>
This function returns &lt;CODE&gt;True&lt;/CODE&gt; iff 10 &lt; &lt;CODE&gt;a&lt;/CODE&gt;
</PRE></TD></TR></TABLE>

<P>
  into the HTML file, and will be rendered as
</P>

<TABLE><TR><TD CLASS="sample">
This function returns <CODE>True</CODE> iff 10 &lt; <CODE>a</CODE>
</TD></TR></TABLE>

<P>
  The "<CODE>@</CODE>"-pair handling is intended to catch and simplify the most common uses of the
  <CODE>&lt;CODE&gt;</CODE>-tag, but it cannot replace <EM>all</EM> uses of <CODE>&lt;CODE&gt;</CODE>.
</P>

<P>
  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:
</P>
<OL>
  <LI><EM>User-defined HTML mark-up</EM> can be used to define your own tags that are macro-expanded. There
      are even ways to define tags that include other files, or that call an external command and
      replace the tag by the command's output. This is described in detail in the section on
      <A HREF="#userdef">user-defined HTML mark-up</A>.
      <BR><BR>
  <LI><EM>Format instructions</EM> allow you to define exactly how AdaBrowse shall format a comment.
      You may define special prefixes and format instructions that apply to all Ada 95 comments
      that start with those prefixes (for instance, you could make any comments beginning with
      "<CODE>--!</CODE>" to be written in a &lt;PRE&gt; block). You may also redefine how
      AdaBrowse formats comments in general by defining your own format instructions for the
      standard prefix "<CODE>--</CODE>". 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
      <A HREF="#Comment_Format">advanced description formatting</A>.
      <BR><BR>
</OL>

<P>
  However, for your first experiments, just use the default settings. As a next step, I suggest trying
  out the "<CODE>@</CODE>"-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.
</P>

<HR>
<H2 CLASS="toc"><A NAME="userdef">7. User-Defined Mark-Up</A></H2>

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

<H3 CLASS="toc">7.1. <A NAME="basic_syntax">Basic Syntax</A></H3>

<P>
A user-defined HTML element is defined by keys of the form
<STRONG><CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;</CODE></STRONG>.
<CODE>&lt;TAG_IDENTIFIER&gt;</CODE> must
be an <A NAME="identifier">identifier</A>, which in AdaBrowse has the syntax
</P>
<PRE>
    Identifier = Letter <B>{</B> Letter <B>|</B> Digit <B>|</B> '_' <B>}</B>.
    Letter     = 'A' .. 'Z' <B>|</B> 'a' ..'z'.
    Digit      = '0' .. '9'.
</PRE>
<P>
This is the same syntax as for Ada 95 identifiers, except that it allows multiple
underscores in a row as well as trailing underscores.
</P>
<P>
To define a container element, the syntax is
</P>
<PRE>
    User_Tag.&lt;TAG_IDENTIFIER&gt;<STRONG>.Before</STRONG> = Definition
    User_Tag.&lt;TAG_IDENTIFIER&gt;<STRONG>.After</STRONG>  = Definition
</PRE>
<P>
Both the "<CODE>.Before</CODE>" and the "<CODE>.After</CODE>" must be present. If one or
the other is missing, AdaBrowse will issue an error message. The "<CODE>.Before</CODE>"
definition replaces any occurrence of the opening tag, and the "<CODE>.After</CODE>"
definition replaces occurrences of the closing tag.
</P>
<P>
To define a non-container element, use the syntax
</P>
<PRE>
    <STRONG>User_Tag.&lt;TAG_IDENTIFIER&gt;</STRONG> = Definition
</PRE>
<P>
i.e. without either "<CODE>.Before</CODE>" or "<CODE>.After</CODE>". In both cases,
the key is case <EM>in</EM>sensitive, 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:
</P>
<PRE>
    User_Tag.&lt;TAG_IDENTIFIER&gt;<STRONG>.Enabled</STRONG> = (True | False)
</PRE>
<P>
By default, all user-defined HTML elements are <EM>enabled</EM>. If an element is
<EM>disabled</EM>, it is completely suppressed. If a container element is disabled,
all its content also is suppressed.
</P>

<H3 CLASS="toc">7.2. <A NAME="userdef_example">A Simple Example</A></H3>

<P>
Consider the following configuration file:
</P>
<PRE>
    User_Tag.COPYRIGHT.Before = &lt;BLOCKQUOTE&gt;&lt;STRONG&gt;Copyright (c)
    User_Tag.COPYRIGHT.After  = &lt;/STRONG&gt;&lt;/BLOCKQUOTE&gt;

    User_Tag.AUTHOR = Thomas Wolf
</PRE>
<P>
An Ada comment like
</P>
<PRE>    --  &lt;COPYRIGHT&gt; 2002 by &lt;AUTHOR&gt;&lt;/COPYRIGHT&gt;</PRE>
<P>
will thus be written to the generated HTML file as:
</P>
<PRE>&lt;BLOCKQUOTE&gt;&lt;STRONG&gt;Copyright (c) 2002 by Thomas Wolf&lt;/STRONG&gt;&lt;/BLOCKQUOTE&gt;</PRE>
<P>
and will be rendered as
</P>
<BLOCKQUOTE><STRONG>Copyright (c) 2002 by Thomas Wolf</STRONG></BLOCKQUOTE>
<P>
Note how the non-container element "AUTHOR" works like a variable!
</P>
<P>
The same effect can also be achieved with the configuration file
</P>
<PRE>
    User_Tag.COPYRIGHT.Before = &lt;BLOCKQUOTE&gt;&lt;STRONG&gt;Copyright (c)
    User_Tag.COPYRIGHT.After  = by &lt;Author&gt;&lt;/STRONG&gt;&lt;/BLOCKQUOTE&gt;

    User_Tag.AUTHOR = Thomas Wolf
</PRE>
<P>
and the Ada comment
</P>
<PRE>    --  &lt;COPYRIGHT&gt; 2002 &lt;/COPYRIGHT&gt;</PRE>
<P>
This latter example also shows that user-defined tags can be defined in terms of other
user-defined tags: AdaBrowse performs <EM>macro substitution</EM> 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
</P>
<PRE>
    User_Tag.RECURSIVE   = &lt;NOT_ALLOWED&gt;
    User_Tag.NOT_ALLOWED = &lt;RECURSIVE&gt;
</PRE>
<P>
it issues an error message and terminates.
</P>

<H3 CLASS="toc">7.3. <A NAME="userdef_advanced">Advanced User-Defined Variables</A></H3>

<P>
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.
</P>
<P>
AdaBrowse offers some more advanced ways to set such user-defined variables (all these
definitions define non-container HTML elements):
</P>
<DL>
  <DT><CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;.<STRONG>Include</STRONG> = File_Name</CODE>
  <DD>
     Replaces any occurrence of <CODE>&lt;TAG_IDENTIFIER&gt;</CODE> by the verbatim
     contents of the file <CODE>File_Name</CODE>. If the file cannot be found or
     read, AdaBrowse issues a warning and replaces the tag by the empty string.
     Within <CODE>File_Name</CODE>, AdaBrowse performs environment variable
     <A HREF="#subst">substitution</A>!
     <BR><BR>
     Note that AdaBrowse does not parse the file in any way, so inside the included
     file, AdaBrowse's user-defined HTML elements are <EM>not</EM> available; the file
     should contain standard HTML only. Also, it is good, prudent practice to make
     the file self-contained in the sense that it should close all container elements
     it has opened. Otherwise, the HTML file generated by AdaBrowse may become hopelessly
     garbled.
     <BR><BR>
     If the file name is empty, no file inclusion occurs, and the tag is replaced by the empty
     string.
     <BR><BR>
  <DT><CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;.<STRONG>Execute</STRONG> = Command</CODE>
  <DD>
     For each occurrence of <CODE>&lt;TAG_IDENTIFIER&gt;</CODE>, AdaBrowse runs the
     <CODE>Command</CODE>
     and replaces the tag by the entire output of the command. Note that the command
     had better not read from <CODE>stdin</CODE>, and it also had better return. If the
     command blocks (does not return), so will AdaBrowse!
     Within the <CODE>Command</CODE>, AdaBrowse performs environment variable
     <A HREF="#subst">substitution</A>.
     <BR><BR>
     The command's output is placed verbatim into the generated HTML file, so again,
     no user-defined HTML elements are available.
     <BR><BR>
     If the command is empty, no command is run and the tag is replaced by the empty string.
     <BR><BR>
  <DT><CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;.<STRONG>Set</STRONG> = Command</CODE>
  <DD>
     As the <CODE>Execute</CODE> selector, but the command is run only once upon the
     first occurrence of <CODE>&lt;TAG_IDENTIFIER&gt;</CODE>. 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 <EM>does</EM> parse the value and expand any
     contained references to other user-defined HTML elements!
     Within the <CODE>Command</CODE>, AdaBrowse performs environment variable
     <A HREF="#subst">substitution</A>.
     <BR><BR>
     If the command is empty, no command is run and the tag is replaced by the empty string.
     <BR><BR>
  <DT><CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;.<STRONG>Variable</STRONG> = ...</CODE>
  <DD>
     As a normal non-container definition of the form <CODE>User_Tag.&lt;TAG_IDENTIFIER&gt;</CODE>
     (without selector), but AdaBrowse performs environment variable
     <A HREF="#subst">substitution</A> on the value.
     <BR><BR>
</DL>

<H3 CLASS="toc"><A NAME="userdef_params">7.4. Parameters of User-Defined Tags</A></H3>

<P>
(Introduced in V2.1)
</P>
<P>
User-defined HTML tags may also have parameters. AdaBrowse considers anything after the tag
identifier in an opening tag up to the closing "<CODE>&gt;</CODE>" the parameters of the tag.
This is similar to standard HTML (where parameters are called "attributes"). Consider e.g.
</P>
<PRE>
    &lt;A HREF="http://www.somewhere.org/" TARGET="_top"&gt;
</PRE>
<P>
In AdaBrowse's terms, this tag has two parameters: one has the name <CODE>HREF</CODE> and the
value <CODE>http://www.somewhere.org/</CODE>, and the other one is named
<CODE>TARGET</CODE> and has the value <CODE>_top</CODE>.
</P>
<P>
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 (<CODE>"</CODE>) 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!
</P>
<P>
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
<A HREF="#env_syntax">environment variable references</A> as explained below, <EM>except</EM>
that the initial character introducing a reference is <EM>not</EM> the "<CODE>$</CODE>" sign
but the "<CODE>%</CODE>" sign. Of course, indirect and recursive references for parameters don't
make much sense and therefore are not allowed.
</P>
<P>
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:
</P>
<UL>
  <LI>Define an HTML tag that includes any file given:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.INCLUDE_ANY.Include = %File</PRE>
      </TD></TR></TABLE>
      A tag <CODE>&lt;INCLUDE_ANY FILE="../somefile.html"&gt;</CODE> will then be replaced by
      the contents of file <CODE>../somefile.html</CODE>. Another tag <CODE>&lt;INCLUDE_ANY
      FILE="other.html"&gt;</CODE> will be replaced by the contents of file
      <CODE>other.html</CODE>. And an <CODE>INCLUDE_FILE</CODE> tag that doesn't have a
      parameter named <CODE>File</CODE> will be silently ignored, since references to undefined
      parameters are replaced by the empty string.
      <BR><BR>
  <LI>Pass parameters to an external command:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.RUN_IT.Execute = some_program %Params</PRE>
      </TD></TR></TABLE>
      A tag <CODE>&lt;RUN_IT PARAMS="-I..&nbsp;-I../something&nbsp;-q&nbsp;-x"&gt;</CODE>
      will then run the command
      "<CODE>some_program&nbsp;-I..&nbsp;-I../something&nbsp;-q&nbsp;-x</CODE>" and replace
      the tag with the output of this command.
      <BR><BR>
  <LI>Pass on some parameters to other tags (standard or user-defined):
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.MY_TAG.Before = &lt;SPAN %{Class:+Class="%Class"}&gt;
User_Tag.MY_TAG.After  = &lt;/SPAN&gt;</PRE>
      </TD></TR></TABLE>
      A fragment like <CODE>&lt;MY_TAG&nbsp;CLASS="something"&gt;Text&lt;/MY_TAG&gt;</CODE> will then
      be replaced by <CODE>&lt;SPAN&nbsp;Class="something"&gt;Text&lt;/SPAN&gt;</CODE>. Note that
      the value of <CODE>%Class</CODE> is just <CODE>something</CODE> (without the quotes, see
      above)! Occurrences of <CODE>MY_TAG</CODE> <EM>without</EM> a <CODE>Class</CODE> parameter
      will expand into a <CODE>SPAN</CODE> tag without parameters. (That's the definition of the
      "<CODE>:+</CODE>" operator used in this example, see <A HREF="#subst_operators">below</A>
      for more information.)
      <BR><BR>
</UL>
<P>
Because the form used in the last example ("<CODE>%{Param:+Param="%Param"}</CODE>") is so
common, the syntax <CODE>%{!Param}</CODE> 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.)
</P>
<P>
The special parameter name <CODE>%</CODE> is defined to denote <EM>all</EM> parameters of the
user-defined HTML tag. I.e., a reference of the form "<CODE>%%</CODE>" or "<CODE>%{%}</CODE>"
is replaced by whatever followed the tag identifier up to the closing "<CODE>&gt;</CODE>" sign.
Example:
</P>
<PRE>
    User_Tag.MY_TAG.Before = &lt;SPAN %%&gt;
    User_Tag.MY_TAG.After  = &lt;/SPAN&gt;
</PRE>
<P>
effectively defines <CODE>MY_TAG</CODE> as an alias for <CODE>SPAN</CODE>.
</P>
<P>
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.
</P>

<HR>
<H2 CLASS="toc"><A NAME="subst">8. Environment Variable Substitution</A></H2>

<P>
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.
</P>

<H3 CLASS="toc">8.1. <A NAME="env_syntax">Syntax and Semantics</A></H3>

<P>
AdaBrowse uses for environment variable substitution a syntax very similar to
that of the GNU <CODE>bash</CODE> shell. An environment variable has a name, which is an
identifier as defined <A HREF="#identifier">above</A>. A simple reference to an environment
variable has the form
</P>
<PRE>
    $Identifier
</PRE>
<P>
and is replaced as a whole (including the '<CODE>$</CODE>' sign) by the variable's value or
by the empty string if no such environment variable is defined.
</P>
<P>
More interesting are the complex variable references, which have the syntax
</P>
<PRE>
    Value         = <EM>any string, maybe containing environment variable references</EM>.
    Operator      = :- <B>|</B> :+.
    Reference     = ${Variable_Name<B>[</B>Operator<B>[</B>Value<B>]]</B>}.
    Variable_Name = Value <B>|</B> !Identifier.
</PRE>
<P>
In all forms, <CODE>Variable_Name</CODE> can have one of three formats:
</P>
<UL>
  <LI>An identifier: expands to the empty string if no such environment variable
      is defined, and to the variable's value otherwise.
  <LI>A '<CODE>!</CODE>' 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 <EM>indirect expansion</EM>, and is limited
      to one level of indirection only.
  <LI>Some arbitrary string that may contain embedded references to environment
      variables: environment variable substitution is performed on the whole thing,
      and the resulting value is taken to be the name of an environment variable,
      which is then expanded. This <EM>recursive expansion</EM> is <EM>unknown</EM>
      in <CODE>bash</CODE>, and it is done for as many levels as specified.
</UL>
<P>
The semantics of these forms is as <A NAME="subst_operators">follows</A>:
</P>
<DL>
  <DT><CODE>${Variable_Name}</CODE>
  <DD>Is identical to the simple form of references <CODE>$Identifier</CODE> except that it
      also allows indirect and recursive expansion.
      <BR><BR>
  <DT><CODE>${Variable_Name:-Value}</CODE>
  <DD>Is replaced by the result of <CODE>${Variable_Name}</CODE> unless that result is empty,
      in which case it is replaced by the expansion of <CODE>Value</CODE>.
      <BR><BR>
  <DT><CODE>${Variable_Name:+Value}</CODE>
  <DD>Is replaced by the expansion of <CODE>Value</CODE> if the result of
      <CODE>${Variable_Name}</CODE> is non-empty, or the empty string otherwise.
      (<CODE>:+</CODE> is the inverse of <CODE>:-</CODE>.)
      <BR><BR>
</DL>
<P>
Indirect expansion using the '<CODE>!</CODE>' character is supported only to keep the syntax
as close to the one used by <CODE>bash</CODE> as possible. It is actually superfluous and can
be replaced by the more powerful (and, so I think, simpler because more regular) recursive
expansion: "<CODE>${!Some_Name}</CODE>" is identical to "<CODE>${${Some_Name}}</CODE>" or
"<CODE>${$Some_Name}</CODE>".
</P>
<P>
In the operators <CODE>:-</CODE> and <CODE>:+</CODE>, the '<CODE>:</CODE>' is actually optional.
It appears that it is optional in <CODE>bash</CODE> (although the manual doesn't say so),
and I have therefore chosen to make it optional in AdaBrowse, too.
</P>

<P>
Within configuration files, AdaBrowse also supports two <EM>special</EM> "environment" variables
named '<CODE>@</CODE>' and '<CODE>$</CODE>'.
</P>

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

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

<UL>
  <LI><CODE>Compile</CODE>,
  <LI><CODE>Include_File</CODE>,
  <LI><CODE>Path....</CODE>,
  <LI><CODE>Style_Sheet</CODE>, and
  <LI><CODE>User_Tag....</CODE> with selectors "<CODE>.Execute</CODE>", "<CODE>.Include</CODE>",
      "<CODE>.Set</CODE>", "<CODE>.Variable</CODE>", and (new in V2.1) "<CODE>.Enabled</CODE>".
</UL>

<P>
To include a literal dollar sign '<CODE>$</CODE>' in any of these keys' values, escape it
with a backslash and write "<CODE>\$</CODE>". 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 <EM>two</EM> backslashes before the dollar. The
sequence "<CODE>\\</CODE>" immediately followed by a variable reference is replaced by
a single backslash and the substitution of the reference. I.e.,
"<CODE>${SOME_PATH}\${SOME_FILE}</CODE>" won't do what is expected, but
"<CODE>${SOME_PATH}\\${SOME_FILE}</CODE>" will (and there will be <EM>one</EM> backslash
between the two variable substitutions).
</P>

<H3 CLASS="toc">8.2. <A NAME="env_examples">Some Examples</A></H3>

<UL>
  <LI>Include a configuration file, but only if a variable giving a prefix of its path
      is set:
      <TABLE BORDER=0><TR><TD>
      <PRE>

Include_File = ${PATH_TO_FILE:+$PATH_TO_FILE\file.cfg}</PRE>
      </TD></TR></TABLE>

  <LI>To include the current date:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.Date.Set = date /t</PRE>
      </TD></TR></TABLE>
      (or whatever the equivalent on Unix would be).
      <BR><BR>
  <LI>To supply a default path, if an environment variable that should be set isn't:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.GMGPL.Include = ${ADABROWSE_HOME:-.}\gmgpl.html</PRE>
      </TD></TR></TABLE>

  <LI>To specify a file relative to the location of the configuration file the key is
      in:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.XYZ.Include = $@some_file.html</PRE>
      </TD></TR></TABLE>

  <LI>To enable a user-defined tag depending on the setting of some environment variable:
      <TABLE BORDER=0><TR><TD>
      <PRE>

User_Tag.SOME_TAG.Enabled = ${SOME_VAR:-False}</PRE>
      </TD></TR></TABLE>
      Note that in this example, the environment variable <CODE>SOME_VAR</CODE>, if defined,
      must have one of the values "<CODE>True</CODE>" or "<CODE>False</CODE>"; otherwise an
      error will occur because the "<CODE>.Enabled</CODE>" selector is defined to accept only
      these two definitions. If the environment variable is not defined (or defined as the
      empty string), the "<CODE>:-</CODE>" operator makes this be treated as <CODE>False</CODE>.
      <BR><BR>
</UL>

<HR>
<H2 CLASS="toc"><A NAME="Comment_Format">9. Advanced Description Formatting</A></H2>

<P>
  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.
</P>

<H3 CLASS="toc"><A NAME="General_Format">9.1. Structure of a Description</A></H3>

<P>
  As mentioned <A HREF="#Format_Descs">above</A>, 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 <EM>blocks</EM>.
</P>

<H4><A NAME="Comment_Block">9.1.1. Comment Blocks and Prefixes</A></H4>

<P>
  A <EM>comment block</EM> 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 <EM>format instructions</EM> defined for the prefix of the lines in each block.
</P>
<P>
  The default prefix is "<CODE>--</CODE>", so by default any Ada 95 comment forms one block.
  Additional prefixes for splitting a comment into <EM>blocks</EM> are defined by the
  configuration key <CODE>Format</CODE>:
</P>
<PRE>
    Format.&lt;Prefix&gt; = <EM>Format_Instruction</EM>
</PRE>
<P>
<CODE>&lt;Prefix&gt;</CODE> is a string, which must start with "<CODE>--</CODE>". AdaBrowse
issues an error if the string doesn't start with "<CODE>--</CODE>". Any consecutive comment
lines (beginning with the "<CODE>--</CODE>" in the Ada source) that start with the same prefix
belong to one comment block. If several prefixes match, the longest match wins.
</P>
<P>
As with most configuration keys, later definitions of a format for the same prefix override
earlier definition for that prefix. A definition of a "<CODE>Format</CODE>" key with an empty
right-hand side (i.e., only white space in the value after the "<CODE>=</CODE>") removes the
comment prefix and any format instructions previously defined for it, <EM>except</EM> in the case
of the standard prefix "<CODE>--</CODE>" (which cannot be removed) where such an empty definition
reverts to the <A HREF="#Standard_Format">default formatting</A>.
</P>
<P>
The prefix "<CODE>--</CODE>" is predefined as if a key &quot;<CODE>Format."--"&nbsp;=&nbsp;...</CODE>&quot;
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
<CODE>Format."--"</CODE>. 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.
</P>
<P>
The <EM>Format Instruction</EM> for a given prefix defines how the <EM>content</EM> 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 <EM>not</EM> self-contained.
</P>
<P>
To show how different format instructions for different blocks can be used, consider the following
example:
<P>
<TABLE BORDER=0><TR>
  <TD WIDTH="10%">&nbsp;</TD>
  <TD CLASS="sample">
    <P>
    Assume our Ada sources contain not only normal Ada comments starting with "<CODE>--</CODE>",
    but also comment lines starting with "<CODE>--!</CODE>" that shall somehow be formatted
    specially, for instance these lines might contain sample code.
    </P>
    <P>
    We can now define a comment prefix
    </P>
    <PRE>
    Format."--!" = <EM>some format instructions</EM></PRE>
    <P>
    to make AdaBrowse format any such comment lines e.g. by including them verbatim in a
    <CODE>&lt;PRE&gt;&lt;/PRE&gt;</CODE> block. (I'll soon explain <EM>how</EM> to write
    such a format instruction below.) As a result, a comment like
    </P>
    <PRE>
    ------------------------------------------------------
    --  This is an example usage of procedure @Foo@:
    --
    --!   declare
    --!      X : Integer := 42;
    --!   begin
    --!      Foo (X);
    --!   end;
    --
    --  Note that @X@ must not be zero!
    ------------------------------------------------------</PRE>
    <P>
    will be split into three blocks:
    </P>
    <TABLE BORDER=1>
    <TR><TD><PRE>
    --  This is an example usage of procedure @Foo@:
    --</PRE></TD></TR>
	<TR><TD><PRE>
    --!   declare
    --!      X : Integer := 42;
    --!   begin
    --!      Foo (X);
    --!   end;</PRE></TD></TR>
	<TR><TD><PRE>
    --
    --  Note that @X@ must not be zero!</PRE></TD></TR>
	</TABLE>
	<P>
	The first and the last block will be formatted according to
	the default rules (we didn't redefine <CODE>Format."--"</CODE>),
	whereas the middle block will be formatted according to our own
	rules.
	<P>
	<P>Note that to just have something enclosed in
	<CODE>&lt;PRE&gt;&lt;/PRE&gt;</CODE> tags, a special format is maybe
	overkill: in new sources, you could just as well directly enclose the
	example code in <CODE>&lt;PRE&gt;&lt;/PRE&gt;</CODE> tags yourself.
	However, if you have legacy code, you may not want to modify it to
	produce HTML documentation, or you may want to do more complex formatting.
	In these cases, the format instructions come in handy.
	</P>
  </TD>
</TR></TABLE>

<H3 CLASS="toc"><A NAME="Userdef_Format">9.2. User-Defined Formatting</A></H3>

<P>
This section explains how to define format instructions for comment blocks.
</P>

<H4><A NAME="Format_Instruction">9.2.1. Format Instructions</A></H4>

<P>
AdaBrowse recognizes the following format instructions, which define how it
should format the content of a comment block:
</P>
<DL>
  <DT><CODE><STRONG>swallow</STRONG></CODE>
  <DD>Swallow the block, i.e. replace it by an empty string. The whole block
      will not appear at all in the generated HTML file.
      <BR><BR>
  <DT><CODE><STRONG>entities</STRONG></CODE>
  <DD>AdaBrowse puts the whole content of the block as-is into the generated
      HTML file. It doesn't parse the HTML, but blindly replaces all special
      characters (such as "<CODE>&lt;</CODE>" or "<CODE>&quot;</CODE>", or
      characters beyond the 7-bit ASCII range) by named character entities.
      Note that if the block <EM>does</EM> contain HTML mark-up, this will
      effectively disable the mark-up (because <EM>all</EM> "<CODE>&lt;</CODE>"
      characters will be replaced by <CODE>&amp;lt;</CODE>, 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.
      <BR><BR>
      Note that because the <CODE>entities</CODE> filter blindly replaces
      special characters, it should come <EM>before</EM> any filter that
      inserts or modifies tags. To replace special characters without affecting
      existing HTML mark-up, use the <CODE>plain</CODE> filter instead!
      <BR><BR>
  <DT><CODE><STRONG>plain</STRONG></CODE>
  <DD>AdaBrowse replaces special characters by character entities, e.g. all
      quotes not within a tag are replaced by <CODE>&amp;quot;</CODE>; any
      "<CODE>&lt;</CODE>" that doesn't belong to a tag is replaced by
      <CODE>&amp;lt;</CODE>, and so on. The difference to the <CODE>entities</CODE>
      filter is that this filter <EM>does</EM> parse the HTML mark-up and
      preserves it.
      <BR><BR>
  <DT><CODE><STRONG>hr [strip | replace]</STRONG></CODE>
  <DD><DIV>
      Defines how AdaBrowse shall handle comment lines that contain only the
      prefix followed by dashes. Such lines may occur within a description (the global
      processing only strips the first and last line of a whole comment if they contain
      only dashes, but not interior comment lines). Possible values for <CODE>hr</CODE>
      are:
      <BR><BR>
      <DL>
        <DT><CODE>strip</CODE>
        <DD>Replace such separator lines by an empty line.
        <DT><CODE>replace</CODE>
        <DD>Replace separator lines by <CODE>&lt;HR&gt;</CODE>.
      </DL>
      <P>
      If only "<CODE>hr</CODE>" appears (i.e., without "<CODE>strip</CODE>" or
      "<CODE>replace</CODE>" following), the default behavior is <CODE>strip</CODE>.
      </P>
      </DIV>
  <DT><CODE><STRONG>strip_comments</STRONG></CODE>
  <DD>Removes all HTML-comments.
      <BR><BR>
  <DT><CODE><STRONG>enclose (</STRONG>string<STRONG>, </STRONG>string<STRONG>)</STRONG></CODE>
  <DD>AdaBrowse encloses the whole block by prefixing it with the first string and
      appending the second string. Typically, the strings will contain HTML mark-up,
      and if <CODE>enclose</CODE> is followed (in a <A HREF="#Format_Pipe">pipe</A>) by <CODE>expand</CODE>,
      they may even contain user-defined HTML mark-up.
      <BR><BR>
      AdaBrowse does <EM>not</EM> verify that the two strings correspond in any way, so if you
      define nonsense parameters such as <CODE>enclose ("&lt;!--", "")</CODE>, 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 <EM>must</EM> be present (even though they may be empty). Embedded double
      quotes in a string must be doubled as in Ada 95.
      <BR><BR>
  <DT><CODE><STRONG>pre</STRONG></CODE>
  <DD>AdaBrowse encloses the whole block in <CODE>&lt;PRE&gt;&lt;/PRE&gt;</CODE>
      tags, i.e. <CODE>pre</CODE> is short-hand for
      <CODE>enclose&nbsp;("&lt;PRE&gt;", "&lt;/PRE&gt;")</CODE>.
      <BR><BR>
  <DT><CODE><STRONG>expand</STRONG></CODE>
  <DD>AdaBrowse performs macro replacement of user-defined HTML entities as described
      <A HREF="#userdef">above</A>.
      <BR><BR>
  <DT><CODE><STRONG>unknown_tags [all | standard]</STRONG></CODE>
  <DD>AdaBrowse converts all references to unknown HTML entities (i.e., unknown tags) to text
      by replacing all special characters, notably the opening <CODE>&lt;</CODE> and the closing
      <CODE>&gt;</CODE>, by character entities. In other words, "<CODE>&lt;UNKNOWN&gt;</CODE>"
      becomes "<CODE>&amp;lt;UNKNOWN&amp;gt;</CODE>".
      <BR><BR>
      The optional parameter defines whether the filter considers only the standard HTML 4.01
      tags as known (<CODE>unknown_tags standard</CODE>), or whether user-defined tags also
      shall be considered as known (<CODE>unknown_tags all</CODE>). Default is <CODE>standard</CODE>,
      i.e., any remaining user-defined tags will be replaced by their text equivalent.
      <BR><BR>
  <DT><CODE><STRONG>shortcut</STRONG></CODE>
  <DD>AdaBrowse replaces all occurrences of pairs of "<CODE>@</CODE>" without
      whitespace in between by <CODE>&lt;CODE&gt;</CODE> and <CODE>&lt;/CODE&gt;</CODE>,
      respectively, as described <A HREF="#Code_Shortcut">above</A>.
      <BR><BR>
  <DT><CODE><STRONG>para</STRONG></CODE>
  <DD>AdaBrowse assumes that an empty content line indicates a new paragraph
      and inserts <CODE>&lt;BR&gt;</CODE> or <CODE>&lt;P&gt;</CODE> tags as
      appropriate.
      <BR><BR>
      This format instruction is smart: it won't change anything inside <CODE>&lt;PRE&gt;</CODE> blocks,
      and it also will never insert <CODE>&lt;BR&gt;</CODE> or <CODE>&lt;P&gt;</CODE> tags where
      they would be illegal (such as directly inside a <CODE>&lt;UL&gt;</CODE>).
      <BR><BR>
  <DT><CODE><STRONG>lines</STRONG></CODE>
  <DD>AdaBrowse tries to maintain the original line structure of the Ada comment
      by replacing all white space outside HTML tags by <CODE>&amp;nbsp;</CODE> and
      adding a <CODE>&lt;BR&gt;</CODE> at each end-of-line outside HTML tags, unless
      the line already ended in a <CODE>&lt;BR&gt;</CODE>.
      <BR><BR>
      This format instruction will only do this wherever such processing is allowed.
      E.g., it won't change anything in a <CODE>&lt;PRE&gt;</CODE> block (because there, it is
      unnecessary), and also won't do anything if the last tag was e.g. <CODE>&lt;UL&gt;</CODE>
      (because inside an unordered list, the only tag allowed is <CODE>&lt;LI&gt;</CODE>).
      Inside each <CODE>&lt;LI&gt;</CODE>, however, it <EM>will</EM> transform the text.
      <BR><BR>
  <DT><CODE><STRONG>standard</STRONG></CODE>
  <DD>This is a shortcut for the <A HREF="#Format_Pipe">pipe</A>
      "<CODE>expand&nbsp;|&nbsp;strip_comments&nbsp;|&nbsp;unknown_tags&nbsp;standard&nbsp;|&nbsp;hr&nbsp;strip&nbsp;|&nbsp;para&nbsp;|&nbsp;shortcut&nbsp;|&nbsp;plain</CODE>",
      which defines the standard formatting AdaBrowse uses by default.
      <BR><BR>
  <DT><CODE><STRONG>execute [end-of-line] (</STRONG>command<STRONG>)</STRONG></CODE>
  <DD>This is the most powerful format instruction. It tells AdaBrowse to run
      the <CODE>command</CODE> to format a comment block, passing the block on
      the command's <CODE>stdin</CODE>. AdaBrowse reads the command's output
      (<CODE>stdout</CODE>) and treats that as the result of the formatting.
      <BR><BR>
      The optional <CODE>end-of-line</CODE> 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 <CODE>sed</CODE> wants single LFs, whereas
      the normal end-of-line marker on Windows in CR-LF, which apparently confuses
      <CODE>sed</CODE>. 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.)
      <BR><BR>
      To properly handle such pathological cases, you can define precisely what
      end-of-line convention AdaBrowse shall use for the input to the <CODE>command</CODE>.
      Possible values of <CODE>end-of-line</CODE> are <CODE>CR</CODE>, <CODE>CRLF</CODE>,
      and <CODE>LF</CODE>. By default, AdaBrowse uses whatever is the standard convention
      on the operating system it runs on.
      <BR><BR>
      The closing parenthesis of an <CODE>execute</CODE> filter is defined to be the next
      right parenthesis ("<CODE>)</CODE>") not within a string (delimited by &quot;, ', 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 ("<CODE>(</CODE>" and
      "<CODE>)</CODE>") or curly braces ("<CODE>{</CODE>" and "<CODE>}</CODE>").
      <BR><BR>
      If the <CODE>command</CODE> is empty or contains only whitespace, AdaBrowse issues
      an error. It also issues an error and terminates if the command fails for any
      reason.
      <BR><BR>
</DL>
<P>
The parsing of format instructions always is case <EM>in</EM>sensitive, e.g. all of
"<CODE>STANDARD</CODE>", "<CODE>standard</CODE>", "<CODE>StAnDaRd</CODE>", or any other
combination of upper and lower case letters is recognized as the format instruction
<CODE>standard</CODE>.
</P>
<P>
All of these format instruction except <CODE>entities</CODE> and <CODE>execute</CODE> skip
any HTML comments they encounter. Hence, <CODE>expand</CODE> will <EM>not</EM> expand
user-defined tags inside HTML comments, <CODE>para</CODE> will not do anything inside
an HTML comment, and so on. However, any command called by an <CODE>execute</CODE>
instruction will have to deal with HTML comments as it sees fit.
</P>

<H4><A NAME="Format_Pipe">9.2.2. Pipes</A></H4>

<P>
All these format instructions are <EM>filters</EM> that transform their input
in some way to produce output. As a consequence, combining these is possible
using the "<CODE>|</CODE>" <EM>pipe</EM> operator. It's an infix, left-associative
operator. The syntax of a pipe is
</P>
<PRE>
    Pipe = Format_Instruction <B>|</B> Pipe "|" Format_Instruction.
</PRE>
<P>
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.
</P>
<P>
Note that in the <CODE>expand</CODE> 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 <EM>not</EM> the case for user-defined tags defined
using the "<CODE>.Include</CODE>" or the "<CODE>.Execute</CODE>" 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 <CODE>expand</CODE> filters in a row. E.g. the format
instruction
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--" = expand | standard
</PRE></TD></TR></TABLE>
<P>
would in a first step expand all user-defined HTML tags, and then (because <CODE>standard</CODE>
contains an <CODE>expand</CODE> filter) expand all remaining user-defined tags again. Note that
any user-defined tags remaining after the first <CODE>expand</CODE> filter must have come from
an expansion of an "<CODE>.Include</CODE>" or "<CODE>.Execute</CODE>" tag.
</P>
<P>
If you use the <CODE>execute</CODE> filter, make sure that the command does terminate! If the
called command blocks, AdaBrowse will block, too.
</P>
<P>
Some combinations of format instructions within a pipe make no sense. For instance,
after a <CODE>pre</CODE> filter, <CODE>para</CODE>, <CODE>lines</CODE>, or <CODE>standard</CODE>
don't make much sense because both <CODE>para</CODE> and <CODE>lines</CODE> leave anything
within a <CODE>&lt;PRE&gt;</CODE> block untouched. The combination of <CODE>para</CODE> followed by
<CODE>lines</CODE> or <CODE>pre</CODE> within the same pipe also is pretty useless. You also should
make sure that any "<CODE>hr replace</CODE>" filter appears <EM>before</EM> an eventual
"<CODE>para</CODE>" filter, otherwise the result may not be what you expect. AdaBrowse
does <EM>not</EM> 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.
</P>
<P>
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.
</P>

<H4><A NAME="Standard_Format">9.2.3. The Default Formatting</A></H4>

<P>
The standard formatting is defined by
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--" = expand | strip_comments | unknown_tags standard | hr strip | para | shortcut | plain
</PRE></TD></TR></TABLE>
<P>
which is the same as
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--" = standard
</PRE></TD></TR></TABLE>
<P>
You can redefine this standard formatting by overriding the key <CODE>Format."--"</CODE>
explicitly in a configuration file.
</P>

<H4><A NAME="Example_Pipe">9.2.4. An Example</A></H4>

<P>
As an example of an <CODE>execute</CODE> filter,
consider how a simple look-alike of the <CODE>lines</CODE> filter could be implemented using
<CODE>sed</CODE>:
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--!" = execute (sed -e"s/^\(.*\)&lt;BR&gt;$/\1/" \
                            -e"s/[[:blank:]]/\&amp;nbsp;/g" \
                            -e"s/^\(.*\)$/\1&lt;BR&gt;/") | \
               plain
</PRE></TD></TR></TABLE>
<P>
The first <CODE>sed</CODE> expression removes any trailing <CODE>&lt;BR&gt;</CODE> to avoid
inadvertantly doubling <CODE>&lt;BR&gt;</CODE>s. The second expression replaces all white
space by <CODE>&amp;nbsp;</CODE>, and the third finally appends a <CODE>&lt;BR&gt;</CODE>
to each line. That's more or less what the predefined <CODE>lines</CODE> filter does, except
that this definition assumes that there are <EM>no</EM> HTML tags in the input (the <CODE>lines</CODE>
filter is smarter: it only replaces whitespace and only adds <CODE>&lt;BR&gt;</CODE> in text
<EM>outside</EM> HTML tags).
</P>
<P>
If the above <CODE>execute</CODE> filter does not work for you, you're probably on Windows
and are using the Cygwin <CODE>sed</CODE>. 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
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--!" = execute lf (sed -e"s/^\(.*\)&lt;BR&gt;$/\1/" \
                               -e"s/[[:blank:]]/\&amp;nbsp;/g" \
                               -e"s/^\(.*\)$/\1&lt;BR&gt;/") | \
               plain
</PRE></TD></TR></TABLE>
<P>
Note that due to the way configuration files are read, we might also write this definition
with embedded comments:
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
Format."--!" = execute (sed -e"s/^\(.*\)&lt;BR&gt;$/\1/" \      # Remove existing &lt;BR&gt;s
                            -e"s/[[:blank:]]/\&amp;nbsp;/g" \ # Replace whitespace
                            -e"s/^\(.*\)$/\1&lt;BR&gt;/") | \   # Add &lt;BR&gt;s
               plain
</PRE></TD></TR></TABLE>
<P>
The comments are removed before any further processing, and the command to be run is in all
three cases
</P>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0><TR><TD CLASS="sample"><PRE>
sed -e"s/^\(.*\)&lt;BR&gt;$/\1/" -e"s/[[:blank:]]/\&amp;nbsp;/g" -e"s/^\(.*\)$/\1&lt;BR&gt;/"
</PRE></TD></TR></TABLE>
<P>
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:
</P>
<UL>
  <LI><CODE>Format."--"&nbsp;=&nbsp;hr&nbsp;strip&nbsp;|&nbsp;entities&nbsp;|&nbsp;lines</CODE>, or
      <BR><BR>
  <LI><CODE>Format."--"&nbsp;=&nbsp;entities&nbsp;|&nbsp;enclose&nbsp;("&lt;DIV&nbsp;CLASS=""LineStructure""&gt;",&nbsp;"&lt;/DIV&gt;")&nbsp;|&nbsp;hr&nbsp;strip</CODE>,
      with a style definition in the style sheet like
      <PRE>
    DIV.LineStructure {
      white-space : pre
    }
</PRE>
  <LI><CODE>Format."--"&nbsp;=&nbsp;entities&nbsp;|&nbsp;pre&nbsp;|&nbsp;hr&nbsp;strip</CODE>,
      which also uses a monospaced (non-proportional) font.
</UL>
<P>
Note, however, that the <A HREF="http://www.w3.org/TR/1998/REC-CSS2-19980512">CSS 2 standard</A> allows
conforming user-agents (browsers) to <EM>ignore</EM> the <CODE>white-space</CODE> property! Hence the
second example may or may not produce the desired result.
</P>
<P>
Also note that the <CODE>entities</CODE> filter must come <EM>before</EM> the <CODE>enclose</CODE> filter;
otherwise, it would replace e.g. the "<CODE>&lt;PRE&gt;</CODE>" inserted by the <CODE>enclose</CODE> filter
by "<CODE>&amp;lt;PRE&amp;gt;</CODE>", and thus the tag would not be interpreted by a browser but rather be
displayed!
</P>

<HR>
<H2 CLASS="toc"><A NAME="XML">10. XML Output</A></H2>

<P>
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. <CODE><A HREF="http://www.oasis-open.org/committees/docbook/">docbook</A></CODE> or
<CODE><A HREF="http://www.gnu.org/software/texinfo/">texinfo</A></CODE>. This saves you the need
to write your own Ada parser if you'd like to have e.g. a <CODE>docbook</CODE> documentation instead
of HTML: you just need to write a <CODE>docbook</CODE> 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.
</P>
<P>
Some publicly available XML parser tool kits are e.g.
<A HREF="http://libre.act-europe.fr/xmlada/">XML/Ada</A> (for Ada 95), or
<A HREF="http://xml.apache.org/index.html">Xerces</A> (Java, C++, Perl),
and there are many others. It might even be possible to use
<A HREF="http://www.w3.org/TR/xslt">XSLT stylesheets</A> to transform the AdaBrowse-generated
XML into other formats; for this, you'd need an XSLT processor such as
<A HREF="http://xml.apache.org/index.html">Xalan</A> (Java) or
<CODE><A HREF="http://xmlsoft.org/XSLT/">xsltproc</A></CODE> (C). (I recommend the latter: it is small,
fast, and works. You'll also need <CODE><A HREF="http://xmlsoft.org/">libxml2</A></CODE>; a
<A HREF="http://www.zlatkovic.com/projects/libxml/index.html">Windows port</A> of <CODE>xsltproc</CODE>
also exists: download <CODE>libxml</CODE>, <CODE>libxslt</CODE>, and <CODE>iconv</CODE>.)
Another suggestion is the <A HREF="http://saxon.sourceforge.net/">Saxon/&AElig;lfred</A> (Java). If you work on Windows,
also be sure to get Markus Hoenicka's excellent
<A HREF="http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html">guide</A> to setting up an
SGML/XML editing and publishing system on Windows NT.
</P>
<P>
The generated XML complies to the XML 1.0 <A HREF="adabrowse_dtd_2_0.html">DTD</A> included in the distribution.
This DTD is also available at the URL
<CODE>http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/xml/adabrowse_2_0.dtd</CODE>.
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.
</P>
<P>
You switch on
XML generation using the "<CODE><A HREF="#G_Option">-G</A></CODE>" option giving the output format
name "<CODE>xml</CODE>". It is possible to generate only XML using "<CODE>-G&nbsp;xml</CODE>", or
to generate both HTML and XML at the same time using "<CODE>-G&nbsp;xml&nbsp;html</CODE>".
</P>
<P>
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 <A HREF="#F_Option">file input mode</A> and of
the name of the input unit with extension "xml" if only one file is being processed and is written to:
</P>
<UL>
  <LI>If the <CODE>-o</CODE> option specifies a file name: to that file, with
      extension "<CODE>xml</CODE>".
  <LI>If the <CODE>-o</CODE> option specifies only a path: to a file named
      as specified above in the given directory.
  <LI>If the <CODE>-o</CODE> option specifies <CODE>stdout</CODE>: to <CODE>stdout</CODE>.
  <LI>If no <CODE>-o</CODE> option at all is given: to a file named
      as specified above in the current directory.
</UL>
<P>
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.
</P>
<P>
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.
</P>
<P>
There are no implicit formatting assumptions in the XML (as e.g. in the <CODE>PRE</CODE> in
HTML). All lines are represented by an XML element <CODE>LINE</CODE>, both in source excerpts
and descriptions.
</P>
<P>
XML generation ignores the following <A HREF="#Options">options</A>: <CODE>-l</CODE>
(cross-references in XML always have both the line and the column number), and <CODE>-s</CODE>.
</P>
<P>
XML generation honors the following configuration file keys: <CODE>Compile</CODE>,
<CODE>Char_Set</CODE>, all the <CODE>Description.*</CODE> keys, all the <CODE>Index</CODE> and
<CODE>Rule</CODE> keys, <CODE>Exclude</CODE>,
<CODE>Include</CODE>, <CODE>Include_File</CODE>, <CODE>No_XRef</CODE>, <CODE>XRef</CODE>,
and <CODE>Refs_To_Standard</CODE>. 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).
</P>

<HR>
<H2 CLASS="toc"><A NAME="GNAT">11. Rebuilding from sources for a GNAT version</A></H2>

<H3 CLASS="toc">11.1 Why does AdaBrowse work only with a specific GNAT version?</H3>

<P>
       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.
</P>
<P>
  AdaBrowse won't work with the FSF GNAT contained in gcc 3.x, because there is no ASIS
  implementation for that compiler. See also <A HREF="#FSF_GNAT">below</A>.
</P>

<H3 CLASS="toc">11.2 Rebuilding</H3>

<P>
       AdaBrowse works ok with versions of GNAT &gt;= 3.14p. To rebuild AdaBrowse
       from the sources, follow these steps:
</P>

<OL>
  <LI>Get ASIS-for-GNAT for your GNAT version.
      <BR><BR>
  <LI>Apply the following corrections to the ASIS-for-GNAT you got:
      <TABLE BORDER=1>
      <TR><TH>GNAT&nbsp;version</TH><TH>Correction to make in ASIS-for-GNAT:</TH><TR>
      <TR><TD ALIGN=Left VALIGN=Top>3.14p</TD>
          <TD><P>Get the version string of your GNAT compiler by compiling something
                 with the options <CODE>gcc&nbsp;-c&nbsp;-gnatv</CODE>. GNAT writes
                 its version string (e.g. "<CODE>3.14p&nbsp;&nbsp;(20010503)</CODE>").
              </P>
              <P>Open the ASIS source file <CODE>./gnat/gnatvsn.ads</CODE>
                 and make sure that the <CODE>GNAT_Version_String</CODE> there is
                 <EM>exactly</EM> the same. (When I downloaded ASIS-for-GNAT 3.14p,
                 there was a blank missing.) If the strings differ, change
                 <CODE>gnatvsn.ads</CODE> to match what GNAT wrote.
              </P>
              <P>
                If you fail to make this correction, the ASIS libraray will <EM>not</EM>
                work at all (it'll always report an inconsistency between the compiler
                version and the ASIS library version.)
              </P>
          </TD>
      </TR>
      <TR><TD ALIGN=Left VALIGN=Top>3.15p</TD>
          <TD>No corrections needed.</TD>
      </TR>
      <TR><TD ALIGN=Left VALIGN=Top>3.16a</TD>
          <TD>No corrections needed.</TD>
      </TR>
      <TR><TD ALIGN=Left VALIGN=Top>3.16a1<BR>5.01a</TD>
          <TD><P>Remove line #295 from file <CODE>./asis/a4g-contt-pd.adb</CODE> (the
                 one reading "<CODE>Result_Unit_Id_List&nbsp;:=&nbsp;Nil_Unit_Id_List;</CODE>").
              </P>
              <P>
                Without this correction, the "<CODE>-all</CODE>" option of AdaBrowse will
                <EM>not</EM> work; ASIS-for-GNAT will always raise a <CODE>CONSTRAINT_ERROR</CODE>!
              </P>
          </TD>
      </TR>
      </TABLE>
      <BR>
  <LI>Install ASIS-for-GNAT.
          <BR><BR>
  <LI>Make sure the path to your ASIS-for-GNAT installation is in
      <CODE>ADA_INCLUDE_PATH</CODE> and <CODE>ADA_OBJECTS_PATH</CODE>.
      <BR><BR>
  <LI>Run the make file by typing <CODE>make</CODE> in the adabrowse directory.
</OL>

<P>
The above procedure will produce an AdaBrowse <EM>without</EM> support for the GNAT project
manager. If you have GNAT <STRONG>3.15p or later</STRONG>, you may rebuild an AdaBrowse
<EM>with</EM> project manager support as follows:
</P>
<OL>
  <LI>Get, correct and install ASIS-for-GNAT for your GNAT version.
      <BR><BR>
  <LI>Make sure the path to your ASIS-for-GNAT installation is in
      <CODE>ADA_INCLUDE_PATH</CODE> and <CODE>ADA_OBJECTS_PATH</CODE>.
      <BR><BR>
  <LI>Get the compiler sources for your GNAT version and put them into a directory,
      e.g. <CODE>C:\gnat-3.15p-src\</CODE>. <EM>Do <STRONG>not</STRONG> include this
      directory in the <CODE>ADA_INCLUDE_PATH</CODE></EM>!
      <BR><BR>
  <LI>Set the environment variable <CODE>GNATSRC</CODE> to the directory in which the
      compiler sources are. (Note that the sources are in a subdirectory <CODE>src/ada</CODE>,
      so you'd have to set it to <CODE>C:\gnat-3.15p-src\src\ada</CODE> in the above case.)
      <BR><BR>
  <LI>Go to the directory where you had unpacked the AdaBrowse source distribution and type
      <CODE>make</CODE>.
</OL>
<P>
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
</P>
<TABLE BORDER=0><TR><TD CLASS="sample">
<PRE>
   make GNATSRC=C:/gnat-3.15p-src/src/ada
</PRE>
</TD></TR></TABLE>
<P>
(You can use forward slashes even on Windows.)
</P>
<P>
Do <STRONG>not</STRONG> include the GNAT source directory in <CODE>ADA_INCLUDE_PATH</CODE>!
Because the GNAT source distribution contains both the compiler <EM>and the library</EM>
sources, this will screw up things completely unless you know <EM>exactly</EM> what you're
doing. The typical outcome is that you will no longer be able to link because "system.ads has
been modified".
</P>
<P>
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 <CODE>GNATSRC</CODE> (it's smart, but it can't read your mind :-), and then let
it do its job.
</P>
<P>
If this does <EM>not</EM> configure AdaBrowse to use the project manager, then either
the environment variable <CODE>GNATSRC</CODE> 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.
</P>
<P>
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.
</P>
<P>
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
</P>
<PRE>
   make adabrowse
</PRE>
<P>
or
</P>
<PRE>
   gcc -c -O2 util-nl.c
   gnatmake -O2 adabrowse -largs -lasis
</PRE>
<P>
Both will build an AdaBrowse using "gcc" as the default compiler name and not having
project manager support.
</P>
<P>
If the make fails, and you're <EM>sure</EM> 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 "<A HREF="#Bugs">Reporting Bugs</A>" 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.
</P>
<P>
(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 -- <EM>I</EM> don't have it, and I didn't test with it)
from the <A HREF="http://www.mingw.org/download.shtml">MinGW</A> site.)
</P>

<HR>
<H2 CLASS="toc"><A NAME="Rebuild">12. Rebuilding from sources for other compilers (not GNAT)</A></H2>

<P>
The procedure is basically the same:
</P>

<OL>
  <LI>Get and install an ASIS implementation for your compiler.
      <BR><BR>
  <LI>Verify that the compiler can find and use the ASIS library.
      <BR><BR>
  <LI>Watch out for implementation-defined ASIS features used in
      AdaBrowse:
      <BR><BR>
      <UL TYPE=DISC>
        <LI>GNAT-specific pragmas <CODE>License</CODE> on all units. These may cause
            compilation warnings when compiled with some compiler other than GNAT.
            <BR><BR>

        <LI>Implementation-defined options passed to
            <CODE>Asis.Ada_Environments.Associate</CODE> in file
            <CODE>adabrowse.adb</CODE>.
            <BR><BR>

        <LI>ASIS-for-GNAT-specific exception handling in <CODE>adabrowse.adb</CODE>.
            <BR><BR>

        <LI>AdaBrowse uses <CODE>GNAT.Os_Lib</CODE> in a few places.
            You'll need to replace that as appropriate in files <CODE>util-pathes.adb</CODE>
            and in <CODE>ad-file_ops.ad[bs]</CODE>.
            <BR><BR>

        <LI>Make sure package <CODE>AD.Projects.Impl</CODE> is a renaming of
            <CODE>AD.Projects.Impl_No</CODE>. (Your compiler most probably doesn't
            come with the GNAT project manager, I suppose.)
            <BR><BR>
      </UL>

  <LI>Build the adabrowse application.
      <BR><BR>
</OL>
<P>
<A NAME="Adapted">If it doesn't work</A>, 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.)
</P>

<HR>
<H2 CLASS="toc"><A NAME="Testing">13. Testing</A></H2>

<P>
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.).
<P>
<P>
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.
</P>
<P>
I have also run AdaBrowse over the following, large libraries:
</P>
<UL>
  <LI>adabindx 0.7.2,
  <LI>the ASIS-for-GNAT 3.14p sources,
  <LI>a subset (all the <CODE>as[go]c*.ads</CODE>) of Corey Minyard's ASL (asl-1.4),
  <LI>Simon Wright's Booch Components (bc-20010819),
  <LI>Matthew Heaney's charles (20020228),
  <LI>RR Software's CLAW 1.3 Introductory Edition,
  <LI>GtkAda 2.0.0,
  <LI>Mats Weber's components (except those files GNAT 3.14p failed or crashed upon),
  <LI>Ted Dennison's OpenToken 3.0b,
  <LI>J. Carter's pragmarc (from 01-DEC-2001),
  <LI>Stephen Leake's SAL 1.03,
  <LI>TASH 8.3.2a,
  <LI>Gautier de Montmollin's UnzipAda 0.9,
  <LI>Stephen Leake's Windex 1.06,
  <LI>The complete Ada 95 standard library and the run-time library of GNAT, and
  <LI>XML/Ada 0.7.1.
</UL>
<P>
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.
</P>
<P>
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.
</P>
<P>
The new indices of V4.0 have been cross-checked against the old indices of V3.4.2;
no significant differences were found.
</P>
<P>
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.
</P>

<HR>
<H2 CLASS="toc"><A NAME="Problems">14. Known Problems</A></H2>

<OL>
  <LI>If AdaBrowse runs an external command, and that command does not terminate,
      AdaBrowse will be blocked, too.
      <BR><BR>
  <LI>Both Netscape and MS IE sometimes produce an extra line at the end of a
     preformatted block. I.e. the HTML fragment
     <BR><BR>
     <TABLE BORDER=0><TR><TD>
       <CODE>&lt;PRE&gt;</CODE>This is some code.<CODE>&lt;/PRE&gt;</CODE><BR>
       Followed by other text.
     </TD></TR></TABLE>
     <BR>
     is rendered as
     <BR><BR>
     <TABLE BORDER=0><TR><TD>
<PRE>This is some code.</PRE>
Followed by other text.
     </TD></TR></TABLE>
     <BR>
     As a result, most code chunks put into the generated HTML page have
     such a trailing empty space, which sometimes makes the layout a bit
     awkward.
     <BR><BR>
     This is a problem with the browsers' rendering of HTML. There's nothing
     whatsoever in the HTML 4.0 spec that would justify this empty space.
     But there's also nothing I can do about it.
     <BR><BR>
  <LI>If you use the <CODE>-all</CODE> option, comments <EM>after</EM> 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.
     <BR><BR>
  <LI>ASIS-for-GNAT only finds the "known child units" if their tree files
     exist and can be found. Hence, if you let AdaBrowse generate the tree
     files on the fly, you'll generally not see any known child units. However,
     if you generate the tree files for all units and then run AdaBrowse, ASIS
     will find them, and AdaBrowse can generate a meaningful section for the
     known child units.
     <BR><BR>
  <LI>In some rare cases, AdaBrowse may fail to generate completely accurate
     cross-references. This is caused by bugs in ASIS-for-GNAT, in particular
     in the area of formal packages. I do my best to work around these bugs
     and try hard to generate cross-references that point at least to the
     correct file, but in some cases, the source position returned by ASIS is
     bogus, and there's nothing I can do about that. However, these cases are
     so rare that you'll most probably not even notice them. If you notice wrong
     or missing cross-references, check the HTML source generated. If it contains
     a comment just before the suspicious place saying something about an ASIS
     failure, the cross-reference is wrong or missing because of a known ASIS
     problem, and it's no use reporting this as a bug.
     <BR><BR>
  <LI>Not really a problem, but I've been asked whether I'd produce a version of
     AdaBrowse for Ada 83. No, I won't, for I have neither an Ada 83 compiler
     nor an Ada 83 ASIS implementation. However, GNAT has an option <CODE>-gnat83</CODE>
     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.
     <BR><BR>
  <LI><A NAME="FSF_GNAT">AdaBrowse</A> won't work (yet) with the FSF GNAT in gcc-3.1. The problem is that
     there is currently <EM>no</EM> ASIS implementation for that compiler. Since
     AdaBrowse uses ASIS, there needs to be an ASIS for the FSF GNAT to make
     AdaBrowse work with it. Once there'll be such an ASIS, it'll be a simple matter
     of recompiling AdaBrowse to get it to work with the FSF GNAT. (I do not know
     what ACT's plans in that respect are. I hope they'll put their ASIS-for-GNAT
     into the FSF CVS tree once gcc-3.1 has stabilized and is out. If they don't, I
     fear somebody will have to write an ASIS implementation for the FSF GNAT.)
     <BR><BR>
  <LI>Not a problem: I've been asked whether I'd agree to have AdaBrowse put into
     the FSF CVS repository (and, supposedly, into the FSF GNAT distribution). I
     have no objections, but again, there needs to be an ASIS for the FSF GNAT first.
     <BR><BR>
</OL>

<HR>
<H2 CLASS="toc"><A NAME="License">15. License</A></H2>

<P>
AdaBrowse is copyright &copy; 2002-2003 by Thomas Wolf <CODE>&lt;twolf@acm.org&gt;</CODE>.
</P>
<P>
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.
</P>
<P>
AdaBrowse is distributed in the hope that it will be useful, but <EM>without any
warranty</EM>; without even the implied warranty of <EM>merchantability</EM> or <EM>fitness
for a particular purpose</EM>. 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 <A HREF="GPL.txt">GPL.txt</A>. If not, write to the
<CODE>Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA</CODE>
or try the URL <A HREF="http://www.gnu.org/licenses/gpl.html" TARGET="blank">http://www.gnu.org/licenses/gpl.html</A>.
</P>
<P>
Some of the sources (all the <CODE>gal*.ad?</CODE>) 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.
</P>
<P>
All the <CODE>util*.ad?</CODE> files are an extract of my
<CODE><A HREF="http://home.tiscalinet.ch/t_wolf/tw/ada95/util/">Util</A></CODE> subsystem
available at the URL <A HREF="http://home.tiscalinet.ch/t_wolf/tw/ada95/util/">http://home.tiscalinet.ch/t_wolf/tw/ada95/util/</A>. These, too, are
covered by the GMGPL.
</P>

<HR>
<H2 CLASS="toc"><A NAME="Bugs">16. Reporting Bugs and Enhancements</A></H2>

<P>
Send bug reports and enhancement propsals to <CODE>&lt;twolf@acm.org&gt;</CODE>. Use a subject
line containing the text "AdaBrowse".
</P>
<P>
For bug reports, I need:
</P>
<UL>
  <LI>Your complete system setup: OS, GNAT version, ASIS-for-GNAT version,
    AdaBrowse version, settings of environment variables such as
    <CODE>ADA_INCLUDE_PATH</CODE> and <CODE>ADA_OBJECTS_PATH</CODE>.
    <BR><BR>
  <LI>The complete sources on which the problem is shown. Preferrably reduced
    to the minimum necessary and in gnatchop format! (Not the AdaBrowse
    sources [I have those :-)], but the ones you tried to run AdaBrowse on!)
    <BR><BR>
    If the error occurs on sources from a publicly available, downloadable
    library, you may also just send me a link to the download location and
    tell me which file causes troubles.
    <BR><BR>
    I can also handle .zip, .tar.gz, .gz, and .bz2 files. Any other funny compression
    or encoding will not be accepted.
    <BR><BR>
  <LI>Any configuration files and style sheets used.
    <BR><BR>
  <LI>The exact command and/or shell script you used for calling AdaBrowse.
    <BR><BR>
  <LI>All output produced by AdaBrowse: HTML files, error and warning messages
    on <CODE>stderr</CODE>, etc.
    <BR><BR>
  <LI>A clear, precise, and comprehensible description of the error (what you
    think is wrong) in English (or, if you prefer, in German or French).
    <BR><BR>
  <LI>A valid e-mail address of yours, so that I can contact you if necessary.
    <BR><BR>
</UL>
<P>
I can only maintain the AdaBrowse version I distribute myself. See
<A HREF="#Adapted">above</A>
for AdaBrowse adapted to work with other compilers.
</P>

<HR>
<!--================================================================-->
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=5 WIDTH="100%" CLASS="footer">
<TR>
  <TD WIDTH="100%" ALIGN="left" NOWRAP>
       <FONT SIZE=-1>Copyright &copy; 2002-2003 by Thomas Wolf. All rights
       reserved.
       </FONT>
       <BR>
       <FONT SIZE=-1>TW, Nov 18, 2003</FONT>
  </TD>
</TR>
</TABLE>

</BODY>
</HTML>