ADABROWSE(1)

📦 version 4.0.3, in ubuntu jammy

✨ ADABROWSE(1) ✨

Welcome to the AdaBrowse User Manual, bestie 🦋 This is part 1 of the manual, so it's a lot, but it's all good stuff 💖

✨ NAME ✨

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

📜 SYNOPSIS

adabrowse [options] -f file

💅 DESCRIPTION

okay so adabrowse makes a fully cross-referenced HTML rendering of Ada 95 specs (no bodies), kind of like what javadoc does for Java sources 🔥 It's a command-line utility, so there's no graphical user interface at all, just vibes in your terminal 💻

adabrowse is highly configurable through command-line options, style sheets, and configuration files. Main character energy, literally 👑

adabrowse completely takes apart the source code and produces 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, and both are iconic 🌈

Way one

  1. Call adabrowse for your spec: adabrowse -f file (plus any other options you need, especially -I if the file isn't in the current directory or depends on other units whose sources aren't in the current directory!) If no tree file for the given unit exists, adabrowse will try to generate one 🧚

or

Way two

  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 were 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 one 🫶

🎀 OPTIONS 🎀

  • -h, -?, -help, --help — Writes a comprehensive help text. Literally your new best friend 🫶
  • -a, -all, --all — Generate HTML not just for the unit given in the -f option, but also for every application unit it depends on semantically (the transitive closure of "with"s and parent units) 🦋
⚠️ bestie, this option only processes the application units in that transitive closure, even if -g is also given. It does not process any "with"ed standard library unit. So if the unit you give is a standard library unit, -all does nothing. This 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 regenerate it every time one of your application units "with"s a standard library unit.
  • -c file — Defines a configuration file for the HTML generator. You can give multiple -c options. The files get processed in the order you give them, and later ones 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 implicit package "Standard". Heads up: this can also be set with the configuration file key Refs_To_Standard, but the latter definition wins 🧚
  • -G output_formats... — Specify the output formats adabrowse should generate. -G has to be followed by one or more output format names, each as a separate argument. The recognized names are html and xml (case insensitive) 🌈
  • -i [file] — If set, adabrowse generates a package index when it runs in "file input mode" (see below), or when -all is set and the output doesn't go to stdout. If you give a filename, the index is written to that file, or to stdout if the filename is "-" 📜
  • -is [file] — Same as -i, but the index uses indentation for child units 🍓
  • -l — Makes adabrowse generate cross-references in HTML output using only the line number. This is what earlier versions (up to and including V2.13) always did. As of V3.0, cross-references take both the line and column number of an item into account. Only use this option if you have HTML docs generated by earlier versions and somehow can't regenerate them. The recommended move is to never use this option and to regenerate any existing HTML docs instead 💀

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.

⚠️ Using this option generates a warning message on stderr.
  • -o [file] — Defines the output file name. If it isn't set, the output goes to a file named after the input with the suffix .html. If the file specifies a directory (i.e., ends in a \ on Windows or a / on Unix), all generated HTML files get put into that directory 🦋 If the filename is "-", the output is written to stdout. Only one -o option may be given 💅
⚠️ A dash as the filename ("-") is only allowed if exactly one output format is specified. If there are multiple output formats (e.g. both XML and HTML), the output is not allowed to go to stdout. No cap, don't skip this one 😭
  • -p [file] — Same 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 that. Instead it replaces the private parts with a comment saying "Implementation defined" 🙈
  • -q — Quiet mode: don't issue warning or info messages. This is a synonym for -w0 🤫
  • -s URL — Defines the URL of the style sheet the generated HTML file should use. This URL should be relative to the final place where you'll put the HTML files! Note that a -s option can be overwritten by a later -c option, if that configuration file defines the key Style_Sheet 🎀
  • -t [file] — Same as -i, but generates a global type index over all units processed 🧚
  • -version, --version — Prints version information for adabrowse to stderr 🌸
  • -wi — Sets the warning level of adabrowse. The i can be one of the following:
    • 0 or e: print only error messages
    • 1 or w: print warnings and errors
    • 2, i, or a: print all messages
  • -x — If set, adabrowse never overwrites existing HTML files. This can be useful together with the -a option 🫶
  • -X name=value — Defines an environment variable name with the value value. This value supersedes any already existing definition of name in the system's environment, for this call to adabrowse. The new definition affects any configuration file processed afterward and also the project file (if any). The name must not contain white space. If value contains white space, quote the whole definition like this: -X"user=John Doe". There may or may not be white space between the -X and the variable definition 💖

part 2 is coming with the rest of the options, so stay tuned 🧚

