Go to the first, previous, next, last section, table of contents.


Generating Installing and Accessing Manuals

Author(s): Manuel Hermenegildo.

Version: 1.9#58 (2002/4/19, 20:59:33 CEST)

Version of last change: 1.9#57 (2002/1/5, 0:47:15 CET)

This part describes how to generate a manual (semi-)automatically from a set of source files using lpdoc, how to install it in a public area, and how to access it on line. It also includes some recommendations for improving the layout of manuals, usage tips, and troubleshooting advice.

Generating a manual from the Ciao emacs mode

If you use the emacs editor (highly recommended in all circumstances), then the simplest way to quickly generate a manual is by doing it from the Ciao emacs mode (this mode comes with the Ciao Prolog distribution and is automatically installed with Ciao). The Ciao emacs mode provides menu- and keyboard-binding driven facilities for generating a stand-alone document with the documentation corresponding to the file in the buffer being visited by emacs. This is specially useful while modifying the source of a file, in order to check the output that will be produced when incorporating this file into a larger document. It is also possible to generate more complex documents, by editing the (automatically provided) SETTINGS in the same way as when generating a manual from the command line (see below). However, when generating complex documents, it is best to devote an independent, permanent directory to the manual, and the full procedure described in the rest of this text is preferred.

Generating a manual

The lpdoc library directory includes two generic files which are quite useful for the generation of complete manuals: the Makefile and SETTINGS files. Use of these files is strongly recommended. Generating a manual using these files involves the following steps:

Working on a manual

In order to speed up processing while developing a manual, it is recommended to work by first generating a .dvi version only (i.e., by typing gmake dvi). The resulting output can be easily viewed by tools such as xdvi (which can be started by simply typing gmake view). Note that once an xdvi window is started, it is not necessary to restart it every time the document is reformatted (gmake dvi), since xdvi automatically updates its view every time the .dvi file changes. This can also be forced by typing R in the xdvi window. The other formats can be generated later, once the .dvi version has the desired contents.

Cleaning up the documentation directory

Several cleanup procedures are provided by the Makefile:

Installing a generated manual in a public area

Once the manual has been generated in the desired formats, the Makefile provided also allows automatic installation in a different area, specified by the DOCDIR option in the SETTINGS file. This is done by typing gmake install.

As mentioned above, lpdoc can generate directly brief descriptions in html or emacs info formats suitable for inclusion in an on-line index of applications. In particular, if the htmlindex and/or infoindex options are selected, gmake install will create the installation directory, place the documentation in the desired formats in this directory, and produce and place in the same directory suitable index.html and/or dir files. These files will contain some basic info on the manual (extracted from the summary and title, respectively) and include pointers to the relevant documents which have been installed. The variables HTMLINDEXHEADFILE / HTMLINDEXTAILFILE and INFODIRHEADFILE / INFODIRTAILFILE (default examples, used in the CLIP group at UPM, are included with the distribution) should point to files which will be used as head and tail templates when generating the index.html and/or dir files. A variable EXTRAFILES allows defining a list of additional files which will be copied to the DOCDIR installation directory. This is useful to place figures or other files which the HTML header files use in the installation directory (so that paths can be local). These files must reside in the directory in which the documentation is being generated.

Several manuals, coming from different doc directories, can be installed in the same DOCDIR directory. In this case, the descriptions of and pointers to the different manuals will be automatically combined (appearing in alphabetic order) in the index.html and/or dir indices, and a contents area will appear at the beginning of the html index page. If only one manual is installed, selecting the -nobullet option for the main file prevents the bullet item from appearing in this contents area. Important Note: In order for the different components to appear in the correct positions in the index pages mentioned above the traditional ('C') Lexical order must be active. In recent Un*x systems (e.g., in most current Linux systems) this may not be the case. There are several possible fixes:

Note that, depending on the structure of the manuals being generated, some formats are not very suitable for public installation. For example, the .dvi format has the disadvantage that it is not self contained if images are included in the manual.

The Makefile also makes provisions for manual deinstallation from the installation area. Typing gmake uninstall in a doc directory will deinstall from DOCDIR the manuals corresponding to the Makefile in that doc directory. If a manual is already installed and changes in the number of formats being installed are desired, gmake uninstall should be made before changing the DOCFORMATS variable and doing gmake install again. This is needed in order to ensure that a complete cleanup is performed.

Enhancing the documentation being generated

The quality of the documentation generated can be greatly enhanced by including within the program text:

Assertions are declarations which are included in the source program and provide the compiler with information regarding characteristics of the program. Typical assertions include type declarations, modes, general properties (such as does not fail), standard compiler directives (such as dynamic/1, op/3, meta_predicate/1...), etc. When documenting a module, lpdoc will use the assertions associated with the module interface to construct a textual description of this interface. In principle, only the exported predicates are documented, although any predicate can be included in the documentation by explicitly requesting it (see the documentation for the comment/2 declaration). Judicious use of these assertions allows at the same time documenting the program code, documenting the external use of the module, and greatly improving the debugging process. The latter is possible because the assertions provide the compiler with information on the intended meaning or behaviour of the program (i.e., the specification) which can be checked at compile-time (by a suitable preprocessor/static analyzer) and/or at run-time (via checks inserted by a preprocessor).

Machine-readable comments are also declarations included in the source program but which contain additional information intended to be read by humans (i.e., this is an instantiation of the literate programming style of Knuth [Knu84]). Typical comments include title, author(s), bugs, changelog, etc. Judicious use of these comments allows enhancing at the same time the documentation of the program text and the manuals generated from it.

lpdoc requires these assertions and comments to be written using the Ciao system assertion language. A simple compatibility library is available in order to make it possible to compile programs documented using assertions and comments in traditional (constraint) logic programming systems which lack native support for them (see the compatibility directory in the lpdoc library). Using this library, such assertions and comments are simply ignored by the compiler. This compatibility library also allows compiling lpdoc itself under (C)LP systems other than the Ciao system under which it is developed.

Accessing on-line manuals

As mentioned previously, it is possible to generate on-line manuals automatically from the .texic files, essentially .html, .info, and man files. This is done by simply including the corresponding options in the list of DOCFORMATS in the SETTINGS file and typing gmake all. We now address the issue of how the different manuals can be read on-line.

Accessing html manuals

Once generated, the .html files can be viewed using any standard WWW browser, e.g., netscape (a command gmake htmlview is available which, if there is an instance of netscape 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 file to this directory and typing gmake 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:

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 and a word-help-setup.el file, 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 file to this directory and typing gmake 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 file, and selecting infoindex and htmlindex for the DOCFORMATS variable, gmake install/gmake 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 gmake install for each installation format/directory.

Some usage tips

This section contains additional suggestions on the use of lpdoc.

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:

Writing comments which document version/patch changes

When writing version comments (:- comment(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:

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 comment/2 declaration (:- comment(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 :- comment(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 :- comment(filetype,part). should be inserted in the sequence of files that make up the COMPONENTS variable of the SETTINGS file at each point in which a major part starts. The :- comment(title,"..."). declaration of this file will be used as the part title, and the :- comment(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 comment/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 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 comment/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:

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

will include the contents of the file Description.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 the lpdoc SETTINGS 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 INSTALL.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:

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

At the same time, this text can be used to generate a nicely formatted INSTALL 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]).
:- comment(title,"Installation instructions").
:- comment(module,"@include{INSTALL.lpdoc}").
main. %% forces file to be documented as an application

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

Troubleshooting

These are some common errors which may be found using lpdoc and the usual fix:


Go to the first, previous, next, last section, table of contents.