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.
print_char(+Char, +Out) is det[private]- Write Char in LaTeX format to Out. This escapes characters for LaTeX
where necessary.
- decompose_char(+Char) is semidet[private]
- Deal with diacritics. Relies on Unicode decomposition, where a
character with diacritics becomes the plain character, followed by a
composing diacritics mark.
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.