1LaTeXML::Package(3)   User Contributed Perl Documentation  LaTeXML::Package(3)
2
3
4

NAME

6       "LaTeXML::Package" - Support for package implementations and document
7       customization.
8

SYNOPSIS

10       This package defines and exports most of the procedures users will need
11       to customize or extend LaTeXML. The LaTeXML implementation of some
12       package might look something like the following, but see the installed
13       "LaTeXML/Package" directory for realistic examples.
14
15         package LaTeXML::Package::pool;  # to put new subs & variables in common pool
16         use LaTeXML::Package;            # to load these definitions
17         use strict;                      # good style
18         use warnings;
19         #
20         # Load "anotherpackage"
21         RequirePackage('anotherpackage');
22         #
23         # A simple macro, just like in TeX
24         DefMacro('\thesection', '\thechapter.\roman{section}');
25         #
26         # A constructor defines how a control sequence generates XML:
27         DefConstructor('\thanks{}', "<ltx:thanks>#1</ltx:thanks>");
28         #
29         # And a simple environment ...
30         DefEnvironment('{abstract}','<abstract>#body</abstract>');
31         #
32         # A math  symbol \Real to stand for the Reals:
33         DefMath('\Real', "\x{211D}", role=>'ID');
34         #
35         # Or a semantic floor:
36         DefMath('\floor{}','\left\lfloor#1\right\rfloor');
37         #
38         # More esoteric ...
39         # Use a RelaxNG schema
40         RelaxNGSchema("MySchema");
41         # Or use a special DocType if you have to:
42         # DocType("rootelement",
43         #         "-//Your Site//Your DocType",'your.dtd',
44         #          prefix=>"http://whatever/");
45         #
46         # Allow sometag elements to be automatically closed if needed
47         Tag('prefix:sometag', autoClose=>1);
48         #
49         # Don't forget this, so perl knows the package loaded.
50         1;
51

DESCRIPTION

