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.
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.
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:
doc
) in which the documentation will be built. It is highly recommended that this be a separate and initially empty directory. This directory is typically created in the top directory of the distribution of the application or library to be documented.
SETTINGS
and copy (or, much better, link, since you typically will not need to change it) the file
Makefile
from the
lpdoc library directory into the doc
directory just created. The location of the
lpdoc
library directory is installation-dependent (see section Installing the source distribution).
SETTINGS
to suit your needs. It is required that you set the following:
FILEPATHS
to include all the directories where the files to be documented can be found.
SYSTEMPATHS
to include all the system directories where system files used (whether they are to be documented or not) can be found.
It is very important to include all related directories either in FILEPATHS
or in SYSTEMPATHS
because on startup
lpdoc
has no default search paths for files defined (not even those typically defined by default in the
Prolog
system under which it was compiled! -- this allows documenting
Prolog
systems other than that under which
lpdoc
was compiled).
The effect of putting a path in SYSTEMPATHS
instead of in FILEPATHS
is that the modules and files in those paths are documented as
system modules (this is useful when documenting an application to distinguish its parts from those which are in the system libraries).
MAIN
to be the name of the
main file of the application or library (e.g., main.pl
, header.src
, etc.).
COMPONENTS
to a (possibly empty) list, separated by spaces, of source files. These are the
component files.
SETTINGS
file you can simply use the default values indicated. You may however want to change several of these:
MAINOPTS
can be set to a series of options which allow more detailed control of what is included in the documentation for the main file and how (i.e., including bug information
, versions and patches or only patches
, authors
, changelog
, explanation of modes,
one-sided printing (
two-sided is the default), etc.). See
option_comment/2
in
autodocformats
or type lpdoc -help
for a list of these options.
COMPOPTS
sets options for the component files. Currently these options are common to all component files but they can be different from MAINOPTS
. The allowable options are the same as above.
DOCFORMATS
determines the set of formats (dvi
, ps
, ascii
, html
, info
, manl
, ...) in which the documentation should be generated by default when typing
gmake all
. Selecting htmlindex
and/or infoindex
requests the generation of (parts of) a master index to be placed in an installation directory and which provide pointers to the documents generated (see below). If the main file is an application, and the manl
option is selected, then
lpdoc
looks for a
usage_message/1
fact, which should contain a string as argument, and will use that string to document the
usage of the application (i.e., it will be used to fill in the
synopsis section of the man page).
INDICES
determines the list of indices to be included at the end of the document. These can include indices for defined predicates, modules, concepts, etc. For a complete list of the types of indices available see
index_comment/2
in
autodocformats
or type
lpdoc -help
for a listing. A setting of all
generates all the supported indices -- but beware of limitations in the number of simultaneous indices supported in many
texinfo
installations.
BIBFILES
determines a list (separated by commas, full paths, no spaces) of
.bib files, i.e., files containing
bibliographic entries in
bibtex
format. This is only relevant if you are
using citations in the text (using the
@cite command). In that case those will be the files in which the citations will be searched for. All the references will appear together in a References appendix at the end of the manual.
If you are not using citations, then select the -norefs
option on the main file, which will prevent an empty 'References' appendix from appearing in the manual.
STARTPAGE
(default value 1) allows changing the page number of the first page of the manual. This can be useful if the manual is to be included in a larger document or set of manuals. Typically, this should be an odd number.
PAPERTYPE
(default value afourpaper
) allows select several paper sizes for the printable outputs (dvi
, ps
, etc.). The currently supported outputs (most of them inherited from
texinfo
) are:
afourpaper
afourwide
afourpaper
on an A4 page. Useful for generating manuals in the least amount of space. Saves more trees.
afourlatex
afourpaper
.
smallbook
letterpaper
afourthesis
lpdoc
output as appendices of a thesis or similar document. Does not save trees.
gmake all
(you can also type gmake dvi
, gmake html
, gmake ps
or gmake info
, ... to force generation of a particular target).
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.
Several cleanup procedures are provided by the
Makefile
:
gmake clean
deletes all intermediate files, but leaves the targets (i.e., the .ps
, .dvi
, .ascii
, .html
, etc. files), as well as all the generated .texic
files.
gmake distclean
deletes all intermediate files and the generated .texic
files, leaving only the targets (i.e., the .ps
, .dvi
, .ascii
, .html
, etc. files). This is the option normally used when building software distributions in which the manuals come ready made in the distribution itself and will not need to be generated during installation.
gmake realclean
deletes all intermediate files and the generated targets, but leaves the .texic
files. This option can be used in software distributions in which the manuals in the different formats will be generated during installation. This is generally more compact, but requires the presence of several tools, such as tex
, emacs
, etc. (see section Other software packages required), in order to generate the manuals in the target formats during installation.
gmake braveclean
performs a complete cleanup, deleting also the .texic files, i.e., it typically leaves only the
SETTINGS
and
Makefile
. This is is the most compact, but requires in order to generate the manuals in the target formats during installation, the presence of the tools mentioned above,
lpdoc
, and the source files from which the manuals are generated.
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:
csh
put setenv LC_COLLATE C
in your
.cshrc
.
bash
put export LC_COLLATE=C
in your
.profile
.
LANG="C"
in /etc/sysconfig/i18n
.
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.
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.
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.
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
.
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:
.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
file to this directory and typing gmake 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).
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.
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:
dir
index. The first part of the process can all be done automatically by setting the DOCDIR
variable in the
SETTINGS
file to this directory, including the infoindex
option in DOCFORMATS
, and typing gmake install
. This will install the info manual in directory DOCDIR
and update the dir
file there. gmake uninstall
does the opposite, eliminating also the manual from the index.
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
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
).
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
.
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.
This section contains additional suggestions on the use of
lpdoc
.
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:
texinfo
supports only a limited number of indices. Thus, if you select too many indices in the
SETTINGS
file you may exceed
texinfo
's capacity (which it will signal by saying something like "No room for a new @write").
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.
info
format, do not use :
or ,
or -
-
in section, chapter, etc. headings.
_
" in names may sometimes give problems in indices, since current versions of
texinfo
do not always handle it correctly.
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).
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:
Prolog
library). The (pseudo-)application file contains the introductory material (title, version, etc.). Each chapter describes a particular library.
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.
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.
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.
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
.
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
.
These are some common errors which may be found using
lpdoc
and the usual fix:
gmake: *** No rule to make target `myfile.texic', needed by `main.texic'. Stop.appear (i.e., in the case above when running (
g
)make
main.
target). Since
lpdoc
definitely knows how to make a .texic
file given a .pl
file, this means (in make's language) that it cannot find the corresponding .pl
file (myfile.pl
in the case above). The usual reason for this is that there is no directory path to this file declared in the SETTINGS
file.
! No room for a new @write .while converting from
.texi
to .dvi
(i.e., while running
tex
). These messages are
tex
's way of saying that an internal area (typically for an index) is full. This is normally because more indices were selected in the INDICES
variable of the SETTINGS
file than the maximum number supported by the installed version of
tex
/
texinfo
installations, as mentioned in section Generating a manual. The easiest fix is to reduce the number of indices generated. Alternatively, it may be possible to recompile your local
tex
/
texinfo
installation with a higher number of indices.
info
files (a section which exists in the printed document cannot be accessed in the on-line document) can be due to the presence of a colon (:
), a comma (,
), a double dash (--
), or other such separators in a section name. Due to limitations of
info
section names cannot contain these symbols.
info
which do not work (i.e., the menu listings are there, but they cannot be followed): see if they are indented. In that case it is due to an itemize
or enumerate
which was not closed.
Go to the first, previous, next, last section, table of contents.