1LaTeXML::Package(3) User Contributed Perl Documentation LaTeXML::Package(3)
2
6 "LaTeXML::Package" - Support for package implementations and document
7 customization.
8
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 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
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 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 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 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 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 Prototypes
102 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 DefConstructor('\usepackage[]{}',...
115 DefPrimitive('\multiply Variable SkipKeyword:by Number',..
116 DefPrimitive('\newcommand OptionalMatch:* DefToken[]{}', ...
117 The general syntax for parameter specification is
119 "{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 "[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 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 "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 "OptionalType"
143 Similar to Type, but it is not considered an error if the reader
144 returns undef.
145 "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 The predefined argument Types are as follows.
151 "Plain, Semiverbatim"
153 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 "Token, XToken"
160 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 "Number, Dimension, Glue | MuGlue"
166 Read an Object corresponding to Number, Dimension, Glue or MuGlue,
168 using TeX's rules for parsing these objects.
169 "Until:match | XUntil:"match>
171 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 "UntilBrace"
179 Reads tokens until the next open brace "{". This corresponds to
181 the peculiar TeX construct "\def\foo#{...".
182 "Match:match(|match)* | Keyword:"match(|match)*>
184 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 "Balanced"
191 Read tokens until a closing }, but respecting nested {} pairs.
193 "BalancedParen"
195 Read a parenthesis delimited tokens, but does not balance any
197 nested parentheses.
198 "Undigested, Digested, DigestUntil:match"
200 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 "Variable"
210 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 "SkipSpaces, Skip1Space"
217 Skips one, or any number of, space tokens, if present, but
219 contributes nothing to the argument list.
220 Common Options
222 "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 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 "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 "protected=>boolean"
242 Makes a definition "protected", in the sense of eTeX's "\protected"
243 directive. This inhibits expansion under certain circumstances.
244 "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 Macros
255 "DefMacro(prototype, expansion, %options);"
257 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 DefMacro options are
269 "scope=>scope",
271 "locked=>boolean"
272 See "Common Options".
273 "mathactive=>boolean"
275 specifies a definition that will only be expanded in math mode;
276 the control sequence must be a single character.
277 Examples:
279 DefMacro('\thefootnote','\arabic{footnote}');
281 DefMacro('\today',sub { ExplodeText(today()); });
282 "DefMacroI(cs, paramlist, expansion, %options);"
284 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 Conditionals
292 "DefConditional(prototype, test, %options);"
294 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 DefConditional options are
308 "scope=>scope",
310 "locked=>boolean"
311 See "Common Options".
312 "skipper=>code($gullet)"
314 This option is only used to define "\ifcase".
315 Example:
317 DefConditional('\ifmmode',sub {
319 LookupValue('IN_MATH'); });
320 "DefConditionalI(cs, paramlist, test, %options);"
322 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 "IfCondition($ifcs,@args)"
329 "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 Primitives
336 "DefPrimitive(prototype, replacement, %options);"
338 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 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 DefPrimitive options are
356 "scope=>scope",
358 "locked=>boolean"
359 See "Common Options".
360 "mode=> ('text' | 'display_math' | 'inline_math')"
362 Changes to this mode during digestion.
363 "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 "bounded=>boolean"
371 If true, TeX grouping (ie. "{}") is enforced around this
372 invocation.
373 "requireMath=>boolean",
375 "forbidMath=>boolean"
376 specifies whether the given constructor can only appear, or
377 cannot appear, in math mode.
378 "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 "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 "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 Example:
399 DefPrimitive('\begingroup',sub { $_[0]->begingroup; });
401 "DefPrimitiveI(cs, paramlist, code($stomach,@args), %options);"
403 Internal form of "DefPrimitive" where the control sequence and
405 parameter list have already been separated; useful for definitions
406 from within code.
407 Registers
409 "DefRegister(prototype, value, %options);"
411 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 Options are
421 "readonly=>boolean"
423 specifies if it is not allowed to change this value.
424 "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 Example:
433 DefRegister('\pretolerance',Number(100));
435 "DefRegisterI(cs, paramlist, value, %options);"
437 Internal form of "DefRegister" where the control sequence and
439 parameter list have already been parsed; useful for definitions
440 from within code.
441 Constructors
443 "DefConstructor(prototype, $replacement, %options);"
445 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 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 "#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 "&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 "?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 "^" 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 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 DefConstructor options are
490 "scope=>scope",
492 "locked=>boolean"
493 See "Common Options".
494 "mode=>mode",
496 "font=>{%fontspec}",
497 "bounded=>boolean",
498 "requireMath=>boolean",
499 "forbidMath=>boolean"
500 These options are the same as for "Primitives"
501 "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 "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 "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 "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 "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 "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 "beforeConstruct=>code($document,$whatsit)"
549 supplies a hook to execute before constructing the XML
550 (generated by replacement).
551 "afterConstruct=>code($document,$whatsit)"
553 Supplies code to execute after constructing the XML.
554 "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 "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 "DefConstructorI(cs, paramlist, replacement, %options);"
568 Internal form of "DefConstructor" where the control sequence and
570 parameter list have already been separated; useful for definitions
571 from within code.
572 "DefMath(prototype, tex, %options);"
574 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 "DefMath" accepts the options:
584 "scope=>scope",
586 "locked=>boolean"
587 See "Common Options".
588 "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 "name=>name"
599 gives a name attribute for the object
600 "omcd=>cdname"
602 gives the OpenMath content dictionary that name is from.
603 "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 "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 "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 "stretchy=>boolean"
623 Whether or not the object is stretchy when displayed.
624 "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 "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 Example:
638 DefMath('\infty',"\x{221E}",
640 role=>'ID', meaning=>'infinity');
641 "DefMathI(cs, paramlist, tex, %options);"
643 Internal form of "DefMath" where the control sequence and parameter
645 list have already been separated; useful for definitions from
646 within code.
647 Environments
649 "DefEnvironment(prototype, replacement, %options);"
651 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 "DefEnvironment" takes the following options:
666 "scope=>scope",
668 "locked=>boolean"
669 See "Common Options".
670 "mode=>mode",
672 "font=>{%fontspec}"
673 "requireMath=>boolean",
674 "forbidMath=>boolean",
675 These options are the same as for "Primitives"
676 "reversion=>reversion",
678 "alias=>cs",
679 "sizer=>sizer",
680 "properties=>properties",
681 "nargs=>nargs"
682 These options are the same as for "Constructors"
683 "beforeDigest=>code($stomach)"
685 This hook is similar to that for "DefConstructor", but it
686 applies to the "\begin{environment}" control sequence.
687 "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 "beforeDigestEnd=>code($stomach)"
697 This hook is similar to "DefConstructor"'s "beforeDigest" but
698 it applies to the "\end{environment}" control sequence.
699 "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 "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 Example:
715 DefConstructor('\emph{}',
717 "<ltx:emph>#1</ltx:emph", mode=>'text');
718 "DefEnvironmentI(name, paramlist, replacement, %options);"
720 Internal form of "DefEnvironment" where the control sequence and
722 parameter list have already been separated; useful for definitions
723 from within code.
724 Inputing Content and Definitions
726 "FindFile(name, %options);"
727 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 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 The options are:
738 "type=>type"
740 specifies the file type. If not set, it will search for both
741 "name.tex" and name.
742 "noltxml=>1"
744 inhibits searching for a LaTeXML binding ("name.type.ltxml") to
745 use instead of the file itself.
746 "notex=>1"
748 inhibits searching for raw tex version of the file. That is,
749 it will only search for the LaTeXML binding.
750 "InputContent(request, %options);"
752 "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 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 InputContent('literal:\textit{Hey}');
764 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 The only option to "InputContent" is:
771 "noerror=>boolean"
773 Inhibits signalling an error if no appropriate file is found.
774 "Input(request);"
776 "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 "InputDefinitions(request, %options);"
784 "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 Options for "InputDefinitions" are:
795 "type=>type"
797 the file type to search for.
798 "noltxml=>boolean"
800 inhibits searching for a LaTeXML binding; only raw TeX files
801 will be sought and loaded.
802 "notex=>boolean"
804 inhibits searching for raw TeX files, only a LaTeXML binding
805 will be sought and loaded.
806 "noerror=>boolean"
808 inhibits reporting an error if no appropriate file is found.
809 The following options are primarily useful when "InputDefinitions"
811 is supporting standard LaTeX package and class loading.
812 "withoptions=>boolean"
814 indicates whether to pass in any options from the calling class
815 or package.
816 "handleoptions=>boolean"
818 indicates whether options processing should be handled.
819 "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 "after=>tokens | code($gullet)"
826 provides tokens or code to be processed by a "name.type-h@@k"
827 macro.
828 "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 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 InputDefinitions('tikz', type => 'sty', noltxml => 1);
840 which would find and read in "tizk.sty", and then follow it by a
842 couple of strategic LaTeXML definitions, "DefMacro", etc.
843 Class and Packages
845 "RequirePackage(package, %options);"
846 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 "type=>type"
853 specifies the file type (default "sty".
854 "options=>[...]"
856 specifies a list of package options.
857 "noltxml=>boolean"
859 inhibits searching for the LaTeXML binding for the file (ie.
860 "name.type.ltxml"
861 "notex=>1"
863 inhibits searching for raw tex version of the file. That is,
864 it will only search for the LaTeXML binding.
865 "LoadClass(class, %options);"
867 Finds and loads a class definition (usually "class.cls.ltxml"). It
869 returns the pathname of the loaded class. The only option is
870 "options=>[...]"
872 specifies a list of class options.
873 "LoadPool(pool, %options);"
875 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 "DeclareOption(option, tokens | string | code($stomach));"
881 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 If a package or class wants to accommodate options, it should start
889 with one or more "DeclareOptions", followed by ProcessOptions().
890 "PassOptions(name, ext, @options); "
892 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 "ProcessOptions(%options);"
897 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 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 "ExecuteOptions(@options);"
909 Process the options given explicitly in @options.
911 "AtBeginDocument(@stuff); "
913 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 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 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 Counters and IDs
935 "NewCounter(ctr, within, %options);"
936 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 "idprefix=>string"
946 Specifies a prefix to be used to generate ID's when using this
947 counter
948 "nested"
950 Not sure that this is even sane.
951 "$num = CounterValue($ctr);"
953 Fetches the value associated with the counter $ctr.
955 "$tokens = StepCounter($ctr);"
957 Analog of "\stepcounter", steps the counter and returns the
959 expansion of "\the$ctr". Usually you should use
960 RefStepCounter($ctr) instead.
961 "$keys = RefStepCounter($ctr);"
963 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 "$keys = RefStepID($ctr);"
971 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 "ResetCounter($ctr);"
977 Resets the counter $ctr to zero.
979 "GenerateID($document,$node,$whatsit,$prefix);"
981 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 Tag('ltx:para',afterClose=>sub { GenerateID(@_,'p'); })
987 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 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 "Tag(tag, %properties);"
998 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 The tag can be specified in one of three forms:
1007 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 There are two kinds of properties:
1013 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 The recognized scalar properties are:
1022 "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 "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 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 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 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 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 The recognized code properties are:
1057 "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 "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 "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 "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 "RelaxNGSchema(schemaname);"
1080 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 "RegisterNamespace(prefix, URL);"
1086 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 "RegisterDocumentNamespace(prefix, URL);"
1095 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 "DocType(rootelement, publicid, systemid, %namespaces);"
1104 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 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 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 "DefLigature(regexp, %options);"
1123 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 Predefined Ligatures combine sequences of "." or single-quotes into
1130 appropriate Unicode characters.
1131 "DefMathLigature($string"=""$replacment,%options);>
1133 A Math Ligature typically combines a sequence of math tokens
1135 (XMTok) into a single one. A simple example is
1136 DefMathLigature(":=" => ":=", role => 'RELOP', meaning => 'assign');
1138 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 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 After document construction, various rewriting and augmenting of the
1153 document can take place.
1154 "DefRewrite(%specification);"
1156 "DefMathRewrite(%specification);"
1157 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 The following select portions of the document:
1167 "label=>label"
1169 Selects the part of the document with label=$label
1170 "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 "xpath=>xpath"
1177 Select those nodes matching an explicit xpath expression.
1178 "match=>tex"
1180 Selects nodes that look like what the processing of tex would
1181 produce.
1182 "regexp=>regexp"
1184 Selects text nodes that match the regular expression.
1185 The following act upon the selected node:
1187 "attributes=>hashref"
1189 Adds the attributes given in the hash reference to the node.
1190 "replace=>replacement"
1192 Interprets replacement as TeX code to generate nodes that will
1193 replace the selected nodes.
1194 Mid-Level support
1196 "$tokens = Expand($tokens);"
1197 Expands the given $tokens according to current definitions.
1199 "$boxes = Digest($tokens);"
1201 Processes and digestes the $tokens. Any arguments needed by
1203 control sequences in $tokens must be contained within the $tokens
1204 itself.
1205 "@tokens = Invocation($cs,@args);"
1207 Constructs a sequence of tokens that would invoke the token $cs on
1209 the arguments.
1210 "RawTeX('... tex code ...');"
1212 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 "Let($token1,$token2);"
1219 Gives $token1 the same `meaning' (definition) as $token2; like
1221 TeX's \let.
1222 "StartSemiVerbatim(); ... ; EndSemiVerbatim();"
1224 Disable disable most TeX catcodes.
1225 "$tokens = Tokenize($string);"
1227 Tokenizes the $string using the standard catcodes, returning a
1228 LaTeXML::Core::Tokens.
1229 "$tokens = TokenizeInternal($string);"
1231 Tokenizes the $string according to the internal cattable (where @
1232 is a letter), returning a LaTeXML::Core::Tokens.
1233 Argument Readers
1235 "ReadParameters($gullet,$spec);"
1236 Reads from $gullet the tokens corresponding to $spec (a Parameters
1238 object).
1239 "DefParameterType(type, code($gullet,@values), %options);"
1241 Defines a new Parameter type, type, with code for its reader.
1243 Options are:
1245 "reversion=>code($arg,@values);"
1247 This code is responsible for converting a previously parsed
1248 argument back into a sequence of Token's.
1249 "optional=>boolean"
1251 whether it is an error if no matching input is found.
1252 "novalue=>boolean"
1254 whether the value returned should contribute to argument lists,
1255 or simply be passed over.
1256 "semiverbatim=>boolean"
1258 whether the catcode table should be modified before reading
1259 tokens.
1260 "<DefColumnType(proto, expansion);"
1262 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 Access to State
1270 "$value = LookupValue($name);"
1271 Lookup the current value associated with the the string $name.
1273 "AssignValue($name,$value,$scope);"
1275 Assign $value to be associated with the the string $name, according
1277 to the given scoping rule.
1278 Values are also used to specify most configuration parameters
1280 (which can therefore also be scoped). The recognized configuration
1281 parameters are:
1282 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 "PushValue($name,@values);"
1295 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 "UnshiftValue($name,@values);"
1302 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 "PopValue($name);"
1308 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 "ShiftValue($name);"
1314 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 "LookupMapping($name,$key);"
1320 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 "AssignMapping($name,$key,$value);"
1328 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 "$value = LookupCatcode($char);"
1334 Lookup the current catcode associated with the the character $char.
1336 "AssignCatcode($char,$catcode,$scope);"
1338 Set $char to have the given $catcode, with the assignment made
1340 according to the given scoping rule.
1341 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 "$meaning = LookupMeaning($token);"
1347 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 "$defn = LookupDefinition($token);"
1353 Looks up the current definition, if any, of the $token.
1355 "InstallDefinition($defn);"
1357 Install the Definition $defn into $STATE under its control
1359 sequence.
1360 "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 Fonts
1366 "MergeFont(%fontspec); "
1367 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 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 Some families will only be used in math. This function returns
1382 nothing so it can be easily used in beforeDigest, afterDigest.
1383 "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 "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 The font map for $encoding is automatically loaded if it has not
1406 already been loaded.
1407 "FontDecodeString($string,$encoding,$implicit);"
1409 Returns the unicode string resulting from decoding the individual
1410 characters in $string according to FontDecode, above.
1411 "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 Color
1420 "$color=LookupColor($name);"
1421 Lookup the color object associated with $name.
1422 "DefColor($name,$color,$scope);"
1424 Associates the $name with the given $color (a color object), with
1425 the given scoping.
1426 "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 Low-level Functions
1435 "CleanID($id);"
1436 Cleans an $id of disallowed characters, trimming space.
1438 "CleanLabel($label,$prefix);"
1440 Cleans a $label of disallowed characters, trimming space. The
1442 prefix $prefix is prepended (or "LABEL", if none given).
1443 "CleanIndexKey($key);"
1445 Cleans an index key, so it can be used as an ID.
1447 "CleanBibKey($key);"
1449 Cleans a bibliographic citation key, so it can be used as an ID.
1450 "CleanURL($url);"
1452 Cleans a url.
1454 "UTF($code);"
1456 Generates a UTF character, handy for the the 8 bit characters. For
1458 example, UTF(0xA0) generates the non-breaking space.
1459 "@tokens = roman($number);"
1461 Formats the $number in (lowercase) roman numerals, returning a list
1463 of the tokens.
1464 "@tokens = Roman($number);"
1466 Formats the $number in (uppercase) roman numerals, returning a list
1468 of the tokens.
1469
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
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.
1486perl v5.38.0 2023-07-19 LaTeXML::Package(3)