ADABROWSE(1)						       AdaBrowse User Manual						      ADABROWSE(1)

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:
       o   All context clauses
       o   Unit header
       o   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 exist-
	      ing 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 file-
	      name 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 gener-
       ated 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  con-
       figuration  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:
       o   In file input mode (-f @file_name or -f-).
       o   When using a project file (-P project_file_name).
       o   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:
       o   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.
       o   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.
       o   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 direc-
	   tory designated by the path part of that file name (the current directory, if the filename doesn't contain a path).
       o   If using a project file, the indices are written into the ADABROWSE_OUTPUT directory.
       o   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 rea-
       sons, 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.

GNU Ada Tools							    14 FEB 2004 						      ADABROWSE(1)