% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{Including PlDoc in a LaTeX document}

\label{sec:doclatex}

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 \file{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 \predref{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 \verb$\input$ command. Typically, this is best established by writing
a \textit{Prolog Script} that generates the required LaTeX document and call
this from a \textit{Makefile}. We give a simple example from PlDoc, creating
this section from the wiki-file \file{latex.txt} below.

\begin{code}
:- use_module(library(doc_latex)).
:- [my_program].
\end{code}

We generate latex.tex from \file{latex.txt} using this Makefile fragment:

\begin{code}
.SUFFIXES: .txt .tex

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

\subsubsection{Predicate reference for the LaTeX backend}

\label{sec:pldoc-latex-predicates}

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

\begin{description}
    \predicate[det]{doc_latex}{3}{+Spec, +OutFile, +Options}
Process one or more objects, writing the LaTeX output to
\arg{OutFile}. \arg{Spec} is one of:

\begin{description}
    \infixtermitem{\Sdiv}{\arg{Name}}{\arg{Arity}}
Generate documentation for predicate
    \infixtermitem{\Sidiv}{\arg{Name}}{\arg{Arity}}
Generate documentation for DCG rule
    \termitem{\arg{File}}{}
If \arg{File} is a prolog file (as defined by
\qpredref{user}{prolog_file_type}{2}), process using
\predref{latex_for_file}{3}, otherwise process using
\predref{latex_for_wiki_file}{3}.
\end{description}

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

\begin{description}
    \termitem{stand_alone}{+Bool}
If \const{true} (default), create a document that can be run
through LaTeX. If \const{false}, produce a document to be
included in another LaTeX document.
    \termitem{public_only}{+Bool}
If \const{true} (default), only emit documentation for
exported predicates.
    \termitem{section_level}{+Level}
Outermost section level produced. \arg{Level} is the
name of a LaTeX section command. Default is \const{section}.
    \termitem{summary}{+File}
Write summary declarations to the named \arg{File}.
    \termitem{modules}{+List}
If [[Name/Arity]] needs to be resolved, search for the
predicates in the given modules.
    \termitem{module}{+Module}
Same as \verb$modules([Module])$.
\end{description}

    \predicate[det]{latex_for_file}{3}{+File, +Out, +Options}
Generate a LaTeX description of all commented predicates in
\arg{File}, writing the LaTeX text to the stream \arg{Out}. Supports
the options \verb$stand_alone$, \verb$public_only$ and \verb$section_level$.
See \predref{doc_latex}{3} for a description of the options.

    \predicate[det]{latex_for_wiki_file}{3}{+File, +Out, +Options}
Write a LaTeX translation of a Wiki file to the steam \arg{Out}.
Supports the options \verb$stand_alone$, \verb$public_only$ and
\verb$section_level$. See \predref{doc_latex}{3} for a description of the
options.

    \predicate[det]{latex_for_predicates}{3}{+PI:list, +Out, +Options}
Generate LaTeX for a list of predicate indicators. This does
\textbf{not} produce the \Sneg{}begin\{description\}...\Sneg{}end\{description\}
environment, just a plain list of \Sneg{}predicate, etc. statements.
The current implementation ignores \arg{Options}.
\end{description}