Contents

1. Description
2. Calling hdocu
3. Files

1. Description

hdocu is a system for documenting installed softwared in a distributed environment. Software packages are usually untar'ed into their own directory (like /usr/local/src/packagename) and compiled. Unfortunatley, installation will usually spread lots of binaries, libraries, headers etc. all over the place.

hdocu was designed to provide the user with information about all software packages that were installed (and documented), and to be able to find the package providing a given binary, header oder library.

The software administrator will put a file named INFO.LDV into every package direcory, fill in the necessary information and call hdocu. This will create several HTML files.

2. Calling hdocu

hdocu [options] [-[no]make] [-[no]man] [-[no]check]

Usually, you will want to only edit the config file and use the options -man and -check as appropriate.

Options offered by hdocu are:

-help

Show help message and stop.

-verbose [level]

Make hdocu more verbose. Levels 1 to 3 are supportet. Multiple -v options will each increase the level, explicitly setting the level overrides any previous setting.

-version

Show version of hdocu and stop.

-[no]old

Will allow the use of old-style INFO.LDV files. Only usefull at our own site (LDV).

-[no]table

Turn usage of HTML tables on or off.

-[no]make

Turn generation of new html files on (the default behaviour) or off. Only usefull in conjunction with -man or -check.

-[no]man

Generate HTML versions of manpages. The HTML mansections will be located in the man/html.<sec> subdirectory within the default output directory. If there are manpages in /usr/local/man/man1 then this option will create HTML versions in man/html1.

-[no]rman

Uses rman (RosettaMan or PolyglottMan) to produce better HTML code than the built-in man-to-HTML-Filter. Set to true by default.

-[no]check

Run several additional tests on installed files. This will provide the softwareadmin with the ability to ensure that all files are properly documented.

-nocheckman

Checking installed manpages can take quite a while and produce too many error messages, especially if one manpage has several links to make it accessible under various names.

-libdir

Directory where the hdocu config file and HTML templates are.

-in

Override default setting of where to look for INFO.LDV files.

-mandir

Override default setting of where to look for man files.

-pub

Like -in, but handled different.

-out

Where to put the HTML files.

All options can be abbreviated. If the abbreviation is not unique, then the following rules apply: -v expands to -verbose, -m to -man and -o to -out.

3. Files

/usr/local/lib/hdocu/config

Default configuration of hdocu. Available options are documented in the file itself.

/usr/local/lib/hdocu/hdocu_table.tml

Template for creating hdocu files using tables.

/usr/local/lib/hdocu/hdocu_notable.tml

Template for creating hdocu files without tables.

/usr/local/lib/hdocu/index.tml

Template for all kind of index files. Tables are constructed by hdocu, so there is only one version for both table and notable setup.

/usr/local/lib/hdocu/man.tml

Template for HTML converted man pages (there is no need for seperate table / notable versions). Conversion can be done

• at a rather low level (the output of a simulated man(1) command ist converted to HTML) or
• or using the PolyglottMan (rman) package's HTML formatting capability (depends on your installation).

/usr/local/lib/hdocu/INFO.LDV

A sample INFO.LDV file. It contains information on how to fill in the information needed.

/usr/local/lib/hdocu/DEFAULT.LDV

Contains default entries if the software administrator does not fill in some information, e.g. if there is nothing to fill in. This is quite usual: not every software package contains libraries and binaries to be installed.