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

SEE ALSO

1456       See also LaTeXML::Global, LaTeXML::Common::Object,
1457       LaTeXML::Common::Error, LaTeXML::Core::Token, LaTeXML::Core::Tokens,
1458       LaTeXML::Core::Box, LaTeXML::Core::List, LaTeXML::Common::Number,
1459       LaTeXML::Common::Float, LaTeXML::Common::Dimension,
1460       LaTeXML::Common::Glue, LaTeXML::Core::MuDimension,
1461       LaTeXML::Core::MuGlue, LaTeXML::Core::Pair, LaTeXML::Core::PairList,
1462       LaTeXML::Common::Color, LaTeXML::Core::Alignment, LaTeXML::Common::XML,
1463       LaTeXML::Util::Radix.
1464

AUTHOR

1466       Bruce Miller <bruce.miller@nist.gov>
1467
1469       Public domain software, produced as part of work done by the United
1470       States Government & not subject to copyright in the US.
1471
1472
1473
1474perl v5.32.1                      2021-01-25               LaTeXML::Package(3)
Impressum