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.

 nopredref(+PI)//[private]

Called from name/arity.

 flagref(+Flag)//[private]

Reference to a Prolog flag

 cite(+Citations) is det[private]

Emit a \cite{Citations} command

 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_header(+File, +Options)// is det[private]

Create the file header.

 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]

Emit the \predicate{}{}{} header.

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 '_'.

 pred_head(+Term, Options) is det[private]

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

- Properly merge with pred_head//1

 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.

 auto_par(+Content) is semidet[private]

True when cell Content is a good candidate for auto-wrapping.

 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_urldefs[private]

 load_urldefs(+File)[private]

Load \urldef definitions from File and populate urldef_name/2. See pldoc.sty for details.