10.5 Including PlDoc in a LaTeX document

The LaTeX backend aims at producing quality paper documentation as well as integration of predicate description and Wiki files in LaTeX documents such as articles and technical reports. It is realised by the library doc_latex.pl.

The best practice for using the LaTeX backend is yet to be established. For now we anticipate processing a Wiki document saved in a .txt file using doc_latex/3 to produce either a simple complete LaTeX document or a partial document that is included into the the main document using the LaTeX \input command. Typically, this is best established by writing a Prolog Script that generates the required LaTeX document and call this from a Makefile. We give a simple example from PlDoc, creating this section from the wiki-file latex.txt below.

:- use_module(library(doc_latex)).
:- [my_program].

We generate latex.tex from latex.txt using this Makefile fragment:

.SUFFIXES: .txt .tex

.txt.tex:
        swipl -f script.pl \
            -g "doc_latex('$*.txt','$*.tex',[stand_alone(false)]),halt" \
            -t "halt(1)"

10.5.1 Predicate reference for the LaTeX backend

High-level access is provided by doc_latex/3, while more low level access is provided by the remaining predicates. Generated LaTeX depends on the style file pldoc.sty, which is a plain copy of pl.sty from the SWI-Prolog manual sources. The installation installs pldoc.sty in the pldoc subdirectory of the Prolog manual.

[det]doc_latex(+Spec, +OutFile, +Options)

Process one or more objects, writing the LaTeX output to OutFile. Spec is one of:

Name / Arity

Generate documentation for predicate

Name // Arity

Generate documentation for DCG rule

File

If File is a prolog file (as defined by user:prolog_file_type/2), process using latex_for_file/3, otherwise process using latex_for_wiki_file/3.

Typically Spec is either a list of filenames or a list of predicate indicators. Defined options are:

stand_alone(+Bool)

If true (default), create a document that can be run through LaTeX. If false, produce a document to be included in another LaTeX document.

public_only(+Bool)

If true (default), only emit documentation for exported predicates.

section_level(+Level)

Outermost section level produced. Level is the name of a LaTeX section command. Default is section.

summary(+File)

Write summary declarations to the named File.

modules(+List)

If [[Name/Arity]] needs to be resolved, search for the predicates in the given modules.

module(+Module)

Same as modules([Module]).

[det]latex_for_file(+File, +Out, +Options)

Generate a LaTeX description of all commented predicates in File, writing the LaTeX text to the stream Out. Supports the options stand_alone, public_only and section_level. See doc_latex/3 for a description of the options.

[det]latex_for_wiki_file(+File, +Out, +Options)

Write a LaTeX translation of a Wiki file to the steam Out. Supports the options stand_alone, public_only and section_level. See doc_latex/3 for a description of the options.

[det]latex_for_predicates(+PI:list, +Out, +Options)

Generate LaTeX for a list of predicate indicators. This does not produce the \begin{description}...\end{description} environment, just a plain list of \predicate, etc. statements. The current implementation ignores Options.