okay bestie, the -f option is literally three personalities in one 💅✨

🦋 THE -f OPTION 🦋

The -f option comes in three different flavors, and ngl each one has its own main character energy 💖

  1. Stdin vibes 🧚: If the filename is - or @-, adabrowse reads the unit specs from stdin, one unit per line, until it hits EOF. Empty lines get skipped, no drama. (If you try this interactively, you gotta signal EOF yourself 😭 This is lowkey useful when your input is coming from a pipe, like ls -1 *.ads | adabrowse -f- ...)
  2. Text file era 📝: If the filename starts with @, adabrowse doesn't treat it as a unit spec. Instead it's the name of a text file, and it reads the unit names from there, one per line. Empty lines in that file get ignored 🫶
  3. Just vibing 🌸: If neither of the above applies, adabrowse uses the filename you gave it as the unit spec. Simple, iconic, no notes.

The first two cases are called the "file input mode" of adabrowse 🎀. The file can have empty lines and comments. A comment starts at the first # on a line and goes to the end of that line, and adabrowse ignores all of it. Now, be careful here: unlike configuration files, comment detection is not done with string handling, and line continuations are not allowed either 🙈

In all three cases, a unit spec is a filename that may contain a path. Any suffix is ignored. Also, a unit spec is a file name, not a unit name. So you give test-gen or test-gen.ads, and NOT Test.Gen 💀 The reason is that most shell scripting languages find it way easier to work with filenames than to mess around turning them into unit names (like swapping dashes for dots). Also, if you have krunched file names, there's no simple connection between the file name and the unit name, so yeah 🌈

If a unit spec contains a path, the HTML file for that unit gets placed into that directory, unless you override it with a -o option. Also, if the unit spec has a path, you'll most probably need to set a -T or -I option too, unless you happen to have the ASIS information available directly (like a tree file for the unit in the current directory). Tbh that's not exactly typical 👑

In file input mode, the -o option (if you give it at all) can be either -, which sends all output to stdout, or a directory. It must not be a file 🚫

adabrowse assumes a GNAT-like naming scheme for source and HTML files. It also assumes there's one library unit per file. As of V1.4, adabrowse can handle krunched file names in the -f option, as long as it can find a source file with the extension .ads. If so, it opens and parses the source file to pull out the unit name, instead of deriving it from the file name. Also, generated files always use names based on the unit name, not the original file name, so output file names will never be krunched ✨

Generated HTML files always end in .html, never .htm 💅

🌈 INDEX GENERATION 🌈

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

There are several options that control 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 of these take an optional filename. If you add a filename, the index gets written to that file (or to stdout, if the filename is -). If you don't give one, some default name gets picked for you 🎀

Okay, real talk: all of these options are only kept around for backwards compatibility. As of V4.0, indices are defined mainly through configuration file entries, not on the command line. But so your existing scripts don't break, the command line options are still available 🫠

adabrowse assumes it'll process several units in these 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, where the index ends up depends on your other options:

  • In file input mode, if a -o option is given, it must specify a directory. All HTML files, including the index, go into that directory 🍓
  • If there's no -o option, but the first unit spec contains a path, the index goes into the directory that path points to 🌸
  • If you're not in file input mode, but the -all option has been given, the -o option may specify a file name. The index goes into the directory from the path part of that file name (or the current directory, if the filename has no path) 🦋
  • If you're using a project file, the indices get written into the ADABROWSE_OUTPUT directory 📂
  • Otherwise, the index lands in the current directory 🏠

If you give a filename that contains a path, the index gets placed into that file inside the given directory. If the filename only has a path, adabrowse uses that path and makes an index named index.html in the designated directory 💖

If you give a -x option (which stops existing HTML files from being overwritten) and a file already exists where adabrowse wants to put the index, no index gets generated and adabrowse will issue a warning ⚠️ It'll also warn if it can't generate an index for any other reason, but it'll keep on processing otherwise 💪

⚠️ Heads up: with -x, an existing index file will block the index from being generated at all. adabrowse warns you, then keeps going.

🔗 SEE ALSO 🔗

gnatgcc(1), gnatkr(1)

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

🐛 BUGS 🐛

The Debian package of adabrowse does not have the Project Manager feature, so the command-line option -P project_file is disabled 😭

👩‍💻 AUTHOR 👩‍💻

adabrowse and its accompanying documentation were written by Thomas Wolf <twolf@acm.org>.

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

GNU Ada Tools, 14 FEB 2004, ADABROWSE(1) 🌸 okay that's the whole page bestie, go be iconic and read the manual of your dreams 💖✨

📦 where this page comes from