man LaTeXML::Package (3): Support for package implementations and document customization.

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 "LaTeXML/Package" directory for realistic examples.

package LaTeXML::Package::pool; # to put new subs & variables in common pool
use LaTeXML::Package; # to load these definitions
use strict; # good style
use warnings;
#
# Load "anotherpackage"
RequirePackage('anotherpackage');
#
# A simple macro, just like in TeX
DefMacro('\thesection', '\thechapter.\roman{section}');
#
# A constructor defines how a control sequence generates XML:
DefConstructor('\thanks{}', "<ltx:thanks>#1</ltx:thanks>");
#
# And a simple environment ...
DefEnvironment('{abstract}','<abstract>#body</abstract>');
#
# A math symbol \Real to stand for the Reals:
DefMath('\Real', "\x{211D}", role=>'ID');
#
# Or a semantic floor:
DefMath('\floor{}','\left\lfloor#1\right\rfloor');
#
# More esoteric ...
# Use a RelaxNG schema
RelaxNGSchema("MySchema");
# Or use a special DocType if you have to:
# DocType("rootelement",
# "-//Your Site//Your DocType",'your.dtd',
# prefix=>"http://whatever/");
#
# Allow sometag elements to be automatically closed if needed
Tag('prefix:sometag', autoClose=>1);
#
# Don't forget this, so perl knows the package loaded.
1;

DESCRIPTION

This module provides a large set of utilities and declarations that are useful for writing `bindings': LaTeXML-specific implementations of a set of control sequences such as would be defined in a LaTeX style or class file. They are also useful for controlling and customization of LaTeXML's processing. See the ``See also'' section, below, for additional lower-level modules imported & re-exported.

To a limited extent (and currently only when explicitly enabled), LaTeXML can process the raw TeX code found in style files. However, to preserve document structure and semantics, as well as for efficiency, it is usually necessary to supply a LaTeXML-specific `binding' for style and class files. For example, a binding "mypackage.sty.ltxml" would encode LaTeXML-specific implementations of all the control sequences in "mypackage.sty" so that "\usepackage{mypackage}" would work. Similarly for "myclass.cls.ltxml". Additionally, document-specific bindings can be supplied: before processing a TeX source file, eg "mydoc.tex", LaTeXML will automatically include the definitions and settings in "mydoc.latexml". These ".ltxml" and ".latexml" files should be placed LaTeXML's searchpaths, where will find them: either in the current directory or in a directory given to the --path option, or possibly added to the variable SEARCHPATHS).

Since LaTeXML mimics TeX, a familiarity with TeX's processing model is critical. LaTeXML models: catcodes and tokens (See LaTeXML::Core::Token, LaTeXML::Core::Tokens) which are extracted from the plain source text characters by the LaTeXML::Core::Mouth; ``Macros'', which are expanded within the LaTeXML::Core::Gullet; and ``Primitives'', which are digested within the LaTeXML::Core::Stomach to produce LaTeXML::Core::Box, LaTeXML::Core::List. A key additional feature is the ``Constructors'': when digested they generate a LaTeXML::Core::Whatsit which, upon absorbtion by LaTeXML::Core::Document, inserts text or XML fragments in the final document tree.

Notation: Many of the following forms take code references as arguments or options. That is, either a reference to a defined sub, eg. "\&somesub", or an anonymous function "sub { ... }". To document these cases, and the arguments that are passed in each case, we'll use a notation like "code($stomach,...)".

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 convienient 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]": reads an LaTeX-style optional argument.
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
"OptionalType": Similar to
"SkipType": Similar to "Optional"

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

Macros

"DefMacro(prototype, expansion, %options);": Defines the macro expansion for
"DefMacroI(cs, paramlist, expansion, %options);": Internal form of "DefMacro"

Conditionals

"DefConditional(prototype, test, %options);": Defines a conditional for
"DefConditionalI(cs, paramlist, test, %options);": Internal form of "DefConditional"
"IfCondition($ifcs,@args)": "IfCondition"

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
"DefPrimitiveI(cs, paramlist, code($stomach,@args), %options);": Internal form of "DefPrimitive"

Registers

"DefRegister(prototype, value, %options);": Defines a register with
"DefRegisterI(cs, paramlist, value, %options);": Internal form of "DefRegister"

Constructors

"DefConstructor(prototype, $replacement, %options);": The Constructor is where LaTeXML really starts getting interesting; invoking the control sequence will generate an arbitrary
"DefConstructorI(cs, paramlist, replacement, %options);": Internal form of "DefConstructor"
"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
"DefMathI(cs, paramlist, tex, %options);": Internal form of "DefMath"

Environments

"DefEnvironment(prototype, replacement, %options);": Defines an Environment that generates a specific
"DefEnvironmentI(name, paramlist, replacement, %options);": Internal form of "DefEnvironment"

Inputing Content and Definitions

"FindFile(name, %options);": Find an appropriate file with the given
"InputContent(request, %options);": "InputContent"
"Input(request);": "Input"
"InputDefinitions(request, %options);": "InputDefinitions"

Class and Packages

"RequirePackage(package, %options);": Finds and loads a package implementation (usually "
"LoadClass(class, %options);": Finds and loads a class definition (usually "
"LoadPool(pool, %options);": Loads a
"DeclareOption(option, tokens | string | code($stomach));": Declares an option for the current package or class. The 2nd argument can be a
"PassOptions(name, ext, @options); ">: Causes the given
"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"
"ExecuteOptions(@options);": Process the options given explicitly in
"AtBeginDocument(@stuff); ">: Arranges for
"AtEndDocument(@stuff)": Arranges for

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 "\the

"IDctrwithin

"idprefix=>string": Specifies a prefix to be used to generate
"nested": Not sure that this is even sane.

"$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
"RelaxNGSchema(schemaname);": Specifies the schema to use for determining document model. You can leave off the extension; it will look for "
"RegisterNamespace(prefix, URL);": Declares the
"RegisterDocumentNamespace(prefix, URL);": Declares the
"DocType(rootelement, publicid, systemid, %namespaces);": Declares the expected

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=>
"DefMathLigature(code($document,@nodes));"

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

"DefRewrite(%specification);"
"DefMathRewrite(: 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

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,
"<DefColumnType(proto, expansion);": Defines a new column type for tabular and arrays.
"DefKeyVal(keyset, key, type, default); ">: Defines a keyword

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 therefor also be scoped). The recognized configuration parameters are:

 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.

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

AUTHOR

Bruce Miller <[email protected]>

COPYRIGHT

Public domain software, produced as part of work done by the United States Government & not subject to copyright in the US.