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


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 section Installing lpdoc.

Other parts of this document provide:

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:

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: Other new functionality: Bug fixes and other minor improvements: (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: (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.