Introduction
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.
Overview of this document
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 Installing lpdoc.
Other parts of this document provide:
- Documentation on the syntax and meaning of the assertions that lpdoc uses (those defined in the Ciao assertions library [PBH97,PBH98,Bue98]). These include comment assertions (containing basically documentation text), formal assertions (containing properties), and combined assertions.
- Documentation on a basic set of properties, types, etc. which are predefined in the Ciao basic_props, regtypes, native_props, and meta_props libraries. These properties, and any others defined by the user or in other Ciao libraries, can be used in program assertions.
- Documentation on the formatting commands that can be embedded in comments.
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:
- The documentation for the autodoc automatic documentation library, which provides the main functionality of lpdoc.
- Documentation on the predicates that define the conversion formats used (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.
Some additional information on lpdoc can be found in [Her00].
lpdoc operation - source and target files
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 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 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 standalone 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 Enhancing the documentation being generated).
If the manual is generated from a single main file (i.e., component/1, 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 Installing a generated manual in a public area).
Additionally, lpdoc can provide some data from the main (prolog) documentation file. For this purpose the option getinfo can be used instead of specifying the format. This option reads the asked fields from getinfo variable (defined in SETTINGS.pl or via arguments with -d option). lpdoc will generate files with main documentation file-name as base-name, followed by one underscore, the asked field (got from getinfo), and the extension. The content of each of these files (so also the extension) is specified by getinfo_format, that can take the values html, ascii, texic. For example, to ask for the summary and the author fields from a prolog file called file.pl, with lpdoc documentation, we can execute the command lpdoc -d getinfo=[author,summary] getinfo. The files myfile_author.txt and myfile_summary.txt will be created. If also the option -d getinfo_format=html is used, the files will have html extension (and content).
