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
• lpdoc operation - source and target files
• lpdoc usage
• Version/Change Log (lpdoc)

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 section 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 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).

lpdoc usage

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.

Version/Change Log (lpdoc)

Version 1.9 (1999/7/8, 18:19:43 MEST)

In this release the name of the application has changed to lpdoc which was found more appropriate, since several formats are generated in addition to texi. The major changes are listed below. New commands:

• @begin{cartouche} and @end{cartouche} commands now supported.
• @foonote command now supported.
• New gmake htmlview command (makes a running netscape visit the generated html manual). Suggested by Per Cederberg.
• New gmake distclean command, intended for software distributions. Leaves the generated documents and eliminates all intermediate files (including .texic/.texi files).
• Adobe pdf format now supported as a valid target. Unfortunately, embedded .eps figures are not supported at this time in pdf output.
• The second argument of :- comment(hide,...). and :- comment(doinclude,...). declarations can now be a list of predicate names.
• A -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).
• Now typing just 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.
• Added a new filetype: part. This allows splitting large documents into parts, each of which groups a series of chapters.

Other new functionality:

• A style sheet can now be specified which allows modifying many characteristics of the html output (fonts, colors, background, ...) (thanks to Per Cederberg).
• Added limited support for changing page numbering (in SETTINGS file).
• The concept indexing commands (@index, @cindex, and @concept) now work somewhat differently, to make them consistent with other indexing commands.
• The old usage index is now called, more appropriately, global index. Correspondingly, changed things so that now every definition goes to the global index in addition to its definitional index.
• Imported files from module user are now documented separately.
• Now a warning is issued if characters unsupported by info are used in section names.
• Navigation in html docs was improved.
• The table of contents in printed manuals now contains entries for the individual descriptions of predicates, props, regtypes, declarations, etc. This can be shut off with the -shorttoc option.
• Made more silent in normal conditions: file inclusion is muted now unless -v option is selected.
• A single .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).
• Now, declarations are always documented as long as there is a decl assertion. Also, they are now documented in a separate section.

Bug fixes and other minor improvements:

• The directory containing html manual is now called BASENAME_html instead of just BASENAME, which was confusing.
• Now requesting building a .ps only does not leave a .dvi behind (useful for distributions).
• File names can now include the symbol _ even if they contain figures.
• TeX-related intermediate files are now cleaned up after each run in order to avoid clutter.
• Fixed -modes, which was broken since going to the new normalizer (was normalizer problem). Fixed problem with no documentation when only modes given.
• Fixed duplication of documentation for internal predicates when also exported.
• Minor formatting problem when no documentation nor definition found for a regtype fixed.
• Determining exports, imports, etc. now done solely by calls to c_itf library (and, thus, synchronized with ciaoc compiler).

(Manuel Hermenegildo)

Version 1.8 (1999/3/24, 21:15:33 MET)

This version completes the port to using the ciao 0.8 modular assertion processing library. In addition, it includes the following improvements:

• Now, if the name of a file being documented ends in _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).
• It is now possible to declare (via a 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).
• Separated generation of the manuals from their installation. I.e., 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.
• New -v option allows using quieter by default operation when not debugging.
• New option -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.
• New option -noisoline makes the textual explanation of the iso/1 property not appear in the description of the usage (but the * ISO * symbol does appear)
• Two new options, '-nosysmods' and '-noengmods', selectively avoid listing the system or engine libraries used.
• If there is no declaration for a predicate, now a line is output with the name and arity and a simple comment saying that there is no further documentation available (this has the great advantage that then it goes in the index, and, for example in ciao, they get added to completion commands!).
• Now, if a property or regtype declaration has no textual comment, the actual definition is given (first level only) in the place where it is documented, and a simple generic message where it is used.
• Added @noindent and @iso commands.
• Nicer spacing now when printing predicate names which are operators, as well as modes, etc.
• Reporting of versions in libraries has been improved: now both the global version and the last version in which the library itself was changed are reported.
• Exported new declarations also documented now for include-type files.
• A module is now documented even if exports nothing at all.
• Engine modules used now documented even if no other modules used (was a reported bug).
• Fixed indexing of names containing @ etc. for newer versions of texinfo.
• Tabs in verbatim modes now converted to a number of spaces (8). Not perfect, but produces better output than leaving the tabs in.
• Tex is now run in 'nonstopmode' which means it will typically not stop if there are minor errors (but some errors may go unnoticed...).
• The full path of the version maintenance directory is now computed (correctly) using the directory of the .pl file being documented as base.
• Notices for missing subtitle, copyright, and summary now only given from main file and not for components.
• Added special handling of regtype and generalized it to handle some props specially if there is a certain comp property present.

