Generating Installing and Accessing Manuals

Accessing html manuals

Once generated, the .html files can be viewed using any standard WWW browser, e.g., Firefox (a command lpdoc htmlview is available which, if there is an instance of a web browser running in the machine, will make that instance visit the manual in html format). To make these files publicly readable on the WWW, they should be copied into a directory visible by browsers running in other machines, such as /home/clip/public_html/lpdoc_docs, /usr/home/httpd/htmldocs/lpdoc_docs, etc. As mentioned before, this is easily done by setting the docdir variable in the SETTINGS.pl file to this directory and typing lpdoc install.

Accessing info manuals

Generated .info files are meant to be viewed by the Emacs editor or by the standalone info application, both publicly available from the GNU project sites. To view the a generated info file from Emacs manually (i.e., before it is installed in a common area), type C-u M-x info. This will prompt for an info file name. Input the name of the info file generated by lpdoc (main.info) and Emacs will open the manual in info mode.

There are several possibilities in order to install an .info file so that it is publicly available, i.e., so that it appears automatically with all other info manuals when starting info or typing C-u M-x info in Emacs:

• Installation in the common info directory:

  • Move the .info file to the common info directory (typically /usr/info, /usr/local/info, ..). This can be done automatically by setting the docdir variable in the SETTINGS.pl file to this directory and typing lpdoc install.

    Warning: if you are installing in an info directory that is not maintained automatically by lpdoc, make sure that you have not selected the infoindex option in docformats, since this will overwrite the existing dir file).

  • Add an entry to the info index in that directory (normally a file in that directory called dir). The manual should appear as part of the normal set of manuals available when typing M-x info in Emacs or info in a shell. See the Emacs manual for details.

• Installation in a different info directory: you may want to place one or more manuals generated by lpdoc in their own directory. This has the advantage that lpdoc will maintain automatically an index for all the lpdoc generated manuals installed in that directory. In order for such manuals to appear when typing M-x info in Emacs or info in a shell there are two requirements:

  • This directory must contain a dir index. The first part of the process can all be done automatically by setting the docdir variable in the SETTINGS.pl file to this directory, including the infoindex option in docformats, and typing lpdoc install. This will install the info manual in directory docdir and update the dir file there. lpdoc uninstall does the opposite, eliminating also the manual from the index.

  • The directory must be added to the info path list. The easiest way to do this is to set the INFOPATH environment variable. For example, assuming that we are installing the info manual in /home/clip/public_html/lpdoc_docs and that /usr/info is the common info directory, for csh in .cshrc:

    setenv INFOPATH /usr/info:/home/clip/public_html/lpdoc_docs

    Adding the directory to the info path list can also be done within Emacs, by including the following line in the .Emacs file:

    (defun add-info-path (newpath)
      (setq Info-default-directory-list
    	(cons (expand-file-name newpath) Info-default-directory-list)))
    (add-info-path "/home/clip/public_html/lpdoc_docs")
    (add-info-path "/usr/info/")
    

    However, this has the disadvantage that it will not be seen by the standalone info command.

Automatic, direct on-line access to the information contained in the info file (e.g., going automatically to predicate descriptions by clicking on predicate names in programs in an Emacs buffer) can be easily implemented via existing .el packages such as word-help, written by Jens T. Berger Thielemann (<jensthi@ifi.uio.no>). word-help may already be in your Emacs distribution, but for convenience the file word-help.el, providing suitable initialization are included in the lpdoc library. A suitable interface for word-help is also provided by the ciao.el Emacs file that comes with the Ciao system distribution (i.e., if ciao.el is loaded it is not necessary to load or initialize word-help).

Accessing man manuals

The Unix man format manuals generated by lpdoc can be viewed using the Unix man command. In order for man to be able to locate the manuals, they should be copied to one of the subdirectories (e.g., /usr/local/man/manl) of one of the main man directories (in the previous case the main directory would be /usr/local/man). As usual, any directory can be used as as a man main directory, provided it is included in the environment variable MANPATH. Again, this process can be performed automatically by setting the docdir variable in the SETTINGS.pl file to this directory and typing lpdoc install.

