☰

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 supported IDEs (Emacs, VSC, the playground, etc.), or from bundle manifest files.

The following describes 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 as well as options to view or clean the generated documentation files.

Use lpdoc --help, Documentation configuration options and Admissible values for the documentation configuration options, or doccfg for a complete list of the available command line and configuration file options.

Generating manuals

Manuals can be generated from a single module, in which case no configuration file is needed. More complex documentation can be generated from a collection of modules, which are then specified in a documentation configuration file (generally SETTINGS.pl as described in Writing documentation). This file 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 input file can be in several formats including source .pl files and files containing only markup and/or markdown (.lpdoc and .md files). 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 the 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 documentation 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.

As mentioned before, you can generate manuals easily also from the the other supported IDEs such as VSC, the playground, etc. which all have buttons and menus for the task. Bundles can also be configured through their manifest files to generate manuals automatically from builder commands (ciao build --docs), see the documentation on bundles in the Ciao reference manual.

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 info-look, written by Ralph Schleicher (<rs@ralph-schleicher.de>). Support for this package can be found in info-look-ciao.el

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.

Accessing Active Logic Documents

Active Logic Documents (ALDs) are standard lpdoc documents that contain runnable examples and queries within them. These examples and queries run directly in the browser without requiring any installation, which greatly facilitates the sharing of ALDs without external dependiencies. The .html pages for source files containing such code are generated with lpdoc in the standard way, and they can be viewed in the same way, i.e.:

lpdoc file.pl

or

lpdoc file.md

and

lpdoc --view file.html/index.html

Generated with LPdoc using Ciao