(Manuel Hermenegildo)

Version 1.7 (1998/12/2, 17:43:50 MET)

Major port to use the ciao 0.8 modular assertion processing library. (Manuel Hermenegildo)

Version 1.6 (1998/9/8, 12:49:26 MEST)

Added support for inserting images (.eps files) in text via @image command, email addresses via @email command, and url references via @uref command. Unix 'man' output much improved. Also, it now includes a usage section. The correspoding text must be given in a string contained in the first argument of a fact of the 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)

Version 1.5 (1998/8/23, 20:30:32 EST)

Now supporting a @cite command (YES!). It automatically accesses the bib entries in .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)

Version 1.4 (1998/8/4, 19:10:35 MET DST)

The set of paths defined in 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)

Version 1.3 (1998/7/10, 16:35:2 MET DST)

Exports are now listed in the chapter header separated by kind (pred, types, properties, ...). The list of other modules used by a module is now separated in the chapter header into User and System modules (controlled by two sets of paths in SETTINGS). New hide option of comment/2 decl prevents an exported predicate from being included in the documentation: :- comment(hide,p/3). (Manuel Hermenegildo)

Version 1.2 (1998/6/4, 9:12:19 MET DST)

Major overall improvements... (Manuel Hermenegildo)

Version 1.1 (1998/3/31)

Incorporated autodoc and autodoformats library to source in order to make distribution standalone. Improvements to installation and documentation. Makefiles now also install documentation in public areas and produce global indices. Several documents can cohexist in the same installation directory. (Manuel Hermenegildo)

Version 1.0 (1998/2/24)

First Ciao-native distribution, with installation. (Manuel Hermenegildo)

Version 0.9 (1998/2/24)

Intermediate version, preparing for first major release. Modified Makefile and SETTINGS to handle installation of manuals. (Manuel Hermenegildo)

Version 0.6 (1998/2/10)

Added new indices and options, as well as more orthogonal handling of files. (Manuel Hermenegildo)

Version 0.4 (1998/2/24)

Added support for nroff -m formatting (e.g., for man pages). Added support for optional selection of indices to be generated. Added support for reexported predicates. Added (low level) ascii format. Added option handling (-nobugs -noauthors -noversion -nochangelog -nopatches -modes and -headprops ...). -literalprops. Fixed presentation when there are multiple kinds of assertions. Better error checking for includefact/includedef. (Manuel Hermenegildo)

Version 0.3 (1998/2/10)

Changed file reader to use Ciao native builtins. As a result, syntax files and full Ciao syntax now supported. Major reorganization of the code to make formatting more orthogonal. Now applications and libraries can be components or main files, standalone or with components interchangeably. @includefact, new predicate types, used libraries now precisely detected, docinclude option. (Manuel Hermenegildo)

Version 0.2 (1997/12/16)

Ported to native ciao. Version handling, selection of indices, @include. Added generation of an html brief description for a global index. Added unix manual page generation. Added support for specifying library paths. -l option for htmlindex and man. Installation improved: now all files for one application in the same directory. (Manuel Hermenegildo)

Version 0.1 (1997/7/30)

First official version (major rewrite from several previous prototypes, autodocumented!). (Manuel Hermenegildo)

Version 0.0 (1996/10/10)

First prototype.

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