xenial (1) adabrowse.1.gz

Provided by: adabrowse_4.0.3-6_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 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

       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).
       •   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.