Provided by: adabrowse_4.0.3-14_amd64 bug

NAME

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

SYNOPSIS

       adabrowse [options] -f file

DESCRIPTION

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

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

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

USAGE

       There are two ways to use adabrowse:

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

           or

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

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

       adabrowse generates HTML files by default in the current directory.

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

OPTIONS

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

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

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

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

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

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

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

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

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

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

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

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

              Usage of this option generates a warning message on stderr.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

THE -f OPTION

       The -f option has three different formats:

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

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

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

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

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

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

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

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

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

INDEX GENERATION

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

       There are several options controlling index generation:

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

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

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

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

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

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

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

SEE ALSO

       gnatgcc(1), gnatkr(1)

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

BUGS

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

AUTHOR

       adabrowse and the accompanying documentation was written by Thomas Wolf <twolf@acm.org>.

       Ludovic  Brenta  <ludovic@ludovic-brenta.org>  merely turned part of the user's guide into
       this manual page for the Debian project.