Putting it all together

A simple, powerful, and very convenient way to use the facilities provided by lpdoc for automatic installation of manuals in different formats is to install all manuals in all formats in the same directory docdir, and to choose a directory which is also accessible via WWW. After setting docdir to this directory in the SETTINGS.pl file, and selecting infoindex and htmlindex for the docformats variable, lpdoc install/lpdoc uninstall will install/uninstall all manuals in all the selected formats in this directory and create and maintain the corresponding html and info indices. Then, setting the environment variables as follows (e.g., for csh in .cshrc):

setenv DOCDIR   /home/clip/public_html/lpdoc_docs
setenv INFOPATH /usr/local/info:${DOCDIR}
setenv MANPATH  ${DOCDIR}:${MANPATH}

Example files for inclusion in user's or common shell initialization files are included in the lpdoc library.

More complex setups can be accommodated, as, for example, installing different types of manuals in different directories. However, this currently requires changing the docformats and docdir variables and performing lpdoc install for each installation format/directory.

Ensuring Compatibility with All Supported Target Formats

One of the nice things about lpdoc is that it allows generating manuals in several formats which are quite different in nature. Because these formats each have widely different requirements it is sometimes a little tricky to get things to work successfully for all formats. The following recommendations are intended to help in achieving useful manuals in all formats:

• The best results are obtained when documenting code organized as a series of libraries, and with a well-designed module structure.

• texinfo supports only a limited number of indices. Thus, if you select too many indices in the SETTINGS.pl file you may exceed texinfo's capacity (which it will signal by saying something like “No room for a new @write”).

• The GNU info format requires all nodes (chapters, sections, etc.) to have different names. This is ensured by lpdoc for the automatically generated sections (by appending the module or file name to all section headings). However, care must be taken when writing section names manually to make them different. For example, use “lpdoc usage” instead of simply “Usage”, which is much more likely to be used as a section name in another file being documented.

• Also due to a limitation of the info format, do not use : or , or -- in section, chapter, etc. headings.

• The character “_” in names may sometimes give problems in indices, since current versions of texinfo do not always handle it correctly.

Writing comments which document version/patch changes

When writing version comments (:- doc(version(...), "...").), it is useful to keep in mind that the text can often be used to include in the manual a list of improvements made to the software since the last time that it was distributed. For this to work well, the textual comments should describe the significance of the work done for the user. For example, it is more useful to write "added support for pred assertions" than "modifying file so pred case is also handled".

