# doc_latex.pl -- PlDoc LaTeX backend

This module translates the Herbrand term from the documentation extracting module doc_wiki.pl into a LaTeX document for us with the pl.sty LaTeX style file. The function of this module is very similar to doc_html.pl, providing the HTML backend, and the implementation follows the same paradigm. The module can

• Generate LaTeX documentation for a Prolog file, both for printing and embedding in a larger document using latex_for_file/3.
• Generate LaTeX from a Wiki file using latex_for_wiki_file/3
• Generate LaTeX for a single predicate or a list of predicates for embedding in a document using latex_for_predicates/3.
author
- Jan Wielemaker
To be done
- See TODO
doc_latex(+Spec, +OutFile, +Options) is det
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 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]).
latex_for_file(+File, +Out, +Options) is det
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.
latex_tokens_for_file(+FileSpec, +Options)//[private]
latex_for_wiki_file(+File, +Out, +Options) is det
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.
latex_for_predicates(+PI:list, +Out, +Options) is det
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.
latex_special(String, Rest)// is semidet[private]
Deals with special sequences of symbols.
latex_arguments(+Args:list)// is det[private]
Write LaTeX command arguments. If an argument is of the form opt(Arg) it is written as [Arg], Otherwise it is written as {Arg}. Note that opt([]) is omitted. I think no LaTeX command is designed to handle an empty optional argument special.

During processing the arguments it asserts fragile/0 to allow is taking care of LaTeX fragile constructs (i.e. constructs that are not allows inside {...}).

latex_arg(+In)//[private]
Write a LaTeX argument. If we can, we will use a defined urldef_name/2.
short_list(+Content) is semidet[private]
True if Content describes the content of a dl or ul/ol list where each elemenent has short content.
latex_section(+Level, +Attributes, +Content)// is det[private]
Emit a LaTeX section, keeping track of the desired highest section level.
Arguments:
 Level - Desired level, relative to the base-level. Must be a non-negative integer.
delete_unsafe_label_chars(+LabelIn, -LabelOut)[private]
delete unsafe characters from LabelIn. Currently only deletes _, as this appears commonly through filenames, but cannot be handled through the LaTeX processing chain.
include(+File, +Type, +Options)// is det[private]
Called from [[File]].
file(+File, +Options)// is det[private]
Called from implicitely linked files. The HTML version creates a hyperlink. We just name the file.
predref(+PI)// is det[private]
Called from name/arity or name//arity patterns in the documentation.
tags(+Tags:list(Tag)) is det[private]
Emit tag list produced by the Wiki processor from the @keyword commands.
tag(+Tag, +Values:list)// is det[private]
Called from \tag(Name, Values) terms produced by doc_wiki.pl.
args(+Params:list) is det[private]
Called from \args(List) created by doc_wiki.pl. Params is a list of arg(Name, Descr).
file_title(+Title:list, +File, +Options)// is det[private]
Emit the file-header and manipulation buttons.
objects(+Objects:list, +Options)// is det[private]
Emit the documentation body.
need_mode(+Mode:atom, +Stack:list, -NewStack:list)// is det[private]
While predicates are part of a description list, sections are not and we therefore need to insert <dl>...</dl> into the output. We do so by demanding an outer environment and push/pop the required elements.
pred_dt(+Modes, +Class, Options)// is det[private]
Arguments:
 Modes - List as returned by process_modes/5. Class - One of privdef or pubdef.
To be done
- Determinism
anon_vars(+Term) is det[private]
Bind remaining variables in Term to '\$VAR'('_'), so they are printed as '_'.
Emit a predicate head. The functor is typeset as a span using class pred and the arguments and var using class arglist.
To be done
- Support determinism in operators
pred_attributes(+Options, -Attributes) is det[private]
Create a comma-separated list of predicate attributes, such as determinism, etc.
term(+Text, +Term, +Bindings)// is det[private]
Process the \term element as produced by doc_wiki.pl.
To be done
termitem(+Text, +Term, +Bindings)// is det[private]
Create a termitem or one of its variations.
latex_table(Attrs, Content)// is det[private]
Emit a table in LaTeX.
latex_summary(+Options)[private]
If Options contains summary(+File), write a summary of all documented predicates to File.
print_latex_tokens(+Tokens, +Out)[private]
Print primitive LaTeX tokens to Output
print_latex(+Out, +Text:atomic) is det[private]
Print Text, such that it comes out as normal LaTeX text.
max_nl(T0, T, M0, M)[private]
Remove leading sequence of nl(N) and return the maximum of it.
identifier(+Atom) is semidet[private]
True if Atom is (lower, alnum*).
urldef_name(?String, ?DefName)[private]
True if \DefName is a urldef for String. UrlDefs are LaTeX sequences that can be used to represent strings with symbols in fragile environments. Whenever a word can be expressed with a urldef, we will do this to enhance the robustness of the generated LaTeX code.
Load \urldef definitions from File and populate urldef_name/2. See pldoc.sty for details.