§ LaTeXML::Package

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.

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:* {Token}[][]{}', ...

RequirePackage($package,%options);

Finds and loads a package implementation (usually *.sty.ltxml, unless raw is specified) for the required $package. The options are:

type=>type specifies

the file type (default sty.

options=>[...] specifies

a list of package options.

raw=>1 specifies that

it is allowable to try to read a raw TeX style file.

LoadClass($class,%options);

Finds and loads a class definition (usually *.cls.ltxml). The only option is

options=>[...] specifies

a list of class options.

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. The options are:

type=>type specifies

the file type (default sty.

raw=>1 specifies that

it is allowable to try to read a raw TeX style file.

DeclareOption($option,$code);

Declares an option for the current package or class. The $code can be a string or Tokens (which will be macro expanded), or can be a code reference which is treated as a primitive.

If a package or class wants to accomodate 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();

Processes the options that have been passed to the current package or class in a fashion similar to LaTeX. If the keyword inorder=>1 is given, the options are processed in the order they were used, like ProcessOptions*.

ExecuteOptions(@options);

Process the options given explicitly in @options.

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$ctr, 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

   idprefix  Specifies a prefix to be used when using this counter
             to generate ID's.
   nested    Not sure that this is even sane.

$num = CounterValue($ctr);

Fetches the value associated with the counter $ctr.

$tokens = StepCounter($ctr);

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

$keys = RefStepCounter($ctr);

Like \refstepcounter, it steps the counter and returns the keys refnum=$refnum, id=>$id>, making 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);

Analogous 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',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 and a unique counter.

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.

The recognized properties are:

autoOpen=>boolean

Specifies whether this $tag can be automatically opened if needed to insert an element that can only be contained by $tag. This property can help match the more SGML-like LaTeX to XML.

autoClose=>boolean

Specifies whether this $tag 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 XML.

afterOpen=>CODE($document,$box)

Provides CODE to be run whenever a node with this $tag 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.

afterClose=>CODE($document,$box)

Provides CODE to be run whenever a node with this $tag is closed. It is called with the document being constructed, and the initiating digested object as arguments.

RelaxNGSchema($schemaname);

Specifies the schema to use for determining document model. You can leave off the extension; it will look for .rng, and maybe eventually, .rnc once that is 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 (See DocType).

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.

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(CODE($document,@nodes));

CODE is called on each sequence of math nodes at a given level. If they should be replaced, return a list of ($n,$string,%attributes) to replace the text content of the first node with $string content and add the given attributes. The next $n-1 nodes are removed. If no replacement is called for, CODE should return undef.

Predefined Math Ligatures combine letter or digit Math Tokens (XMTok) into multicharacter symbols or numbers, depending on the font (non math italic).

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

The following select portions of the document:

label =>$label

Selects the part of the document with label=$label

scope =>$scope

The $scope could be "label:foo" or "section:1.2.3" or something similar. These select a subtree labelled 'foo', or a section with reference number "1.2.3"

xpath =>$xpath

Select those nodes matching an explicit xpath expression.

match =>$TeX

Selects nodes that look like what the processing of $TeX would produce.

regexp=>$regexp

Selects text nodes that match the regular expression.

The following act upon the selected node:

attributes =>$hash

Adds the attributes given in the hash reference to the node.

replace =>$replacement

Interprets the $replacement as TeX code to generate nodes that will replace the selected nodes.

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

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:

reversion=>CODE($arg,@values);

This CODE is responsible for converting a previously parsed argument back into a sequence of Token's.

optional=>boolean

whether it is an error if no matching input is found.

novalue=>boolean

whether the value returned should contribute to argument lists, or simply be passed over.

semiverbatim=>boolean

whether the catcode table should be modified before reading tokens.

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.

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

Reads an argument delimted by braces, while disabling most TeX catcodes.

$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($type,$name,@values);

This is like AssignValue, but pushes values onto the end of the value, which should be a LIST reference. Scoping is not handled here (yet?), it simply pushes the value onto the last binding of $name.

UnshiftValue($type,$name,@values);

Similar to PushValue, but pushes a value onto the front of the values, which should be a LIST reference.

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

CleanLabel($label,$prefix);

Cleans a $label of disallowed characters, and prepends $prefix (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.

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):

 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.

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