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.
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.
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.
lpdoc can also take care of tidying up the output of the documentation generation and the intermediate documenation generation files, using the following options:
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.
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
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.