Control Sequences¶

Many of the following forms define the behaviour of control sequences. While in TeX you'll typically only define macros, LaTeXML is effectively redefining TeX itself, so we define "Macros" as well as "Primitives", "Registers", "Constructors" and "Environments". These define the behaviour of these control sequences when processed during the various phases of LaTeX's imitation of TeX's digestive tract.

Prototypes

LaTeXML uses a more convenient method of specifying parameter patterns for control sequences. The first argument to each of these defining forms ("DefMacro", "DefPrimive", etc) is a prototype 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 "\def" or LaTeX's "\newcommand". Examples of the prototypes for familiar TeX or LaTeX control sequences are:

   DefConstructor('\usepackage[]{}',...
   DefPrimitive('\multiply Variable SkipKeyword:by Number',..
   DefPrimitive('\newcommand OptionalMatch:* DefToken[]{}', ...

The general syntax for parameter specification is

"{spec}"

reads a regular TeX argument. spec can be omitted (ie. "{}"). Otherwise spec is itself a parameter specification and the argument is reparsed to accordingly. ("{}" is a shorthand for "Plain".)

"[spec]"

reads an LaTeX-style optional argument. spec can be omitted (ie. "{}"). Otherwise, if spec is of the form Default:stuff, then stuff would be the default value. Otherwise spec is itself a parameter specification and the argument, if supplied, is reparsed according to that specification. ("[]" is a shorthand for "Optional".)

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. See the available types, below.

"Type:value | Type:value1:value2..."

These forms invoke the parser for Type but pass additional Tokens to the reader function. Typically this would supply defaults or parameters to a match.

"OptionalType"

Similar to Type, but it is not considered an error if the reader returns undef.

"SkipType"

Similar to "Optional"Type, but the value returned from the reader is ignored, and does not occupy a position in the arguments list.

The predefined argument Types are as follows.

"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 "Semiverbatim", many catcodes are disabled, which is handy for URL's, labels and similar.

"Token, XToken"

Read a single TeX Token. For "XToken", if the next token is expandable, it is repeatedly expanded until an unexpandable token remains, which is returned.

"Number, Dimension, Glue | MuGlue"

Read an Object corresponding to Number, Dimension, Glue or MuGlue, using TeX's rules for parsing these objects.

"Until:match | XUntil:"match>

Reads tokens until a match to the tokens match is found, returning the tokens preceding the match. This corresponds to TeX delimited arguments. For "XUntil", tokens are expanded as they are matched and accumulated (but a brace reads and accumulates till a matching close brace, without expanding).

"UntilBrace"

Reads tokens until the next open brace "{". This corresponds to the peculiar TeX construct "\def\foo#{...".

"Match:match(|match)* | Keyword:"match(|match)*>

Reads tokens expecting a match to one of the token lists match, returning the one that matches, or undef. For "Keyword", case and catcode of the matches are ignored. Additionally, any leading spaces are skipped.

"Balanced"

Read tokens until a closing }, but respecting nested {} pairs.

"BalancedParen"

Read a parenthesis delimited tokens, but does not balance any nested parentheses.

"Undigested, Digested, DigestUntil:match"

These types alter the usual sequence of tokenization and digestion in separate stages (like TeX). A "Undigested" parameter inhibits digestion completely and remains in token form. A "Digested" 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. "DigestUntil" digests tokens until a token matching match is found.

"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.

"SkipSpaces, Skip1Space"

Skips one, or any number of, space tokens, if present, but contributes nothing to the argument list.

Common Options

"scope=>'local' | 'global' | scope"

Most defining commands accept an option to control how the definition is stored, for global or local definitions, or using a named scope A named scope saves a set of definitions and values that can be activated at a later time.

Particularly interesting forms of scope are those that get automatically activated upon changes of counter and label. For example, definitions that have "scope=>'section:1.1'" will be activated when the section number is "1.1", and will be deactivated when that section ends.

"locked=>boolean"

This option controls whether this definition is locked from further changes in the TeX sources; this keeps local 'customizations' by an author from overriding important LaTeXML definitions and breaking the conversion.

"protected=>boolean"

Makes a definition "protected", in the sense of eTeX's "\protected" directive. This inhibits expansion under certain circumstances.

"robust=>boolean"

Makes a definition "robust", in the sense of LaTeX's "\DeclareRobustCommand". This essentially creates an indirect macro definition which is preceded by "\protect". This inhibits expansion (and argument processing!) under certain circumstances. It usually only makes sense for macros, but may be useful for Primitives, Constructors and DefMath in cases where LaTeX would normally have created a macro that needs protection.

Macros

"DefMacro(prototype, expansion, %options);"

Defines the macro expansion for prototype; a macro control sequence that is expanded during macro expansion time in the LaTeXML::Core::Gullet. The expansion should be one of tokens | string | code($gullet,@args)>: a string will be tokenized upon first usage. Any macro arguments will be substituted for parameter indicators (eg #1) in the tokens or tokenized string and the result is used as the expansion of the control sequence. If code is used, it is called at expansion time and should return a list of tokens as its result.

DefMacro options are

  DefMacro('\thefootnote','\arabic{footnote}');
  DefMacro('\today',sub { ExplodeText(today()); });

"DefMacroI(cs, paramlist, expansion, %options);"

Internal form of "DefMacro" 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 "undef" for paramlist), and useful for obscure cases like defining "\begin{something*}" as a Macro.

Conditionals

"DefConditional(prototype, test, %options);"

Defines a conditional for prototype; a control sequence that is processed during macro expansion time (in the LaTeXML::Core::Gullet). A conditional corresponds to a TeX "\if". If the test is "undef", a "\newif" type of conditional is defined, which is controlled with control sequences like "\footrue" and "\foofalse". Otherwise the test should be "code($gullet,@args)" (with the control sequence's arguments) that is called at expand time to determine the condition. 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.

DefConditional options are

  DefConditional('\ifmmode',sub {
     LookupValue('IN_MATH'); });

"DefConditionalI(cs, paramlist, test, %options);"

Internal form of "DefConditional" 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 "undef" for "paramlist").

"IfCondition($ifcs,@args)"

"IfCondition" allows you to test a conditional from within perl. Thus something like "if(IfCondition('\ifmmode')){ domath } else { dotext }" might be equivalent to TeX's "\ifmmode domath \else dotext \fi".

Primitives

"DefPrimitive(prototype, replacement, %options);"

Defines 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 XML. Primitive control sequences are also executed for side effect during digestion, effecting changes to the LaTeXML::Core::State.

The replacement can be a string used as the text content of a Box to be created (using the current font). Alternatively replacement can be "code($stomach,@args)" (with the control sequence's arguments) which is invoked at digestion time, probably for side-effect, but returning Boxes or Lists or nothing. replacement may also be undef, which contributes nothing to the document, but does record the TeX code that created it.

DefPrimitive options are

   DefPrimitive('\begingroup',sub { $_[0]->begingroup; });

"DefPrimitiveI(cs, paramlist, code($stomach,@args), %options);"

Internal form of "DefPrimitive" where the control sequence and parameter list have already been separated; useful for definitions from within code.

Registers

"DefRegister(prototype, value, %options);"

Defines a register with value as the initial value (a Number, Dimension, Glue, MuGlue or Tokens --- I haven't handled Box's yet). Usually, the prototype is just the control sequence, but registers are also handled by prototypes like "\count{Number}". "DefRegister" arranges that the register value can be accessed when a numeric, dimension, ... value is being read, and also defines the control sequence for assignment.

Options are

  DefRegister('\pretolerance',Number(100));

"DefRegisterI(cs, paramlist, value, %options);"

Internal form of "DefRegister" where the control sequence and parameter list have already been parsed; useful for definitions from within code.

Constructors

"DefConstructor(prototype, $replacement, %options);"

The Constructor is where LaTeXML really starts getting interesting; invoking the control sequence will generate an arbitrary XML 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 absorption by the LaTeXML::Core::Document, the "Whatsit" will generate the XML fragment according to replacement. The replacement can be "code($document,@args,%properties)" which is called during document absorption to create the appropriate XML (See the methods of LaTeXML::Core::Document).

More conveniently, replacement can be an pattern: simply a bit of XML as a string with certain substitutions to be made. The substitutions are of the following forms:

"DefConstructorI(cs, paramlist, replacement, %options);"

Internal form of "DefConstructor" where the control sequence and parameter list have already been separated; useful for definitions from within code.

"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 tex for the presentation. The content information is drawn from the name and options

"DefMath" accepts the options:

  DefMath('\infty',"\x{221E}",
     role=>'ID', meaning=>'infinity');

"DefMathI(cs, paramlist, tex, %options);"

Internal form of "DefMath" where the control sequence and parameter list have already been separated; useful for definitions from within code.

Environments

"DefEnvironment(prototype, replacement, %options);"

Defines an Environment that generates a specific XML fragment. "replacement" is of the same form as for DefConstructor, but will generally include reference to the "#body" property. Upon encountering a "\begin{env}": the mode is switched, if needed, else a new group is opened; then the environment name is noted; the beforeDigest hook is run. Then the Whatsit representing the begin command (but ultimately the whole environment) is created and the afterDigestBegin hook is run. Next, the body will be digested and collected until the balancing "\end{env}". Then, any afterDigest hook is run, the environment is ended, finally the mode is ended or the group is closed. The body and "\end{env}" whatsit are added to the "\begin{env}"'s whatsit as body and trailer, respectively.

"DefEnvironment" takes the following options:

  DefConstructor('\emph{}',
     "<ltx:emph>#1</ltx:emph", mode=>'text');

"DefEnvironmentI(name, paramlist, replacement, %options);"

Internal form of "DefEnvironment" where the control sequence and parameter list have already been separated; useful for definitions from within code.

Inputing Content and Definitions¶

"FindFile(name, %options);"

Find an appropriate file with the given name in the current directories in "SEARCHPATHS". If a file ending with ".ltxml" is found, it will be preferred.

Note that if the "name" starts with a recognized protocol (currently one of "(literal|http|https|ftp)") followed by a colon, the name is returned, as is, and no search for files is carried out.

The options are:

"InputContent(request, %options);"

"InputContent" 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.

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 "literal" pseudo-protocal may be used:

  InputContent('literal:\textit{Hey}');
    

If a file named "$request.latexml" 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.

The only option to "InputContent" is:

"Input(request);"

"Input" is analogous to LaTeX's "\input", 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.

"InputDefinitions(request, %options);"

"InputDefinitions" is used for loading definitions, 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").

Options for "InputDefinitions" are:

  InputDefinitions('tikz', type => 'sty', noltxml => 1);

Class and Packages¶

"RequirePackage(package, %options);"

Finds and loads a package implementation (usually "package.sty.ltxml", unless "noltxml" is specified)for the requested package. It returns the pathname of the loaded package. The options are:

"LoadClass(class, %options);"

Finds and loads a class definition (usually "class.cls.ltxml"). It returns the pathname of the loaded class. The only option is

"LoadPool(pool, %options);"

Loads a pool file (usually "pool.pool.ltxml"), one of the top-level definition files, such as TeX, LaTeX or AMSTeX. It returns the pathname of the loaded file.

"DeclareOption(option, tokens | string | code($stomach));"

Declares an option for the current package or class. The 2nd argument can be a string (which will be tokenized and expanded) or tokens (which will be macro expanded), to provide the value for the option, or it can be a code reference which is treated as a primitive for side-effect.

If a package or class wants to accommodate options, it should start with one or more "DeclareOptions", followed by "ProcessOptions()".

"PassOptions(name, ext, @options); "

Causes the given @options (strings) to be passed to the package (if ext is "sty") or class (if ext is "cls") named by name.

"ProcessOptions(%options);"

Processes the options that have been passed to the current package or class in a fashion similar to LaTeX. The only option (to "ProcessOptions" is "inorder=>boolean" indicating whehter the (package) options are processed in the order they were used, like "ProcessOptions*".

This will also process a limited form of keyval class and package options, if option "keysets" provides a list of keyval set names, and option "inorder" is true.

"ExecuteOptions(@options);"

Process the options given explicitly in @options.

"AtBeginDocument(@stuff); "

Arranges for @stuff to be carried out after the preamble, at the beginning of the document. @stuff should typically be macro-level stuff, but carried out for side effect; it should be tokens, tokens lists, strings (which will be tokenized), or "code($gullet)" which would yield tokens to be expanded.

This operation is useful for style files loaded with "--preload" or document specific customization files (ie. ending with ".latexml"); 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.

"AtEndDocument(@stuff)"

Arranges for @stuff to be carried out just before "\\end{document}". These tokens can be used for side effect, or any content they generate will appear as the last children of the document.

Counters and IDs¶

"NewCounter(ctr, within, %options);"

Defines a new counter, like LaTeX's \newcounter, but extended. It defines a counter that can be used to generate reference numbers, and defines "\thectr", etc. It also defines an "uncounter" which can be used to generate ID's (xml:id) for unnumbered objects. ctr is the name of the counter. If defined, within is the name of another counter which, when incremented, will cause this counter to be reset. The options are

"$num = CounterValue($ctr);"

Fetches the value associated with the counter $ctr.

"$tokens = StepCounter($ctr);"

Analog of "\stepcounter", steps the counter and returns the expansion of "\the$ctr". Usually you should use "RefStepCounter($ctr)" instead.

"$keys = RefStepCounter($ctr);"

Analog of "\refstepcounter", steps the counter and returns a hash containing the keys "refnum="$refnum, id=>$id>. This makes it suitable for use in a "properties" option to constructors. The "id" is generated in parallel with the reference number to assist debugging.

"$keys = RefStepID($ctr);"

Like to "RefStepCounter", but only steps the "uncounter", and returns only the id; This is useful for unnumbered cases of objects that normally get both a refnum and id.

"ResetCounter($ctr);"

Resets the counter $ctr to zero.

"GenerateID($document,$node,$whatsit,$prefix);"

Generates an ID 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'); })
    

If $node 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.

Document Model¶

Constructors define how TeX markup will generate XML fragments, but the Document Model is used to control exactly how those fragments are assembled.

"Tag(tag, %properties);"

Declares properties of elements with the name tag. Note that "Tag" can set or add properties to any element from any binding file, unlike the properties set on control by "DefPrimtive", "DefConstructor", 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.

The tag can be specified in one of three forms:

   prefix:name matches specific name in specific namespace
   prefix:*    matches any tag in the specific namespace;
   *           matches any tag in any namespace.
    

There are two kinds of properties:

"RelaxNGSchema(schemaname);"

Specifies the schema to use for determining document model. You can leave off the extension; it will look for "schemaname.rng" (and maybe eventually, ".rnc" if that is ever implemented).

"RegisterNamespace(prefix, URL);"

Declares the prefix to be associated with the given URL. 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 "#default" for the default, non-prefixed, namespace. (See RegisterDocumentNamespace, as well as DocType or RelaxNGSchema).

"RegisterDocumentNamespace(prefix, URL);"

Declares the prefix to be associated with the given URL used within the generated XML. 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 DTD or Schema themselves Use the prefix "#default" for the default, non-prefixed, namespace. (See DocType or RelaxNGSchema).

"DocType(rootelement, publicid, systemid, %namespaces);"

Declares the expected rootelement, the public and system ID's of the document type to be used in the final document. The hash %namespaces specifies the namespaces prefixes that are expected to be found in the DTD, along with each associated namespace URI. Use the prefix "#default" for the default namespace (ie. the namespace of non-prefixed elements in the DTD).

The prefixes defined for the DTD may be different from the prefixes used in implementation CODE (eg. in ltxml files; see RegisterNamespace). The generated document will use the namespaces and prefixes defined for the DTD.

Document Rewriting¶

During document construction, as each node gets closed, the text content gets simplfied. We'll call it applying ligatures, for lack of a better name.

"DefLigature(regexp, %options);"

Apply the regular expression (given as a string: "/fa/fa/" since it will be converted internally to a true regexp), to the text content. The only option is "fontTest=>code($font)"; if given, then the substitution is applied only when "fontTest" returns true.

Predefined Ligatures combine sequences of "." or single-quotes into appropriate Unicode characters.

"DefMathLigature($string"=""$replacment,%options);>

A Math Ligature typically combines a sequence of math tokens (XMTok) into a single one. A simple example is

   DefMathLigature(":=" => ":=", role => 'RELOP', meaning => 'assign');
    

replaces the two tokens for colon and equals by a token representing assignment. The options are those characterising an XMTok, namely: "role", "meaning" and "name".

For more complex cases (recognizing numbers, for example), you may supply a function "matcher="CODE($document,$node)>, which is passed the current document and the last math node in the sequence. It should examine $node and any preceding nodes (using "previousSibling") and return a list of "($n,$string,%attributes)" to replace the $n nodes by a new one with text content being $string content and the given attributes. If no replacement is called for, CODE should return undef.

After document construction, various rewriting and augmenting of the document can take place.

"DefRewrite(%specification);"

"DefMathRewrite(%specification);"

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 %specification consists of a sequence 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.

The following select portions of the document:

Mid-Level support¶

"$tokens = Expand($tokens);"

Expands the given $tokens according to current definitions.

"$boxes = Digest($tokens);"

Processes and digestes the $tokens. Any arguments needed by control sequences in $tokens must be contained within the $tokens itself.

"@tokens = Invocation($cs,@args);"

Constructs a sequence of tokens that would invoke the token $cs on the arguments.

"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.

"Let($token1,$token2);"

Gives $token1 the same `meaning' (definition) as $token2; like TeX's \let.

"StartSemiVerbatim(); ... ; EndSemiVerbatim();"

Disable disable most TeX catcodes.

"$tokens = Tokenize($string);"

Tokenizes the $string using the standard catcodes, returning a LaTeXML::Core::Tokens.

"$tokens = TokenizeInternal($string);"

Tokenizes the $string according to the internal cattable (where @ is a letter), returning a LaTeXML::Core::Tokens.

Argument Readers¶

"ReadParameters($gullet,$spec);"

Reads from $gullet the tokens corresponding to $spec (a Parameters object).

"DefParameterType(type, code($gullet,@values), %options);"

Defines a new Parameter type, type, with code for its reader.

Options are:

"<DefColumnType(proto, expansion);"

Defines a new column type for tabular and arrays. proto is the prototype for the pattern, analogous to the pattern used for other definitions, except that macro being defined is a single character. The expansion is a string specifying what it should expand into, typically more verbose column specification.

Access to State¶

"$value = LookupValue($name);"

Lookup the current value associated with the the string $name.

"AssignValue($name,$value,$scope);"

Assign $value to be associated with the the string $name, according to the given scoping rule.

Values are also used to specify most configuration parameters (which can therefore also be scoped). The recognized configuration parameters are:

 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.
    

"PushValue($name,@values);"

This function, along with the next three are like "AssignValue", but maintain a global list of values. "PushValue" pushes the provided values onto the end of a list. The data stored for $name is global and must be a LIST reference; it is created if needed.

"UnshiftValue($name,@values);"

Similar to "PushValue", but pushes a value onto the front of the list. The data stored for $name is global and must be a LIST reference; it is created if needed.

"PopValue($name);"

Removes and returns the value on the end of the list named by $name. The data stored for $name is global and must be a LIST reference. Returns "undef" if there is no data in the list.

"ShiftValue($name);"

Removes and returns the first value in the list named by $name. The data stored for $name is global and must be a LIST reference. Returns "undef" if there is no data in the list.

"LookupMapping($name,$key);"

This function maintains a hash association named by $name. It returns the value associated with $key within that mapping. The data stored for $name is global and must be a HASH reference. Returns "undef" if there is no data associated with $key in the mapping, or the mapping is not (yet) defined.

"AssignMapping($name,$key,$value);"

This function associates $value with $key within the mapping named by $name. The data stored for $name is global and must be a HASH reference; it is created if needed.

"$value = LookupCatcode($char);"

Lookup the current catcode associated with the the character $char.

"AssignCatcode($char,$catcode,$scope);"

Set $char to have the given $catcode, with the assignment made according to the given scoping rule.

This method is also used to specify whether a given character is active in math mode, by using "math:$char" for the character, and using a value of 1 to specify that it is active.

"$meaning = LookupMeaning($token);"

Looks up the current meaning of the given $token which may be a Definition, another token, or the token itself if it has not otherwise been defined.

"$defn = LookupDefinition($token);"

Looks up the current definition, if any, of the $token.

"InstallDefinition($defn);"

Install the Definition $defn into $STATE under its control sequence.

"XEquals($token1,$token2)"

Tests whether the two tokens are equal in the sense that they are either equal tokens, or if defined, have the same definition.

Fonts¶

"MergeFont(%fontspec); "

Set the current font by merging the font style attributes with the current font. The %fontspec specifies the properties of the desired font. Likely values include (the values aren't required to be in this set):

 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
    

Some families will only be used in math. This function returns nothing so it can be easily used in beforeDigest, afterDigest.

"DeclareFontMap($name,$map,%options);"

Declares a font map for the encoding $name. The map $map 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 "family" used because some fonts (notably cmr!) have different glyphs in some font families, such as "family="'typewriter'>.

"FontDecode($code,$encoding,$implicit);"

Returns the unicode string representing the given codepoint $code (an integer) in the given font encoding $encoding. If $encoding is undefined, the usual case, the current font encoding and font family is used for the lookup. Explicit decoding is used when "\\char" or similar are invoked ($implicit is false), and the codepoint must be represented in the fontmap, otherwise undef is returned. Implicit decoding (ie. $implicit 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.

The font map for $encoding is automatically loaded if it has not already been loaded.

"FontDecodeString($string,$encoding,$implicit);"

Returns the unicode string resulting from decoding the individual characters in $string according to FontDecode, above.

"LoadFontMap($encoding);"

Finds and loads the font map for the encoding named $encoding, if it hasn't been loaded before. It looks for "encoding.fontmap.ltxml", which would typically define the font map using "DeclareFontMap", possibly including extra maps for families like "typewriter".

Color¶

"$color=LookupColor($name);"

Lookup the color object associated with $name.

"DefColor($name,$color,$scope);"

Associates the $name with the given $color (a color object), with the given scoping.

"DefColorModel($model,$coremodel,$tocore,$fromcore);"

Defines a color model $model that is derived from the core color model $coremodel. The two functions $tocore and $fromcore 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.

Low-level Functions¶

"CleanID($id);"

Cleans an $id of disallowed characters, trimming space.

"CleanLabel($label,$prefix);"

Cleans a $label of disallowed characters, trimming space. The prefix $prefix is prepended (or "LABEL", if none given).

"CleanIndexKey($key);"

Cleans an index key, so it can be used as an ID.

"CleanBibKey($key);"

Cleans a bibliographic citation key, so it can be used as an ID.

"CleanURL($url);"

Cleans a url.

"UTF($code);"

Generates a UTF character, handy for the the 8 bit characters. For example, "UTF(0xA0)" generates the non-breaking space.

"@tokens = roman($number);"

Formats the $number in (lowercase) roman numerals, returning a list of the tokens.

"@tokens = Roman($number);"

Formats the $number in (uppercase) roman numerals, returning a list of the tokens.