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-
Prolog
[DEDC96],
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
assertions and
comments. Examples are given using the files in the examples
directory provided with the
lpdoc
distribution.
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:
lpdoc
uses (those defined in the
CIAO
assertions
library [PBH97,PBH98,Bue98]).
CIAO
basicprops
library).
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:
autodoc
automatic documentation library, which provides the main functionality of
lpdoc
.
texinfo
, and others), and which are in the
autodocformats
library.
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
lpdoc
.
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
ending.
If the .pl
file does not define the predicates
main/0
or
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/0
or
main/1
, it is assumed to be an
application and no description of the interface is generated (see section Some usage tips).
If needed,
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 (.pl
or .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
texinfo
files,
lpdoc
can generate printed and on-line manuals in several formats (dvi
, ps
, ascii
, html
, 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
html
and/or
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 ] -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 thesepaths 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. 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.
lpdoc
)lpdoc
which was found more appropriate, since several formats are generated in addition to texi. The major changes are listed below.
New commands:
gmake htmlview
command (makes a running
netscape
visit the generated html manual). Suggested by Per Cederberg.
gmake distclean
command, intended for software distributions. Leaves the generated documents and eliminates all intermediate files (including .texic
/.texi
files).
pdf
format now supported as a valid target. Unfortunately, embedded .eps
figures are not supported at this time in pdf output.
:- comment(hide,...).
and :- comment(doinclude,...).
declarations can now be a list of predicate names.
-u
File option is now supported so that a file including, e.g., path alias definitions can be included (this has the same functionality as the -u
option in
ciaoc
).
gmake
does 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.
SETTINGS
file).
user
are now documented separately.
-shorttoc
option.
-v
option is selected.
.texi
file is now constructed (by grouping the .texic
files 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, texi
is now a valid target (perhaps useful for distributions). The generated files now have texic
(texinfo component).
decl
assertion. Also, they are now documented in a separate section.
_html
instead 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_itf
library (and, thus, synchronized with
ciaoc
compiler).
_doc
, the _doc
part 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/2
declaration) 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
ensure_loaded/1
).
gmake install
now 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.
-v
option allows using quieter by default operation when not debugging.
-propmods
makes 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.
-noisoline
makes the textual explanation of the
iso/1
property not appear in the description of the usage (but the * ISO * symbol does appear)
.pl
file being documented as base.
usage_message/1
predicate 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)
.bib
files (using
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 SETTINGS
file.
Defining the type of version maintenance that should be performed by the
emacs
ciao.el mode (i.e., whether version numbers are in a given directory or in the file itself) is controlled now via a standard
commment/2
declaration. 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)
SETTINGS
for 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)
Makefile
s now also install documentation in public areas and produce global indices. Several documents can cohexist in the same installation directory. (Manuel Hermenegildo)
Makefile
and SETTINGS
to handle installation of manuals. (Manuel Hermenegildo)
docinclude
option. (Manuel Hermenegildo)
Go to the first, previous, next, last section, table of contents.