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
470 the function "func" on the first argument to the control
471 sequence; 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
619 operators 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 "ExecuteOptions(@options);"
905 Process the options given explicitly in @options.
907 "AtBeginDocument(@stuff); "
909 Arranges for @stuff to be carried out after the preamble, at the
911 beginning of the document. @stuff should typically be macro-level
912 stuff, but carried out for side effect; it should be tokens, tokens
913 lists, strings (which will be tokenized), or "code($gullet)" which
914 would yield tokens to be expanded.
915 This operation is useful for style files loaded with "--preload" or
917 document specific customization files (ie. ending with ".latexml");
918 normally the contents would be executed before LaTeX and other
919 style files are loaded and thus can be overridden by them. By
920 deferring the evaluation to begin-document time, these contents can
921 override those style files. This is likely to only be meaningful
922 for LaTeX documents.
923 "AtEndDocument(@stuff)"
925 Arranges for @stuff to be carried out just before
926 "\\end{document}". These tokens can be used for side effect, or
927 any content they generate will appear as the last children of the
928 document.
929 Counters and IDs
931 "NewCounter(ctr, within, %options);"
932 Defines a new counter, like LaTeX's \newcounter, but extended. It
934 defines a counter that can be used to generate reference numbers,
935 and defines "\thectr", etc. It also defines an "uncounter" which
936 can be used to generate ID's (xml:id) for unnumbered objects. ctr
937 is the name of the counter. If defined, within is the name of
938 another counter which, when incremented, will cause this counter to
939 be reset. The options are
940 "idprefix=>string"
942 Specifies a prefix to be used to generate ID's when using this
943 counter
944 "nested"
946 Not sure that this is even sane.
947 "$num = CounterValue($ctr);"
949 Fetches the value associated with the counter $ctr.
951 "$tokens = StepCounter($ctr);"
953 Analog of "\stepcounter", steps the counter and returns the
955 expansion of "\the$ctr". Usually you should use
956 "RefStepCounter($ctr)" instead.
957 "$keys = RefStepCounter($ctr);"
959 Analog of "\refstepcounter", steps the counter and returns a hash
961 containing the keys "refnum="$refnum, id=>$id>. This makes it
962 suitable for use in a "properties" option to constructors. The
963 "id" is generated in parallel with the reference number to assist
964 debugging.
965 "$keys = RefStepID($ctr);"
967 Like to "RefStepCounter", but only steps the "uncounter", and
969 returns only the id; This is useful for unnumbered cases of
970 objects that normally get both a refnum and id.
971 "ResetCounter($ctr);"
973 Resets the counter $ctr to zero.
975 "GenerateID($document,$node,$whatsit,$prefix);"
977 Generates an ID for nodes during the construction phase, useful for
979 cases where the counter based scheme is inappropriate. The calling
980 pattern makes it appropriate for use in Tag, as in
981 Tag('ltx:para',afterClose=>sub { GenerateID(@_,'p'); })
983 If $node doesn't already have an xml:id set, it computes an
985 appropriate id by concatenating the xml:id of the closest ancestor
986 with an id (if any), the prefix (if any) and a unique counter.
987 Document Model
989 Constructors define how TeX markup will generate XML fragments, but the
990 Document Model is used to control exactly how those fragments are
991 assembled.
992 "Tag(tag, %properties);"
994 Declares properties of elements with the name tag. Note that "Tag"
996 can set or add properties to any element from any binding file,
997 unlike the properties set on control by "DefPrimtive",
998 "DefConstructor", etc.. And, since the properties are recorded in
999 the current Model, they are not subject to TeX grouping; once set,
1000 they remain in effect until changed or the end of the document.
1001 The tag can be specified in one of three forms:
1003 prefix:name matches specific name in specific namespace
1005 prefix:* matches any tag in the specific namespace;
1006 * matches any tag in any namespace.
1007 There are two kinds of properties:
1009 Scalar properties
1011 For scalar properties, only a single value is returned for a
1012 given element. When the property is looked up, each of the
1013 above forms is considered (the specific element name, the
1014 namespace, and all elements); the first defined value is
1015 returned.
1016 The recognized scalar properties are:
1018 "autoOpen=>boolean"
1020 Specifies whether tag can be automatically opened if needed
1021 to insert an element that can only be contained by tag.
1022 This property can help match the more SGML-like LaTeX to
1023 XML.
1024 "autoClose=>boolean"
1026 Specifies whether this tag can be automatically closed if
1027 needed to close an ancestor node, or insert an element into
1028 an ancestor. This property can help match the more SGML-
1029 like LaTeX to XML.
1030 Code properties
1032 These properties provide a bit of code to be run at the times
1033 of certain events associated with an element. All the code
1034 bits that match a given element will be run, and since they can
1035 be added by any binding file, and be specified in a random
1036 orders, a little bit of extra control is desirable.
1037 Firstly, any early codes are run (eg "afterOpen:early"), then
1039 any normal codes (without modifier) are run, and finally any
1040 late codes are run (eg. "afterOpen:late").
1041 Within each of those groups, the codes assigned for an
1043 element's specific name are run first, then those assigned for
1044 its package and finally the generic one ("*"); that is, the
1045 most specific codes are run first.
1046 When code properties are accumulated by "Tag" for normal or
1048 late events, the code is appended to the end of the current
1049 list (if there were any previous codes added); for early event,
1050 the code is prepended.
1051 The recognized code properties are:
1053 "afterOpen=>code($document,$box)"
1055 Provides code to be run whenever a node with this tag is
1056 opened. It is called with the document being constructed,
1057 and the initiating digested object as arguments. It is
1058 called after the node has been created, and after any
1059 initial attributes due to the constructor (passed to
1060 openElement) are added.
1061 "afterOpen:early" or "afterOpen:late" can be used in place
1063 of "afterOpen"; these will be run as a group before, or
1064 after (respectively) the unmodified blocks.
1065 "afterClose=>code($document,$box)"
1067 Provides code to be run whenever a node with this tag is
1068 closed. It is called with the document being constructed,
1069 and the initiating digested object as arguments.
1070 "afterClose:early" or "afterClose:late" can be used in
1072 place of "afterClose"; these will be run as a group bfore,
1073 or after (respectively) the unmodified blocks.
1074 "RelaxNGSchema(schemaname);"
1076 Specifies the schema to use for determining document model. You
1078 can leave off the extension; it will look for "schemaname.rng" (and
1079 maybe eventually, ".rnc" if that is ever implemented).
1080 "RegisterNamespace(prefix, URL);"
1082 Declares the prefix to be associated with the given URL. These
1084 prefixes may be used in ltxml files, particularly for constructors,
1085 xpath expressions, etc. They are not necessarily the same as the
1086 prefixes that will be used in the generated document Use the prefix
1087 "#default" for the default, non-prefixed, namespace. (See
1088 RegisterDocumentNamespace, as well as DocType or RelaxNGSchema).
1089 "RegisterDocumentNamespace(prefix, URL);"
1091 Declares the prefix to be associated with the given URL used within
1093 the generated XML. They are not necessarily the same as the
1094 prefixes used in code (RegisterNamespace). This function is less
1095 rarely needed, as the namespace declarations are generally obtained
1096 from the DTD or Schema themselves Use the prefix "#default" for the
1097 default, non-prefixed, namespace. (See DocType or RelaxNGSchema).
1098 "DocType(rootelement, publicid, systemid, %namespaces);"
1100 Declares the expected rootelement, the public and system ID's of
1102 the document type to be used in the final document. The hash
1103 %namespaces specifies the namespaces prefixes that are expected to
1104 be found in the DTD, along with each associated namespace URI. Use
1105 the prefix "#default" for the default namespace (ie. the namespace
1106 of non-prefixed elements in the DTD).
1107 The prefixes defined for the DTD may be different from the prefixes
1109 used in implementation CODE (eg. in ltxml files; see
1110 RegisterNamespace). The generated document will use the namespaces
1111 and prefixes defined for the DTD.
1112 Document Rewriting
1114 During document construction, as each node gets closed, the text
1115 content gets simplfied. We'll call it applying ligatures, for lack of
1116 a better name.
1117 "DefLigature(regexp, %options);"
1119 Apply the regular expression (given as a string: "/fa/fa/" since it
1121 will be converted internally to a true regexp), to the text
1122 content. The only option is "fontTest=>code($font)"; if given,
1123 then the substitution is applied only when "fontTest" returns true.
1124 Predefined Ligatures combine sequences of "." or single-quotes into
1126 appropriate Unicode characters.
1127 "DefMathLigature($string"=""$replacment,%options);>
1129 A Math Ligature typically combines a sequence of math tokens
1131 (XMTok) into a single one. A simple example is
1132 DefMathLigature(":=" => ":=", role => 'RELOP', meaning => 'assign');
1134 replaces the two tokens for colon and equals by a token
1136 representing assignment. The options are those characterising an
1137 XMTok, namely: "role", "meaning" and "name".
1138 For more complex cases (recognizing numbers, for example), you may
1140 supply a function "matcher="CODE($document,$node)>, which is passed
1141 the current document and the last math node in the sequence. It
1142 should examine $node and any preceding nodes (using
1143 "previousSibling") and return a list of "($n,$string,%attributes)"
1144 to replace the $n nodes by a new one with text content being
1145 $string content and the given attributes. If no replacement is
1146 called for, CODE should return undef.
1147 After document construction, various rewriting and augmenting of the
1149 document can take place.
1150 "DefRewrite(%specification);"
1152 "DefMathRewrite(%specification);"
1153 These two declarations define document rewrite rules that are
1155 applied to the document tree after it has been constructed, but
1156 before math parsing, or any other postprocessing, is done. The
1157 %specification consists of a sequence of key/value pairs with the
1158 initial specs successively narrowing the selection of document
1159 nodes, and the remaining specs indicating how to modify or replace
1160 the selected nodes.
1161 The following select portions of the document:
1163 "label=>label"
1165 Selects the part of the document with label=$label
1166 "scope=>scope"
1168 The scope could be "label:foo" or "section:1.2.3" or something
1169 similar. These select a subtree labelled 'foo', or a section
1170 with reference number "1.2.3"
1171 "xpath=>xpath"
1173 Select those nodes matching an explicit xpath expression.
1174 "match=>tex"
1176 Selects nodes that look like what the processing of tex would
1177 produce.
1178 "regexp=>regexp"
1180 Selects text nodes that match the regular expression.
1181 The following act upon the selected node:
1183 "attributes=>hashref"
1185 Adds the attributes given in the hash reference to the node.
1186 "replace=>replacement"
1188 Interprets replacement as TeX code to generate nodes that will
1189 replace the selected nodes.
1190 Mid-Level support
1192 "$tokens = Expand($tokens);"
1193 Expands the given $tokens according to current definitions.
1195 "$boxes = Digest($tokens);"
1197 Processes and digestes the $tokens. Any arguments needed by
1199 control sequences in $tokens must be contained within the $tokens
1200 itself.
1201 "@tokens = Invocation($cs,@args);"
1203 Constructs a sequence of tokens that would invoke the token $cs on
1205 the arguments.
1206 "RawTeX('... tex code ...');"
1208 RawTeX is a convenience function for including chunks of raw TeX
1210 (or LaTeX) code in a Package implementation. It is useful for
1211 copying portions of the normal implementation that can be handled
1212 simply using macros and primitives.
1213 "Let($token1,$token2);"
1215 Gives $token1 the same `meaning' (definition) as $token2; like
1217 TeX's \let.
1218 "StartSemiVerbatim(); ... ; EndSemiVerbatim();"
1220 Disable disable most TeX catcodes.
1221 "$tokens = Tokenize($string);"
1223 Tokenizes the $string using the standard catcodes, returning a
1224 LaTeXML::Core::Tokens.
1225 "$tokens = TokenizeInternal($string);"
1227 Tokenizes the $string according to the internal cattable (where @
1228 is a letter), returning a LaTeXML::Core::Tokens.
1229 Argument Readers
1231 "ReadParameters($gullet,$spec);"
1232 Reads from $gullet the tokens corresponding to $spec (a Parameters
1234 object).
1235 "DefParameterType(type, code($gullet,@values), %options);"
1237 Defines a new Parameter type, type, with code for its reader.
1239 Options are:
1241 "reversion=>code($arg,@values);"
1243 This code is responsible for converting a previously parsed
1244 argument back into a sequence of Token's.
1245 "optional=>boolean"
1247 whether it is an error if no matching input is found.
1248 "novalue=>boolean"
1250 whether the value returned should contribute to argument lists,
1251 or simply be passed over.
1252 "semiverbatim=>boolean"
1254 whether the catcode table should be modified before reading
1255 tokens.
1256 "<DefColumnType(proto, expansion);"
1258 Defines a new column type for tabular and arrays. proto is the
1260 prototype for the pattern, analogous to the pattern used for other
1261 definitions, except that macro being defined is a single character.
1262 The expansion is a string specifying what it should expand into,
1263 typically more verbose column specification.
1264 Access to State
1266 "$value = LookupValue($name);"
1267 Lookup the current value associated with the the string $name.
1269 "AssignValue($name,$value,$scope);"
1271 Assign $value to be associated with the the string $name, according
1273 to the given scoping rule.
1274 Values are also used to specify most configuration parameters
1276 (which can therefore also be scoped). The recognized configuration
1277 parameters are:
1278 STRICT : whether errors (eg. undefined macros)
1280 are fatal.
1281 INCLUDE_COMMENTS : whether to preserve comments in the
1282 source, and to add occasional line
1283 number comments. (Default true).
1284 PRESERVE_NEWLINES : whether newlines in the source should
1285 be preserved (not 100% TeX-like).
1286 By default this is true.
1287 SEARCHPATHS : a list of directories to search for
1288 sources, implementations, etc.
1289 "PushValue($name,@values);"
1291 This function, along with the next three are like "AssignValue",
1293 but maintain a global list of values. "PushValue" pushes the
1294 provided values onto the end of a list. The data stored for $name
1295 is global and must be a LIST reference; it is created if needed.
1296 "UnshiftValue($name,@values);"
1298 Similar to "PushValue", but pushes a value onto the front of the
1300 list. The data stored for $name is global and must be a LIST
1301 reference; it is created if needed.
1302 "PopValue($name);"
1304 Removes and returns the value on the end of the list named by
1306 $name. The data stored for $name is global and must be a LIST
1307 reference. Returns "undef" if there is no data in the list.
1308 "ShiftValue($name);"
1310 Removes and returns the first value in the list named by $name.
1312 The data stored for $name is global and must be a LIST reference.
1313 Returns "undef" if there is no data in the list.
1314 "LookupMapping($name,$key);"
1316 This function maintains a hash association named by $name. It
1318 returns the value associated with $key within that mapping. The
1319 data stored for $name is global and must be a HASH reference.
1320 Returns "undef" if there is no data associated with $key in the
1321 mapping, or the mapping is not (yet) defined.
1322 "AssignMapping($name,$key,$value);"
1324 This function associates $value with $key within the mapping named
1326 by $name. The data stored for $name is global and must be a HASH
1327 reference; it is created if needed.
1328 "$value = LookupCatcode($char);"
1330 Lookup the current catcode associated with the the character $char.
1332 "AssignCatcode($char,$catcode,$scope);"
1334 Set $char to have the given $catcode, with the assignment made
1336 according to the given scoping rule.
1337 This method is also used to specify whether a given character is
1339 active in math mode, by using "math:$char" for the character, and
1340 using a value of 1 to specify that it is active.
1341 "$meaning = LookupMeaning($token);"
1343 Looks up the current meaning of the given $token which may be a
1345 Definition, another token, or the token itself if it has not
1346 otherwise been defined.
1347 "$defn = LookupDefinition($token);"
1349 Looks up the current definition, if any, of the $token.
1351 "InstallDefinition($defn);"
1353 Install the Definition $defn into $STATE under its control
1355 sequence.
1356 "XEquals($token1,$token2)"
1358 Tests whether the two tokens are equal in the sense that they are
1359 either equal tokens, or if defined, have the same definition.
1360 Fonts
1362 "MergeFont(%fontspec); "
1363 Set the current font by merging the font style attributes with the
1365 current font. The %fontspec specifies the properties of the
1366 desired font. Likely values include (the values aren't required to
1367 be in this set):
1368 family : serif, sansserif, typewriter, caligraphic,
1370 fraktur, script
1371 series : medium, bold
1372 shape : upright, italic, slanted, smallcaps
1373 size : tiny, footnote, small, normal, large,
1374 Large, LARGE, huge, Huge
1375 color : any named color, default is black
1376 Some families will only be used in math. This function returns
1378 nothing so it can be easily used in beforeDigest, afterDigest.
1379 "DeclareFontMap($name,$map,%options);"
1381 Declares a font map for the encoding $name. The map $map is an
1382 array of 128 or 256 entries, each element is either a unicode
1383 string for the representation of that codepoint, or undef if that
1384 codepoint is not supported by this encoding. The only option
1385 currently is "family" used because some fonts (notably cmr!) have
1386 different glyphs in some font families, such as
1387 "family="'typewriter'>.
1388 "FontDecode($code,$encoding,$implicit);"
1390 Returns the unicode string representing the given codepoint $code
1391 (an integer) in the given font encoding $encoding. If $encoding is
1392 undefined, the usual case, the current font encoding and font
1393 family is used for the lookup. Explicit decoding is used when
1394 "\\char" or similar are invoked ($implicit is false), and the
1395 codepoint must be represented in the fontmap, otherwise undef is
1396 returned. Implicit decoding (ie. $implicit is true) occurs within
1397 the Stomach when a Token's content is being digested and converted
1398 to a Box; in that case only the lower 128 codepoints are converted;
1399 all codepoints above 128 are assumed to already be Unicode.
1400 The font map for $encoding is automatically loaded if it has not
1402 already been loaded.
1403 "FontDecodeString($string,$encoding,$implicit);"
1405 Returns the unicode string resulting from decoding the individual
1406 characters in $string according to FontDecode, above.
1407 "LoadFontMap($encoding);"
1409 Finds and loads the font map for the encoding named $encoding, if
1410 it hasn't been loaded before. It looks for
1411 "encoding.fontmap.ltxml", which would typically define the font map
1412 using "DeclareFontMap", possibly including extra maps for families
1413 like "typewriter".
1414 Color
1416 "$color=LookupColor($name);"
1417 Lookup the color object associated with $name.
1418 "DefColor($name,$color,$scope);"
1420 Associates the $name with the given $color (a color object), with
1421 the given scoping.
1422 "DefColorModel($model,$coremodel,$tocore,$fromcore);"
1424 Defines a color model $model that is derived from the core color
1425 model $coremodel. The two functions $tocore and $fromcore convert
1426 a color object in that model to the core model, or from the core
1427 model to the derived model. Core models are rgb, cmy, cmyk, hsb
1428 and gray.
1429 Low-level Functions
1431 "CleanID($id);"
1432 Cleans an $id of disallowed characters, trimming space.
1434 "CleanLabel($label,$prefix);"
1436 Cleans a $label of disallowed characters, trimming space. The
1438 prefix $prefix is prepended (or "LABEL", if none given).
1439 "CleanIndexKey($key);"
1441 Cleans an index key, so it can be used as an ID.
1443 "CleanBibKey($key);"
1445 Cleans a bibliographic citation key, so it can be used as an ID.
1446 "CleanURL($url);"
1448 Cleans a url.
1450 "UTF($code);"
1452 Generates a UTF character, handy for the the 8 bit characters. For
1454 example, "UTF(0xA0)" generates the non-breaking space.
1455 "@tokens = roman($number);"
1457 Formats the $number in (lowercase) roman numerals, returning a list
1459 of the tokens.
1460 "@tokens = Roman($number);"
1462 Formats the $number in (uppercase) roman numerals, returning a list
1464 of the tokens.
1465
1467 See also LaTeXML::Global, LaTeXML::Common::Object,
1468 LaTeXML::Common::Error, LaTeXML::Core::Token, LaTeXML::Core::Tokens,
1469 LaTeXML::Core::Box, LaTeXML::Core::List, LaTeXML::Common::Number,
1470 LaTeXML::Common::Float, LaTeXML::Common::Dimension,
1471 LaTeXML::Common::Glue, LaTeXML::Core::MuDimension,
1472 LaTeXML::Core::MuGlue, LaTeXML::Core::Pair, LaTeXML::Core::PairList,
1473 LaTeXML::Common::Color, LaTeXML::Core::Alignment, LaTeXML::Common::XML,
1474 LaTeXML::Util::Radix.
1475
1477 Bruce Miller <bruce.miller@nist.gov>
1478
1480 Public domain software, produced as part of work done by the United
1481 States Government & not subject to copyright in the US.
1482perl v5.34.0 2021-11-24 LaTeXML::Package(3)