.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LaTeXML::Package 3pm"
.TH LaTeXML::Package 3pm "2014-05-02" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"LaTeXML::Package" \- Support for package implementations and document customization.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This package defines and exports most of the procedures users will need
to customize or extend LaTeXML. The LaTeXML implementation of some package
might look something like the following, but see the
installed \f(CW\*(C`LaTeXML/Package\*(C'\fR directory for realistic examples.
.PP
.Vb 10
\& use LaTeXML::Package;
\& use strict;
\& #
\& # Load "anotherpackage"
\& RequirePackage(\*(Aqanotherpackage\*(Aq);
\& #
\& # A simple macro, just like in TeX
\& DefMacro(\*(Aq\ethesection\*(Aq, \*(Aq\ethechapter.\eroman{section}\*(Aq);
\& #
\& # A constructor defines how a control sequence generates XML:
\& DefConstructor(\*(Aq\ethanks{}\*(Aq, "#1");
\& #
\& # And a simple environment ...
\& DefEnvironment(\*(Aq{abstract}\*(Aq,\*(Aq#body\*(Aq);
\& #
\& # A math symbol \eReal to stand for the Reals:
\& DefMath(\*(Aq\eReal\*(Aq, "\ex{211D}", role=>\*(AqID\*(Aq);
\& #
\& # Or a semantic floor:
\& DefMath(\*(Aq\efloor{}\*(Aq,\*(Aq\eleft\elfloor#1\eright\erfloor\*(Aq);
\& #
\& # More esoteric ...
\& # Use a RelaxNG schema
\& RelaxNGSchema("MySchema");
\& # Or use a special DocType if you have to:
\& # DocType("rootelement",
\& # "\-//Your Site//Your DocType",\*(Aqyour.dtd\*(Aq,
\& # prefix=>"http://whatever/");
\& #
\& # Allow sometag elements to be automatically closed if needed
\& Tag(\*(Aqprefix:sometag\*(Aq, autoClose=>1);
\& #
\& # Don\*(Aqt forget this, so perl knows the package loaded.
\& 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
To provide a LaTeXML-specific version of a LaTeX package \f(CW\*(C`mypackage.sty\*(C'\fR
or class \f(CW\*(C`myclass.cls\*(C'\fR (so that eg. \f(CW\*(C`\eusepackage{mypackage}\*(C'\fR works),
you create the file \f(CW\*(C`mypackage.sty.ltxml\*(C'\fR or \f(CW\*(C`myclass.cls.ltxml\*(C'\fR
and save it in the searchpath (current directory, or one of the directories
given to the \-\-path option, or possibly added to the variable \s-1SEARCHPATHS\s0).
Similarly, to provide document-specific customization for, say, \f(CW\*(C`mydoc.tex\*(C'\fR,
you would create the file \f(CW\*(C`mydoc.latexml\*(C'\fR (typically in the same directory).
However, in the first cases, \f(CW\*(C`mypackage.sty.ltxml\*(C'\fR are loaded \fIinstead\fR of
\&\f(CW\*(C`mypackage.sty\*(C'\fR, while a file like \f(CW\*(C`mydoc.latexml\*(C'\fR is loaded in \fIaddition\fR to
\&\f(CW\*(C`mydoc.tex\*(C'\fR.
In either case, you'll \f(CW\*(C`use LaTeXML::Package;\*(C'\fR to import the various declarations
and defining forms that allow you to specify what should be done with various
control sequences, whether there is special treatment of certain document elements,
and so forth. Using \f(CW\*(C`LaTeXML::Package\*(C'\fR also imports the functions and variables
defined in LaTeXML::Global, so see that documentation as well.
.PP
Since LaTeXML attempts to mimic TeX, a familiarity with TeX's processing
model is also helpful. Additionally, it is often useful, when implementing
non-trivial behaviour, to think TeX-like.
.PP
Many of the following forms take code references as arguments or options.
That is, either a reference to a defined sub, \f(CW\*(C`\e&somesub\*(C'\fR, or an
anonymous function sub\ {\ ...\ }. To document these cases, and the
arguments that are passed in each case, we'll use a notation like
\&\s-1CODE\s0($token,..).
.SS "Control Sequences"
.IX Subsection "Control Sequences"
Many of the following forms define the behaviour of control sequences.
In TeX you'll typically only define macros. In LaTeXML, we're
effectively redefining TeX itself, so we define macros as well as primitives,
registers, constructors and environments. These define the behaviour
of these commands when processed during the various phases of LaTeX's
immitation of TeX's digestive tract.
.PP
The first argument to each of these defining forms (\f(CW\*(C`DefMacro\*(C'\fR, \f(CW\*(C`DefPrimive\*(C'\fR, etc)
is a \fIprototype\fR consisting of the control sequence being defined along with
the specification of parameters required by the control sequence.
Each parameter describes how to parse tokens following the control sequence into
arguments or how to delimit them. To simplify coding and capture common idioms
in TeX/LaTeX programming, latexml's parameter specifications are more expressive
than TeX's \f(CW\*(C`\edef\*(C'\fR or LaTeX's \f(CW\*(C`\enewcommand\*(C'\fR. Examples of the prototypes for
familiar TeX or LaTeX control sequences are:
.PP
.Vb 3
\& DefConstructor(\*(Aq\eusepackage[]{}\*(Aq,...
\& DefPrimitive(\*(Aq\emultiply Variable SkipKeyword:by Number\*(Aq,..
\& DefPrimitive(\*(Aq\enewcommand OptionalMatch:* {Token}[]{}\*(Aq, ...
.Ve
.PP
\fIControl Sequence Parameters\fR
.IX Subsection "Control Sequence Parameters"
.PP
The general syntax for parameter for a control sequence is something like
.PP
.Vb 1
\& OpenDelim? Modifier? Type (: value (| value)* )? CloseDelim?
.Ve
.PP
The enclosing delimiters, if any, are either {} or [], affect the way the
argument is delimited. With {}, a regular TeX argument (token or sequence
balanced by braces) is read before parsing according to the type (if needed).
With [], a LaTeX optional argument is read, delimited by (non-nested) square brackets.
.PP
The modifier can be either \f(CW\*(C`Optional\*(C'\fR or \f(CW\*(C`Skip\*(C'\fR, allowing the argument to
be optional. For \f(CW\*(C`Skip\*(C'\fR, no argument is contributed to the argument list.
.PP
The shorthands {} and [] default the type to \f(CW\*(C`Plain\*(C'\fR and reads a normal
TeX argument or LaTeX default argument with no special parsing.
.PP
The general syntax for parameter specification is
.PP
.Vb 10
\& {} reads a regular TeX argument, a sequence of
\& tokens delimited by braces, or a single token.
\& {spec} reads a regular TeX argument, then reparses it
\& to match the given spec. The spec is parsed
\& recursively, but usually should correspond to
\& a single argument.
\& [spec] reads an LaTeX\-style optional argument. If the
\& spec is of the form Default:stuff, then stuff
\& would be the default value.
\& Type Reads an argument of the given type, where either
\& Type has been declared, or there exists a ReadType
\& function accessible from LaTeXML::Package::Pool.
\& Type:value, or Type:value1:value2... These forms
\& pass additional Tokens to the reader function.
\& OptionalType Similar to Type, but it is not considered
\& an error if the reader returns undef.
\& SkipType Similar to OptionalType, but the value returned
\& from the reader is ignored, and does not occupy a
\& position in the arguments list.
.Ve
.PP
The predefined argument types are as follows.
.ie n .IP """Plain"", ""Semiverbatim""" 4
.el .IP "\f(CWPlain\fR, \f(CWSemiverbatim\fR" 4
.IX Item "Plain, Semiverbatim"
Reads a standard TeX argument being either the next token, or if the
next token is an {, the balanced token list. In the case of \f(CW\*(C`Semiverbatim\*(C'\fR,
many catcodes are disabled, which is handy for \s-1URL\s0's, labels and similar.
.IX Xref "Plain Semiverbatim"
.ie n .IP """Token"", ""XToken""" 4
.el .IP "\f(CWToken\fR, \f(CWXToken\fR" 4
.IX Item "Token, XToken"
Read a single TeX Token. For \f(CW\*(C`XToken\*(C'\fR, if the next token is expandable,
it is repeatedly expanded until an unexpandable token remains, which is returned.
.IX Xref "Token XToken"
.ie n .IP """Number"", ""Dimension"", ""Glue"" or ""MuGlue""" 4
.el .IP "\f(CWNumber\fR, \f(CWDimension\fR, \f(CWGlue\fR or \f(CWMuGlue\fR" 4
.IX Item "Number, Dimension, Glue or MuGlue"
Read an Object corresponding to Number, Dimension, Glue or MuGlue,
using TeX's rules for parsing these objects.
.IX Xref "Number Dimension Glue MuGlue"
.ie n .IP """Until:""\fImatch\fR, ""XUntil:""\fImatch\fR" 4
.el .IP "\f(CWUntil:\fR\fImatch\fR, \f(CWXUntil:\fR\fImatch\fR" 4
.IX Item "Until:match, XUntil:match"
Reads tokens until a match to the tokens \fImatch\fR is found, returning
the tokens preceding the match. This corresponds to TeX delimited arguments.
For \f(CW\*(C`XUntil\*(C'\fR, tokens are expanded as they are matched and accumulated.
.IX Xref "Until XUntil"
.ie n .IP """UntilBrace""" 4
.el .IP "\f(CWUntilBrace\fR" 4
.IX Item "UntilBrace"
Reads tokens until the next open brace \f(CW\*(C`{\*(C'\fR.
This corresponds to the peculiar TeX construct \f(CW\*(C`\edef\efoo#{...\*(C'\fR.
.IX Xref "UntilBrace"
.ie n .IP """Match:""\fImatch(|match)*\fR, ""Keyword:""\fImatch(|match)*\fR" 4
.el .IP "\f(CWMatch:\fR\fImatch(|match)*\fR, \f(CWKeyword:\fR\fImatch(|match)*\fR" 4
.IX Item "Match:match(|match)*, Keyword:match(|match)*"
Reads tokens expecting a match to one of the token lists \fImatch\fR,
returning the one that matches, or undef.
For \f(CW\*(C`Keyword\*(C'\fR, case and catcode of the \fImatches\fR are ignored.
Additionally, any leading spaces are skipped.
.IX Xref "Match Keyword"
.ie n .IP """Balanced""" 4
.el .IP "\f(CWBalanced\fR" 4
.IX Item "Balanced"
Read tokens until a closing }, but respecting nested {} pairs.
.IX Xref "Balanced"
.ie n .IP """BalancedParen""" 4
.el .IP "\f(CWBalancedParen\fR" 4
.IX Item "BalancedParen"
Read a parenthesis delimited tokens, but does \fInot\fR balance any nested parentheses.
.IX Xref "BalancedParen"
.ie n .IP """Undigested"", ""Digested"", ""DigestUntil:""\fImatch\fR" 4
.el .IP "\f(CWUndigested\fR, \f(CWDigested\fR, \f(CWDigestUntil:\fR\fImatch\fR" 4
.IX Item "Undigested, Digested, DigestUntil:match"
These types alter the usual sequence of tokenization and digestion in separate stages (like TeX).
A \f(CW\*(C`Undigested\*(C'\fR parameter inhibits digestion completely and remains in token form.
A \f(CW\*(C`Digested\*(C'\fR parameter gets digested until the (required) opening { is balanced; this is
useful when the content would usually need to have been protected in order to correctly deal
with catcodes. \f(CW\*(C`DigestUntil\*(C'\fR digests tokens until a token matching \fImatch\fR is found.
.IX Xref "Undigested Digested"
.ie n .IP """Variable""" 4
.el .IP "\f(CWVariable\fR" 4
.IX Item "Variable"
Reads a token, expanding if necessary, and expects a control sequence naming
a writable register. If such is found, it returns an array of the corresponding
definition object, and any arguments required by that definition.
.IX Xref "Variable"
.ie n .IP """SkipSpaces"",""Skip1Space""" 4
.el .IP "\f(CWSkipSpaces\fR,\f(CWSkip1Space\fR" 4
.IX Item "SkipSpaces,Skip1Space"
Skips one, or any number of, space tokens, if present, but contributes nothing to the argument list.
.IX Xref "SkipSpaces Skip1Space"
.PP
\fIControl of Scoping\fR
.IX Subsection "Control of Scoping"
.PP
Most defining commands accept an option to control how the definition is stored,
\&\f(CW\*(C`scope=>$scope\*(C'\fR, where \f(CW$scope\fR can be c<'global'> for global definitions,
\&\f(CW\*(Aqlocal\*(Aq\fR, to be stored in the current stack frame, or a string naming a \fIscope\fR.
A scope saves a set of definitions and values that can be activated at a later time.
.PP
Particularly interesting forms of scope are those that get automatically activated
upon changes of counter and label. For example, definitions that have
\&\f(CW\*(C`scope=>\*(Aqsection:1.1\*(Aq\*(C'\fR will be activated when the section number is \*(L"1.1\*(R",
and will be deactivated when the section ends.
.PP
\fIMacros\fR
.IX Subsection "Macros"
.ie n .IP """DefMacro($prototype,$string | $tokens | $code,%options);""" 4
.el .IP "\f(CWDefMacro($prototype,$string | $tokens | $code,%options);\fR" 4
.IX Item "DefMacro($prototype,$string | $tokens | $code,%options);"
Defines the macro expansion for \f(CW$prototype\fR; a macro control sequence that is
expanded during macro expansion time (in the LaTeXML::Core::Gullet). If a \f(CW$string\fR is supplied, it will be
tokenized at definition time. Any macro arguments will be substituted for parameter
indicators (eg #1) at expansion time; the result is used as the expansion of
the control sequence.
.IX Xref "DefMacro"
.Sp
If defined by \f(CW$code\fR, the form is \f(CW\*(C`CODE($gullet,@args)\*(C'\fR and it
must return a list of LaTeXML::Core::Token's.
.Sp
DefMacro options are
.RS 4
.IP "scope=>$scope" 4
.IX Item "scope=>$scope"
See \*(L"Control of Scoping\*(R".
.IP "locked=>boolean" 4
.IX Item "locked=>boolean"
Whether this definition is locked out of changes in the TeX sources.
.RE
.RS 4
.Sp
Examples:
.Sp
.Vb 2
\& DefMacro(\*(Aq\ethefootnote\*(Aq,\*(Aq\earabic{footnote}\*(Aq);
\& DefMacro(\*(Aq\etoday\*(Aq,sub { ExplodeText(today()); });
.Ve
.RE
.ie n .IP """DefMacroI($cs,$paramlist,$string | $tokens | $code,%options);""" 4
.el .IP "\f(CWDefMacroI($cs,$paramlist,$string | $tokens | $code,%options);\fR" 4
.IX Item "DefMacroI($cs,$paramlist,$string | $tokens | $code,%options);"
Internal form of \f(CW\*(C`DefMacro\*(C'\fR where the control sequence and parameter list
have already been separated; useful for definitions from within code.
Also, slightly more efficient for macros with no arguments (use \f(CW\*(C`undef\*(C'\fR for
\&\f(CW$paramlist\fR), and useful for obscure cases like defining \f(CW\*(C`\ebegin{something*}\*(C'\fR
as a Macro.
.IX Xref "DefMacroI"
.PP
\fIConditionals\fR
.IX Subsection "Conditionals"
.ie n .IP """DefConditional($prototype,$test,%options);""" 4
.el .IP "\f(CWDefConditional($prototype,$test,%options);\fR" 4
.IX Item "DefConditional($prototype,$test,%options);"
Defines a conditional for \f(CW$prototype\fR; a control sequence that is
processed during macro expansion time (in the LaTeXML::Core::Gullet).
A conditional corresponds to a TeX \f(CW\*(C`\eif\*(C'\fR.
It evaluates \f(CW$test\fR, which should be \s-1CODE\s0 that is applied to the arguments, if any.
Depending on whether the result of that evaluation returns a true or false value
(in the usual Perl sense), the result of the expansion is either the
first or else code following, in the usual TeX sense.
.IX Xref "DefConditional"
.Sp
DefConditional options are
.RS 4
.IP "scope=>$scope" 4
.IX Item "scope=>$scope"
See \*(L"Control of Scoping\*(R".
.IP "locked=>boolean" 4
.IX Item "locked=>boolean"
Whether this definition is locked out of changes in the TeX sources.
.RE
.RS 4
.Sp
Example:
.Sp
.Vb 2
\& DefConditional(\*(Aq\eifmmode\*(Aq,sub {
\& LookupValue(\*(AqIN_MATH\*(Aq); });
.Ve
.RE
.ie n .IP """DefConditionalI($cs,$paramlist,$test,%options);""" 4
.el .IP "\f(CWDefConditionalI($cs,$paramlist,$test,%options);\fR" 4
.IX Item "DefConditionalI($cs,$paramlist,$test,%options);"
Internal form of \f(CW\*(C`DefConditional\*(C'\fR where the control sequence and parameter list
have already been parsed; useful for definitions from within code.
Also, slightly more efficient for conditinal with no arguments (use \f(CW\*(C`undef\*(C'\fR for
\&\f(CW$paramlist\fR).
.IX Xref "DefConditionalI"
.PP
\fIPrimitives\fR
.IX Subsection "Primitives"
.ie n .IP """DefPrimitive($prototype,$replacement,%options);""" 4
.el .IP "\f(CWDefPrimitive($prototype,$replacement,%options);\fR" 4
.IX Item "DefPrimitive($prototype,$replacement,%options);"
Define a primitive control sequence; a primitive is processed during
digestion (in the LaTeXML::Core::Stomach), after macro expansion but before Construction time.
Primitive control sequences generate Boxes or Lists, generally
containing basic Unicode content, rather than structured \s-1XML.\s0
Primitive control sequences are also executed for side effect during digestion,
effecting changes to the LaTeXML::Core::State.
.IX Xref "DefPrimitive"
.Sp
The \f(CW$replacement\fR is either a string, used as the Boxes text content
(the box gets the current font), or \f(CW\*(C`CODE($stomach,@args)\*(C'\fR, which is
invoked at digestion time, probably for side-effect, but returning Boxes or Lists.
\&\f(CW$replacement\fR may also be undef, which contributes nothing to the document,
but does record the TeX code that created it.
.Sp
DefPrimitive options are
.RS 4
.IP "mode=>(text|display_math|inline_math)" 4
.IX Item "mode=>(text|display_math|inline_math)"
Changes to this mode during digestion.
.IP "bounded=>boolean" 4
.IX Item "bounded=>boolean"
If true, TeX grouping (ie. \f(CW\*(C`{}\*(C'\fR) is enforced around this invocation.
.IP "requireMath=>boolean," 4
.IX Item "requireMath=>boolean,"
.PD 0
.IP "forbidMath=>boolean" 4
.IX Item "forbidMath=>boolean"
.PD
These specify whether the given constructor can only appear,
or cannot appear, in math mode.
.IP "font=>{fontspec...}" 4
.IX Item "font=>{fontspec...}"
Specifies the font to use (see \*(L"MergeFont(%style);\*(R").
If the font change is to only apply to material generated within this command,
you would also use \f(CW\*(C`>; otherwise, the font will remain in effect afterwards
as for a font switching command.
.IP "beforeDigest=>\s-1CODE\s0($stomach)" 4
.IX Item "beforeDigest=>CODE($stomach)"
This option supplies a Daemon to be executed during digestion
just before the main part of the primitive is executed.
The \s-1CODE\s0 should either return nothing (return;) or a list of digested items (Box's,List,Whatsit).
It can thus change the State and/or add to the digested output.
.IP "afterDigest=>\s-1CODE\s0($stomach)" 4
.IX Item "afterDigest=>CODE($stomach)"
This option supplies a Daemon to be executed during digestion
just after the main part of the primitive ie executed.
it should either return nothing (return;) or digested items.
It can thus change the State and/or add to the digested output.
.IP "scope=>$scope" 4
.IX Item "scope=>$scope"
See \*(L"Control of Scoping\*(R".
.IP "locked=>boolean" 4
.IX Item "locked=>boolean"
Whether this definition is locked out of changes in the TeX sources.
.ie n .IP """isPrefix=>1""" 4
.el .IP "\f(CWisPrefix=>1\fR" 4
.IX Item "isPrefix=>1"
Indicates whether this is a prefix type of command;
This is only used for the special TeX assignment prefixes, like \f(CW\*(C`\eglobal\*(C'\fR.
.RE
.RS 4
.Sp
Example:
.Sp
.Vb 1
\& DefPrimitive(\*(Aq\ebegingroup\*(Aq,sub { $_[0]\->begingroup; });
.Ve
.RE
.ie n .IP """DefPrimitiveI($cs,$paramlist,CODE($stomach,@args),%options);""" 4
.el .IP "\f(CWDefPrimitiveI($cs,$paramlist,CODE($stomach,@args),%options);\fR" 4
.IX Item "DefPrimitiveI($cs,$paramlist,CODE($stomach,@args),%options);"
Internal form of \f(CW\*(C`DefPrimitive\*(C'\fR where the control sequence and parameter list
have already been separated; useful for definitions from within code.
.IX Xref "DefPrimitiveI"
.ie n .IP """DefRegister($prototype,$value,%options);""" 4
.el .IP "\f(CWDefRegister($prototype,$value,%options);\fR" 4
.IX Item "DefRegister($prototype,$value,%options);"
Defines a register with the given initial value (a Number, Dimension, Glue, MuGlue or Tokens
\&\-\-\- I haven't handled Box's yet). Usually, the \f(CW$prototype\fR is just the control sequence,
but registers are also handled by prototypes like \f(CW\*(C`\ecount{Number}\*(C'\fR. \f(CW\*(C`DefRegister\*(C'\fR arranges
that the register value can be accessed when a numeric, dimension, ... value is being read,
and also defines the control sequence for assignment.
.IX Xref "DefRegister"
.Sp
Options are
.RS 4
.ie n .IP """readonly""" 4
.el .IP "\f(CWreadonly\fR" 4
.IX Item "readonly"
specifies if it is not allowed to change this value.
.ie n .IP """getter""=>\s-1CODE\s0(@args)" 4
.el .IP "\f(CWgetter\fR=>\s-1CODE\s0(@args)" 4
.IX Item "getter=>CODE(@args)"
.PD 0
.ie n .IP """setter""=>\s-1CODE\s0($value,@args)" 4
.el .IP "\f(CWsetter\fR=>\s-1CODE\s0($value,@args)" 4
.IX Item "setter=>CODE($value,@args)"
.PD
By default the value is stored in the State's Value table under a name concatenating the
control sequence and argument values. These options allow other means of fetching and
storing the value.
.RE
.RS 4
.Sp
Example:
.Sp
.Vb 1
\& DefRegister(\*(Aq\epretolerance\*(Aq,Number(100));
.Ve
.RE
.ie n .IP """DefRegisterI($cs,$paramlist,$value,%options);""" 4
.el .IP "\f(CWDefRegisterI($cs,$paramlist,$value,%options);\fR" 4
.IX Item "DefRegisterI($cs,$paramlist,$value,%options);"
Internal form of \f(CW\*(C`DefRegister\*(C'\fR where the control sequence and parameter list
have already been parsed; useful for definitions from within code.
.IX Xref "DefRegisterI"
.PP
\fIConstructors\fR
.IX Subsection "Constructors"
.ie n .IP """DefConstructor($prototype,$xmlpattern | $code,%options);""" 4
.el .IP "\f(CWDefConstructor($prototype,$xmlpattern | $code,%options);\fR" 4
.IX Item "DefConstructor($prototype,$xmlpattern | $code,%options);"
The Constructor is where LaTeXML really starts getting interesting;
invoking the control sequence will generate an arbitrary \s-1XML\s0
fragment in the document tree. More specifically: during digestion, the arguments
will be read and digested, creating a LaTeXML::Core::Whatsit to represent the object. During
absorbtion by the LaTeXML::Core::Document, the \f(CW\*(C`Whatsit\*(C'\fR will generate the \s-1XML\s0 fragment according
to the replacement \f(CW$xmlpattern\fR, or by executing \f(CW\*(C`CODE\*(C'\fR.
.IX Xref "DefConstructor"
.Sp
The \f(CW$xmlpattern\fR is simply a bit of \s-1XML\s0 as a string with certain substitutions to be made.
The substitutions are of the following forms:
.Sp
If code is supplied, the form is \f(CW\*(C`CODE($document,@args,%properties)\*(C'\fR
.RS 4
.IP "#1, #2 ... #name" 4
.IX Item "#1, #2 ... #name"
These are replaced by the corresponding argument (for #1) or property (for #name)
stored with the Whatsit. Each are turned into a string when it appears as
in an attribute position, or recursively processed when it appears as content.
.ie n .IP """&function(@args)""" 4
.el .IP "\f(CW&function(@args)\fR" 4
.IX Item "&function(@args)"
Another form of substituted value is prefixed with \f(CW\*(C`&\*(C'\fR which invokes a function.
For example, \f(CW\*(C` &func(#1) \*(C'\fR would invoke the function \f(CW\*(C`func\*(C'\fR on the first argument
to the control sequence; what it returns will be inserted into the document.
.ie n .IP """?COND(pattern)"" or ""?COND(ifpattern)(elsepattern)""" 4
.el .IP "\f(CW?COND(pattern)\fR or \f(CW?COND(ifpattern)(elsepattern)\fR" 4
.IX Item "?COND(pattern) or ?COND(ifpattern)(elsepattern)"
Patterns can be conditionallized using this form. The \f(CW\*(C`COND\*(C'\fR is any
of the above expressions, considered true if the result is non-empty.
Thus \f(CW\*(C`?#1()\*(C'\fR would add the empty element \f(CW\*(C`foo\*(C'\fR if the first argument
were given.
.ie n .IP """^""" 4
.el .IP "\f(CW^\fR" 4
.IX Item "^"
If the constuctor \fIbegins\fR with \f(CW\*(C`^\*(C'\fR, the \s-1XML\s0 fragment is allowed to \fIfloat up\fR
to a parent node that is allowed to contain it, according to the Document Type.
.RE
.RS 4
.Sp
The Whatsit property \f(CW\*(C`font\*(C'\fR is defined by default. Additional properties
\&\f(CW\*(C`body\*(C'\fR and \f(CW\*(C`trailer\*(C'\fR are defined when \f(CW\*(C`captureBody\*(C'\fR is true, or for environments.
By using \f(CW\*(C`$whatsit\->setProperty(key=>$value);\*(C'\fR within \f(CW\*(C`afterDigest\*(C'\fR,
or by using the \f(CW\*(C`properties\*(C'\fR option, other properties can be added.
.Sp
DefConstructor options are
.IP "mode=>(text|display_math|inline_math)" 4
.IX Item "mode=>(text|display_math|inline_math)"
Changes to this mode during digestion.
.IP "bounded=>boolean" 4
.IX Item "bounded=>boolean"
If true, TeX grouping (ie. \f(CW\*(C`{}\*(C'\fR) is enforced around this invocation.
.IP "requireMath=>boolean," 4
.IX Item "requireMath=>boolean,"
.PD 0
.IP "forbidMath=>boolean" 4
.IX Item "forbidMath=>boolean"
.PD
These specify whether the given constructor can only appear,
or cannot appear, in math mode.
.IP "font=>{fontspec...}" 4
.IX Item "font=>{fontspec...}"
Specifies the font to use (see \*(L"MergeFont(%style);\*(R").
If the font change is to only apply to material generated within this command,
you would also use \f(CW\*(C`>; otherwise, the font will remain in effect afterwards
as for a font switching command.
.IP "reversion=>$texstring or \s-1CODE\s0($whatsit,#1,#2,...)" 4
.IX Item "reversion=>$texstring or CODE($whatsit,#1,#2,...)"
Specifies the reversion of the invocation back into TeX tokens
(if the default reversion is not appropriate).
The \f(CW$textstring\fR string can include #1,#2...
The \s-1CODE\s0 is called with the \f(CW$whatsit\fR and digested arguments
and must return a list of Token's.
.IP "properties=>{prop=>value,...} or \s-1CODE\s0($stomach,#1,#2...)" 4
.IX Item "properties=>{prop=>value,...} or CODE($stomach,#1,#2...)"
This option supplies additional properties to be set on the
generated Whatsit. In the first form, the values can
be of any type, but if a value is a code references, it takes
the same args ($stomach,#1,#2,...) and should return the value;
it is executed before creating the Whatsit.
In the second form, the code should return a hash of properties.
.IP "beforeDigest=>\s-1CODE\s0($stomach)" 4
.IX Item "beforeDigest=>CODE($stomach)"
This option supplies a Daemon to be executed during digestion
just before the Whatsit is created. The \s-1CODE\s0 should either
return nothing (return;) or a list of digested items (Box's,List,Whatsit).
It can thus change the State and/or add to the digested output.
.IP "afterDigest=>\s-1CODE\s0($stomach,$whatsit)" 4
.IX Item "afterDigest=>CODE($stomach,$whatsit)"
This option supplies a Daemon to be executed during digestion
just after the Whatsit is created (and so the Whatsit already
has its arguments and properties). It should either return
nothing (return;) or digested items. It can thus change the State,
modify the Whatsit, and/or add to the digested output.
.IP "beforeConstruct=>\s-1CODE\s0($document,$whatsit)" 4
.IX Item "beforeConstruct=>CODE($document,$whatsit)"
Supplies \s-1CODE\s0 to execute before constructing the \s-1XML
\&\s0(generated by \f(CW$replacement\fR).
.IP "afterConstruct=>\s-1CODE\s0($document,$whatsit)" 4
.IX Item "afterConstruct=>CODE($document,$whatsit)"
Supplies \s-1CODE\s0 to execute after constructing the \s-1XML.\s0
.IP "captureBody=>boolean or Token" 4
.IX Item "captureBody=>boolean or Token"
if true, arbitrary following material will be accumulated into
a `body' until the current grouping level is reverted,
or till the \f(CW\*(C`Token\*(C'\fR is encountered if the option is a \f(CW\*(C`Token\*(C'\fR.
This body is available as the \f(CW\*(C`body\*(C'\fR property of the Whatsit.
This is used by environments and math.
.IP "alias=>$control_sequence" 4
.IX Item "alias=>$control_sequence"
Provides a control sequence to be used when reverting Whatsit's back to Tokens,
in cases where it isn't the command used in the \f(CW$prototype\fR.
.IP "nargs=>$nargs" 4
.IX Item "nargs=>$nargs"
This gives a number of args for cases where it can't be infered directly
from the \f(CW$prototype\fR (eg. when more args are explictly read by Daemons).
.IP "scope=>$scope" 4
.IX Item "scope=>$scope"
See \*(L"Control of Scoping\*(R".
.RE
.RS 4
.RE
.ie n .IP """DefConstructorI($cs,$paramlist,$xmlpattern | $code,%options);""" 4
.el .IP "\f(CWDefConstructorI($cs,$paramlist,$xmlpattern | $code,%options);\fR" 4
.IX Item "DefConstructorI($cs,$paramlist,$xmlpattern | $code,%options);"
Internal form of \f(CW\*(C`DefConstructor\*(C'\fR where the control sequence and parameter list
have already been separated; useful for definitions from within code.
.IX Xref "DefConstructorI"
.ie n .IP """DefMath($prototype,$tex,%options);""" 4
.el .IP "\f(CWDefMath($prototype,$tex,%options);\fR" 4
.IX Item "DefMath($prototype,$tex,%options);"
A common shorthand constructor; it defines a control sequence that creates a mathematical object,
such as a symbol, function or operator application.
The options given can effectively create semantic macros that contribute to the eventual
parsing of mathematical content.
In particular, it generates an XMDual using the replacement \f(CW$tex\fR for the presentation.
The content information is drawn from the name and options
.IX Xref "DefMath"
.Sp
These \f(CW\*(C`DefConstructor\*(C'\fR options also apply:
.Sp
.Vb 2
\& reversion, alias, beforeDigest, afterDigest,
\& beforeConstruct, afterConstruct and scope.
.Ve
.Sp
Additionally, it accepts
.RS 4
.IP "style=>astyle" 4
.IX Item "style=>astyle"
adds a style attribute to the object.
.IP "name=>aname" 4
.IX Item "name=>aname"
gives a name attribute for the object
.IP "omcd=>cdname" 4
.IX Item "omcd=>cdname"
gives the OpenMath content dictionary that name is from.
.IP "role=>grammatical_role" 4
.IX Item "role=>grammatical_role"
adds a grammatical role attribute to the object; this specifies
the grammatical role that the object plays in surrounding expressions.
This direly needs documentation!
.IP "font=>{fontspec}" 4
.IX Item "font=>{fontspec}"
Specifies the font to use (see \*(L"MergeFont(%style);\*(R").
.IP "mathstyle=(display|text|inline)" 4
.IX Item "mathstyle=(display|text|inline)"
Controls whether the this object will be presented in a specific
mathstyle, or according to the current setting of \f(CW\*(C`mathstyle\*(C'\fR.
.IP "scriptpos=>(mid|post)" 4
.IX Item "scriptpos=>(mid|post)"
Controls the positioning of any sub and super-scripts relative to this object;
whether they be stacked over or under it, or whether they will appear in the usual position.
TeX.pool defines a function \f(CW\*(C`doScriptpos()\*(C'\fR which is useful for operators
like \f(CW\*(C`\esum\*(C'\fR in that it sets to \f(CW\*(C`mid\*(C'\fR position when in displaystyle, otherwise \f(CW\*(C`post\*(C'\fR.
.IP "stretchy=>boolean" 4
.IX Item "stretchy=>boolean"
Whether or not the object is stretchy when displayed.
.IP "operator_role=>grammatical_role" 4
.IX Item "operator_role=>grammatical_role"
.PD 0
.IP "operator_scriptpos=>boolean" 4
.IX Item "operator_scriptpos=>boolean"
.IP "operator_stretchy=>boolean" 4
.IX Item "operator_stretchy=>boolean"
.PD
These three are similar to \f(CW\*(C`role\*(C'\fR, \f(CW\*(C`scriptpos\*(C'\fR and \f(CW\*(C`stretchy\*(C'\fR, but are used in
unusual cases. These apply to the given attributes to the operator token
in the content branch.
.IP "nogroup=>boolean" 4
.IX Item "nogroup=>boolean"
Normally, these commands are digested with an implicit grouping around them,
localizing changes to fonts, etc; \f(CW\*(C`noggroup=>1\*(C'\fR inhibits this.
.Sp
Example:
.Sp
.Vb 2
\& DefMath(\*(Aq\einfty\*(Aq,"\ex{221E}",
\& role=>\*(AqID\*(Aq, meaning=>\*(Aqinfinity\*(Aq);
.Ve
.RE
.RS 4
.RE
.ie n .IP """DefMathI($cs,$paramlist,$tex,%options);""" 4
.el .IP "\f(CWDefMathI($cs,$paramlist,$tex,%options);\fR" 4
.IX Item "DefMathI($cs,$paramlist,$tex,%options);"
Internal form of \f(CW\*(C`DefMath\*(C'\fR where the control sequence and parameter list
have already been separated; useful for definitions from within code.
.IX Xref "DefMathI"
.ie n .IP """DefEnvironment($prototype,$replacement,%options);""" 4
.el .IP "\f(CWDefEnvironment($prototype,$replacement,%options);\fR" 4
.IX Item "DefEnvironment($prototype,$replacement,%options);"
Defines an Environment that generates a specific \s-1XML\s0 fragment. \f(CW$replacement\fR is
of the same form as for DefConstructor, but will generally include reference to
the \f(CW\*(C`#body\*(C'\fR property. Upon encountering a \f(CW\*(C`\ebegin{env}\*(C'\fR: the mode is switched, if needed,
else a new group is opened; then the environment name is noted; the beforeDigest daemon is run.
Then the Whatsit representing the begin command (but ultimately the whole environment) is created
and the afterDigestBegin daemon is run.
Next, the body will be digested and collected until the balancing \f(CW\*(C`\eend{env}\*(C'\fR. Then,
any afterDigest daemon is run, the environment is ended, finally the mode is ended or
the group is closed. The body and \f(CW\*(C`\eend{env}\*(C'\fR whatsit are added to the \f(CW\*(C`\ebegin{env}\*(C'\fR's whatsit
as body and trailer, respectively.
.IX Xref "DefEnvironment"
.Sp
It shares options with \f(CW\*(C`DefConstructor\*(C'\fR:
.Sp
.Vb 3
\& mode, requireMath, forbidMath, properties, nargs,
\& font, beforeDigest, afterDigest, beforeConstruct,
\& afterConstruct and scope.
.Ve
.Sp
Additionally, \f(CW\*(C`afterDigestBegin\*(C'\fR is effectively an \f(CW\*(C`afterDigest\*(C'\fR
for the \f(CW\*(C`\ebegin{env}\*(C'\fR control sequence.
.Sp
Example:
.Sp
.Vb 2
\& DefConstructor(\*(Aq\eemph{}\*(Aq,
\& "#1\*(Aqtext\*(Aq);
.Ve
.Sp
DefEnvironment gives slightly different interpretation to some of
\&\f(CW\*(C`DefConstructor\*(C'\fR's options and adds some new ones:
.RS 4
.IP "beforeDigest=>\s-1CODE\s0($stomach)" 4
.IX Item "beforeDigest=>CODE($stomach)"
This option is the same as for \f(CW\*(C`DefConstructor\*(C'\fR,
but it applies to the \f(CW\*(C`\ebegin{environment}\*(C'\fR control sequence.
.IP "afterDigestBegin=>\s-1CODE\s0($stomach,$whatsit)" 4
.IX Item "afterDigestBegin=>CODE($stomach,$whatsit)"
This option is the same as \f(CW\*(C`DefConstructor\*(C'\fR's \f(CW\*(C`afterDigest\*(C'\fR
but it applies to the \f(CW\*(C`\ebegin{environment}\*(C'\fR control sequence.
The Whatsit is the one for the begining control sequence,
but represents the environment as a whole.
Note that although the arguments and properties are present in
the Whatsit, the body of the environment is \fInot\fR.
.IP "beforeDigestEnd=>\s-1CODE\s0($stomach)" 4
.IX Item "beforeDigestEnd=>CODE($stomach)"
This option is the same as \f(CW\*(C`DefConstructor\*(C'\fR's \f(CW\*(C`beforeDigest\*(C'\fR
but it applies to the \f(CW\*(C`\eend{environment}\*(C'\fR control sequence.
.IP "afterDigest=>\s-1CODE\s0($stomach,$whatsit)" 4
.IX Item "afterDigest=>CODE($stomach,$whatsit)"
This option is the same as \f(CW\*(C`DefConstructor\*(C'\fR's \f(CW\*(C`afterDigest\*(C'\fR
but it applies to the \f(CW\*(C`\eend{environment}\*(C'\fR control sequence.
Note, however that the Whatsit is only for the ending control sequence,
\&\fInot\fR the Whatsit for the environment as a whole.
.IP "afterDigestBody=>\s-1CODE\s0($stomach,$whatsit)" 4
.IX Item "afterDigestBody=>CODE($stomach,$whatsit)"
This option supplies a Daemon to be executed during digestion
after the ending control sequence has been digested (and all the 4
other digestion Daemons have executed) and after
the body of the environment has been obtained.
The Whatsit is the (usefull) one representing the whole
environment, and it now does have the body and trailer available,
stored as a properties.
.RE
.RS 4
.RE
.ie n .IP """DefEnvironmentI($name,$paramlist,$replacement,%options);""" 4
.el .IP "\f(CWDefEnvironmentI($name,$paramlist,$replacement,%options);\fR" 4
.IX Item "DefEnvironmentI($name,$paramlist,$replacement,%options);"
Internal form of \f(CW\*(C`DefEnvironment\*(C'\fR where the control sequence and parameter list
have already been separated; useful for definitions from within code.
.IX Xref "DefEnvironmentI"
.SS "Inputing Content and Definitions"
.IX Subsection "Inputing Content and Definitions"
.ie n .IP """FindFile($name,%options);""" 4
.el .IP "\f(CWFindFile($name,%options);\fR" 4
.IX Item "FindFile($name,%options);"
Find an appropriate file with the given \f(CW$name\fR in the current directories
in \f(CW\*(C`SEARCHPATHS\*(C'\fR.
If a file ending with \f(CW\*(C`.ltxml\*(C'\fR is found, it will be preferred.
.IX Xref "FindFile"
.Sp
Note that if the \f(CW$name\fR starts with a recognized \fIprotocol\fR
(currently one of \f(CW\*(C`(literal|http|https|ftp)\*(C'\fR) followed by a colon,
the name is returned, as is, and no search for files is carried out.
.Sp
The options are:
.RS 4
.IP "type=>type" 4
.IX Item "type=>type"
specifies the file type. If not set, it will search for
both \f(CW\*(C`$name.tex\*(C'\fR and \f(CW$name\fR.
.IP "noltxml=>1" 4
.IX Item "noltxml=>1"
inhibits searching for a LaTeXML binding to use instead
of the file itself (\f(CW\*(C`$name.$type.ltxml\*(C'\fR)
.IP "notex=>1" 4
.IX Item "notex=>1"
inhibits searching for raw tex version of the file.
That is, it will \fIonly\fR search for the LaTeXML binding.
.RE
.RS 4
.RE
.ie n .IP """InputContent($request,%options);""" 4
.el .IP "\f(CWInputContent($request,%options);\fR" 4
.IX Item "InputContent($request,%options);"
\&\f(CW\*(C`InputContent\*(C'\fR is used for cases when the file (or data)
is plain TeX material that is expected to contribute content
to the document (as opposed to pure definitions).
A Mouth is opened onto the file, and subsequent reading
and/or digestion will pull Tokens from that Mouth until it is
exhausted, or closed.
.IX Xref "InputContent"
.Sp
In some circumstances it may be useful to provide a string containing
the TeX material explicitly, rather than referencing a file.
In this case, the \f(CW\*(C`literal\*(C'\fR pseudo-protocal may be used:
.Sp
.Vb 1
\& InputContent(\*(Aqliteral:\etextit{Hey}\*(Aq);
.Ve
.Sp
If a file named \f(CW\*(C`$request.latexml\*(C'\fR exists, it will be read
in as if it were a latexml binding file, before processing.
This can be used for adhoc customization of the conversion of specific files,
without modifying the source, or creating more elaborate bindings.
.Sp
The only option to \f(CW\*(C`InputContent\*(C'\fR is:
.RS 4
.IP "noerror=>boolean" 4
.IX Item "noerror=>boolean"
Inhibits signalling an error if no appropriate file is found.
.RE
.RS 4
.RE
.ie n .IP """Input($request);""" 4
.el .IP "\f(CWInput($request);\fR" 4
.IX Item "Input($request);"
\&\f(CW\*(C`Input\*(C'\fR is analogous to LaTeX's \f(CW\*(C`\einput\*(C'\fR, and is used in
cases where it isn't completely clear whether content or definitions
is expected. Once a file is found, the approach specified
by InputContent or InputDefinitions is used, depending on
which type of file is found.
.IX Xref "Input"
.ie n .IP """InputDefinitions($request,%options);""" 4
.el .IP "\f(CWInputDefinitions($request,%options);\fR" 4
.IX Item "InputDefinitions($request,%options);"
\&\f(CW\*(C`InputDefinitions\*(C'\fR is used for loading \fIdefinitions\fR,
ie. various macros, settings, etc, rather than document content;
it can be used to load LaTeXML's binding files, or for
reading in raw TeX definitions or style files.
It reads and processes the material completely before
returning, even in the case of TeX definitions.
This procedure optionally supports the conventions used
for standard LaTeX packages and classes (see RequirePackage and LoadClass).
.IX Xref "InputDefinitions"
.Sp
Options for \f(CW\*(C`InputDefinitions\*(C'\fR are:
.RS 4
.IP "type=>$type" 4
.IX Item "type=>$type"
the file type to search for.
.IP "noltxml=>boolean" 4
.IX Item "noltxml=>boolean"
inhibits searching for a LaTeXML binding; only raw TeX files will be sought and loaded.
.IP "notex=>boolean" 4
.IX Item "notex=>boolean"
inhibits searching for raw TeX files, only a LaTeXML binding will be sought and loaded.
.IP "noerror=>boolean" 4
.IX Item "noerror=>boolean"
inhibits reporting an error if no appropriate file is found.
.RE
.RS 4
.Sp
The following options are primarily useful when \f(CW\*(C`InputDefinitions\*(C'\fR
is supporting standard LaTeX package and class loading.
.IP "withoptions=boolean" 4
.IX Item "withoptions=boolean"
indicates whether to pass in any options from the calling class or package.
.IP "handleoptions=boolean" 4
.IX Item "handleoptions=boolean"
indicates whether options processing should be handled.
.IP "options=>[...]" 4
.IX Item "options=>[...]"
specifies a list of options to be passed
(possibly in addition to any provided by the calling class or package).
.IP "after" 4
.IX Item "after"
provides code or tokens to be processed by a \f(CW\*(C`$name.$type\-hook\*(C'\fR macro.
.IP "as_class" 4
.IX Item "as_class"
fishy option that indicates that this definitions file should
be treated as if it were defining a class; typically shows up
in latex compatibility mode, or AMSTeX.
.RE
.RS 4
.RE
.SS "Class and Packages"
.IX Subsection "Class and Packages"
.ie n .IP """RequirePackage($package,%options);""" 4
.el .IP "\f(CWRequirePackage($package,%options);\fR" 4
.IX Item "RequirePackage($package,%options);"
Finds and loads a package implementation (usually \f(CW\*(C`*.sty.ltxml\*(C'\fR, unless \f(CW\*(C`raw\*(C'\fR is specified)
for the required \f(CW$package\fR. It returns the pathname of the loaded package.
The options are:
.IX Xref "RequirePackage"
.RS 4
.IP "type=>type" 4
.IX Item "type=>type"
specifies the file type (default \f(CW\*(C`sty\*(C'\fR.
.IP "options=>[...]" 4
.IX Item "options=>[...]"
specifies a list of package options.
.IP "noltxml=>1" 4
.IX Item "noltxml=>1"
inhibits searching for the LaTeXML binding for the file (ie. \f(CW\*(C`$name.$type.ltxml\*(C'\fR
.IP "notex=>1" 4
.IX Item "notex=>1"
inhibits searching for raw tex version of the file.
That is, it will \fIonly\fR search for the LaTeXML binding.
.RE
.RS 4
.RE
.ie n .IP """LoadClass($class,%options);""" 4
.el .IP "\f(CWLoadClass($class,%options);\fR" 4
.IX Item "LoadClass($class,%options);"
Finds and loads a class definition (usually \f(CW\*(C`*.cls.ltxml\*(C'\fR).
It returns the pathname of the loaded class.
The only option is
.IX Xref "LoadClass"
.RS 4
.IP "options=>[...]" 4
.IX Item "options=>[...]"
specifies a list of class options.
.RE
.RS 4
.RE
.ie n .IP """LoadPool($pool,%options);""" 4
.el .IP "\f(CWLoadPool($pool,%options);\fR" 4
.IX Item "LoadPool($pool,%options);"
Loads a \fIpool\fR file, one of the top-level definition files,
such as TeX, LaTeX or AMSTeX.
It returns the pathname of the loaded file.
.IX Xref "LoadPool"
.ie n .IP """DeclareOption($option,$code);""" 4
.el .IP "\f(CWDeclareOption($option,$code);\fR" 4
.IX Item "DeclareOption($option,$code);"
Declares an option for the current package or class.
The \f(CW$code\fR can be a string or Tokens (which will be macro expanded),
or can be a code reference which is treated as a primitive.
.IX Xref "DeclareOption"
.Sp
If a package or class wants to accomodate options, it should start
with one or more \f(CW\*(C`DeclareOptions\*(C'\fR, followed by \f(CW\*(C`ProcessOptions()\*(C'\fR.
.ie n .IP """PassOptions($name,$ext,@options);""" 4
.el .IP "\f(CWPassOptions($name,$ext,@options);\fR" 4
.IX Item "PassOptions($name,$ext,@options);"
Causes the given \f(CW@options\fR (strings) to be passed to the package
(if \f(CW$ext\fR is \f(CW\*(C`sty\*(C'\fR) or class (if \f(CW$ext\fR is \f(CW\*(C`cls\*(C'\fR)
named by \f(CW$name\fR.
.IX Xref "PassOptions"
.ie n .IP """ProcessOptions();""" 4
.el .IP "\f(CWProcessOptions();\fR" 4
.IX Item "ProcessOptions();"
Processes the options that have been passed to the current package
or class in a fashion similar to LaTeX. If the keyword
\&\f(CW\*(C`inorder=>1\*(C'\fR is given, the options are processed in the
order they were used, like \f(CW\*(C`ProcessOptions*\*(C'\fR.
.IX Xref "ProcessOptions"
.ie n .IP """ExecuteOptions(@options);""" 4
.el .IP "\f(CWExecuteOptions(@options);\fR" 4
.IX Item "ExecuteOptions(@options);"
Process the options given explicitly in \f(CW@options\fR.
.IX Xref "ExecuteOptions"
.ie n .IP """AtBeginDocument(@stuff);""" 4
.el .IP "\f(CWAtBeginDocument(@stuff);\fR" 4
.IX Item "AtBeginDocument(@stuff);"
Arranges for \f(CW@stuff\fR to be carried out after the preamble, at the beginning of the document.
\&\f(CW@stuff\fR should typically be macro-level stuff, but carried out for side effect;
it should be tokens, tokens lists, strings (which will be tokenized),
or a sub (which presumably contains code as would be in a package file, such as \f(CW\*(C`DefMacro\*(C'\fR
or similar.
.IX Xref "AtBeginDocument"
.Sp
This operation is useful for style files loaded with \f(CW\*(C`\-\-preload\*(C'\fR or document specific
customization files (ie. ending with \f(CW\*(C`.latexml\*(C'\fR); normally the contents would be executed
before LaTeX and other style files are loaded and thus can be overridden by them.
By deferring the evaluation to begin-document time, these contents can override those style files.
This is likely to only be meaningful for LaTeX documents.
.SS "Counters and IDs"
.IX Subsection "Counters and IDs"
.ie n .IP """NewCounter($ctr,$within,%options);""" 4
.el .IP "\f(CWNewCounter($ctr,$within,%options);\fR" 4
.IX Item "NewCounter($ctr,$within,%options);"
Defines a new counter, like LaTeX's \enewcounter, but extended.
It defines a counter that can be used to generate reference numbers,
and defines \ethe$ctr, etc. It also defines an \*(L"uncounter\*(R" which
can be used to generate \s-1ID\s0's (xml:id) for unnumbered objects.
\&\f(CW$ctr\fR is the name of the counter. If defined, \f(CW$within\fR is the name
of another counter which, when incremented, will cause this counter
to be reset.
The options are
.IX Xref "NewCounter"
.Sp
.Vb 3
\& idprefix Specifies a prefix to be used to generate ID\*(Aqs
\& when using this counter
\& nested Not sure that this is even sane.
.Ve
.ie n .IP """$num = CounterValue($ctr);""" 4
.el .IP "\f(CW$num = CounterValue($ctr);\fR" 4
.IX Item "$num = CounterValue($ctr);"
Fetches the value associated with the counter \f(CW$ctr\fR.
.IX Xref "CounterValue"
.ie n .IP """$tokens = StepCounter($ctr);""" 4
.el .IP "\f(CW$tokens = StepCounter($ctr);\fR" 4
.IX Item "$tokens = StepCounter($ctr);"
Analog of \f(CW\*(C`\estepcounter\*(C'\fR, steps the counter and returns the expansion of
\&\f(CW\*(C`\ethe$ctr\*(C'\fR. Usually you should use \f(CW\*(C`RefStepCounter($ctr)\*(C'\fR instead.
.IX Xref "StepCounter"
.ie n .IP """$keys = RefStepCounter($ctr);""" 4
.el .IP "\f(CW$keys = RefStepCounter($ctr);\fR" 4
.IX Item "$keys = RefStepCounter($ctr);"
Analog of \f(CW\*(C`\erefstepcounter\*(C'\fR, steps the counter and returns a hash
containing the keys \f(CW\*(C`refnum=\*(C'\fR\f(CW$refnum\fR, id=>$id>. This makes it
suitable for use in a \f(CW\*(C`properties\*(C'\fR option to constructors.
The \f(CW\*(C`id\*(C'\fR is generated in parallel with the reference number
to assist debugging.
.IX Xref "RefStepCounter"
.ie n .IP """$keys = RefStepID($ctr);""" 4
.el .IP "\f(CW$keys = RefStepID($ctr);\fR" 4
.IX Item "$keys = RefStepID($ctr);"
Like to \f(CW\*(C`RefStepCounter\*(C'\fR, but only steps the \*(L"uncounter\*(R",
and returns only the id; This is useful for unnumbered cases
of objects that normally get both a refnum and id.
.IX Xref "RefStepID"
.ie n .IP """ResetCounter($ctr);""" 4
.el .IP "\f(CWResetCounter($ctr);\fR" 4
.IX Item "ResetCounter($ctr);"
Resets the counter \f(CW$ctr\fR to zero.
.IX Xref "ResetCounter"
.ie n .IP """GenerateID($document,$node,$whatsit,$prefix);""" 4
.el .IP "\f(CWGenerateID($document,$node,$whatsit,$prefix);\fR" 4
.IX Item "GenerateID($document,$node,$whatsit,$prefix);"
Generates an \s-1ID\s0 for nodes during the construction phase, useful
for cases where the counter based scheme is inappropriate.
The calling pattern makes it appropriate for use in Tag, as in
Tag('ltx:para',afterClose=>sub { GenerateID(@_,'p'); })
.IX Xref "GenerateID"
.Sp
If \f(CW$node\fR doesn't already have an xml:id set, it computes an
appropriate id by concatenating the xml:id of the closest
ancestor with an id (if any), the prefix (if any) and a unique counter.
.SS "Document Model"
.IX Subsection "Document Model"
Constructors define how TeX markup will generate \s-1XML\s0 fragments, but the
Document Model is used to control exactly how those fragments are assembled.
.ie n .IP """Tag($tag,%properties);""" 4
.el .IP "\f(CWTag($tag,%properties);\fR" 4
.IX Item "Tag($tag,%properties);"
Declares properties of elements with the name \f(CW$tag\fR.
Note that \f(CW\*(C`Tag\*(C'\fR can set or add properties to any element from any binding file,
unlike the properties set on control by \f(CW\*(C`DefPrimtive\*(C'\fR, \f(CW\*(C`DefConstructor\*(C'\fR, etc..
And, since the properties are recorded in the current Model, they are not
subject to TeX grouping; once set, they remain in effect until changed
or the end of the document.
.IX Xref "Tag"
.Sp
The \f(CW$tag\fR can be specified in one of three forms:
.Sp
.Vb 3
\& prefix:name matches specific name in specific namespace
\& prefix:* matches any tag in the specific namespace;
\& * matches any tag in any namespace.
.Ve
.Sp
There are two kinds of properties:
.RS 4
.IP "Scalar properties" 4
.IX Item "Scalar properties"
For scalar properties, only a single value is returned for a given element.
When the property is looked up, each of the above forms is considered
(the specific element name, the namespace, and all elements);
the first defined value is returned.
.Sp
The recognized scalar properties are:
.RS 4
.IP "autoOpen=>boolean" 4
.IX Item "autoOpen=>boolean"
Specifies whether this \f(CW$tag\fR can be automatically opened
if needed to insert an element that can only
be contained by \f(CW$tag\fR.
This property can help match the more SGML-like LaTeX to \s-1XML.\s0
.IP "autoClose=>boolean" 4
.IX Item "autoClose=>boolean"
Specifies whether this \f(CW$tag\fR can be automatically closed
if needed to close an ancestor node, or insert
an element into an ancestor.
This property can help match the more SGML-like LaTeX to \s-1XML.\s0
.RE
.RS 4
.RE
.IP "Code properties" 4
.IX Item "Code properties"
These properties provide a bit of code to be run at the times
of certain events associated with an element. \fIAll\fR the code bits
that match a given element will be run, and since they can be added by
any binding file, and be specified in a random orders,
a little bit of extra control is desirable.
.Sp
Firstly, any \fIearly\fR codes are run (eg \f(CW\*(C`afterOpen:early\*(C'\fR), then
any normal codes (without modifier) are run, and finally
any \fIlate\fR codes are run (eg. \f(CW\*(C`afterOpen:late\*(C'\fR).
.Sp
Within \fIeach\fR of those groups, the codes assigned for an element's specific
name are run first, then those assigned for its package and finally the generic one (\f(CW\*(C`*\*(C'\fR);
that is, the most specific codes are run first.
.Sp
When code properties are accumulated by \f(CW\*(C`Tag\*(C'\fR for normal or late events,
the code is appended to the end of the current list (if there were any previous codes added);
for early event, the code is prepended.
.Sp
The recognized code properties are:
.RS 4
.ie n .IP """afterOpen=>CODE($document,$box)""" 4
.el .IP "\f(CWafterOpen=>CODE($document,$box)\fR" 4
.IX Item "afterOpen=>CODE($document,$box)"
Provides \s-1CODE\s0 to be run whenever a node with this \f(CW$tag\fR
is opened. It is called with the document being constructed,
and the initiating digested object as arguments.
It is called after the node has been created, and after
any initial attributes due to the constructor (passed to openElement)
are added.
.Sp
\&\f(CW\*(C`afterOpen:early\*(C'\fR or \f(CW\*(C`afterOpen:late\*(C'\fR can be used in
place of \f(CW\*(C`afterOpen\*(C'\fR; these will be run as a group
bfore, or after (respectively) the unmodified blocks.
.ie n .IP """afterClose=>CODE($document,$box)""" 4
.el .IP "\f(CWafterClose=>CODE($document,$box)\fR" 4
.IX Item "afterClose=>CODE($document,$box)"
Provides \s-1CODE\s0 to be run whenever a node with this \f(CW$tag\fR
is closed. It is called with the document being constructed,
and the initiating digested object as arguments.
.Sp
\&\f(CW\*(C`afterClose:early\*(C'\fR or \f(CW\*(C`afterClose:late\*(C'\fR can be used in
place of \f(CW\*(C`afterClose\*(C'\fR; these will be run as a group
bfore, or after (respectively) the unmodified blocks.
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.ie n .IP """RelaxNGSchema($schemaname);""" 4
.el .IP "\f(CWRelaxNGSchema($schemaname);\fR" 4
.IX Item "RelaxNGSchema($schemaname);"
Specifies the schema to use for determining document model.
You can leave off the extension; it will look for \f(CW\*(C`.rng\*(C'\fR,
and maybe eventually, \f(CW\*(C`.rnc\*(C'\fR once that is implemented.
.IX Xref "RelaxNGSchema"
.ie n .IP """RegisterNamespace($prefix,$URL);""" 4
.el .IP "\f(CWRegisterNamespace($prefix,$URL);\fR" 4
.IX Item "RegisterNamespace($prefix,$URL);"
Declares the \f(CW$prefix\fR to be associated with the given \f(CW$URL\fR.
These prefixes may be used in ltxml files, particularly for
constructors, xpath expressions, etc. They are not necessarily
the same as the prefixes that will be used in the generated document
Use the prefix \f(CW\*(C`#default\*(C'\fR for the default, non-prefixed, namespace.
(See RegisterDocumentNamespace, as well as DocType or RelaxNGSchema).
.IX Xref "RegisterNamespace"
.ie n .IP """RegisterDocumentNamespace($prefix,$URL);""" 4
.el .IP "\f(CWRegisterDocumentNamespace($prefix,$URL);\fR" 4
.IX Item "RegisterDocumentNamespace($prefix,$URL);"
Declares the \f(CW$prefix\fR to be associated with the given \f(CW$URL\fR
used within the generated \s-1XML.\s0 They are not necessarily
the same as the prefixes used in code (RegisterNamespace).
This function is less rarely needed, as the namespace declarations
are generally obtained from the \s-1DTD\s0 or Schema themselves
Use the prefix \f(CW\*(C`#default\*(C'\fR for the default, non-prefixed, namespace.
(See DocType or RelaxNGSchema).
.IX Xref "RegisterDocumentNamespace"
.ie n .IP """DocType($rootelement,$publicid,$systemid,%namespaces);""" 4
.el .IP "\f(CWDocType($rootelement,$publicid,$systemid,%namespaces);\fR" 4
.IX Item "DocType($rootelement,$publicid,$systemid,%namespaces);"
Declares the expected rootelement, the public and system \s-1ID\s0's of the document type
to be used in the final document. The hash \f(CW%namespaces\fR specifies
the namespaces prefixes that are expected to be found in the \s-1DTD,\s0 along with
each associated namespace \s-1URI. \s0 Use the prefix \f(CW\*(C`#default\*(C'\fR for the default namespace
(ie. the namespace of non-prefixed elements in the \s-1DTD\s0).
.IX Xref "DocType"
.Sp
The prefixes defined for the \s-1DTD\s0 may be different from the prefixes used in
implementation \s-1CODE \s0(eg. in ltxml files; see RegisterNamespace).
The generated document will use the namespaces and prefixes defined for the \s-1DTD.\s0
.PP
A related capability is adding commands to be executed at the beginning
and end of the document
.ie n .IP """AtBeginDocument($tokens,...)""" 4
.el .IP "\f(CWAtBeginDocument($tokens,...)\fR" 4
.IX Item "AtBeginDocument($tokens,...)"
adds the \f(CW$tokens\fR to a list to be processed just after \f(CW\*(C`\e\ebegin{document}\*(C'\fR.
These tokens can be used for side effect, or any content they generate will appear as the
first children of the document (but probably after titles and frontmatter).
.ie n .IP """AtEndDocument($tokens,...)""" 4
.el .IP "\f(CWAtEndDocument($tokens,...)\fR" 4
.IX Item "AtEndDocument($tokens,...)"
adds the \f(CW$tokens\fR to the list to be processed just before \f(CW\*(C`\e\eend{document}\*(C'\fR.
These tokens can be used for side effect, or any content they generate will appear as the
last children of the document.
.SS "Document Rewriting"
.IX Subsection "Document Rewriting"
During document construction, as each node gets closed, the text content gets simplfied.
We'll call it \fIapplying ligatures\fR, for lack of a better name.
.ie n .IP """DefLigature($regexp,%options);""" 4
.el .IP "\f(CWDefLigature($regexp,%options);\fR" 4
.IX Item "DefLigature($regexp,%options);"
Apply the regular expression (given as a string: \*(L"/fa/fa/\*(R" since it will
be converted internally to a true regexp), to the text content.
The only option is \f(CW\*(C`fontTest=CODE($font)\*(C'\fR; if given, then the substitution
is applied only when \f(CW\*(C`fontTest\*(C'\fR returns true.
.IX Xref "DefLigature"
.Sp
Predefined Ligatures combine sequences of \*(L".\*(R" or single-quotes into appropriate
Unicode characters.
.ie n .IP """DefMathLigature(CODE($document,@nodes));""" 4
.el .IP "\f(CWDefMathLigature(CODE($document,@nodes));\fR" 4
.IX Item "DefMathLigature(CODE($document,@nodes));"
\&\s-1CODE\s0 is called on each sequence of math nodes at a given level. If they should
be replaced, return a list of \f(CW\*(C`($n,$string,%attributes)\*(C'\fR to replace
the text content of the first node with \f(CW$string\fR content and add the given attributes.
The next \f(CW\*(C`$n\-1\*(C'\fR nodes are removed. If no replacement is called for, \s-1CODE\s0
should return undef.
.IX Xref "DefMathLigature"
.Sp
Predefined Math Ligatures combine letter or digit Math Tokens (XMTok) into multicharacter
symbols or numbers, depending on the font (non math italic).
.PP
After document construction, various rewriting and augmenting of the
document can take place.
.ie n .IP """DefRewrite(%specification);""" 4
.el .IP "\f(CWDefRewrite(%specification);\fR" 4
.IX Item "DefRewrite(%specification);"
.PD 0
.ie n .IP """DefMathRewrite(%specification);""" 4
.el .IP "\f(CWDefMathRewrite(%specification);\fR" 4
.IX Item "DefMathRewrite(%specification);"
.PD
These two declarations define document rewrite rules that are applied to the
document tree after it has been constructed, but before math parsing, or
any other postprocessing, is done. The \f(CW%specification\fR consists of a
seqeuence of key/value pairs with the initial specs successively narrowing the
selection of document nodes, and the remaining specs indicating how
to modify or replace the selected nodes.
.IX Xref "DefRewrite DefMathRewrite"
.Sp
The following select portions of the document:
.RS 4
.IP "label =>$label" 4
.IX Item "label =>$label"
Selects the part of the document with label=$label
.IP "scope =>$scope" 4
.IX Item "scope =>$scope"
The \f(CW$scope\fR could be \*(L"label:foo\*(R" or \*(L"section:1.2.3\*(R" or something
similar. These select a subtree labelled 'foo', or
a section with reference number \*(L"1.2.3\*(R"
.IP "xpath =>$xpath" 4
.IX Item "xpath =>$xpath"
Select those nodes matching an explicit xpath expression.
.IP "match =>$TeX" 4
.IX Item "match =>$TeX"
Selects nodes that look like what the processing of \f(CW$TeX\fR would produce.
.IP "regexp=>$regexp" 4
.IX Item "regexp=>$regexp"
Selects text nodes that match the regular expression.
.RE
.RS 4
.Sp
The following act upon the selected node:
.ie n .IP "attributes => $hash" 4
.el .IP "attributes => \f(CW$hash\fR" 4
.IX Item "attributes => $hash"
Adds the attributes given in the hash reference to the node.
.IP "replace =>$replacement" 4
.IX Item "replace =>$replacement"
Interprets the \f(CW$replacement\fR as TeX code to generate nodes that will
replace the selected nodes.
.RE
.RS 4
.RE
.SS "Mid-Level support"
.IX Subsection "Mid-Level support"
.ie n .IP """$tokens = Expand($tokens);""" 4
.el .IP "\f(CW$tokens = Expand($tokens);\fR" 4
.IX Item "$tokens = Expand($tokens);"
Expands the given \f(CW$tokens\fR according to current definitions.
.IX Xref "Expand"
.ie n .IP """$boxes = Digest($tokens);""" 4
.el .IP "\f(CW$boxes = Digest($tokens);\fR" 4
.IX Item "$boxes = Digest($tokens);"
Processes and digestes the \f(CW$tokens\fR. Any arguments needed by
control sequences in \f(CW$tokens\fR must be contained within the \f(CW$tokens\fR itself.
.IX Xref "Digest"
.ie n .IP """@tokens = Invocation($cs,@args);""" 4
.el .IP "\f(CW@tokens = Invocation($cs,@args);\fR" 4
.IX Item "@tokens = Invocation($cs,@args);"
Constructs a sequence of tokens that would invoke the token \f(CW$cs\fR
on the arguments.
.IX Xref "Invocation"
.ie n .IP """RawTeX(\*(Aq... tex code ...\*(Aq);""" 4
.el .IP "\f(CWRawTeX(\*(Aq... tex code ...\*(Aq);\fR" 4
.IX Item "RawTeX(... tex code ...);"
RawTeX is a convenience function for including chunks of raw TeX (or LaTeX) code
in a Package implementation. It is useful for copying portions of the normal
implementation that can be handled simply using macros and primitives.
.IX Xref "RawTeX"
.ie n .IP """Let($token1,$token2);""" 4
.el .IP "\f(CWLet($token1,$token2);\fR" 4
.IX Item "Let($token1,$token2);"
Gives \f(CW$token1\fR the same `meaning' (definition) as \f(CW$token2\fR; like TeX's \elet.
.IX Xref "Let"
.ie n .IP """StartSemiVerbatim(); ... ; EndSemiVerbatim();""" 4
.el .IP "\f(CWStartSemiVerbatim(); ... ; EndSemiVerbatim();\fR" 4
.IX Item "StartSemiVerbatim(); ... ; EndSemiVerbatim();"
Disable disable most TeX catcodes.
.ie n .IP """$tokens = Tokenize($string);""" 4
.el .IP "\f(CW$tokens = Tokenize($string);\fR" 4
.IX Item "$tokens = Tokenize($string);"
Tokenizes the \f(CW$string\fR using the standard catcodes, returning a LaTeXML::Core::Tokens.
.ie n .IP """$tokens = TokenizeInternal($string);""" 4
.el .IP "\f(CW$tokens = TokenizeInternal($string);\fR" 4
.IX Item "$tokens = TokenizeInternal($string);"
Tokenizes the \f(CW$string\fR according to the internal cattable (where @ is a letter),
returning a LaTeXML::Core::Tokens.
.SS "Argument Readers"
.IX Subsection "Argument Readers"
.ie n .IP """ReadParameters($gullet,$spec);""" 4
.el .IP "\f(CWReadParameters($gullet,$spec);\fR" 4
.IX Item "ReadParameters($gullet,$spec);"
Reads from \f(CW$gullet\fR the tokens corresponding to \f(CW$spec\fR
(a Parameters object).
.IX Xref "ReadParameters"
.ie n .IP """DefParameterType($type,CODE($gullet,@values),%options);""" 4
.el .IP "\f(CWDefParameterType($type,CODE($gullet,@values),%options);\fR" 4
.IX Item "DefParameterType($type,CODE($gullet,@values),%options);"
Defines a new Parameter type, \f(CW$type\fR, with \s-1CODE\s0 for its reader.
.IX Xref "DefParameterType"
.Sp
Options are:
.RS 4
.IP "reversion=>\s-1CODE\s0($arg,@values);" 4
.IX Item "reversion=>CODE($arg,@values);"
This \s-1CODE\s0 is responsible for converting a previously parsed argument back
into a sequence of Token's.
.IP "optional=>boolean" 4
.IX Item "optional=>boolean"
whether it is an error if no matching input is found.
.IP "novalue=>boolean" 4
.IX Item "novalue=>boolean"
whether the value returned should contribute to argument lists, or
simply be passed over.
.IP "semiverbatim=>boolean" 4
.IX Item "semiverbatim=>boolean"
whether the catcode table should be modified before reading tokens.
.RE
.RS 4
.RE
.ie n .IP """DefColumnType($proto,$expansion);""" 4
.el .IP "\f(CWDefColumnType($proto,$expansion);\fR" 4
.IX Item "DefColumnType($proto,$expansion);"
Defines a new column type for tabular and arrays.
\&\f(CW$proto\fR is the prototype for the pattern, analogous to the pattern
used for other definitions, except that macro being defined is a single character.
The \f(CW$expansion\fR is a string specifying what it should expand into,
typically more verbose column specification.
.IX Xref "DefColumnType"
.ie n .IP """DefKeyVal($keyset,$key,$type,$default);""" 4
.el .IP "\f(CWDefKeyVal($keyset,$key,$type,$default);\fR" 4
.IX Item "DefKeyVal($keyset,$key,$type,$default);"
Defines a keyword \f(CW$key\fR used in keyval arguments for the set \f(CW$keyset\fR.
If type is given, it defines the type of value that must be supplied,
such as \f(CW\*(AqDimension\*(Aq\fR. If \f(CW$default\fR is given, that value will be used
when \f(CW$key\fR is used without an equals and explicit value.
.IX Xref "DefKeyVal"
.SS "Access to State"
.IX Subsection "Access to State"
.ie n .IP """$value = LookupValue($name);""" 4
.el .IP "\f(CW$value = LookupValue($name);\fR" 4
.IX Item "$value = LookupValue($name);"
Lookup the current value associated with the the string \f(CW$name\fR.
.IX Xref "LookupValue"
.ie n .IP """AssignValue($name,$value,$scope);""" 4
.el .IP "\f(CWAssignValue($name,$value,$scope);\fR" 4
.IX Item "AssignValue($name,$value,$scope);"
Assign \f(CW$value\fR to be associated with the the string \f(CW$name\fR, according
to the given scoping rule.
.IX Xref "AssignValue"
.Sp
Values are also used to specify most configuration parameters (which can
therefor also be scoped). The recognized configuration parameters are:
.Sp
.Vb 12
\& VERBOSITY : the level of verbosity for debugging
\& output, with 0 being default.
\& STRICT : whether errors (eg. undefined macros)
\& are fatal.
\& INCLUDE_COMMENTS : whether to preserve comments in the
\& source, and to add occasional line
\& number comments. (Default true).
\& PRESERVE_NEWLINES : whether newlines in the source should
\& be preserved (not 100% TeX\-like).
\& By default this is true.
\& SEARCHPATHS : a list of directories to search for
\& sources, implementations, etc.
.Ve
.ie n .IP """PushValue($name,@values);""" 4
.el .IP "\f(CWPushValue($name,@values);\fR" 4
.IX Item "PushValue($name,@values);"
This function, along with the next three are like \f(CW\*(C`AssignValue\*(C'\fR,
but maintain a global list of values.
\&\f(CW\*(C`PushValue\*(C'\fR pushes the provided values onto the end of a list.
The data stored for \f(CW$name\fR is global and must be a \s-1LIST\s0 reference; it is created if needed.
.IX Xref "PushValue"
.ie n .IP """UnshiftValue($name,@values);""" 4
.el .IP "\f(CWUnshiftValue($name,@values);\fR" 4
.IX Item "UnshiftValue($name,@values);"
Similar to \f(CW\*(C`PushValue\*(C'\fR, but pushes a value onto the front of the list.
The data stored for \f(CW$name\fR is global and must be a \s-1LIST\s0 reference; it is created if needed.
.IX Xref "UnshiftValue"
.ie n .IP """PopValue($name);""" 4
.el .IP "\f(CWPopValue($name);\fR" 4
.IX Item "PopValue($name);"
Removes and returns the value on the end of the list named by \f(CW$name\fR.
The data stored for \f(CW$name\fR is global and must be a \s-1LIST\s0 reference.
Returns \f(CW\*(C`undef\*(C'\fR if there is no data in the list.
.IX Xref "PopValue"
.ie n .IP """ShiftValue($name);""" 4
.el .IP "\f(CWShiftValue($name);\fR" 4
.IX Item "ShiftValue($name);"
Removes and returns the first value in the list named by \f(CW$name\fR.
The data stored for \f(CW$name\fR is global and must be a \s-1LIST\s0 reference.
Returns \f(CW\*(C`undef\*(C'\fR if there is no data in the list.
.IX Xref "ShiftValue"
.ie n .IP """LookupMapping($name,$key);""" 4
.el .IP "\f(CWLookupMapping($name,$key);\fR" 4
.IX Item "LookupMapping($name,$key);"
This function maintains a hash association named by \f(CW$name\fR.
It returns the value associated with \f(CW$key\fR within that mapping.
The data stored for \f(CW$name\fR is global and must be a \s-1HASH\s0 reference.
Returns \f(CW\*(C`undef\*(C'\fR if there is no data associated with \f(CW$key\fR in the mapping,
or the mapping is not (yet) defined.
.IX Xref "LookupMapping"
.ie n .IP """AssignMapping($name,$key,$value);""" 4
.el .IP "\f(CWAssignMapping($name,$key,$value);\fR" 4
.IX Item "AssignMapping($name,$key,$value);"
This function associates \f(CW$value\fR with \f(CW$key\fR within the mapping named by \f(CW$name\fR.
The data stored for \f(CW$name\fR is global and must be a \s-1HASH\s0 reference; it is created if needed.
.IX Xref "AssignMapping"
.ie n .IP """$value = LookupCatcode($char);""" 4
.el .IP "\f(CW$value = LookupCatcode($char);\fR" 4
.IX Item "$value = LookupCatcode($char);"
Lookup the current catcode associated with the the character \f(CW$char\fR.
.IX Xref "LookupCatcode"
.ie n .IP """AssignCatcode($char,$catcode,$scope);""" 4
.el .IP "\f(CWAssignCatcode($char,$catcode,$scope);\fR" 4
.IX Item "AssignCatcode($char,$catcode,$scope);"
Set \f(CW$char\fR to have the given \f(CW$catcode\fR, with the assignment made
according to the given scoping rule.
.IX Xref "AssignCatcode"
.Sp
This method is also used to specify whether a given character is
active in math mode, by using \f(CW\*(C`math:$char\*(C'\fR for the character,
and using a value of 1 to specify that it is active.
.ie n .IP """$meaning = LookupMeaning($token);""" 4
.el .IP "\f(CW$meaning = LookupMeaning($token);\fR" 4
.IX Item "$meaning = LookupMeaning($token);"
Looks up the current meaning of the given \f(CW$token\fR which may be a
Definition, another token, or the token itself if it has not
otherwise been defined.
.IX Xref "LookupMeaning"
.ie n .IP """$defn = LookupDefinition($token);""" 4
.el .IP "\f(CW$defn = LookupDefinition($token);\fR" 4
.IX Item "$defn = LookupDefinition($token);"
Looks up the current definition, if any, of the \f(CW$token\fR.
.IX Xref "LookupDefinition"
.ie n .IP """InstallDefinition($defn);""" 4
.el .IP "\f(CWInstallDefinition($defn);\fR" 4
.IX Item "InstallDefinition($defn);"
Install the Definition \f(CW$defn\fR into \f(CW$STATE\fR under its
control sequence.
.IX Xref "InstallDefinition"
.SS "Font Encoding"
.IX Subsection "Font Encoding"
.ie n .IP """DeclareFontMap($name,$map,%options);""" 4
.el .IP "\f(CWDeclareFontMap($name,$map,%options);\fR" 4
.IX Item "DeclareFontMap($name,$map,%options);"
Declares a font map for the encoding \f(CW$name\fR. The map \f(CW$map\fR
is an array of 128 or 256 entries, each element is either a unicode
string for the representation of that codepoint, or undef if that
codepoint is not supported by this encoding. The only option
currently is \f(CW\*(C`family\*(C'\fR used because some fonts (notably cmr!)
have different glyphs in some font families, such as
\&\f(CW\*(C`family=\*(C'\fR'typewriter'>.
.ie n .IP """FontDecode($code,$encoding,$implicit);""" 4
.el .IP "\f(CWFontDecode($code,$encoding,$implicit);\fR" 4
.IX Item "FontDecode($code,$encoding,$implicit);"
Returns the unicode string representing the given codepoint \f(CW$code\fR
(an integer) in the given font encoding \f(CW$encoding\fR.
If \f(CW$encoding\fR is undefined, the usual case, the current font encoding
and font family is used for the lookup. Explicit decoding is
used when \f(CW\*(C`\e\echar\*(C'\fR or similar are invoked (\f(CW$implicit\fR is false), and
the codepoint must be represented in the fontmap, otherwise undef is returned.
Implicit decoding (ie. \f(CW$implicit\fR is true) occurs within the Stomach
when a Token's content is being digested and converted to a Box; in that case
only the lower 128 codepoints are converted; all codepoints above 128 are assumed to already be Unicode.
.Sp
The font map for \f(CW$encoding\fR is automatically loaded if it has not already been loaded.
.ie n .IP """FontDecodeString($string,$encoding,$implicit);""" 4
.el .IP "\f(CWFontDecodeString($string,$encoding,$implicit);\fR" 4
.IX Item "FontDecodeString($string,$encoding,$implicit);"
Returns the unicode string resulting from decoding the individual
characters in \f(CW$string\fR according to FontDecode, above.
.ie n .IP """LoadFontMap($encoding);""" 4
.el .IP "\f(CWLoadFontMap($encoding);\fR" 4
.IX Item "LoadFontMap($encoding);"
Finds and loads the font map for the encoding named \f(CW$encoding\fR, if it hasn't been
loaded before. It looks for \f(CW\*(C`encoding.fontmap.ltxml\*(C'\fR, which would typically define
the font map using \f(CW\*(C`DeclareFontMap\*(C'\fR, possibly including extra maps for families
like \f(CW\*(C`typewriter\*(C'\fR.
.SS "Color"
.IX Subsection "Color"
.ie n .IP """$color=LookupColor($name);""" 4
.el .IP "\f(CW$color=LookupColor($name);\fR" 4
.IX Item "$color=LookupColor($name);"
Lookup the color object associated with \f(CW$name\fR.
.ie n .IP """DefColor($name,$color,$scope);""" 4
.el .IP "\f(CWDefColor($name,$color,$scope);\fR" 4
.IX Item "DefColor($name,$color,$scope);"
Associates the \f(CW$name\fR with the given \f(CW$color\fR (a color object),
with the given scoping.
.ie n .IP """DefColorModel($model,$coremodel,$tocore,$fromcore);""" 4
.el .IP "\f(CWDefColorModel($model,$coremodel,$tocore,$fromcore);\fR" 4
.IX Item "DefColorModel($model,$coremodel,$tocore,$fromcore);"
Defines a color model \f(CW$model\fR that is derived from the core color
model \f(CW$coremodel\fR. The two functions \f(CW$tocore\fR and \f(CW$fromcore\fR
convert a color object in that model to the core model, or from the core model
to the derived model. Core models are rgb, cmy, cmyk, hsb and gray.
.SS "Low-level Functions"
.IX Subsection "Low-level Functions"
.ie n .IP """CleanID($id);""" 4
.el .IP "\f(CWCleanID($id);\fR" 4
.IX Item "CleanID($id);"
Cleans an \f(CW$id\fR of disallowed characters, trimming space.
.IX Xref "CleanID"
.ie n .IP """CleanLabel($label,$prefix);""" 4
.el .IP "\f(CWCleanLabel($label,$prefix);\fR" 4
.IX Item "CleanLabel($label,$prefix);"
Cleans a \f(CW$label\fR of disallowed characters, trimming space.
The prefix \f(CW$prefix\fR is prepended (or \f(CW\*(C`LABEL\*(C'\fR, if none given).
.IX Xref "CleanLabel"
.ie n .IP """CleanIndexKey($key);""" 4
.el .IP "\f(CWCleanIndexKey($key);\fR" 4
.IX Item "CleanIndexKey($key);"
Cleans an index key, so it can be used as an \s-1ID.\s0
.IX Xref "CleanIndexKey"
.ie n .IP """CleanBibKey($key);""" 4
.el .IP "\f(CWCleanBibKey($key);\fR" 4
.IX Item "CleanBibKey($key);"
Cleans a bibliographic citation key, so it can be used as an \s-1ID.\s0
.ie n .IP """CleanURL($url);""" 4
.el .IP "\f(CWCleanURL($url);\fR" 4
.IX Item "CleanURL($url);"
Cleans a url.
.IX Xref "CleanURL"
.ie n .IP """UTF($code);""" 4
.el .IP "\f(CWUTF($code);\fR" 4
.IX Item "UTF($code);"
Generates a \s-1UTF\s0 character, handy for the the 8 bit characters.
For example, \f(CW\*(C`UTF(0xA0)\*(C'\fR generates the non-breaking space.
.IX Xref "UTF"
.ie n .IP """MergeFont(%style);""" 4
.el .IP "\f(CWMergeFont(%style);\fR" 4
.IX Item "MergeFont(%style);"
Set the current font by merging the font style attributes with the current font.
The attributes and likely values (the values aren't required to be in this set):
.IX Xref "MergeFont"
.Sp
.Vb 7
\& family : serif, sansserif, typewriter, caligraphic,
\& fraktur, script
\& series : medium, bold
\& shape : upright, italic, slanted, smallcaps
\& size : tiny, footnote, small, normal, large,
\& Large, LARGE, huge, Huge
\& color : any named color, default is black
.Ve
.Sp
Some families will only be used in math.
This function returns nothing so it can be easily used in beforeDigest, afterDigest.
.ie n .IP """@tokens = roman($number);""" 4
.el .IP "\f(CW@tokens = roman($number);\fR" 4
.IX Item "@tokens = roman($number);"
Formats the \f(CW$number\fR in (lowercase) roman numerals, returning a list of the tokens.
.IX Xref "roman"
.ie n .IP """@tokens = Roman($number);""" 4
.el .IP "\f(CW@tokens = Roman($number);\fR" 4
.IX Item "@tokens = Roman($number);"
Formats the \f(CW$number\fR in (uppercase) roman numerals, returning a list of the tokens.
.IX Xref "Roman"
.SH "AUTHOR"
.IX Header "AUTHOR"
Bruce Miller
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Public domain software, produced as part of work done by the
United States Government & not subject to copyright in the \s-1US.\s0