Man Linux: Main Page and Category List


       adabrowse  -  Generate  fully cross-referenced HTML rendering of Ada 95


       adabrowse [options] -f file


       adabrowse produces a fully cross-referenced HTML rendering  of  Ada  95
       specs  (no  bodies)  similar  to  what  javadoc  does for Java sources.
       adabrowse  is  a  command-line  utility;  it  has  no  graphical   user

       adabrowse  is  highly  configurable through command-line options, style
       sheets, and configuration files.

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


       There are two ways to use adabrowse:

       1.  Call  adabrowse  for  your  spec:  adabrowse -f file (and any other
           options as needed, in particular -I if  the  file  is  not  in  the
           current  directory  or depends on other units whose sources are not
           in the current directory!) If no  tree  file  for  the  given  unit
           exists, adabrowse will try to generate one.


       1.  Generate  the  tree  files  for  the  specs  you want to process by
           calling gnatgcc -c -gnatc -gnatt  file  (with  the  appropriate  -I
           options, if needed.)

       2.  Call  adabrowse  for  these specs: adabrowse -f file (and any other
           options, as needed [look in particular at -T!]).

       adabrowse generates HTML files by default in the current directory.

       adabrowse doesn’t care whether the tree files have been  produced  from
       specs or bodies: since the tree file of a body always also contains the
       information on the spec, it can work with either.


       -h, -?, -help, --help
              Writes a comprehensive help text.

       -a, -all, --all
              Generate HTML not only for the unit given in the -f option,  but
              also  for all application units on which it depends semantically
              (transitive closure of "with"es and parent units).

              Note that this option processes only the  application  units  in
              the transitive closure even if the "-g" option is also given; it
              does not process any "with"ed standard library unit.  This  also
              means  that  if  the  unit given is a standard library unit, the
              "-all" option has  no  effect.  This  behavior  is  intentional:
              you’ll  normally  generate HTML for the standard library once by
              processing all standard library units explicitly, and you  don’t
              want  to  re-generate HTML for these units each time one of your
              application unit "with"es a standard library unit.

       -c file
              Defines a configuration file for the HTML generator. Multiple -c
              options may be given; the files are processed in the given order
              and may overwrite earlier config settings.

       -f file
              Gives the filename (*.ads) of the spec to process. This filename
              may  contain  a  path!  See below for more comments. Only one -f
              option may be given.

       -g     If set, adabrowse also generates cross-references to items  from
              library  units in the standard and run-time packages, except for
              items from the implict package "Standard". Note: This  can  also
              be  set  by  a  configuration  file  key "Refs_To_Standard". The
              latter definition wins.

       -G output_formats...
              Specify the output formats  adabrowse  shall  generate.  The  -G
              option  must  be  followed  by  one or more output format names,
              given as separate arguments. Recognized output format names  are
              html and xml (case insensitive).

       -i [file]
              If  set,  adabrowse  will generate a package index if it runs in
              "file input mode" (see below) or the -all option is set and  the
              output does not go to stdout.

              If a filename is given, the index is written to that file (or to
              stdout, if the filename is "-").

       -is [file]
              Same as -i, but generates an index using indentation  for  child

       -l     Make  adabrowse  generate  cross-references in HTML output using
              only the line number. This is what earlier versions of adabrowse
              (up  to  and  including  V2.13)  always  did. As of V3.0, cross-
              references are constructed taking into  account  both  line  and
              column number of an item. You should use this option only if you
              have HTML documentation generated by earlier adabrowse  versions
              and  somehow cannot re-generate that documentation. However, the
              recommended usage is never to use this option and to  regenerate
              possibly already existing HTML documentation.

              Note  that  HTML  generated  with -l is not compatible with HTML
              generated without -l! Also, HTML generated by adabrowse 3.0  and
              beyond  is  compatible with HTML generated by adabrowse 2.13 and
              earlier only if the -l option is given.

              Usage of this option generates a warning message on stderr.

       -o [file]
              Define the output file name. If not set, the output  goes  to  a
              file  with  the  name  of  the  input  and suffix .html. If file
              specifies a directory (i.e., ends in a "\" on Windows or  a  "/"
              on  Unix),  all  generated  HTML  files  will  be  put into that
              directory. If the filename is "-", output is written to  stdout.
              Only one -o option may be given.

              A dash as the filename ("-") is allowed only if there is exactly
              one output  format  specified.  If  there  are  multiple  output
              formats  specified  (e.g.  both  XML  and  HTML),  output is not
              allowed to go to stdout.

       -p [file]
              As  -i,  but  generates  a  subprogram  index  over  all   units

       -private, --private
              If  given,  adabrowse  will  also  process  the private parts of
              packages and task or protected  declarations.  (By  default,  it
              doesn’t do so but replaces the private parts by a comment saying
              "Implementation defined".)

       -q     Quiet mode: do not issue warning or info  messages.  Synonym  to

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

       -t [file]
              As  -i,  but  generates  a  global  type  index  over  all units

       -version, --version
              Print version information of adabrowse to stderr.

       -wi    Sets the warning level  of  adabrowse.  i  may  be  one  of  the
           0, or e         print only error messages.
           1, or w         print warnings and errors.
           2, or i, or a   print all messages.

       -x     If  set, adabrowse never overwrites existing HTML files. (May be
              useful in conjunction with the -a option.)

       -X name=value
              Define an environment variable name with value value. The  value
              supersedes  any  possibly already existing definition of name in
              the system’s environment for this call  to  adabrowse.  The  new
              definition affects any configuration file processed subsequently
              and also the project file (if any). The name  must  not  contain
              white  space;  if  value  contains  white space, quote the whole
              definition as in -X"user=John Doe". There  may  or  may  not  be
              white space between the -X and the variable definition.

       -I directory
              Define  source  paths  for  ASIS.  Same  semantics  as for GNAT.
              Multiple -I options may be given.

       -T directory
              Define pathes  for  ASIS  to  search  for  tree  files  (*.adt).
              Multiple -T options may be given.

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

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


       The -f option has three different formats:

       1.  If the filename is "-" or "@-", adabrowse reads the unit  specs  of
           the  units  to  process from stdin, one unit per line, until EOF is
           encountered.  Empty  lines  are   skipped.   (If   you   try   this
           interactively,  you’ll have to signal EOF yourself. Otherwise, this
           may be useful if the input comes from a pipe, like in "ls -1  *.ads
           | adabrowse -f- ...")

       2.  If  the  filename  starts with "@", adabrowse doesn’t consider it a
           unit spec, but as the name of a text file from which  to  read  the
           unit names, one unit per line. Empty lines in the file are ignored.

       3.  If neither applies, adabrowse uses the given filename as  the  unit

       The  first two cases are called the "file input mode" of adabrowse. The
       file may contain empty lines and comments (starting with the first  "#"
       on  a line and extending up to the end of the line), which are ignored.
       Note that contrary to configuration files, string handling for  finding
       comment  starts  is  not  done,  and  line  continuations  also are not

       In all three cases, a unit spec is a filename that may contain a  path;
       a  possible suffix is ignored. Note that a unit spec is a file name; in
       other words, you give test-gen, or, and not Test.Gen.  The
       reason  is simply that for most shell scripting languages, it is easier
       to work with filenames than to massage them into unit  names  (e.g.  by
       replacing dashes by dots). Also, if you have krunched file names, there
       is no simple connection between the file name and the unit name.

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

       In  file  input mode, the -o option (if given at all) may either be "-"
       (in which case all output goes to stdout) or specify a  directory,  but
       must not specify a file.

       adabrowse  assumes a GNAT-like naming scheme for source and HTML files.
       It also assumes that there is one library unit per file.  As  of  V1.4,
       adabrowse  can handle krunched file names in the -f option, provided it
       can find a source file, and it has the extension .ads. If so, adabrowse
       opens  and  parses the source file to extract the unit name, instead of
       deriving it directly from the file  name.  Note  that  generated  files
       always  have  names based on the unit name, not the original file name:
       i.e., output file names will never be krunched.

       Generated HTML files always have the suffix ".html" (not ".htm").


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

       There are several options controlling index generation:

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

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

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

       adabrowse assumes it will process several units in the following cases:
       ·   In file input mode (-f @file_name or -f-).
       ·   When using a project file (-P project_file_name).
       ·   When the -all option is given.

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

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

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


       gnatgcc(1), gnatkr(1)

       The full user’s guide in /usr/share/doc/adabrowse.


       The  Debian  package  of  adabrowse  does  not have the Project Manager
       feature; the command-line option -P project_file is therefore disabled.


       adabrowse and the accompanying documentation was written by Thomas Wolf

       Ludovic Brenta <> merely turned part  of  the
       user’s guide into this manual page for the Debian project.