Sometimes one would like to write version comments which are internal, i.e., not meant to appear in the manual. This can easily be done with standard Prolog comments (which lpdoc will not read). An alternative and quite useful solution is to put such internal comments in patch changes (e.g., 1.1#2 to 1.1#3), and put the more general comments, which describe major changes to the user and should appear in the manual, in version changes (e.g., 1.1#2 to 1.2#0). Selecting the appropriate options in lpdoc then allows including in the manual the version changes but not the patch changes (which might on the other hand be included in an internals manual).

Documenting Libraries and/or Applications

As mentioned before, for each a .pl file, lpdoc tries to determine whether it is a library or the main file of an application, and documents it accordingly. Any combination of libraries and/or main files of applications can be used arbitrarily as components or main files of a lpdoc manual. Some typical combinations are:

• Main file is a library, no components: A manual of a simple library, which appears externally as a single module. The manual describes the purpose of the library and its interface.

• Main file is an application, no components: A manual of a simple application.

• Main file is a library, components are also libraries: This can be used for example for generating an internals manual of a library. The main file describes the purpose and use of the library, while the components describe the internal modules of the library.

• Main file is an application, components are libraries: This can be used similarly for generating an internals manual of an application. The main file describes the purpose and use of the application, while the components describe the internal modules which compose the application.

• Main file is a (pseudo-)application, components are libraries: A manual of a complex library made up of smaller libraries (for example, the Prolog library). The (pseudo-)application file contains the introductory material (title, version, etc.). Each chapter describes a particular library.

• Main file is a (pseudo-)application, components are applications: This can be used to generate a manual of a set of applications (e.g., a set of utilities). The (pseudo-)application file contains the introductory material (title, version, etc.). Each chapter describes a particular component application.

Documenting files which are not modules

Sometimes it is difficult for lpdoc to distinguish include files and Ciao packages from normal user files (i.e., normal code files but which are not modules). The distinction is important because the former are quite different in their form of use (they are loaded via include/1 or use_package/1 declarations instead of ensure_loaded/1) and effect (since they are included, they 'export' operators, declarations, etc.), and should typically be documented differently. There is a special doc/2 declaration (:- doc(filetype,...).) which provides a way of defining the intended use of the file. This declaration is normally not needed in modules, include files, or packages, but should be added in user files (i.e., those meant to be loaded using ensure_loaded/1). Adding this declaration will, for example, avoid spurious documentation of the declarations in the assertions package themselves when this package is included in a user file.

Splitting large documents into parts

As mentioned before, in lpdoc each documented file (each component) corresponds to a chapter in the generated manual. In large documents, it is sometimes convenient to build a super-structure of parts, each of which groups several chapters. There is a special value of the second argument of the :- doc(filetype,...). declaration mentioned above designed for this purpose. The special filetype value part can be used to flag that the file in which it appears should be documented as the start of one of the major parts in a large document. In order to introduce such a part, a .pl file with a declaration :- doc(filetype,part). should be inserted in the sequence of files that make up the components variable of the SETTINGS.pl file at each point in which a major part starts. The :- doc(title,"..."). declaration of this file will be used as the part title, and the :- doc(module,"..."). declaration text will be used as the introduction to the part.

Documenting reexported predicates

Reexported predicates, i.e., predicates which are exported by a module m1 but defined in another module m2 which is used by m1, are normally not documented in the original module, but instead a simple reference is included to the module in which it is defined. This can be changed, so that the documentation is included in the original module, by using a doc/2 declaration with doinclude in the first argument (see the comments library). This is often useful when documenting a library made of several components. For a simple user's manual, it is often sufficient to include in the lpdoc SETTINGS.pl file the principal module, which is the one which users will do a use_module/1 of, in the manual. This module typically exports or reexports all the predicates which define the library's user interface. Note, however, that currently, due to limitations in the implementation, only the comments inside assertions (but not those in doc/2 declarations) are included for reexported predicates.

Separating the documentation from the source file

Sometimes one would not like to include long introductory comments in the module itself but would rather have them in a different file. This can be done quite simply by using the @include command. For example, the following declaration:

:- doc(module,"@include{Intro.lpdoc}").

will include the contents of the file Intro.lpdoc as the module description.

Alternatively, sometimes one may want to generate the documentation from a completely different file. Assuming that the original module is m1.pl, this can be done by calling the module containing the documentation m1_doc.pl. This m1_doc.pl file is the one that will be included in the lpdoc SETTINGS.pl file, instead of m1.pl. lpdoc recognizes and treats such _doc files specially so that the name without the _doc part is used in the different parts of the documentation, in the same way as if the documentation were placed in file m1.

Generating auxiliary files (e.g. READMEs)

Using lpdoc it is often possible to use a common source for documentation text which should appear in several places. For example, assume a file INSTALLATION.lpdoc contains text (with lpdoc formatting commands) describing an application. This text can be included in a section of the main file documentation as follows:

:- doc(module,"
   ...
   @section{Installation instructions}
   @include{INSTALLATION.lpdoc}
   ...
   ").

At the same time, this text can be used to generate a nicely formatted INSTALLATION file in ascii, which can perhaps be included in the top level of the source directory of the application. To this end, an INSTALL.pl file as follows can be constructed:

:- use_package([assertions]).
:- doc(filetype, application). %% forces file to be documented as an application
:- doc(title,"Installation instructions").
:- doc(module,"@include{INSTALLATION.lpdoc}").

Then, the ascii INSTALLATION file can be generated by simply running lpdoc ascii in a directory with a SETTINGS.pl file where MAIN is set to INSTALLATION.pl.