Generating and accessing manuals

Author(s): Manuel Hermenegildo, Jose F. Morales.

This section describes how to generate a manual (semi-)automatically from a set of source files using lpdoc and how to access it. See Writing documentation for details about writing proper lpdoc documentation.

Basic usage

lpdoc can be used directly from the command line, the Emacs editor, or from bundle manifest files (see bundles in the Ciao reference manual).

The following provides the basic command-line usage and the main command line options available when invoking lpdoc. The basic usage is:

lpdoc [Options] Input

where Input is the input file (a module or a documentation configuration file), and (optional) options specifying the selected target format (-t Format, as described in docformat/1), generation options --Name=Value (see doccfg for a complete list), as well as options to view or clean the generated documentation files.

Use lpdoc --help to see a complete list of the available command line options.

Generating manuals

Manuals can be generated from single module or from a collection of modules specified in a documentation configuration file (as described in Writing documentation) which defines how the documentation is structured, as well as options for its generation). For example, executing from the command line:

lpdoc file.pl

generates the documentation for file.pl in the default format (HTML for single modules or the default formats specified in docformat/1 for complex manuals), while the command:

lpdoc -t pdf file.pl

generates a PDF manual. The manuals generated will generally be written in the same directory as the input file, and they will have the same name but with the format as extension (i.e., in the example above it would be file.pdf). See output_dir/1 and output_name/1 options to change the location or name of the output).

To enable incremental documentation generation, lpdoc maintains intermediate files in a directory named file.cachedoc/. See Cleaning up for cleanup commands to remove both the intermediate and target files.

If you use the Emacs editor (highly recommended in all circumstances), then the simplest way to quickly generate a manual is by doing it from the Ciao Emacs mode (this mode comes with the Ciao distribution and is automatically installed with Ciao). The Ciao Emacs mode provides menu- and keyboard-binding driven facilities for generating a standalone document with the documentation corresponding to the file in the buffer being visited by Emacs. This is specially useful while modifying the source of a file, in order to check the output that will be produced when incorporating this file into a larger document.

Cleaning up documentation

lpdoc can also take care of tidying up the output of the documentation generation and the intermediate documenation generation files, using the following options:

  • --clean: deletes all intermediate files, but leaves the targets (i.e., the .pdf, .ascii, .html, etc. files), as well as all the generated .texic files.

  • --distclean: deletes all intermediate files and the generated .texic files, leaving only the targets (i.e., the .pdf, .ascii, .html, etc. files). This is the option normally used when building software distributions in which the manuals come ready made in the distribution itself and will not need to be generated during installation.

  • --docsclean: deletes all intermediate files and the generated targets, but leaves the .texic files. This option can be used in software distributions in which the manuals in the different formats will be generated during installation. This is generally more compact, but requires the presence of several tools, such as tex, Emacs, etc., in order to generate the manuals in the target formats during installation.

  • --realclean: performs a complete cleanup, deleting also the .texic files, i.e., it typically leaves only the original source files. This is is the most compact, but requires the presence of the tools mentioned above, the source files from which the manuals are generated and lpdoc in order to regenerate the manuals in the target formats during installation.

Accessing manuals

Once generated, the documentation can be viewed by opening the target output with an appriopriate viewer (e.g., Web browser for file.html/index.html, PDF viewer for file.pdf, etc.). For convenience lpdoc provides a generic view command:

lpdoc -t Format --view file.pl

which will open a default viewer application for the specified format and file.

For HTML documentation (specially when it is part of bundles) we encourage the use of the ciao-serve command, which starts a local HTTP server and provides access to dynamic documentation parts (such as search, and advanced index options).

Accessing info manuals

Generated .info files are meant to be viewed by the Emacs editor or by the standalone info application, both publicly available from the GNU project sites. To view the a generated info file from Emacs manually (i.e., before it is installed in a common area), type C-u M-x info. This will prompt for an info file name. Input the name of the info file generated by lpdoc (main.info) and Emacs will open the manual in info mode.

Automatic, direct on-line access to the information contained in the info file (e.g., going automatically to predicate descriptions by clicking on predicate names in programs in an Emacs buffer) can be easily implemented via existing .el packages such as word-help, written by Jens T. Berger Thielemann (<jensthi@ifi.uio.no>). word-help may already be in your Emacs distribution, but for convenience the file word-help.el, providing suitable initialization are included in the lpdoc library. A suitable interface for word-help is also provided by the ciao.el Emacs file that comes with the Ciao system distribution (i.e., if ciao.el is loaded it is not necessary to load or initialize word-help).

Accessing man manuals

The Unix man format manuals generated by lpdoc can be viewed using the Unix man command. In order for man to be able to locate the manuals, they should be copied to one of the subdirectories (e.g., /usr/local/man/manl) of one of the main man directories (in the previous case the main directory would be /usr/local/man). As usual, any directory can be used as as a man main directory, provided it is included in the environment variable MANPATH.