lpdoc is an automatic program documentation generator for (C)LP systems.
lpdoc generates a reference manual automatically from one or more source files for a logic program (including ISO-
Ciao [Bue95], many
CLP [JM94] systems, ...). It is particularly useful for documenting library modules, for which it automatically generates a description of the module interface. However,
lpdoc can also be used quite successfully to document full applications and to generate nicely formatted plain ASCII "readme" files. A fundamental advantage of using
lpdoc to document programs is that it is much easier to maintain a true correspondence between the program and its documentation, and to identify precisely to what version of the program a given printed manual corresponds.
This first part of the document provides basic explanations on how to generate a manual from a set of files that already contain
comments. Examples are given using the files in the
examples directory provided with the
These instructions assume that
lpdoc (at least the executable and the library) is installed somewhere in your system. Installation instructions
can be found in section Installing lpdoc.
Other parts of this document provide:
lpdocuses (those defined in the
assertionslibrary [PBH97,PBH98,Bue98]). These include comment assertions (containing basically documentation text), formal assertions (containing properties), and combined assertions.
meta_propslibraries. These properties, and any others defined by the user or in other
Ciaolibraries, can be used in program assertions.
This document is also an
internals manual, providing information on how the different internal parts of
lpdoc are connected, which can be useful if new capabilities need to be added to the system or its libraries are used for other purposes. To this end, the document also provides:
autodocautomatic documentation library, which provides the main functionality of
texinfo, and others), and which are in the
All of the above have been generated automatically from the assertions in the corresponding sources and can also be seen as examples of the use of
Some additional information on
lpdoc can be found in [Her00].
The main input used by
lpdoc in order to generate a manual are
Prolog source files. Basically,
lpdoc generates a file in the GNU
texinfo format (with a
.texi ending) for each
Prolog file (see "The GNU Texinfo Documentation System" manual for more info on this format). The
Prolog files must have a
.pl file does not define the predicates
main/1, it is assumed to be a
library and it is documented as such: the
.texi file generated will contain information on the interface (e.g., the predicates exported by the file, the name of the module and usage if it is a module, etc.), in addition to any other machine readable comments included in the file (see section Enhancing the documentation being generated). If, on the contrary, the file defines the predicates
main/1, it is assumed to be an
application and no description of the interface is generated (see section Some usage tips).
files written directly in
texinfo can also be used as input files for
lpdoc. These files must have a
.src (instead of
.texi ) ending. This is needed to distinguish them from any automatically generated
.texi files. Writing files directly in
texinfo has the disadvantage that it may be difficult to adhere to all the conventions used by
lpdoc. For example, these files will be typically used as chapters and must be written as such. Also, the set of indices used must be the same that
lpdoc is generating automatically. Finally, no bibliographic citations can be used. Because of this, and because in the future
lpdoc may be able to generate documentation in formats other than
texinfo directly (in which case these files would not be useful), writing files in
texinfo directly is discouraged. This facility was added mainly to be able to reuse parts of manuals which were already written in
texinfo. Note that if a stand-alone file needs to be written (i.e., a piece of documentation that is not associated to any
.pl file) it can always be written as a "dummy"
.pl file (i.e., one that is not used as code), but which contains machine readable comments).
A manual can be generated either from a single source file (
.src) or from a set of source files. In the latter case, then one of these files should be chosen to be the
main file, and the others will be the
component files. The main file is the one that will provide the title, author, date, summary, etc. to the entire document. In principle, any set of source files can be documented, even if they contain no assertions or comments. However, the presence of these will greatly improve the documentation (see section Enhancing the documentation being generated).
If the manual is generated from a single main file (i.e.,
COMPONENTS, defined below, is empty), then the document generated will be a flat document containing no chapters. If the manual is generated from a main file and one or more components, then the document will contain chapters. The comments in the main file will be used to generate the introduction, while each of the component files will be used to generate a separate chapter. The contents of each chapter will be controlled by the contents of the corresponding component file.
As mentioned before,
lpdoc typically generates
texinfo files. From the
lpdoc can generate printed and on-line manuals in several formats (
info, etc.) automatically, using different (publicly available) packages. Documentation in some other formats (e.g.,
manl pages) can be generated directly by
lpdoc, selecting the appropriate options (see below).
lpdoc can also generate directly includes generating (parts of) a
master index of documents which can be placed in an installation directory and which will provide pointers to the individual manuals generated. Using this feature,
lpdoc can maintain global
info documentation sites automatically (see section Installing a generated manual in a public area).
The following provides the different command line options available when invoking
lpdoc. This description is intended only for advanced users which might like to use
lpdoc in custom applications. Note that the normal way to use
lpdoc is by setting parameters in a
SETTINGS file (see section Generating a manual), and
lpdoc will be invoked automatically with the correct options by the
Makefile provided with the distribution.
lpdoc -help Print this help message. lpdoc [MiscOpts] [-l <path1> ... <pathN> ] [-s <path1> ... <pathN> ] [-i <i1> ... <iN> ] [-u path_aliases_file ] [-p start_page ] [-t paper_type ] -main <main> [ <f1.texic> ... <fN.texic> ] Generate the main .texic file for main application file <file> and whose component .texic files are <file1.texic>... <fileN.texic>. The optional arguments preceded by -l are the directory paths where files used (via use_module/1) by the file being documented (main in this case) can be found (-s is similar, but putting paths in the -s list flags that such paths are 'system' paths). They are treated in the same way as 'library paths'. The optional arguments preceded by -i are the names of the indices which should be generated. The special index name 'all' results in all indices being generated. -u indicates a Prolog file with defi- nitions to be loaded. lpdoc [MiscOpts] [-l <path1> ... <pathN> ] [-s <path1> ... <pathN> ] [-i <idx1> ... <idxN> ] [-u path_aliases_file ] -component <file.pl> Generate a .texic file for module <file.pl>. The optional arguments are as above. lpdoc [MiscOpts] [-l <path1> ... <pathN> ] [-s <path1> ... <pathN> ] [-u path_aliases_file ] -htmlindex <main> Generate (part of an) html file suitable for including in an html page. lpdoc [MiscOpts] [-l <path1> ... <pathN> ] [-s <path1> ... <pathN> ] [-u path_aliases_file ] -man <main> Generate a man page. lpdoc [MiscOpts] [-l <path1> ... <pathN> ] [-s <path1> ... <pathN> ] [-u path_aliases_file ] -infoindex <main> Generate an info directory entry suitable for including in an info directory.
lpdocwhich was found more appropriate, since several formats are generated in addition to texi. The major changes are listed below. New commands:
gmake htmlviewcommand (makes a running
netscapevisit the generated html manual). Suggested by Per Cederberg.
gmake distcleancommand, intended for software distributions. Leaves the generated documents and eliminates all intermediate files (including
.epsfigures are not supported at this time in pdf output.
:- comment(doinclude,...).declarations can now be a list of predicate names.
-uFile option is now supported so that a file including, e.g., path alias definitions can be included (this has the same functionality as the
gmakedoes nothing. In order to do something at least one target should be specified. This was necessary so that recursive invocations with empty arguments did nothing.
part. This allows splitting large documents into parts, each of which groups a series of chapters.
userare now documented separately.
-voption is selected.
.texifile is now constructed (by grouping the
.texicfiles generated for all components) in which the references and menus are resolved. This has the advantage that the process of resolving references and menus has now been sped up very significantly. Also,
texiis now a valid target (perhaps useful for distributions). The generated files now have
declassertion. Also, they are now documented in a separate section.
_htmlinstead of just BASENAME, which was confusing.
_even if they contain figures.
TeX-related intermediate files are now cleaned up after each run in order to avoid clutter.
-modes, which was broken since going to the new normalizer (was normalizer problem). Fixed problem with no documentation when only modes given.
c_itflibrary (and, thus, synchronized with
_docpart is left out when referring to the file in the documentation (useful if one would like to place the documentation declarations in different file).
comment/2declaration) the intended use of a file which is not a module (i.e. a package, user, or include file), which results in correct documentation of operator definitions, new declarations, etc. The declaration is only needed for 'user' files (i.e., files to be loaded with
gmake installnow does not force a
gmake all, which has to be done by hand. This was necessary to ensure correct installation of distributed manuals, even if modification dates are changed during installation. Previously, in some cases generation was triggered unnecessarily.
-voption allows using quieter by default operation when not debugging.
-propmodsmakes the name of the module in which a property is defined appear in front of the property in the places where the property is used.
-noisolinemakes the textual explanation of the
iso/1property not appear in the description of the usage (but the * ISO * symbol does appear)
.plfile being documented as base.
usage_message/1predicate which appears in the program. Also, formatting of 'man' pages has been greatly improved. A new 'ascii' format is now supported: a simple minded ascii manual (basically, an info file without pointers). (Manuel Hermenegildo)
bibtex) and produces a 'References' appendix. @cite can be used in the text strings exactly as ite in LaTeX. The set of bib files to be used is given in the
SETTINGSfile. Defining the type of version maintenance that should be performed by the
emacsciao.el mode (i.e., whether version numbers are in a given directory or in the file itself) is controlled now via a standard
commment/2declaration. You should now write a declaration such as: :- comment(version_maintenance,dir('../version')). to state that control info is kept in directory
../version. This has the advantage that it is shorter than the previous solution and that lpdoc can read this info easily. Using this guarantees that the version numbers of the manuals always concide with those of the software. Generation of indices of manuals (.htmlbullet files): if several manuals are installed in the same directory, an index to them is now generated at the beginning of the html cover page describing the directory. (Manuel Hermenegildo)
SETTINGSfor finding the source files are now also used to find 'included' files. As a result, full path is not needed any more in, e.g, @include command. New @ref command which can be used to refer to chapeter, sections, subsections, etc.. Support for recent minor changes in assertion format, including '#' as comment separator. Used modules are now separated in documentation (in the interface description) by type (user, system, engine...). Supports new 'hide' option in comments, to prevent an exported predicate from being documented. This is useful for example for avoiding mentioning in the documentation multifile predicates which are not intended to be modified by the user. (Manuel Hermenegildo)
SETTINGS). New hide option of comment/2 decl prevents an exported predicate from being included in the documentation:
:- comment(hide,p/3). (Manuel Hermenegildo)
Makefiles now also install documentation in public areas and produce global indices. Several documents can cohexist in the same installation directory. (Manuel Hermenegildo)
SETTINGSto handle installation of manuals. (Manuel Hermenegildo)
docincludeoption. (Manuel Hermenegildo)
Go to the first, previous, next, last section, table of contents.