53       This module provides a large set of utilities and declarations that are
54       useful for writing `bindings': LaTeXML-specific implementations of a
55       set of control sequences such as would be defined in a LaTeX style or
56       class file. They are also useful for controlling and customization of
57       LaTeXML's processing.  See the "See also" section, below, for
58       additional lower-level modules imported & re-exported.
59
60       To a limited extent (and currently only when explicitly enabled),
61       LaTeXML can process the raw TeX code found in style files.  However, to
62       preserve document structure and semantics, as well as for efficiency,
63       it is usually necessary to supply a LaTeXML-specific `binding' for
64       style and class files. For example, a binding "mypackage.sty.ltxml"
65       would encode LaTeXML-specific implementations of all the control
66       sequences in "mypackage.sty" so that "\usepackage{mypackage}" would
67       work.  Similarly for "myclass.cls.ltxml".  Additionally, document-
68       specific bindings can be supplied: before processing a TeX source file,
69       eg "mydoc.tex", LaTeXML will automatically include the definitions and
70       settings in "mydoc.latexml".  These ".ltxml" and ".latexml" files
71       should be placed LaTeXML's searchpaths, where will find them: either in
72       the current directory or in a directory given to the --path option, or
73       possibly added to the variable SEARCHPATHS).
74
75       Since LaTeXML mimics TeX, a familiarity with TeX's processing model is
76       critical.  LaTeXML models: catcodes and tokens (See
77       LaTeXML::Core::Token,  LaTeXML::Core::Tokens) which are extracted from
78       the plain source text characters by the LaTeXML::Core::Mouth; "Macros",
79       which are expanded within the LaTeXML::Core::Gullet; and "Primitives",
80       which are digested within the LaTeXML::Core::Stomach to produce
81       LaTeXML::Core::Box, LaTeXML::Core::List.  A key additional feature is
82       the "Constructors": when digested they generate a
83       LaTeXML::Core::Whatsit which, upon absorption by
84       LaTeXML::Core::Document, inserts text or XML fragments in the final
85       document tree.
86
87       Notation: Many of the following forms take code references as arguments
88       or options.  That is, either a reference to a defined sub, eg.
89       "\&somesub", or an anonymous function "sub { ... }".  To document these
90       cases, and the arguments that are passed in each case, we'll use a
91       notation like "code($stomach,...)".
92
93   Control Sequences
94       Many of the following forms define the behaviour of control sequences.
95       While in TeX you'll typically only define macros, LaTeXML is
96       effectively redefining TeX itself, so we define "Macros" as well as
97       "Primitives", "Registers", "Constructors" and "Environments".  These
98       define the behaviour of these control sequences when processed during
99       the various phases of LaTeX's imitation of TeX's digestive tract.
100
101       Prototypes
102
103       LaTeXML uses a more convenient method of specifying parameter patterns
104       for control sequences. The first argument to each of these defining
105       forms ("DefMacro", "DefPrimive", etc) is a prototype consisting of the
106       control sequence being defined along with the specification of
107       parameters required by the control sequence.  Each parameter describes
108       how to parse tokens following the control sequence into arguments or
109       how to delimit them.  To simplify coding and capture common idioms in
110       TeX/LaTeX programming, latexml's parameter specifications are more
111       expressive than TeX's  "\def" or LaTeX's "\newcommand".  Examples of
112       the prototypes for familiar TeX or LaTeX control sequences are:
113
114          DefConstructor('\usepackage[]{}',...
115          DefPrimitive('\multiply Variable SkipKeyword:by Number',..
116          DefPrimitive('\newcommand OptionalMatch:* DefToken[]{}', ...
117
118       The general syntax for parameter specification is
119
120       "{spec}"
121           reads a regular TeX argument.  spec can be omitted (ie. "{}").
122           Otherwise spec is itself a parameter specification and the argument
123           is reparsed to accordingly.  ("{}" is a shorthand for "Plain".)
124
125       "[spec]"
126           reads an LaTeX-style optional argument.  spec can be omitted (ie.
127           "{}").  Otherwise, if spec is of the form Default:stuff, then stuff
128           would be the default value.  Otherwise spec is itself a parameter
129           specification and the argument, if supplied, is reparsed according
130           to that specification.  ("[]" is a shorthand for "Optional".)
131
132       Type
133           Reads an argument of the given type, where either Type has been
134           declared, or there exists a ReadType function accessible from
135           LaTeXML::Package::Pool.  See the available types, below.
136
137       "Type:value | Type:value1:value2..."
138           These forms invoke the parser for Type but pass additional Tokens
139           to the reader function.  Typically this would supply defaults or
140           parameters to a match.
141
142       "OptionalType"
143           Similar to Type, but it is not considered an error if the reader
144           returns undef.
145
146       "SkipType"
147           Similar to "Optional"Type, but the value returned from the reader
148           is ignored, and does not occupy a position in the arguments list.
149
150       The predefined argument Types are as follows.
151
152       "Plain, Semiverbatim"
153
154           Reads a standard TeX argument being either the next token, or if
155           the next token is an {, the balanced token list.  In the case of
156           "Semiverbatim", many catcodes are disabled, which is handy for
157           URL's, labels and similar.
158
159       "Token, XToken"
160
161           Read a single TeX Token.  For "XToken", if the next token is
162           expandable, it is repeatedly expanded until an unexpandable token
163           remains, which is returned.
164
165       "Number, Dimension, Glue | MuGlue"
166
167           Read an Object corresponding to Number, Dimension, Glue or MuGlue,
168           using TeX's rules for parsing these objects.
169
170       "Until:match | XUntil:"match>
171
172           Reads tokens until a match to the tokens match is found, returning
173           the tokens preceding the match. This corresponds to TeX delimited
174           arguments.  For "XUntil", tokens are expanded as they are matched
175           and accumulated (but a brace reads and accumulates till a matching
176           close brace, without expanding).
177
178       "UntilBrace"
179
180           Reads tokens until the next open brace "{".  This corresponds to
181           the peculiar TeX construct "\def\foo#{...".
182
183       "Match:match(|match)* | Keyword:"match(|match)*>
184
185           Reads tokens expecting a match to one of the token lists match,
186           returning the one that matches, or undef.  For "Keyword", case and
187           catcode of the matches are ignored.  Additionally, any leading
188           spaces are skipped.
189
190       "Balanced"
191
192           Read tokens until a closing }, but respecting nested {} pairs.
193
194       "BalancedParen"
195
196           Read a parenthesis delimited tokens, but does not balance any
197           nested parentheses.
198
199       "Undigested, Digested, DigestUntil:match"
200
201           These types alter the usual sequence of tokenization and digestion
202           in separate stages (like TeX).  A "Undigested" parameter inhibits
203           digestion completely and remains in token form.  A "Digested"
204           parameter gets digested until the (required) opening { is balanced;
205           this is useful when the content would usually need to have been
206           protected in order to correctly deal with catcodes.  "DigestUntil"
207           digests tokens until a token matching match is found.
208
209       "Variable"
210
211           Reads a token, expanding if necessary, and expects a control
212           sequence naming a writable register.  If such is found, it returns
213           an array of the corresponding definition object, and any arguments
214           required by that definition.
215
216       "SkipSpaces, Skip1Space"
217
218           Skips one, or any number of, space tokens, if present, but
219           contributes nothing to the argument list.
220
221       Common Options
222
223       "scope=>'local' | 'global' | scope"
224           Most defining commands accept an option to control how the
225           definition is stored, for global or local definitions, or using a
226           named scope A named scope saves a set of definitions and values
227           that can be activated at a later time.
228
229           Particularly interesting forms of scope are those that get
230           automatically activated upon changes of counter and label.  For
231           example, definitions that have "scope=>'section:1.1'"  will be
232           activated when the section number is "1.1", and will be deactivated
233           when that section ends.
234
235       "locked=>boolean"
236           This option controls whether this definition is locked from further
237           changes in the TeX sources; this keeps local 'customizations' by an
238           author from overriding important LaTeXML definitions and breaking
239           the conversion.
240
241       "protected=>boolean"
242           Makes a definition "protected", in the sense of eTeX's "\protected"
243           directive.  This inhibits expansion under certain circumstances.
244
245       "robust=>boolean"
246           Makes a definition "robust", in the sense of LaTeX's
247           "\DeclareRobustCommand".  This essentially creates an indirect
248           macro definition which is preceded by "\protect".  This inhibits
249           expansion (and argument processing!) under certain circumstances.
250           It usually only makes sense for macros, but may be useful for
251           Primitives, Constructors and DefMath in cases where LaTeX would
252           normally have created a macro that needs protection.
253
254       Macros
255
256       "DefMacro(prototype, expansion, %options);"
257
258           Defines the macro expansion for prototype; a macro control sequence
259           that is expanded during macro expansion time in the
260           LaTeXML::Core::Gullet.  The expansion should be one of tokens |
261           string | code($gullet,@args)>: a string will be tokenized upon
262           first usage.  Any macro arguments will be substituted for parameter
263           indicators (eg #1) in the tokens or tokenized string and the result
264           is used as the expansion of the control sequence. If code is used,
265           it is called at expansion time and should return a list of tokens
266           as its result.
267
268           DefMacro options are
269
270           "scope=>scope",
271           "locked=>boolean"
272               See "Common Options".
273
274           "mathactive=>boolean"
275               specifies a definition that will only be expanded in math mode;
276               the control sequence must be a single character.
277
278           Examples:
279
280             DefMacro('\thefootnote','\arabic{footnote}');
281             DefMacro('\today',sub { ExplodeText(today()); });
282
283       "DefMacroI(cs, paramlist, expansion, %options);"
284
285           Internal form of "DefMacro" where the control sequence and
286           parameter list have already been separated; useful for definitions
287           from within code.  Also, slightly more efficient for macros with no
288           arguments (use "undef" for paramlist), and useful for obscure cases
289           like defining "\begin{something*}" as a Macro.
290
291       Conditionals
292
293       "DefConditional(prototype, test, %options);"
294
295           Defines a conditional for prototype; a control sequence that is
296           processed during macro expansion time (in the
297           LaTeXML::Core::Gullet).  A conditional corresponds to a TeX "\if".
298           If the test is "undef", a "\newif" type of conditional is defined,
299           which is controlled with control sequences like "\footrue" and
300           "\foofalse".  Otherwise the test should be "code($gullet,@args)"
301           (with the control sequence's arguments) that is called at expand
302           time to determine the condition.  Depending on whether the result
303           of that evaluation returns a true or false value (in the usual Perl
304           sense), the result of the expansion is either the first or else
305           code following, in the usual TeX sense.
306
307           DefConditional options are
308
309           "scope=>scope",
310           "locked=>boolean"
311               See "Common Options".
312
313           "skipper=>code($gullet)"
314               This option is only used to define "\ifcase".
315
316           Example:
317
318             DefConditional('\ifmmode',sub {
319                LookupValue('IN_MATH'); });
320
321       "DefConditionalI(cs, paramlist, test, %options);"
322
323           Internal form of "DefConditional" where the control sequence and
324           parameter list have already been parsed; useful for definitions
325           from within code.  Also, slightly more efficient for conditinal
326           with no arguments (use "undef" for "paramlist").
327
328       "IfCondition($ifcs,@args)"
329
330           "IfCondition" allows you to test a conditional from within perl.
331           Thus something like "if(IfCondition('\ifmmode')){ domath } else {
332           dotext }" might be equivalent to TeX's "\ifmmode domath \else
333           dotext \fi".
334
335       Primitives
336
337       "DefPrimitive(prototype, replacement, %options);"
338
339           Defines a primitive control sequence; a primitive is processed
340           during digestion (in the  LaTeXML::Core::Stomach), after macro
341           expansion but before Construction time.  Primitive control
342           sequences generate Boxes or Lists, generally containing basic
343           Unicode content, rather than structured XML.  Primitive control
344           sequences are also executed for side effect during digestion,
345           effecting changes to the LaTeXML::Core::State.
346
347           The replacement can be a string used as the text content of a Box
348           to be created (using the current font).  Alternatively replacement
349           can be "code($stomach,@args)" (with the control sequence's
350           arguments) which is invoked at digestion time, probably for side-
351           effect, but returning Boxes or Lists or nothing.  replacement may
352           also be undef, which contributes nothing to the document, but does
353           record the TeX code that created it.
354
355           DefPrimitive options are
356
357           "scope=>scope",
358           "locked=>boolean"
359               See "Common Options".
360
361           "mode=> ('text' | 'display_math' | 'inline_math')"
362               Changes to this mode during digestion.
363
364           "font=>{%fontspec}"
365               Specifies the font to use (see "Fonts").  If the font change is
366               to only apply to material generated within this command, you
367               would also use "<bounded="1>>; otherwise, the font will remain
368               in effect afterwards as for a font switching command.
369
370           "bounded=>boolean"
371               If true, TeX grouping (ie. "{}") is enforced around this
372               invocation.
373
374           "requireMath=>boolean",
375           "forbidMath=>boolean"
376               specifies whether the given constructor can only appear, or
377               cannot appear, in math mode.
378
379           "beforeDigest=>code($stomach)"
380               supplies a hook to execute during digestion just before the
381               main part of the primitive is executed (and before any
382               arguments have been read).  The code should either return
383               nothing (return;) or a list of digested items
384               (Box's,List,Whatsit).  It can thus change the State and/or add
385               to the digested output.
386
387           "afterDigest=>code($stomach)"
388               supplies a hook to execute during digestion just after the main
389               part of the primitive ie executed.  it should either return
390               nothing (return;) or digested items.  It can thus change the
391               State and/or add to the digested output.
392
393           "isPrefix=>boolean"
394               indicates whether this is a prefix type of command; This is
395               only used for the special TeX assignment prefixes, like
396               "\global".
397
398           Example:
399
400              DefPrimitive('\begingroup',sub { $_[0]->begingroup; });
401
402       "DefPrimitiveI(cs, paramlist, code($stomach,@args), %options);"
403
404           Internal form of "DefPrimitive" where the control sequence and
405           parameter list have already been separated; useful for definitions
406           from within code.
407
408       Registers
409
410       "DefRegister(prototype, value, %options);"
411
412           Defines a register with value as the initial value (a Number,
413           Dimension, Glue, MuGlue or Tokens --- I haven't handled Box's yet).
414           Usually, the prototype is just the control sequence, but registers
415           are also handled by prototypes like "\count{Number}". "DefRegister"
416           arranges that the register value can be accessed when a numeric,
417           dimension, ... value is being read, and also defines the control
418           sequence for assignment.
419
420           Options are
421
422           "readonly=>boolean"
423               specifies if it is not allowed to change this value.
424
425           "getter=>code(@args)",
426           "setter=>code($value,@args)"
427               By default value is stored in the State's Value table under a
428               name concatenating the control sequence and argument values.
429               These options allow other means of fetching and storing the
430               value.
431
432           Example:
433
434             DefRegister('\pretolerance',Number(100));
435
436       "DefRegisterI(cs, paramlist, value, %options);"
437
438           Internal form of "DefRegister" where the control sequence and
439           parameter list have already been parsed; useful for definitions
440           from within code.
441
442       Constructors
443
444       "DefConstructor(prototype, $replacement, %options);"
445
446           The Constructor is where LaTeXML really starts getting interesting;
447           invoking the control sequence will generate an arbitrary XML
448           fragment in the document tree.  More specifically: during
449           digestion, the arguments will be read and digested, creating a
450           LaTeXML::Core::Whatsit to represent the object. During absorption
451           by the LaTeXML::Core::Document, the "Whatsit" will generate the XML
452           fragment according to replacement. The replacement can be
453           "code($document,@args,%properties)" which is called during document
454           absorption to create the appropriate XML (See the methods of
455           LaTeXML::Core::Document).
456
457           More conveniently, replacement can be an pattern: simply a bit of
458           XML as a string with certain substitutions to be made. The
459           substitutions are of the following forms:
460
461           "#1, #2 ... #name"
462               These are replaced by the corresponding argument (for #1) or
463               property (for #name) stored with the Whatsit. Each are turned
464               into a string when it appears as in an attribute position, or
465               recursively processed when it appears as content.
466
467           "&function(@args)"
468               Another form of substituted value is prefixed with "&" which
469               invokes a function.  For example,  &func(#1)  would invoke the
470               function "func" on the first argument to the control sequence;
471               what it returns will be inserted into the document.
472
473           "?test(pattern)"  or "?test(ifpattern)(elsepattern)"
474               Patterns can be conditionallized using this form.  The test is
475               any of the above expressions (eg. "#1"), considered true if the
476               result is non-empty.  Thus "?#1(<foo/>)" would add the empty
477               element "foo" if the first argument were given.
478
479           "^" If the constructor begins with "^", the XML fragment is allowed
480               to float up to a parent node that is allowed to contain it,
481               according to the Document Type.
482
483           The Whatsit property "font" is defined by default.  Additional
484           properties "body" and "trailer" are defined when "captureBody" is
485           true, or for environments.  By using
486           "$whatsit->setProperty(key=>$value);" within "afterDigest", or by
487           using the "properties" option, other properties can be added.
488
489           DefConstructor options are
490
491           "scope=>scope",
492           "locked=>boolean"
493               See "Common Options".
494
495           "mode=>mode",
496           "font=>{%fontspec}",
497           "bounded=>boolean",
498           "requireMath=>boolean",
499           "forbidMath=>boolean"
500               These options are the same as for "Primitives"
501
502           "reversion=>texstring | code($whatsit,#1,#2,...)"
503               specifies the reversion of the invocation back into TeX tokens
504               (if the default reversion is not appropriate).  The textstring
505               string can include "#1", "#2"...  The code is called with the
506               $whatsit and digested arguments and must return a list of
507               Token's.
508
509           "alias=>control_sequence"
510               provides a control sequence to be used in the "reversion"
511               instead of the one defined in the "prototype".  This is a
512               convenient alternative for reversion when a 'public' command
513               conditionally expands into an internal one, but the reversion
514               should be for the public command.
515
516           "sizer=>string | code($whatsit)"
517               specifies how to compute (approximate) the displayed size of
518               the object, if that size is ever needed (typically needed for
519               graphics generation).  If a string is given, it should contain
520               only a sequence of "#1" or "#name" to access arguments and
521               properties of the Whatsit: the size is computed from these
522               items layed out side-by-side.  If code is given, it should
523               return the three Dimensions (width, height and depth).  If
524               neither is given, and the "reversion" specification is of
525               suitible format, it will be used for the sizer.
526
527           "properties=>{%properties} | code($stomach,#1,#2...)"
528               supplies additional properties to be set on the generated
529               Whatsit.  In the first form, the values can be of any type, but
530               if a value is a code references, it takes the same args
531               ($stomach,#1,#2,...) and should return the value; it is
532               executed before creating the Whatsit.  In the second form, the
533               code should return a hash of properties.
534
535           "beforeDigest=>code($stomach)"
536               supplies a hook to execute during digestion just before the
537               Whatsit is created.  The code should either return nothing
538               (return;) or a list of digested items (Box's,List,Whatsit).  It
539               can thus change the State and/or add to the digested output.
540
541           "afterDigest=>code($stomach,$whatsit)"
542               supplies a hook to execute during digestion just after the
543               Whatsit is created (and so the Whatsit already has its
544               arguments and properties). It should either return nothing
545               (return;) or digested items.  It can thus change the State,
546               modify the Whatsit, and/or add to the digested output.
547
548           "beforeConstruct=>code($document,$whatsit)"
549               supplies a hook to execute before constructing the XML
550               (generated by replacement).
551
552           "afterConstruct=>code($document,$whatsit)"
553               Supplies code to execute after constructing the XML.
554
555           "captureBody=>boolean | Token"
556               if true, arbitrary following material will be accumulated into
557               a `body' until the current grouping level is reverted, or till
558               the "Token" is encountered if the option is a "Token".  This
559               body is available as the "body" property of the Whatsit.  This
560               is used by environments and math.
561
562           "nargs=>nargs"
563               This gives a number of args for cases where it can't be
564               inferred directly from the prototype (eg. when more args are
565               explicitly read by hooks).
566
567       "DefConstructorI(cs, paramlist, replacement, %options);"
568
569           Internal form of "DefConstructor" where the control sequence and
570           parameter list have already been separated; useful for definitions
571           from within code.
572
573       "DefMath(prototype, tex, %options);"
574
575           A common shorthand constructor; it defines a control sequence that
576           creates a mathematical object, such as a symbol, function or
577           operator application.  The options given can effectively create
578           semantic macros that contribute to the eventual parsing of
579           mathematical content.  In particular, it generates an XMDual using
580           the replacement tex for the presentation.  The content information
581           is drawn from the name and options
582
583           "DefMath" accepts the options:
584
585           "scope=>scope",
586           "locked=>boolean"
587               See "Common Options".
588
589           "font=>{%fontspec}",
590           "reversion=>reversion",
591           "alias=>cs",
592           "sizer=>sizer",
593           "properties=>properties",
594           "beforeDigest=>code($stomach)",
595           "afterDigest=>code($stomach,$whatsit)",
596               These options are the same as for "Constructors"
597
598           "name=>name"
599               gives a name attribute for the object
600
601           "omcd=>cdname"
602               gives the OpenMath content dictionary that name is from.
603
604           "role=>grammatical_role"
605               adds a grammatical role attribute to the object; this specifies
606               the grammatical role that the object plays in surrounding
607               expressions.  This direly needs documentation!
608
609           "mathstyle=>('display' | 'text' | 'script' | 'scriptscript')"
610               Controls whether the this object will be presented in a
611               specific mathstyle, or according to the current setting of
612               "mathstyle".
613
614           "scriptpos=>('mid' | 'post')"
615               Controls the positioning of any sub and super-scripts relative
616               to this object; whether they be stacked over or under it, or
617               whether they will appear in the usual position.  TeX.pool
618               defines a function doScriptpos() which is useful for operators
619               like "\sum" in that it sets to "mid" position when in
620               displaystyle, otherwise "post".
621
622           "stretchy=>boolean"
623               Whether or not the object is stretchy when displayed.
624
625           "operator_role=>grammatical_role",
626           "operator_scriptpos=>boolean",
627           "operator_stretchy=>boolean"
628               These three are similar to "role", "scriptpos" and "stretchy",
629               but are used in unusual cases.  These apply to the given
630               attributes to the operator token in the content branch.
631
632           "nogroup=>boolean"
633               Normally, these commands are digested with an implicit grouping
634               around them, localizing changes to fonts, etc; "noggroup=>1"
635               inhibits this.
636
637           Example:
638
639             DefMath('\infty',"\x{221E}",
640                role=>'ID', meaning=>'infinity');
641
642       "DefMathI(cs, paramlist, tex, %options);"
643
644           Internal form of "DefMath" where the control sequence and parameter
645           list have already been separated; useful for definitions from
646           within code.
647
648       Environments
649
650       "DefEnvironment(prototype, replacement, %options);"
651
652           Defines an Environment that generates a specific XML fragment.
653           "replacement" is of the same form as for DefConstructor, but will
654           generally include reference to the "#body" property. Upon
655           encountering a "\begin{env}":  the mode is switched, if needed,
656           else a new group is opened; then the environment name is noted; the
657           beforeDigest hook is run.  Then the Whatsit representing the begin
658           command (but ultimately the whole environment) is created and the
659           afterDigestBegin hook is run.  Next, the body will be digested and
660           collected until the balancing "\end{env}".   Then, any afterDigest
661           hook is run, the environment is ended, finally the mode is ended or
662           the group is closed.  The body and "\end{env}" whatsit are added to
663           the "\begin{env}"'s whatsit as body and trailer, respectively.
664
665           "DefEnvironment" takes the following options:
666
667           "scope=>scope",
668           "locked=>boolean"
669               See "Common Options".
670
671           "mode=>mode",
672           "font=>{%fontspec}"
673           "requireMath=>boolean",
674           "forbidMath=>boolean",
675               These options are the same as for "Primitives"
676
677           "reversion=>reversion",
678           "alias=>cs",
679           "sizer=>sizer",
680           "properties=>properties",
681           "nargs=>nargs"
682               These options are the same as for "Constructors"
683
684           "beforeDigest=>code($stomach)"
685               This hook is similar to that for "DefConstructor", but it
686               applies to the "\begin{environment}" control sequence.
687
688           "afterDigestBegin=>code($stomach,$whatsit)"
689               This hook is similar to "DefConstructor"'s "afterDigest" but it
690               applies to the "\begin{environment}" control sequence.  The
691               Whatsit is the one for the beginning control sequence, but
692               represents the environment as a whole.  Note that although the
693               arguments and properties are present in the Whatsit, the body
694               of the environment is not yet available!
695
696           "beforeDigestEnd=>code($stomach)"
697               This hook is similar to "DefConstructor"'s "beforeDigest" but
698               it applies to the "\end{environment}" control sequence.
699
700           "afterDigest=>code($stomach,$whatsit)"
701               This hook is similar to "DefConstructor"'s "afterDigest" but it
702               applies to the "\end{environment}" control sequence.  Note,
703               however that the Whatsit is only for the ending control
704               sequence, not the Whatsit for the environment as a whole.
705
706           "afterDigestBody=>code($stomach,$whatsit)"
707               This option supplies a hook to be executed during digestion
708               after the ending control sequence has been digested (and all
709               the 4 other digestion hook have executed) and after the body of
710               the environment has been obtained.  The Whatsit is the (useful)
711               one representing the whole environment, and it now does have
712               the body and trailer available, stored as a properties.
713
714           Example:
715
716             DefConstructor('\emph{}',
717                "<ltx:emph>#1</ltx:emph", mode=>'text');
718
719       "DefEnvironmentI(name, paramlist, replacement, %options);"
720
721           Internal form of "DefEnvironment" where the control sequence and
722           parameter list have already been separated; useful for definitions
723           from within code.
724
725   Inputing Content and Definitions
726       "FindFile(name, %options);"
727
728           Find an appropriate file with the given name in the current
729           directories in "SEARCHPATHS".  If a file ending with ".ltxml" is
730           found, it will be preferred.
731
732           Note that if the "name" starts with a recognized protocol
733           (currently one of "(literal|http|https|ftp)") followed by a colon,
734           the name is returned, as is, and no search for files is carried
735           out.
736
737           The options are:
738
739           "type=>type"
740               specifies the file type.  If not set, it will search for both
741               "name.tex" and name.
742
743           "noltxml=>1"
744               inhibits searching for a LaTeXML binding ("name.type.ltxml") to
745               use instead of the file itself.
746
747           "notex=>1"
748               inhibits searching for raw tex version of the file.  That is,
749               it will only search for the LaTeXML binding.
750
751       "InputContent(request, %options);"
752
753           "InputContent" is used for cases when the file (or data) is plain
754           TeX material that is expected to contribute content to the document
755           (as opposed to pure definitions).  A Mouth is opened onto the file,
756           and subsequent reading and/or digestion will pull Tokens from that
757           Mouth until it is exhausted, or closed.
758
759           In some circumstances it may be useful to provide a string
760           containing the TeX material explicitly, rather than referencing a
761           file.  In this case, the "literal" pseudo-protocal may be used:
762
763             InputContent('literal:\textit{Hey}');
764
765           If a file named "$request.latexml" exists, it will be read in as if
766           it were a latexml binding file, before processing.  This can be
767           used for adhoc customization of the conversion of specific files,
768           without modifying the source, or creating more elaborate bindings.
769
770           The only option to "InputContent" is:
771
772           "noerror=>boolean"
773               Inhibits signalling an error if no appropriate file is found.
774
775       "Input(request);"
776
777           "Input" is analogous to LaTeX's "\input", and is used in cases
778           where it isn't completely clear whether content or definitions is
779           expected.  Once a file is found, the approach specified by
780           "InputContent" or "InputDefinitions" is used, depending on which
781           type of file is found.
782
783       "InputDefinitions(request, %options);"
784
785           "InputDefinitions" is used for loading definitions, ie. various
786           macros, settings, etc, rather than document content; it can be used
787           to load LaTeXML's binding files, or for reading in raw TeX
788           definitions or style files.  It reads and processes the material
789           completely before returning, even in the case of TeX definitions.
790           This procedure optionally supports the conventions used for
791           standard LaTeX packages and classes (see "RequirePackage" and
792           "LoadClass").
793
794           Options for "InputDefinitions" are:
795
796           "type=>type"
797               the file type to search for.
798
799           "noltxml=>boolean"
800               inhibits searching for a LaTeXML binding; only raw TeX files
801               will be sought and loaded.
802
803           "notex=>boolean"
804               inhibits searching for raw TeX files, only a LaTeXML binding
805               will be sought and loaded.
806
807           "noerror=>boolean"
808               inhibits reporting an error if no appropriate file is found.
809
810           The following options are primarily useful when "InputDefinitions"
811           is supporting standard LaTeX package and class loading.
812
813           "withoptions=>boolean"
814               indicates whether to pass in any options from the calling class
815               or package.
816
817           "handleoptions=>boolean"
818               indicates whether options processing should be handled.
819
820           "options=>[...]"
821               specifies a list of options (in the 'package options' sense) to
822               be passed (possibly in addition to any provided by the calling
823               class or package).
824
825           "after=>tokens | code($gullet)"
826               provides tokens or code to be processed by a "name.type-h@@k"
827               macro.
828
829           "as_class=>boolean"
830               fishy option that indicates that this definitions file should
831               be treated as if it were defining a class; typically shows up
832               in latex compatibility mode, or AMSTeX.
833
834           A handy method to use most of the TeX distribution's raw TeX
835           definitions for a package, but override only a few with LaTeXML
836           bindings is by defining a binding file, say "tikz.sty.ltxml", to
837           contain
838
839             InputDefinitions('tikz', type => 'sty', noltxml => 1);
840
841           which would find and read in "tizk.sty", and then follow it by a
842           couple of strategic LaTeXML definitions, "DefMacro", etc.
843
844   Class and Packages
845       "RequirePackage(package, %options);"
846
847           Finds and loads a package implementation (usually
848           "package.sty.ltxml", unless "noltxml" is specified)for the
849           requested package.  It returns the pathname of the loaded package.
850           The options are:
851
852           "type=>type"
853               specifies the file type (default "sty".
854
855           "options=>[...]"
856               specifies a list of package options.
857
858           "noltxml=>boolean"
859               inhibits searching for the LaTeXML binding for the file (ie.
860               "name.type.ltxml"
861
862           "notex=>1"
863               inhibits searching for raw tex version of the file.  That is,
864               it will only search for the LaTeXML binding.
865
866       "LoadClass(class, %options);"
867
868           Finds and loads a class definition (usually "class.cls.ltxml").  It
869           returns the pathname of the loaded class.  The only option is
870
871           "options=>[...]"
872               specifies a list of class options.
873
874       "LoadPool(pool, %options);"
875
876           Loads a pool file (usually "pool.pool.ltxml"), one of the top-level
877           definition files, such as TeX, LaTeX or AMSTeX.  It returns the
878           pathname of the loaded file.
879
880       "DeclareOption(option, tokens | string | code($stomach));"
881
882           Declares an option for the current package or class.  The 2nd
883           argument can be a string (which will be tokenized and expanded) or
884           tokens (which will be macro expanded), to provide the value for the
885           option, or it can be a code reference which is treated as a
886           primitive for side-effect.
887
888           If a package or class wants to accommodate options, it should start
889           with one or more "DeclareOptions", followed by ProcessOptions().
890
891       "PassOptions(name, ext, @options); "
892
893           Causes the given @options (strings) to be passed to the package (if
894           ext is "sty") or class (if ext is "cls") named by name.
895
896       "ProcessOptions(%options);"
897
898           Processes the options that have been passed to the current package
899           or class in a fashion similar to LaTeX.  The only option (to
900           "ProcessOptions" is "inorder=>boolean" indicating whehter the
901           (package) options are processed in the order they were used, like
902           "ProcessOptions*".
903
904           This will also process a limited form of keyval class and package
905           options, if option "keysets" provides a list of keyval set names,
906           and option "inorder" is true.
907
908       "ExecuteOptions(@options);"
909
910           Process the options given explicitly in @options.
911
912       "AtBeginDocument(@stuff); "
913
914           Arranges for @stuff to be carried out after the preamble, at the
915           beginning of the document.  @stuff should typically be macro-level
916           stuff, but carried out for side effect; it should be tokens, tokens
917           lists, strings (which will be tokenized), or "code($gullet)" which
918           would yield tokens to be expanded.
919
920           This operation is useful for style files loaded with "--preload" or
921           document specific customization files (ie. ending with ".latexml");
922           normally the contents would be executed before LaTeX and other
923           style files are loaded and thus can be overridden by them.  By
924           deferring the evaluation to begin-document time, these contents can
925           override those style files.  This is likely to only be meaningful
926           for LaTeX documents.
927
928       AtEndDocument(@stuff)
929           Arranges for @stuff to be carried out just before
930           "\\end{document}".  These tokens can be used for side effect, or
931           any content they generate will appear as the last children of the
932           document.
933
934   Counters and IDs
935       "NewCounter(ctr, within, %options);"
936
937           Defines a new counter, like LaTeX's \newcounter, but extended.  It
938           defines a counter that can be used to generate reference numbers,
939           and defines "\thectr", etc. It also defines an "uncounter" which
940           can be used to generate ID's (xml:id) for unnumbered objects.  ctr
941           is the name of the counter.  If defined, within is the name of
942           another counter which, when incremented, will cause this counter to
943           be reset.  The options are
944
945           "idprefix=>string"
946               Specifies a prefix to be used to generate ID's when using this
947               counter
948
949           "nested"
950               Not sure that this is even sane.
951
952       "$num = CounterValue($ctr);"
953
954           Fetches the value associated with the counter $ctr.
955
956       "$tokens = StepCounter($ctr);"
957
958           Analog of "\stepcounter", steps the counter and returns the
959           expansion of "\the$ctr".  Usually you should use
960           RefStepCounter($ctr) instead.
961
962       "$keys = RefStepCounter($ctr);"
963
964           Analog of "\refstepcounter", steps the counter and returns a hash
965           containing the keys "refnum="$refnum, id=>$id>.  This makes it
966           suitable for use in a "properties" option to constructors.  The
967           "id" is generated in parallel with the reference number to assist
968           debugging.
969
970       "$keys = RefStepID($ctr);"
971
972           Like to "RefStepCounter", but only steps the "uncounter", and
973           returns only the id;  This is useful for unnumbered cases of
974           objects that normally get both a refnum and id.
975
976       "ResetCounter($ctr);"
977
978           Resets the counter $ctr to zero.
979
980       "GenerateID($document,$node,$whatsit,$prefix);"
981
982           Generates an ID for nodes during the construction phase, useful for
983           cases where the counter based scheme is inappropriate.  The calling
984           pattern makes it appropriate for use in Tag, as in
985
986              Tag('ltx:para',afterClose=>sub { GenerateID(@_,'p'); })
987
988           If $node doesn't already have an xml:id set, it computes an
989           appropriate id by concatenating the xml:id of the closest ancestor
990           with an id (if any), the prefix (if any) and a unique counter.
991
992   Document Model
993       Constructors define how TeX markup will generate XML fragments, but the
994       Document Model is used to control exactly how those fragments are
995       assembled.
996
997       "Tag(tag, %properties);"
998
999           Declares properties of elements with the name tag.  Note that "Tag"
1000           can set or add properties to any element from any binding file,
1001           unlike the properties set on control by  "DefPrimtive",
1002           "DefConstructor", etc..  And, since the properties are recorded in
1003           the current Model, they are not subject to TeX grouping; once set,
1004           they remain in effect until changed or the end of the document.
1005
1006           The tag can be specified in one of three forms:
1007
1008              prefix:name matches specific name in specific namespace
1009              prefix:*    matches any tag in the specific namespace;
1010              *           matches any tag in any namespace.
1011
1012           There are two kinds of properties:
1013
1014           Scalar properties
1015               For scalar properties, only a single value is returned for a
1016               given element.  When the property is looked up, each of the
1017               above forms is considered (the specific element name, the
1018               namespace, and all elements); the first defined value is
1019               returned.
1020
1021               The recognized scalar properties are:
1022
1023               "autoOpen=>boolean"
1024                   Specifies whether tag can be automatically opened if needed
1025                   to insert an element that can only be contained by tag.
1026                   This property can help match the more  SGML-like LaTeX to
1027                   XML.
1028
1029               "autoClose=>boolean"
1030                   Specifies whether this tag can be automatically closed if
1031                   needed to close an ancestor node, or insert an element into
1032                   an ancestor.  This property can help match the more  SGML-
1033                   like LaTeX to XML.
1034
1035           Code properties
1036               These properties provide a bit of code to be run at the times
1037               of certain events associated with an element.  All the code
1038               bits that match a given element will be run, and since they can
1039               be added by any binding file, and be specified in a random
1040               orders, a little bit of extra control is desirable.
1041
1042               Firstly, any early codes are run (eg "afterOpen:early"), then
1043               any normal codes (without modifier) are run, and finally any
1044               late codes are run (eg. "afterOpen:late").
1045
1046               Within each of those groups, the codes assigned for an
1047               element's specific name are run first, then those assigned for
1048               its package and finally the generic one ("*"); that is, the
1049               most specific codes are run first.
1050
1051               When code properties are accumulated by "Tag" for normal or
1052               late events, the code is appended to the end of the current
1053               list (if there were any previous codes added); for early event,
1054               the code is prepended.
1055
1056               The recognized code properties are:
1057
1058               "afterOpen=>code($document,$box)"
1059                   Provides code to be run whenever a node with this tag is
1060                   opened.  It is called with the document being constructed,
1061                   and the initiating digested object as arguments.  It is
1062                   called after the node has been created, and after any
1063                   initial attributes due to the constructor (passed to
1064                   openElement) are added.
1065
1066                   "afterOpen:early" or "afterOpen:late" can be used in place
1067                   of "afterOpen"; these will be run as a group before, or
1068                   after (respectively) the unmodified blocks.
1069
1070               "afterClose=>code($document,$box)"
1071                   Provides code to be run whenever a node with this tag is
1072                   closed.  It is called with the document being constructed,
1073                   and the initiating digested object as arguments.
1074
1075                   "afterClose:early" or "afterClose:late" can be used in
1076                   place of "afterClose"; these will be run as a group bfore,
1077                   or after (respectively) the unmodified blocks.
1078
1079       "RelaxNGSchema(schemaname);"
1080
1081           Specifies the schema to use for determining document model.  You
1082           can leave off the extension; it will look for "schemaname.rng" (and
1083           maybe eventually, ".rnc" if that is ever implemented).
1084
1085       "RegisterNamespace(prefix, URL);"
1086
1087           Declares the prefix to be associated with the given URL.  These
1088           prefixes may be used in ltxml files, particularly for constructors,
1089           xpath expressions, etc.  They are not necessarily the same as the
1090           prefixes that will be used in the generated document Use the prefix
1091           "#default" for the default, non-prefixed, namespace.  (See
1092           RegisterDocumentNamespace, as well as DocType or RelaxNGSchema).
1093
1094       "RegisterDocumentNamespace(prefix, URL);"
1095
1096           Declares the prefix to be associated with the given URL used within
1097           the generated XML. They are not necessarily the same as the
1098           prefixes used in code (RegisterNamespace).  This function is less
1099           rarely needed, as the namespace declarations are generally obtained
1100           from the DTD or Schema themselves Use the prefix "#default" for the
1101           default, non-prefixed, namespace.  (See DocType or RelaxNGSchema).
1102
1103       "DocType(rootelement, publicid, systemid, %namespaces);"
1104
1105           Declares the expected rootelement, the public and system ID's of
1106           the document type to be used in the final document.  The hash
1107           %namespaces specifies the namespaces prefixes that are expected to
1108           be found in the DTD, along with each associated namespace URI.  Use
1109           the prefix "#default" for the default namespace (ie. the namespace
1110           of non-prefixed elements in the DTD).
1111
1112           The prefixes defined for the DTD may be different from the prefixes
1113           used in implementation CODE (eg. in ltxml files; see
1114           RegisterNamespace).  The generated document will use the namespaces
1115           and prefixes defined for the DTD.
1116
1117   Document Rewriting
1118       During document construction, as each node gets closed, the text
1119       content gets simplfied.  We'll call it applying ligatures, for lack of
1120       a better name.
1121
1122       "DefLigature(regexp, %options);"
1123
1124           Apply the regular expression (given as a string: "/fa/fa/" since it
1125           will be converted internally to a true regexp), to the text
1126           content.  The only option is "fontTest=>code($font)"; if given,
1127           then the substitution is applied only when "fontTest" returns true.
1128
1129           Predefined Ligatures combine sequences of "." or single-quotes into
1130           appropriate Unicode characters.
1131
1132       "DefMathLigature($string"=""$replacment,%options);>
1133
1134           A Math Ligature typically combines a sequence of math tokens
1135           (XMTok) into a single one.  A simple example is
1136
1137              DefMathLigature(":=" => ":=", role => 'RELOP', meaning => 'assign');
1138
1139           replaces the two tokens for colon and equals by a token
1140           representing assignment.  The options are those characterising an
1141           XMTok, namely: "role", "meaning" and "name".
1142
1143           For more complex cases (recognizing numbers, for example), you may
1144           supply a function "matcher="CODE($document,$node)>, which is passed
1145           the current document and the last math node in the sequence.  It
1146           should examine $node and any preceding nodes (using
1147           "previousSibling") and return a list of "($n,$string,%attributes)"
1148           to replace the $n nodes by a new one with text content being
1149           $string content and the given attributes.  If no replacement is
1150           called for, CODE should return undef.
1151
1152       After document construction, various rewriting and augmenting of the
1153       document can take place.
1154
1155       "DefRewrite(%specification);"
1156       "DefMathRewrite(%specification);"
1157
1158           These two declarations define document rewrite rules that are
1159           applied to the document tree after it has been constructed, but
1160           before math parsing, or any other postprocessing, is done.  The
1161           %specification consists of a sequence of key/value pairs with the
1162           initial specs successively narrowing the selection of document
1163           nodes, and the remaining specs indicating how to modify or replace
1164           the selected nodes.
1165
1166           The following select portions of the document:
1167
1168           "label=>label"
1169               Selects the part of the document with label=$label
1170
1171           "scope=>scope"
1172               The scope could be "label:foo" or "section:1.2.3" or something
1173               similar. These select a subtree labelled 'foo', or a section
1174               with reference number "1.2.3"
1175
1176           "xpath=>xpath"
1177               Select those nodes matching an explicit xpath expression.
1178
1179           "match=>tex"
1180               Selects nodes that look like what the processing of tex would
1181               produce.
1182
1183           "regexp=>regexp"
1184               Selects text nodes that match the regular expression.
1185
1186           The following act upon the selected node:
1187
1188           "attributes=>hashref"
1189               Adds the attributes given in the hash reference to the node.
1190
1191           "replace=>replacement"
1192               Interprets replacement as TeX code to generate nodes that will
1193               replace the selected nodes.
1194
1195   Mid-Level support
1196       "$tokens = Expand($tokens);"
1197
1198           Expands the given $tokens according to current definitions.
1199
1200       "$boxes = Digest($tokens);"
1201
1202           Processes and digestes the $tokens.  Any arguments needed by
1203           control sequences in $tokens must be contained within the $tokens
1204           itself.
1205
1206       "@tokens = Invocation($cs,@args);"
1207
1208           Constructs a sequence of tokens that would invoke the token $cs on
1209           the arguments.
1210
1211       "RawTeX('... tex code ...');"
1212
1213           RawTeX is a convenience function for including chunks of raw TeX
1214           (or LaTeX) code in a Package implementation.  It is useful for
1215           copying portions of the normal implementation that can be handled
1216           simply using macros and primitives.
1217
1218       "Let($token1,$token2);"
1219
1220           Gives $token1 the same `meaning' (definition) as $token2; like
1221           TeX's \let.
1222
1223       "StartSemiVerbatim(); ... ; EndSemiVerbatim();"
1224           Disable disable most TeX catcodes.
1225
1226       "$tokens = Tokenize($string);"
1227           Tokenizes the $string using the standard catcodes, returning a
1228           LaTeXML::Core::Tokens.
1229
1230       "$tokens = TokenizeInternal($string);"
1231           Tokenizes the $string according to the internal cattable (where @
1232           is a letter), returning a LaTeXML::Core::Tokens.
1233
1234   Argument Readers
1235       "ReadParameters($gullet,$spec);"
1236
1237           Reads from $gullet the tokens corresponding to $spec (a Parameters
1238           object).
1239
1240       "DefParameterType(type, code($gullet,@values), %options);"
1241
1242           Defines a new Parameter type, type, with code for its reader.
1243
1244           Options are:
1245
1246           "reversion=>code($arg,@values);"
1247               This code is responsible for converting a previously parsed
1248               argument back into a sequence of Token's.
1249
1250           "optional=>boolean"
1251               whether it is an error if no matching input is found.
1252
1253           "novalue=>boolean"
1254               whether the value returned should contribute to argument lists,
1255               or simply be passed over.
1256
1257           "semiverbatim=>boolean"
1258               whether the catcode table should be modified before reading
1259               tokens.
1260
1261       "<DefColumnType(proto, expansion);"
1262
1263           Defines a new column type for tabular and arrays.  proto is the
1264           prototype for the pattern, analogous to the pattern used for other
1265           definitions, except that macro being defined is a single character.
1266           The expansion is a string specifying what it should expand into,
1267           typically more verbose column specification.
1268
1269   Access to State
1270       "$value = LookupValue($name);"
1271
1272           Lookup the current value associated with the the string $name.
1273
1274       "AssignValue($name,$value,$scope);"
1275
1276           Assign $value to be associated with the the string $name, according
1277           to the given scoping rule.
1278
1279           Values are also used to specify most configuration parameters
1280           (which can therefore also be scoped).  The recognized configuration
1281           parameters are:
1282
1283            STRICT            : whether errors (eg. undefined macros)
1284                                are fatal.
1285            INCLUDE_COMMENTS  : whether to preserve comments in the
1286                                source, and to add occasional line
1287                                number comments. (Default true).
1288            PRESERVE_NEWLINES : whether newlines in the source should
1289                                be preserved (not 100% TeX-like).
1290                                By default this is true.
1291            SEARCHPATHS       : a list of directories to search for
1292                                sources, implementations, etc.
1293
1294       "PushValue($name,@values);"
1295
1296           This function, along with the next three are like "AssignValue",
1297           but maintain a global list of values.  "PushValue" pushes the
1298           provided values onto the end of a list.  The data stored for $name
1299           is global and must be a LIST reference; it is created if needed.
1300
1301       "UnshiftValue($name,@values);"
1302
1303           Similar to  "PushValue", but pushes a value onto the front of the
1304           list.  The data stored for $name is global and must be a LIST
1305           reference; it is created if needed.
1306
1307       "PopValue($name);"
1308
1309           Removes and returns the value on the end of the list named by
1310           $name.  The data stored for $name is global and must be a LIST
1311           reference.  Returns "undef" if there is no data in the list.
1312
1313       "ShiftValue($name);"
1314
1315           Removes and returns the first value in the list named by $name.
1316           The data stored for $name is global and must be a LIST reference.
1317           Returns "undef" if there is no data in the list.
1318
1319       "LookupMapping($name,$key);"
1320
1321           This function maintains a hash association named by $name.  It
1322           returns the value associated with $key within that mapping.  The
1323           data stored for $name is global and must be a HASH reference.
1324           Returns "undef" if there is no data associated with $key in the
1325           mapping, or the mapping is not (yet) defined.
1326
1327       "AssignMapping($name,$key,$value);"
1328
1329           This function associates $value with $key within the mapping named
1330           by $name.  The data stored for $name is global and must be a HASH
1331           reference; it is created if needed.
1332
1333       "$value = LookupCatcode($char);"
1334
1335           Lookup the current catcode associated with the the character $char.
1336
1337       "AssignCatcode($char,$catcode,$scope);"
1338
1339           Set $char to have the given $catcode, with the assignment made
1340           according to the given scoping rule.
1341
1342           This method is also used to specify whether a given character is
1343           active in math mode, by using "math:$char" for the character, and
1344           using a value of 1 to specify that it is active.
1345
1346       "$meaning = LookupMeaning($token);"
1347
1348           Looks up the current meaning of the given $token which may be a
1349           Definition, another token, or the token itself if it has not
1350           otherwise been defined.
1351
1352       "$defn = LookupDefinition($token);"
1353
1354           Looks up the current definition, if any, of the $token.
1355
1356       "InstallDefinition($defn);"
1357
1358           Install the Definition $defn into $STATE under its control
1359           sequence.
1360
1361       "XEquals($token1,$token2)"
1362           Tests whether the two tokens are equal in the sense that they are
1363           either equal tokens, or if defined, have the same definition.
1364
1365   Fonts
1366       "MergeFont(%fontspec); "
1367
1368           Set the current font by merging the font style attributes with the
1369           current font.  The %fontspec specifies the properties of the
1370           desired font.  Likely values include (the values aren't required to
1371           be in this set):
1372
1373            family : serif, sansserif, typewriter, caligraphic,
1374                     fraktur, script
1375            series : medium, bold
1376            shape  : upright, italic, slanted, smallcaps
1377            size   : tiny, footnote, small, normal, large,
1378                     Large, LARGE, huge, Huge
1379            color  : any named color, default is black
1380
1381           Some families will only be used in math.  This function returns
1382           nothing so it can be easily used in beforeDigest, afterDigest.
1383
1384       "DeclareFontMap($name,$map,%options);"
1385           Declares a font map for the encoding $name. The map $map is an
1386           array of 128 or 256 entries, each element is either a unicode
1387           string for the representation of that codepoint, or undef if that
1388           codepoint is not supported  by this encoding.  The only option
1389           currently is "family" used because some fonts (notably cmr!)  have
1390           different glyphs in some font families, such as
1391           "family="'typewriter'>.
1392
1393       "FontDecode($code,$encoding,$implicit);"
1394           Returns the unicode string representing the given codepoint $code
1395           (an integer) in the given font encoding $encoding.  If $encoding is
1396           undefined, the usual case, the current font encoding and font
1397           family is used for the lookup.  Explicit decoding is used when
1398           "\\char" or similar are invoked ($implicit is false), and the
1399           codepoint must be represented in the fontmap, otherwise undef is
1400           returned.  Implicit decoding (ie. $implicit is true) occurs within
1401           the Stomach when a Token's content is being digested and converted
1402           to a Box; in that case only the lower 128 codepoints are converted;
1403           all codepoints above 128 are assumed to already be Unicode.
1404
1405           The font map for $encoding is automatically loaded if it has not
1406           already been loaded.
1407
1408       "FontDecodeString($string,$encoding,$implicit);"
1409           Returns the unicode string resulting from decoding the individual
1410           characters in $string according to FontDecode, above.
1411
1412       "LoadFontMap($encoding);"
1413           Finds and loads the font map for the encoding named $encoding, if
1414           it hasn't been loaded before.  It looks for
1415           "encoding.fontmap.ltxml", which would typically define the font map
1416           using "DeclareFontMap", possibly including extra maps for families
1417           like "typewriter".
1418
1419   Color
1420       "$color=LookupColor($name);"
1421           Lookup the color object associated with $name.
1422
1423       "DefColor($name,$color,$scope);"
1424           Associates the $name with the given $color (a color object), with
1425           the given scoping.
1426
1427       "DefColorModel($model,$coremodel,$tocore,$fromcore);"
1428           Defines a color model $model that is derived from the core color
1429           model $coremodel.  The two functions $tocore and $fromcore convert
1430           a color object in that model to the core model, or from the core
1431           model to the derived model.  Core models are rgb, cmy, cmyk, hsb
1432           and gray.
1433
1434   Low-level Functions
1435       "CleanID($id);"
1436
1437           Cleans an $id of disallowed characters, trimming space.
1438
1439       "CleanLabel($label,$prefix);"
1440
1441           Cleans a $label of disallowed characters, trimming space.  The
1442           prefix $prefix is prepended (or "LABEL", if none given).
1443
1444       "CleanIndexKey($key);"
1445
1446           Cleans an index key, so it can be used as an ID.
1447
1448       "CleanBibKey($key);"
1449           Cleans a bibliographic citation key, so it can be used as an ID.
1450
1451       "CleanURL($url);"
1452
1453           Cleans a url.
1454
1455       "UTF($code);"
1456
1457           Generates a UTF character, handy for the the 8 bit characters.  For
1458           example, UTF(0xA0) generates the non-breaking space.
1459
1460       "@tokens = roman($number);"
1461
1462           Formats the $number in (lowercase) roman numerals, returning a list
1463           of the tokens.
1464
1465       "@tokens = Roman($number);"
1466
1467           Formats the $number in (uppercase) roman numerals, returning a list
1468           of the tokens.
1469

SEE ALSO

1471       See also LaTeXML::Global, LaTeXML::Common::Object,
1472       LaTeXML::Common::Error, LaTeXML::Core::Token, LaTeXML::Core::Tokens,
1473       LaTeXML::Core::Box, LaTeXML::Core::List, LaTeXML::Common::Number,
1474       LaTeXML::Common::Float, LaTeXML::Common::Dimension,
1475       LaTeXML::Common::Glue, LaTeXML::Core::MuDimension,
1476       LaTeXML::Core::MuGlue, LaTeXML::Core::Pair, LaTeXML::Core::PairList,
1477       LaTeXML::Common::Color, LaTeXML::Core::Alignment, LaTeXML::Common::XML,
1478       LaTeXML::Util::Radix.
1479

AUTHOR

1481       Bruce Miller <bruce.miller@nist.gov>
1482
1484       Public domain software, produced as part of work done by the United
1485       States Government & not subject to copyright in the US.
1486
1487
1488
1489perl v5.36.0                      2023-01-22               LaTeXML::Package(3)
Impressum