plasTeX A Python Framework for Processing LaTeX Documents

Kevin D. Smith

7 February 2008

SAS Email:
[email protected]

ii

CONTENTS

1 2

Introduction plastex The Command-Line Interface 2.1 Command-Line and Conguration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The plasTEX Document 3.1 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Complex Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding Macros and Packages A 4.1 Dening Macros in LTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Dening Macros in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renderers 5.1 Simple Renderer Example . . 5.2 Renderable Objects . . . . . . 5.3 Page Template Renderer . . . 5.4 XHTML Renderer . . . . . . 5.5 DocBook Renderer . . . . . . 5.6 ManPage and Text Renderers

1 3 3 11 13 16 16 23 23 24 32 35 36 39 42 52 53 53 55 55 60 68 73 75 79 82 87 89 89 91

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

plasTEX Frameworks and APIs 6.1 plasTeX The Python Macro and Document Interfaces . . . . . 6.2 plasTeX.ConfigManager plasTEX Conguration . . . . . 6.3 plasTeX.DOM The plasTEX Document Object Model (DOM) . 6.4 plasTeX.TeX The TEX Stream . . . . . . . . . . . . . . . . . 6.5 plasTeX.Context The TEX Context . . . . . . . . . . . . . 6.6 plasTeX.Renderers The plasTEX Rendering Framework . 6.7 plasTeX.Imagers The plasTEX Imaging Framework . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

A About This Document B Frequently Asked Questions A B.1 Parsing LTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index

ii

CHAPTER

ONE

Introduction
A plasTEXis a collection of Python frameworks that allow you to process LTEX documents. This processing includes, but A is not limited to, conversion of LTEX documents to various document formats. Of course, it is capable of converting to HTML or XML formats such as DocBook and tBook, but it is an open framework that allows you to drive any type of rendering. This means that it could be used to drive a COM object that creates a MS Word Document.

The plasTEX framework allows you to control all of the processes including tokenizing, object creation, and rendering through API calls. You also have access to all of the internals such as counters, the states of if commands, locally A and globally dened macros, labels and references, etc. In essence, it is a LTEX document processor that gives you the advantages of an XML document in the context of a language as superb as Python. Here are some of the main features and benets of plasTEX.
A A Simple High-Level API The API for processing a LTEX document is simple enough that you can write a LTEX to HTML converter in one line of code (not including the Python import lines). Just to prove it, here it is!

import sys from plasTeX.TeX import TeX from plasTeX.Renderers.XHTML import Renderer Renderer().render(TeX(file=sys.argv[-1]).parse())

Full Conguration File and Command-Line Option Control The conguration object included with plasTEX can be extended to include your own options. Low-Level Tokenizing Control The tokenizer in plasTEX works very much like the tokenizer in TEX itself. In your macro classes, you can actually control the draining of tokens and even change category codes.
A A Document Object While most other LTEX converters translate from LTEX source another type of markup, plasTEX actually converts the document into a document object very similar to the DOM used in XML. Of course, there are many Python constructs built on top of this object to make it more Pythonic, so you dont have to deal with the objects using only DOM methods. Whats really nice about this is that you can actually manipulate the document object prior to rendering. While this may be an esoteric feature, not many other converters let you get between the parser and the renderer.

Full Rendering Control In plasTEX you get full control over the renderer. There is a Zope Page Template (ZPT) based renderer included for HTML and XML applications, but that is merely an example of what you can do. A renderer is simply a collection of functions1 . During the rendering process, each node in the document object is passed to the function in the renderer that has the same name as the node. What that function does is up to the renderer. In the case of the ZPT-based renderer, the node is simply applied to the template using the expand() method. If you dont like ZPT, there is nothing preventing you from populating a renderer with functions that
1 functions is being used loosely here. Actually, any callable Python object (i.e. function, method, or any object with the __call__ method implemented) can be used.

invoke other types of templates, or functions that simply generate markup with print statements. You could even drive a COM interface to create a MS Word document.

Contents

CHAPTER

TWO

plastex The Command-Line Interface

A While plasTEX makes it possible to parse LTEX directly from Python code, most people will simply use the supplied command-line interface, plastex. plastex will invoke the parsing processes and apply a specied renderer. By default, plastex will convert to HTML, although this can be changed in the plastex conguration. A Invoking plastex is very simple. To convert a LTEX document to HTML using all of the defaults, simply type the following at shell prompt.

plastex mylatex.tex

A A where mylatex.tex is the name of your LTEX le. The LTEX source will be parsed, all packages will be loaded and macros expanded, and converted to HTML. Hopefully, at this point you will have a lovely set of HTML les that A A accurately reect the LTEX source document. Unfortunately, converting LTEX to other formats can be tricky, and there are many pitfalls. If you are getting warnings or errors while converting your document, you may want to check the FAQ in the appendix to see if your problem is addressed.

Running plastex with the default options may not give you output exactly the way you had envisioned. Luckily, there are many options that allow you to change the rendering behavior. These options are described in the following section.

2.1

Command-Line and Conguration Options

There are many options to plastex that allow you to control things input and output le encodings, where les are generated and what the lenames look like, rendering parameters, etc. While plastex is the interface where the options are specied, for the most part these options are simply passed to the parser and renderers for their use. It is even possible to create your own options for use in your own Python-based macros and renderers. The following options are currently available on the plastex command. They are categorized for convenience.

2.1.1

General Options

Conguration les Command-Line Options: --cong=cong-le or -c cong-le Cong File: [ general ] cong species a conguration le to load. This should be the rst option specied on the command-line. Kpsewhich Command-Line Options: --kpsewhich=program Cong File: [ general ] kpsewhich

Default: kpsewhich A species the kpsewhich program to use to locate LTEX les and packages. Renderer Command-Line Options: --renderer=renderer-name Cong File: [ general ] renderer Default: XHTML species which renderer to use. Themes Command-Line Options: --theme=theme-name Cong File: [ general ] theme Default: default species which theme to use. Extra theme les Command-Line Options: --copy-theme-extras or --ignore-theme-extras Cong File: [ general ] copy-theme-extras Default: yes indicates whether or not extra les that belong to a theme (if there are any) should be copied to the output directory.

2.1.2

Document Properties

Base URL Command-Line Options: --base-url=url Cong File: [ document ] base-url species a base URL to prepend to the path of all links. Number of Columns in the Index Command-Line Options: --index-columns=integer Cong File: [ document ] index-columns species the number of columns to group the index into. Section number depth Command-Line Options: --sec-num-depth=integer Cong File: [ document ] sec-num-depth Default: 6 species the section level depth that should appear in section numbers. This value overrides the value of the secnumdepth counter in the document. Title for the document Command-Line Options: --title=string Cong File: [ document ] title A species a title to use for the document instead of the title given in the LTEX source document Table of contents depth Command-Line Options: --toc-depth=integer Cong File: [ document ] toc-depth species the number of levels to include in each table of contents.

Contents

Display sections in the table of contents that do not create les Command-Line Options: --toc-non-les Cong File: [ document ] toc-non-les species that sections that do not create les should still appear in the table of contents. By default, only sections that create les will show up in the table of contents.

2.1.3

Counters

It is possible to set the initial value of a counter from the command-line using the --counter option or the counters section in a conguration le. The conguration le format for setting counters is very simple. The option name in the conguration le corresponds to the counter name, and the value is the value to set the counter to.
[counters] chapter=4 part=2

The sample conguration above sets the chapter counter to 4, and the part counter to 2. The --counter can also set counters. It accepts multiple arguments which must be surrounded by square brackets ([ ]). Each counter set in the --counter option requires two values: the name of the counter and the value to set the counter to. An example of --counter is shown below.
plastex --counter [ part 2 chapter 4 ] file.tex

Just as in the conguration example, this command-line sets the part counter to 2, and the chapter counter to 4. Set initial counter values Command-Line Options: --counter=[ counter-name initial-value ] species the initial counter values.

2.1.4

Document Links

The links section of the conguration is a little different than the others. The options in the links section are not precongured, they are all user-specied. The links section includes information to be included in the navigation object available on all sections in a document. By default, the sections navigation object includes things like the previous and next objects in the document, the child nodes, the sibling nodes, etc. The table below lists all of the navigation objects that are already dened. The names for these items came from the link types dened at http: //fantasai.tripod.com/qref/Appendix/LinkTypes/ltdef.html. Of course, it is up to the renderer to actually make use of them.

Contents

Name home start begin rst end last next prev previous up top origin parent child siblings document part chapter section subsection navigator toc contents breadcrumbs

Description the rst section in the document same as home same as home same as home the last section in the document same as end the next section in the document the previous section in the document same as prev the parent section the top section in the document same as top the parent section a list of the subsections a list of the sibling sections the document object the current part object the current chapter object the current section object the current subsection object the top node in the document object the node containing the table of contents same as toc a list of the parent objects of the current node

Since each of these items references an object that is expected to have a URL and a title, any user-dened elds should contain these as well (although the URL is optional in some items). To create a user-dened eld in this object, you need to use two options: one for the title and one for the URL, if one exists. They are specied in the cong le as follows:
[links] next-url=http://myhost.com/glossary next-title=The Next Document mylink-title=Another Title

These option names are split on the dash (-) to create a key, before the dash, and a member, after the dash. A dictionary is inserted into the navigation object with the name of the key, and the members are added to that dictionary. The conguration above would create the following Python dictionary.
{ next: { url:http://myhost.com/glossary, title:The Next Document }, mylink: { title:Another Title } }

Contents

While you can not override a eld that is populated by the document, there are times when a eld isnt populated. This occurs, for example, in the prev eld at the beginning of the document, or the next eld at the end of the document. If you specify a prev or next eld in your conguration, those elds will be used when no prev or next is available. This allows you to link to external documents at those points. Set document links Command-Line Options: --links=[ key optional-url title ] species links to be included in the navigation object. Since at least two values are needed in the links (key and title, with an optional URL), the values are grouped in square brackets on the command-line ([ ]).

2.1.5

Input and Output Files

If you have a renderer that only generates one le, specifying the output lename is simple: use the --lename option to specify the name. However, if the renderer you are using generates multiple les, things get more complicated. The --lename option is also capable of handling multiple names, as well as giving you a templating way to build lenames. Below is a list of all of the options that affect lename generation. Characters that shouldnt be used in a lename Command-Line Options: --bad-lename-chars=string Cong File: [ les ] bad-chars Default: : #$%^&*!~"=?/[]()|<>;\,. species all characters that should not be allowed in a lename. These characters will be replaced by the value in --bad-lename-chars-sub. String to use in place of invalid characters Command-Line Options: --bad-lename-chars-sub=string Cong File: [ les ] bad-chars-sub Default: species a string to use in place of invalid lename characters ( specied by the --bad-chars-sub option) Output Directory Command-Line Options: --dir=directory or -d directory Cong File: [ les ] directory Default: $jobname species a directory name to use as the output directory. Escaping characters higher than 7-bit Command-Line Options: --escape-high-chars Cong File: [ les ] escape-high-chars Default: False some output types allow you to represent characters that are greater than 7-bits with an alternate representation to alleviate the issue of le encoding. This option indicates that these alternate representations should be used. Note: The renderer is responsible for doing the translation into the alternate format. This might not be supported by all output types. Template to use for output lenames Command-Line Options: --lename=string Cong File: [ les ] lename species the templates to use for generating lenames. The lename template is a list of space separated names. Each name in the list is returned once. An example is shown below. Contents 7

index.html toc.html file1.html file2.html

If you dont know how many les you are going to be reproducing, using static lenames like in the example above is not practical. For this reason, these lenames can also contain variables as described in Pythons string Templates (e.g. $title, $id). These variables come from the namespace created in the renderer and include: $id, A the ID (i.e. label) of the item, $title, the title of the item, and $jobname, the basename of the LTEX le being processed. One special variable is $num. This value in generated dynamically whenever a lename with $num is requested. Each time a lename with $num is successfully generated, the value of $num is incremented. The values of variables can also be modied by a format specied in parentheses after the variable. The format is simply an integer that species how wide of a eld to create for integers (zero-padded), or, for strings, how many space separated words to limit the name to. The example below shows $num being padded to four places and $title being limited to ve words.
sect$num(4).html $title(5).html

The list can also contain a wildcard lename (which should be specied last). Once a wildcard name is reached, it is used from that point on to generate the remaining lenames. The wildcard lename contains a list of alternatives to use as part of the lename indicated by a comma separated list of alternatives surrounded by a set of square brackets ([ ]). Each of the alternatives specied is tried until a lename is successfully created (i.e. all variables resolve). For example, the specication below creates three alternatives.
$jobname_[$id, $title, sect$num(4)].html

The code above is expanded to the following possibilities.

$jobname_$id.html $jobname_$title.html $jobname_sect$num(4).html

Each of the alternatives is attempted until one of them succeeds. In order for an alternative to succeed, all of the variables referenced in the template must be populated. For example, the $id variable will not be populated unless the node had a \$label macro pointing to it. The title variable would not be populated unless the node had a title associated with it (e.g. such as section, subsection, etc.). Generally, the last one should contain no variables except for $num as a fail-safe alternative. Input Encoding Command-Line Options: --input-encoding=string Cong File: [ les ] input-encoding Default: utf-8 A species which encoding the LTEX source le is in Output Encoding Command-Line Options: --output-encoding=string Cong File: [ les ] output-encoding Default: utf-8 species which encoding the output les should use. Note: This depends on the output format as well. While HTML and XML use encodings, a binary format like MS Word, would not. Splitting document into multiple les Command-Line Options: --split-level=integer 8 Contents

Cong File: [ les ] split-level Default: 2 A species the highest section level that generates a new le. Each section in a LTEX document has a number associated with its hierarchical level. These levels are -2 for the document, -1 for parts, 0 for chapters, 1 for sections, 2 for subsections, 3 for subsubsections, 4 for paragraphs, and 5 for subparagraphs. A new le will be generated for every section in the hierarchy with a value less than or equal to the value of this option. This means that for the value of 2, les will be generated for the document, parts, chapters, sections, and subsections.

2.1.6

Image Options

Images are created by renderers when the output type in incapable of rendering the content in any other way. This method is commonly used to display equations in HTML output. The following options control how images are generated. Base URL Command-Line Options: --image-base-url=url Cong File: [ images ] base-url species a base URL to prepend to the path of all images.
A LTEX program to use to compile image document Command-Line Options: --image-compiler=program Cong File: [ images ] compiler Default: latex A species which program to use to compile the images LTEX document.

Enable or disable image generation Command-Line Options: --enable-images or --disable-images Cong File: [ images ] enabled Default: yes indicates whether or not images should be generated. Enable or disable the image cache Command-Line Options: --enable-image-cache or --disable-image-cache Cong File: [ images ] cache Default: yes indicates whether or not images should use a cache between runs.
A Convert LTEX output to images Command-Line Options: --imager=program Cong File: [ images ] imager Default: dvipng dvi2bitmap gsdvipng gspdfpng OSXCoreGraphics A species which converter will be used to take the output from the LTEX compiler and convert it to images. You can specify a space delimited list of names as well. If a list of names is specied, each one is veried in order to see if it works on the current machine. The rst one that succeeds is used.

You can use the value of none to turn the imager off. Image lenames Command-Line Options: --image-lenames=lename-template Cong File: [ images ] lenames Default: images/img-$num(4).png species the image naming template to use to generate lenames. This template is the same as the templates used by the --lename option. Contents 9

A Convert LTEX output to vector images Command-Line Options: --vector-imager=program Cong File: [ images ] vector-imager Default: dvisvgm A species which converter will be used to take the output from the LTEX compiler and convert it to vector images. You can specify a space delimited list of names as well. If a list of names is specied, each one is veried in order to see if it works on the current machine. The rst one that succeeds is used.

You can use the value of none to turn the vector imager off. Note: When using the vector imager, a bitmap image is also created using the regular imager. This bitmap is used to determine the depth information about the vector image and can also be used as a backup if the vector image is not supported by the viewer.

10

Contents

CHAPTER

THREE

The plasTEX Document

The plasTEX document is very similar to an XML DOM structure. In fact, you can use XML DOM methods to create and populate nodes, delete or move nodes, etc. The biggest difference between the plasTEX document and an XML document is that in XML the attributes of an element are simply string values, whereas attributes in a plasTEX document are generally document fragments that contain the arguments of a macro. Attributes can be cangured to hold other Python objects like lists, dictionaries, and strings as well (see the section 4 for more information).
A While XML document objects have a very strict syntax, LTEX documents are a little more free-form. Because of this, A the plasTEX framework does a lot of normalizing of the LTEX document to make it conform to a set of rules. This set of rules means that you will always get a consistent output document which is necessary for easy manipulation and programability.

The overall document structure should not be surprising. There is a document element at the top level which correA sponds to the XML Document node. The child nodes of the Document node begin with the preamble to the LTEX document. This includes things like the \documentclass, \newcommands, \title, \author, counter settings, etc. For the most part, these nodes can be ignored. While they are a useful part of the document, they are generally only used by internal processes in plasTEX. What is important is the last node in the document which corresponds to A LTEXs document environment. The document environment has a very simple structure. It consists solely of paragraphs (actually \pars in TEXs terms) and sections1 . In fact, all sections have this same format including parts, chapters, sections, subsections, subsubsections, paragraphs, and subparagraphs. plasTEX can tell which pieces of a document correspond to a sectioning element by looking at the level attribute of the Python class that corresponds to the given macro. The section levels A in plasTEX are the same as those used by LTEX: -1 for part, 0 for chapter, 1 for section, etc. You can create your own sectioning commands simply by subclassing an existing macro class, or by setting the level attribute to a value that corresponds to the level of section you want to mimic. All level values less than 100 are reserved for sectioning so you A arent limited to LTEXs sectioning depth. Figure 3.1 below shows an example of the overall document structure. This document is constructed during the parsing process by calling the digest method on each node. The digest method is passed an iterator of document nodes that correspond to the nodes in the document that follow the current node. It is the responsibility of the current node to only absorb the nodes that belong to it during the digest process. Luckily, the default digest method will work in nearly all cases. See section 4 for more information on the digestion process. Part of this digestion process is grouping nodes into paragraphs. This is done using the paragraphs method available in all Macro based classes. This method uses the same technique as TEX to group paragraphs of content. Section 3.2 has more information about the details of paragraph grouping. In addition to the level attribute of sections, there is also a mixin class that assists in generating the table of contents and navigation elements during rendering. If you create your own sectioning commands, you should include A plasTeX.Base.LaTeX.Sectioning.SectionUtils as a base class as well. All of the standard LTEX section commands already inherit from this class, so if you subclass one of those, youll get the helper methods for free. For more information on these helper methods see section 3.1.
1 sections

in this document is used loosely to mean any type of section: part, chapter, section, etc.

11

Figure 3.1: The overall plasTEX document structure

A The structure of the rest of the document is also fairly simple and well-dened. LTEX commands are each converted A into a document node with its arguments getting placed into the attributes dictionary. LTEX environments also create a single node in the document, where the child nodes of the environment include everything between the \begin and \end commands. By default, the child nodes of an environment are simply inserted in the order that they appear in the document. However, there are some environments that require further processing due to their more complex structures. These structures include arrays and tabular environments, as well as itemized lists. For more information A on these structures see sections 3.3.3 and 3.3.1, respectively. Figures 3.2 and 3.3 shows a common LTEX document fragment and the resulting plasTEX document node structure.

\begin{center} Every \textbf{good} boy does \textit{fine}. \end{center}

A Figure 3.2: Sample LTEX document fragment code

You may have noticed that in the document structure in Figure 3.3 the text corresponding to the argument for \textbf and \textit is actually a child node and not an attribute. This is actually a convenience feature in plasTEX. For macros like this where there is only one argument and that argument corresponds to the content of the macro, it is common to put that content into the child nodes. This is done in the args attribute of the macro class by setting the arguments name to self. This magical value will link the attribute called self to the child nodes array. For more information on the args attribute and how it populates the attributes dictionary see section 4.
A In the plasTEX framework, the input LTEX document is parsed and digested until the document is nished. At this point, you should have an output document that conforms to the rules described above. The document should have a regular enough structure that working with it programatically using DOM methods or Python practices should be fairly straight-forward. The following sections give more detail on document structure elements that require extra

12

Contents

Figure 3.3: Resulting plasTEX document node structure processing beyond the standard parse-digest process.

3.1

Sections

Sections in plasTEX refer to any macro that creates a section-like construct in a document including the document environment, \part, \chapter, \section, \subsection, \subsubsection, \paragraph, and A \subparagraph. While these are the sectioning macros dened by LTEX, you are not limited to using just those commands to create sections in your own documents. There are two elements that must exist for a Python macro class to act like a section: 1) the level attribute must be set to a value less than 100, and 2) the class should inherit from plasTeX.Base.LaTeX.Sectioning.SectionUtils. The level attribute refers to the section level in the document. The values for this attribute are the same values that A LTEX uses for its section levels, namely: -1 or Node.PART_LEVEL corresponds to \part 0 or Node.CHAPTER_LEVEL corresponds to \chapter 1 or Node.SECTION_LEVEL corresponds to \section 2 or Node.SUBSECTION_LEVEL corresponds to \subsection 3 or Node.SUBSUBSECTION_LEVEL corresponds to \subsubsection 4 or Node.PARAGRAPH_LEVEL corresponds to \paragraph 5 or Node.SUBPARAGRAPH_LEVEL corresponds to \subparagraph plasTEX adds the following section related levels: -sys.maxint or Node.DOCUMENT_LEVEL corresponds to the document environment and is always the toplevel section Contents 13

6 or Node.SUBSUBPARAGRAPH_LEVEL this level was added to correspond to the sixth level of headings dened in HTML 100 or Node.ENDSECTIONS_LEVEL ag that indicates the last possible section nesting level. This is mainly used for internal purposes. plasTEX uses the level attribute to build the appropriate document structure. If all you need is a proper document structure, the level attribute is the only thing that needs to be set on a macro. However, there are many convenience properties in the plasTeX.Base.LaTeX.Sectioning.SectionUtils class that are used in the rendering process. If you plan on rendering your document, your section classes should inherit from this class. Below is a list of the additional properties and their purpose. Name allSections documentSections links Purpose contains a sequential list of all of the sections within and including the current section contains a sequential list of all of the sections within the entire document contains a dictionary contain various amounts of navigation information corresponding mostly to the link types described at http://fantasai.tripod.com/qref/Appendix/ LinkTypes/ltdef.html. This includes things like breadcrumb trails, previous and next links, links to the overall table of contents, etc. See section 3.1.1 for more information. contains a list of all of the sibling sections contains a list of all of the sections within the current section contains an object that corresponds to the table of contents for the section. The table of contents is congurable as well. For more information on how to congure the table of contents see section 3.1.2

siblings subsections tableofcontents

Note: When rst accessed, each of these properties actually navigates the document and builds the returned object. Since these operations can be rather costly, the values are cached. Therefore, if you modify the document after accessing one of these properties you will not see the change reected.

3.1.1

Navigation and Links

The plasTeX.Base.LaTeX.Sectioning.SectionUtils class has a property named links that contains a dictionary of many useful objects that assist in creating navigation bars and breadcrumb trails in the rendered output. This dictionary was modeled after the links described at http://fantasai.tripod.com/qref/Appendix/ LinkTypes/ltdef.html. Some of the objects in this dictionary are created automatically, others are created with the help of the linkType attribute on the document nodes, and yet others can be added manually from a conguration le or command-line options. The automatically generated values are listed in the following table.

14

Contents

Name begin breadcrumbs chapter child contents document end rst home home last navigator next origin parent part prev previous section sibling subsection start toc top up

Purpose the rst section of the document a list containing the entire parentage of the current section (including the current section) the current chapter node a list of the subsections the section that contains the top-level table of contents the document level node the last section of the document the rst section of the document the rst section of the document the rst section of the document the last section of the document the section that contains the top-level table of contents the next section in the document the section that contains the top-level table of contents the parent node the current part node the previous section in the document the previous section in the document the current section a list of the section siblings the current subsection the rst section of the document the section that contains the top-level table of contents the rst section of the document the parent section

Note: The keys in every case are simply strings. Note: Each of the elements in the table above is either a section node or a list of section nodes. Of course, once you have a reference to a node you can acces the attributes and methods of that object for further introspection. An example of accessing these objects from a section instance is shown below.
previousnode = sectionnode.links[prev] nextnode = sectionnode.links[next]

The next method of populating the links table is semi-automatic and uses the linkType attribute on the Python macro class. There are certain parts of a document that only occur once such as an index, glossary, or bibliography. You can set the linkType attribute on the Python macro class to a string that corresponds to that sections role in the document (i.e. index for the index, glossary for the glossary, bibliography for the bibliography). When a node with a special link type is created, it is inserted into the dictionary of links with the given name. This allows you to have links to indexes, glossaries, etc. appear in the links object only when they are in the current document. The example below shows the theindex environment being congured to show up under the index key in the links dictionary.
class theindex(Environment, SectionUtils): nodeType = index level = Environment.SECTION_LEVEL

Note: These links are actually stored under the links key of the owner documents userdata dictionary (i.e. self.ownerDocument.userdata[links]). Other objects can be added to this dictionary manually. The nal way of getting objects into the links dictionary is through a conguration le or command-line options. This method is described fully in section 2.1.4. Contents 15

3.1.2

Table of Contents

The table of contents object returned by the tableofcontents property of SectionUtils is not an actual node of the document, but it is a proxy object that limits the number of levels that you can traverse. The number of levels that you are allowed to traverse is determined by document:toc-depth section of the conguration (see section 2.1.2). Other than the fact that you can only see a certain number of levels of subsections, the object otherwise acts just like any other section node. In addition to limiting the number of levels of a table of contents, you can also determine whether or not sections that do not generate new les while rendering should appear in the table of contents. By default, only sections that generate a new le while rendering will appear in the table of contents object. If you set the value of document:toc-non-files in the conguration to True, then all sections will appear in the table of contents.

3.2

Paragraphs

Paragraphs in a plasTEX document are grouped in the same way that they are grouped in TEX: essentially anything within a section that isnt a section itself is put into a paragraph. This is different than the HTML model where tables and lists are not grouped into paragraphs. Because of this, it is likely that HTML generated that keeps the same paragraph model will not be 100% valid. However, it is highly unlikely that this variance from validity will cause any real problems in the browser rendering the correct output. Paragraphs are grouped using the paragraphs method available on all Python macro classes. When this method is invoked on a node, all of the child nodes are grouped into paragraphs. If there are no paragraph objects in the list of child nodes already, one is created. This is done to make sure that the document is fully normalized and that paragraphs occur everywhere that they can occur. This is most noteworthy in constructs like tables and lists where some table cells or list items have multiple paragraphs and others do not. If a paragraph werent forced into these areas, you could have inconsistently paragraph-ed content. Some areas where paragraphs are allowed, but not necessarily needed might not want the forced paragraph to be generated, such as within a grouping of curly braces ({ }). In these cases, you can use the force=False keyword argument to paragraphs. This still does paragraph grouping, but only if there is a paragraph element already in the list of child nodes.

3.3

Complex Structures

A While much of a plasTEX document mirrors the structure of the source LTEX document, some constructs do require a little more work to be useful in the more rigid structure. The most noteworthy of these constructs are lists, arrays (or tabular environments), and indexes. These objects are described in more detail in the following sections.

3.3.1

Lists

Lists are normalized slightly more than the rest of the document. They are treated almost like sections in that they are only allowed to contain a minimal set of child node types. In fact, lists can only contain one type of child node: list item. The consequence of this is that any content before the rst item in a list will be thrown out. In turn, list items will only contain paragraph nodes. The structure of all list structures will look like the structure in Figure 3.4. This structure allows you to easily traverse a list with code like the following.

16

Contents

Figure 3.4: Normalized structure of all lists

# Iterate through the items in the list node for item in listnode: # Iterate through the paragraphs in each item for par in item: # Print the text content of each paragraph print par.textContent # Print a blank line to separate each item print

3.3.2

Bibliography

The bibliography is really just another list structure with a few enhancements to allow referencing of the items throughout the document. Bibliography processing is left to the normal tools. plasTEX expects a properly .bbl le for the A bibliography. The LTEX bibliography is the format used by default; however, the natbib package is also included with plasTEX for more complex formatting of bibliographies.

3.3.3

Arrays and Tabular Environments

Arrays and tabular environments are the most complex structures in a plasTEX document. This because tables can include spanning columns, spanning rows, and borders specied on the table, rows, and individual cells. In addition, there are alignments associated with each column and alignments can be specied by any \multicolumn command. It is also possible with some packages to create your own column declarations. Add to that the fact that the longtable package allows you to specify multiple headers, footers, and coptions, and you can see why tabular environments can be rather tricky to deal with. As with all parts of the document, plasTEX tries to normalize all tables to have a consistent structure. The structure for arrays and tables is shown in Figure 3.5.

Contents

17

Figure 3.5: Normalized structure of all tables and arrays Luckily, the array macro class that comes with plasTEX was made to handle all of the work for you. In fact, it also handles the work of some extra packages such as longtable to make processing them transparent. The details of the tabular environments are described in the following sections. With this normalized structure, you can traverse all array and table structures with code like the following.
# Iterate through all rows in the table for row in tablenode: # Iterate through all cells in the row for cell in row: # Iterate through all paragraphs in the cell for par in cell: # Print the text content of each cell print + par.textContent # Print a blank line after each cell print # Print a blank line after each row print

18

Contents

Borders Borders in a tabular environment are generally handled by \hline, \vline, \cline, as well as the column specications on the tabular environment and the \multicolumn command. plasTEX merges all of the border specications and puts them into CSS formatted values in the style attribute of each of the table cell nodes. To get the CSS information formatted such that it can be used in an inline style, simply access the inline property of the style object. Here is an example of a tabular environment.
\begin{tabular}{|l|l|}\hline x & y \\ 1 & 2 \\\hline \end{tabular}

The table node can be traversed as follows.

# Print the CSS for the borders of each cell for rownum, row in enumerate(table): for cellnum, cell in enumerate(row): print (%s,%s) %s -- %s % (rownum, cellnum, cell.textContent.strip(), cell.style.inline)

The code above will print the following output (whitespace has been added to make the output easier to read).
(0,0) x -- border-top-style:solid; border-left:1px solid black; border-right:1px solid black; border-top-color:black; border-top-width:1px; text-align:left (0,1) y -- border-top-style:solid; text-align:left; border-top-color:black; border-top-width:1px; border-right:1px solid black (1,0) 1 -- border-bottom-style:solid; border-bottom-width:1px; border-left:1px solid black; border-right:1px solid black; text-align:left; border-bottom-color:black (1,1) 2 -- border-bottom-color:black; border-bottom-width:1px; text-align:left; border-bottom-style:solid; border-right:1px solid black

Alignments Alignments can be specied in the column specication of the tabular environment as well as in the column specication of \multicolumn commands. Just like the border information, the alignment information is also stored in CSS Contents 19

formatted values in each cells style attribute. Longtables Longtables are treated just like regular tables. Only the rst header and the last footer are supported in the resulting table structure. To indicate that these are veriable header or footer cells, the isHeader attribute of the corresponding cells is set to True. This information can be used by the renderer to more accurately represent the table cells.

3.3.4

Indexes

All index building and sorting is done internally in plasTEX. It is done this way because the information that tools like A makeindex generate is only useful to LTEX itself since the refence to the place where the index tag was inserted is simply a page number. Since plasTEX wants to be able to reference the index tag node, it has to do all of the index processing natively. There are actually two index structures. The default structure is simply the index nodes sorted and grouped into the appropriate hierarchies. This structure looks like the structure pictured in Figure 3.6.

Figure 3.6: Default index structure Each item, subitem, and subsubitem has an attribute called key that contains a document fragment of the key for that index item. The document nodes that this key corresponds to are held in a list in the pages attribute. These nodes A are the actual nodes corresponding to the index entry macros from the LTEX document. The content of the node is a number corresponding to the index entry that is formatted according to the formatting rules specied in the index entry. While the structure above works well for paged media, it is sometimes nice to have the index entries grouped by rst letter and possibly even arranged into multiple columns. This alternate representation can be accessed in the groups property. The structure for this type of index is shown in Figure 3.7. In this case, the item, subitem, and subsubitem nodes are the same as in the default scheme. The group has a title 20 Contents

Figure 3.7: Grouped index structure attribute that contains the rst letter of the entries in that group. Entries that start with something other than a letter or an underscore are put into a group called Symbols. The columns are approximately equally sized columns of index entries. The number of columns is determined by the document:index-columns conguration item.

Contents

21

22

CHAPTER

FOUR

Understanding Macros and Packages

A Macros and packages in plasTEX live a dual life. On one hand, macros can be dened in LTEX les and expanded by plasTEX itself. On the other hand, macros can also be implemented as Python classes. Packages are the same way. A plasTEX can handle some LTEX packages natively. Others may have to be implemented in Python. In most cases, both implementations work transparently together. If you dont dene that many macros, and the ones that you do dene are simple or even of intermediate complexity, its probably better to just let plasTEX handle them natively. However, there are some reasons that you may want to implement Python versions of your macros:

Python versions of macros are generally faster You have more control over what gets inserted into the output document You can store information in the documents userdata dictionary for use later
A You can prevent a macro from being expanded into primitive LTEX commands, so that a custom renderer can be used on that node

Some macros just dont make sense in a plasTEX document Some macros are just too complicated for plasTEX If any of these reasons appeal to you, read the following sections on how to implement macros and packages in plasTEX.

4.1

A Dening Macros in LTEX

A Dening macros in LTEX using plasTEX is no different than the way you would normally dene you macros; however, there is a trick that you can use to improve you macros for plasTEX, if needed. While plasTEX can handle fairly complicated macros, some macros might do things that dont make sense in the context of a plasTEX document, or they might just be too complicated for the plasTEX engine to handle. In cases such as these, you can use the \ifplastex construct. As you may know in TEX, you can dene your own \if commands using the \newif primitive. There is an \if command called \ifplastex built into the plasTEX engine that is always set to true. In you document, you A can dene this command and set it to false (as far as LTEX is concerned) as follows.

\newif\ifplastex \plastexfalse

Now you can surround the portions of your macros that plasTEX has trouble with, or even write alternative versions of A the macro for LTEX and plasTEX. Here is an example.

23

\newcommand{\foo}[1]{ \ifplastex\else\vspace*{0.25in}\fi \textbf{\Large{#1}} \ifplastex\else\vspace*{1in}\fi } \ifplastex \newenvironment{coolbox}{}{} \else \newenvironment{coolbox} {fbox\bgroup\begin{minipage}{5in}} {\end{minipage}\egroup} \fi

4.2

Dening Macros in Python

Dening macros using Python classes (or, at least through Python interfaces) is done in one of three ways: INI les, Python classes, and the document context. These three methods are described in the following sections.

4.2.1

Python Classes

A Both LTEX command and environments can be implemented in Python classes. plasTEX includes a base class for each one: Command for commands and Environment for environments. For the most part, these two classes behave in the same way. They both are responsible for parsing their arguments, organizing their child nodes, incrementing A A counters, etc. much like their LTEX counterparts. The Python macro class feature set is based on common LTEX A X macro you are implementing in Python uses standard LT X conventions, you job will be A conventions. So if the LTE E very easy. If you are doing unconventional operations, you will probably still succeed, you just might have to do a little more work.

The three most important parts of the Python macro API are: 1) the args attribute, 2) the invoke method, and 3) the digest method. When writing your own macros, these are used the most by far. The args Attribute The args attribute is a string attribute on the class that indicates what the arguments to the macro are. In addition to simply indicating the number of arguments, whether they are mandatory or optional, and what characters surround A the argument as in LTEX, the args string also gives names to each of the argument and can also indicate the content of the argument (i.e. int, oat, list, dictionary, string, etc.). The names given to each argument determine the key that the argument is stored under in the the attributes dictionary of the class instance. Below is a simple example of a macro class.
from plasTeX import Command, Environment class framebox(Command): """ \framebox[width][pos]{text} """ args = [ width ] [ pos ] text

In the args string of the \framebox macro, three arguments are dened. The rst two are optional and the third one is mandatory. Once each argument is parsed, in is put into the attributes dictionary under the name given in the

24

Contents

args string. For example, the attributes dictionary of an instance of \framebox will have the keys width, pos, and text once it is parsed and can be accessed in the usual Python way.
self.attributes[width] self.attributes[pos] self.attributes[text]

In plasTEX, any argument that isnt mandatory (i.e. no grouping characters in the args string) is optional1 . This includes arguments surrounded by parentheses (( )), square brackets ([ ]), and angle brackets (< >). This also lets you combine multiple versions of a command into one macro. For example, the \framebox command also has a form that looks like: \framebox(x_dimen,y_dimen)[pos]{text}. This leads to the Python macro class in the following code sample that encompasses both forms.
from plasTeX import Command, Environment class framebox(Command): """ \framebox[width][pos]{text} or \framebox(x_dimen,ydimen)[pos]{text} """ args = ( dimens ) [ width ] [ pos ] text

The only thing to keep in mind is that in the second form, the pos attribute is going to end up under the width key in the attributes dictionary since it is the rst argument in square brackets, but this can be xed up in the invoke method if needed. Also, if an optional argument is not present on the macro, the value of that argument in the attributes dictionary is set to None. As mentioned earlier, it is also possible to convert arguments to data types other than the default (a document fragment). A list of the available types is shown in the table below.
1 While this isnt always true when L T X expands the macros, it will not cause any problems when plasT X compiles the document because AE E plasTEX is less stringent.

Contents

25

Name str chr char cs label

id idref

ref nox list

dict

dimen dimension length number count int oat double

Purpose expands all macros then sets the value of the argument in the attributes dictionary to the string content of the argument same as str same as str sets the attribute to an unexpanded control sequence expands all macros, converts the result to a string, then sets the current label to the object that is in the currentlabel attribute of the document context. Generally, an object is put into the currentlabel attribute if it incremented a counter when it was invoked. The value stored in the attributes dictionary is the string value of the argument. same as label expands all macros, converts the result to a string, retrieves the object that was labeled by that value, then adds the labeled object to the idref dictionary under the name of the argument. This type of argument is used in commands like \ref that must reference other abjects. The nice thing about idref is that it gives you a reference to the object itself which you can then use to retrieve any type of information from it such as the reference value, title, etc. The value stored in the attributes dictionary is the string value of the argument. same as idref just parses the argument, but doesnt expand the macros converts the argument to a Python list. By default, the list item separator is a comma (,). You can change the item separator in the args string by appending a set of parentheses surrounding the separator character immediately after list. For example, to specify a semi-colon separated list for an argument called foo you would use the args string: foo:list(;). It is also possible to cast the type of each item by appending another colon and the data type from this table that you want each item to be. However, you are limited to one data type for every item in the list. converts the argument to a Python dictionary. This is commonly used by A arguments set up using LTEXs keyval package. By default, key/value pairs are separated by commas, although this character can be changed in the same way as the delimiter in the list type. You can also cast each value of the dictionary using the same method as the list type. In all cases, keys are converted to strings. reads a dimension and returns an instance of dimen same as dimen same as dimen reads an integer and returns a Python integer same as number same as number reads a decimal value and returns a Python oat same as oat

A There are also several argument types used for more low-level routines. These dont parse the typical LTEX arguments, they are used for the somewhat more free-form TEX arguments.

26

Contents

Name Dimen Length Dimension MuDimen MuLength Glue Skip Number Int Integer Token Tok XToken XTok Args

Purpose reads a TEX dimension and returns an instance of dimen same as Dimen same as Dimen reads a TEX mu-dimension and returns an instance of mudimen same as MuDimen reads a TEX glue parameter and returns an instance of glue same as MuLength reads a TEX integer parameter and returns a Python integer same as Number same as Number reads an unexpanded token same as Token reads an expanded token same as XToken reads tokens up to the rst begin group (i.e. {)

To use one of the data types, simple append a colon (:) and the data type name to the attribute name in the args string. Going back to the \framebox example, the argument in parentheses would be better represented as a list of dimensions. The width parameter is also a dimension, and the pos parameter is a string.
from plasTeX import Command, Environment class framebox(Command): """ \framebox[width][pos]{text} or \framebox(x_dimen,ydimen)[pos]{text} """ args = ( dimens:list:dimen ) [ width:dimen ] [ pos:chr ] text

The invoke Method The invoke method is responsible for creating a new document context, parsing the macro arguments, and incrementing counters. In most cases, the default implementation will work just ne, but you may want to do some extra processing of the macro arguments or counters before letting the parsing of the document proceed. There are actually several methods in the API that are called within the scope of the invoke method: preParse, preArgument, postArgument, and postParse. The order of execution is quite simple. Before any arguments have been parsed, the preParse method is called. The preArgument and postArgument methods are called before and after each argument, respectively. Then, after all arguments have been parsed, the postParse method is called. The default implementations of these methods handle the stepping of counters and setting the current labeled item in the document. By default, macros that have been starred (i.e. have a * before the arguments) do not increment the counter. You can override this behavior in one of these methods if you prefer. The most common reason for overriding the invoke method is to post-process the arguments in the attributes A dictionary, or add information to the instance. For example, the \color command in LTEXs color package could A X color to the correct CSS format and add it to the CSS style object. convert the LTE

Contents

27

from plasTeX import Command, Environment def latex2htmlcolor(arg): if , in arg: red, green, blue = [float(x) for x in arg.split(,)] red = min(int(red * 255), 255) green = min(int(green * 255), 255) blue = min(int(blue * 255), 255) else: try: red = green = blue = float(arg) except ValueError: return arg.strip() return #%.2X%.2X%.2X % (red, green, blue) class color(Environment): args = color:str def invoke(self, tex): a = Environment.invoke(tex) self.style[color] = latex2htmlcolor(a[color])

While simple things like attribute post-processing is the most common use of the invoke method, you can do very advanced things like changing category codes, and iterating over the tokens in the TEX processor directly like the verbatim environment does. One other feature of the invoke method that may be of interest is the return value. Most invoke method implementations do not return anything (or return None). In this case, the macro instance itself is sent to the output stream. However, you can also return a list of tokens. If a list of tokens is returned, instead of the macro instance, those tokens are inserted into the output stream. This is useful if you dont want the macro instance to be part of the output stream or document. In this case, you can simply return an empty list. The digest Method The digest method is responsible for converting the output stream into the nal document structure. For commands, this generally doesnt mean anything since they just consist of arguments which have already been parsed. Environments, on the other hand, have a beginning and an ending which surround tokens that belong to that environment. In most cases, the tokens between the \begin and \end need to be absorbed into the childNodes list. The default implementation of the digest method should work for most macros, but there are instances where you may want to do some extra processing on the document structure. For example, the \caption command within figures and tables uses the digest method to populate the enclosing gure/tables caption attribute.

28

Contents

from plasTeX import Command, Environment class Caption(Command): args = [ toc ] self def digest(self, tokens): res = Command.digest(self, tokens) # Look for the figure environment that we belong to node = self.parentNode while node is not None and not isinstance(node, figure): node = node.parentNode # If the figure was found, populate the caption attribute if isinstance(node, figure): node.caption = self return res class figure(Environment): args = [ loc:str ] caption = None class caption_(Caption): macroName = caption counter = figure

More advanced uses of the digest method might be to construct more complex document structures. For example, tabular and array structures in a document get converted from a simple list of tokens to complex structures with lots of style information added (see section 3.3.3). One simple example of a digest that does something extra is shown below. It looks for the rst node with the name item then bails out.
from plasTeX import Command, Environment class toitem(Command): def digest(self, tokens): """ Throw away everything up to the first item token """ for tok in tokens: if tok.nodeName == item: # Put the item back into the stream tokens.push(tok) break

One of the more advanced uses of the digest is on the sectioning commands: \section, \subsection, etc. The digest method on sections absorb tokens based on the level attribute which indicates the hierarchical level of the node. When digested, each section absorbs all tokens until it reaches a section that has a level that is equal to or higher than its own level. This creates the overall document structure as discussed in section 3. Other Nifty Methods and Attributes There are many other attributes and methods on macros that can be used to affect their behavior. For a full listing, see the API documentation in section 6.1. Below are descriptions of some of the more commonly used attributes and methods.

Contents

29

The level attribute The level attribute is an integer that indicates the hierarchical level of the node in the output A document structure. The values of this attribute are taken from LTEX: \part is -1, \chapter is 0, \section is 1, \subsection is 2, etc. To create your owne sectioning commands, you can either subclass one of the existing sectioning macros, or simply set its level attribute to the appropriate number.
A The macroName attribute The macroName attribute is used when you are creating a LTEX macro whose name is not a legal Python class name. For example, the macro \@ifundefined has a @ in the name which isnt legal in a Python class name. In this case, you could dene the macro as shown below.

class ifundefined_(Command): macroName = @ifundefined

The counter attribute The counter attribute associates a counter with the macro class. It is simply a string that contains the name of the counter. Each time that an instance of the macro class is invoked, the counter is incremented (unless the macro has a * argument). The ref attribute The ref attribute contains the value normally returned by the \ref command. The title attribute The title attribute retrieves the title attribute from the attributes dictionary. This attribute is also overridable. The fullTitle attribute The same as the title attribute, but also includes the counter value at the beginning. The tocEntry attribute The tocEntry attribute retrieves the toc attribute from the attributes dictionary. This attribute is also overridable. The fullTocEntry attribute The same as the tocEntry attribute, but also includes the counter value at the beginning. The style attribute The style attribute is a CSS style object. Essentially, this is just a dictionary where the key is the CSS property name and the value is the CSS property value. It has an attribute called inline which contains an inline version of the CSS properties for use in the style= attribute of HTML elements. The id attribute This attribute contains a unique ID for the object. If the object was labeled by a \label command, the ID for the object will be that label; otherwise, an ID is generated.
A The source attribute The source attribute contains the LTEX source representation of the node and all of its contents.

The currentSection attribute The currentSection attribute contains the section that the node belongs to. The expand method The expand method is a thin wrapper around the invoke method. It simply invokes the macro and returns the result of expanding all of the tokens. Unlike invoke, you will always get the expanded node (or nodes); you will not get a None return value. 30 Contents

The paragraphs method The paragraphs method does the nal processing of paragraphs in a nodes child nodes. It makes sure that all content is wrapped within paragraph nodes. This method is generally called from the digest method.

4.2.2

INI Files

Using INI les is the simplest way of creating customized Python macro classes. It does require a little bit of knowledge of writing macros in Python classes (section 4.2.1), but not much. The only two pieces of information about Python macro classes you need to know are 1) the args string format, and 2) the superclass name (in most cases, you can simply use Command or Environment). The INI le features correspond to Python macros in the following way. INI File section name option name option value Python Macro Use the Python class to inherit from the name of the macro to create the args string for the macro

Here is an example of an INI le that denes several macros.

[Command] ; \program{ self } program=self ; \programopt{ self } programopt=self [Environment] ; \begin{methoddesc}[ classname ]{ name methoddesc=[ classname ] name args ; \begin{memberdesc}[ classname ]{ name memberdesc=[ classname ] name args [section] ; \headi( options:dict )[ toc ]{ title } headi=( options:dict ) [ toc ] title [subsection] ; \headii( options:dict )[ toc ]{ title } headii=( options:dict ) [ toc ] title

{ args } ... \end{methoddesc} { args } ... \end{memberdesc}

In the INI le above, six macro are being dened. \program and \programopt both inherit from Command, A the generic LTEX macro superclass. They also both take a single mandatory argument called self. There are two environments dened also: methoddesc and memberdesc. Each of these has three arguments where the rst A argument is optional. The last two macros actually inherit from standard LTEX sectioning commands. They add an option, surrounded by parentheses, to the options that \section and \subsection already had dened. INI versions of plasTEX packages are loaded much in the same way as Python plasTEX packages. For details on how packages are loaded, see section 4.3.

4.2.3

The Document Context

It is possible to dene commands using the same interface that is used by the plasTEX engine itself. This interface belongs to the Context object (usually accessed through the document objects context attribute). Dening

Contents

31

commands using the context object is generally done in the ProcessOptions function of a package. The following methods of the context object create new commands. Method newcounter Purpose creates a new counter, and also creates a command called \thecounter which generates the formatted version of the counter. This macro correA sponds to the \newcounter macro in LTEX. corresponds to TEXs \newcount command. corresponds to TEXs \newdimen command. corresponds to TEXs \newskip command. corresponds to TEXs \newmuskip command. corresponds to TEXs \newif command. This command also generates macros for \ifcommandtrue and \ifcommandfalse. A corresponds to LTEXs \newcommand macro. A corresponds to LTEXs \newenvironment macro. corresponds to TEXs \def command. corresponds to TEXs \chardef command.

newcount newdimen newskip newmuskip newif newcommand newenvironment newdef chardef

A Note: Since many of these methods accept strings containing LTEX markup, you need to remember that the category codes of some characters can be changed during processing. If you are dening macros using these methods in the ProcessOptions function in a package, you should be safe since this function is executed in the preamble of the document where category codes are not changed frequently. However, if you dene a macro with this interface in a context where the category codes are not set to the default values, you will have to adjust the markup in your macros accordingly.

Below is an example of using this interface within the context of a package to dene some commands. For the full usage of these methods see the API documentation of the Context object in section 6.5.
def ProcessOptions(options, document): context = document.context # Create some counters context.newcounter(secnumdepth, initial=3) context.newcounter(tocdepth, initial=2) # \newcommand{\config}[2][general]{\textbf{#2:#1} context.newcommand(config, 2, r\textbf{#2:#1}, opt=general) # \newenvironment{note}{\textbf{Note:}}{} context.newenvironment(note, 0, (r\textbf{Note:}, r))

4.3

Packages

A A Packages in plasTEX are loaded in one of three ways: standard LTEX package, Python package, and INI le. LTEX A packages are loaded in much the same way that LTEX itself loads packages. The kpsewhich program is used to locate A the requested le which can be either in the search path of your LTEX distribution or in one of the directories specied A in the TEXINPUTS environment variable. plasTEX read the le and expand the macros therein just as LTEX would do.

Python packages are located using Pythons search path. This includes all directories listed in sys.path as well as those listed in the PYTHONPATH environment variable. After a package is loaded, it is checked to see if there is a function called ProcessOptions in its namespace. If there is, that function is called with two arguments: 1) the dictionary of options that were specied when loading the package, and 2) the document object that is currently being processed. This function allows you to make adjustments to the loaded macros based on the options specied, and dene new 32 Contents

commands in the documents context (see section 4.2.3 for more information). Of course, you can also dene Python based macros (section 4.2.1) in the Python package as well. The last type of packages is based on the INI le format. This format is discussed in more detail in section 4.2.2. A INI formatted packages are loaded in conjunction with a LTEX or Python package. When a package is loaded, an INI le with the same basename is searched for in the same director as the package. If it exists, it is loaded as well. For example, if you had a package called python.sty and a le called python.ini in the same package directory, python.sty would be loaded rst, then python.ini would be loaded. The same operation applies for Python based packages.

Contents

33

34

CHAPTER

FIVE

Renderers
Renderers allow you to convert a plasTEX document object into viewable output such as HTML, RTF, or PDF, or simply a data structure format such as DocBook or tBook. Since the plasTEX document object gives you everything A that you could possibly want to know about the LTEX document, it should, in theory, be possible to generate any type of output from the plasTEX document object while preserving as much information as the output format is capable of. In addition, since the document object is not affected by the rendering process, you can apply multiple renderers in A sequence so that the LTEX document only needs to be parsed one time for all output types. While it is possible to write a completely custom renderer, one possible rendeerer implementation is included with the plasTEX framework. While the rendering process in this implementation is fairly simple, it is also very powerful. Some of the main features are listed below. ability to generate multiple output les automatic splitting of les is congurable by section level, or can be invoked using ad-hoc methods in the filenameoverride property powerful output lename generation utility image generation for portions of the document that cannot be easily rendered in a particular output formate (e.g. equations in HTML) themeing support hooks for post-processing of output les congurable output encodings The API of the renderer itself is very small. In fact, there are only a couple of methods that are of real interest to an end user: render and cleanup. The render method is the method that starts the rendering process. Its only argument is a plasTEX document object. The cleanup method is called at the end of the rendering process. It is passed the document object and a list of all of the les that were generated. This method allows you to do post-processing on the output les. In general, this method will probably only be of interest to someone writing a subclass of the Renderer class, so most users of plasTEX will only use the render method. The real work of the rendering process is handled in the Renderable class which is discussed later in this chapter. The Renderer class is a subclass of the Python dictionary. Each key in the renderer corresponds to the name of a node in the document object. The value stored under each key is a function. As each node in the document object is traversed, the renderer is queried to see if there is a key that matches the name of the node. If a key is found, the value at that key (which must be a function) is called with the node as its only argument. The return value from this call must be a unicode object that contains the rendered output. Based on the conguration, the renderer will handle all of the le generation and encoding issues. If a node is traversed that doesnt correspond to a key in the renderer dictionary, the default rendering method is called. The default rendering method is stored in the default attribute. One exception to this rule is for text nodes. The 35

default rendering method for text nodes is actually stored in textDefault. Again, these attributes simply need to reference any Python function that returns a unicode object of the rendered output. The default method in both of these attributes is the unicode built-in function. As mention previously, most of the work of the renderer is actually done by the Renderable class. This is a mixin class1 that is mixed into the Node class in the render method. It is unmixed at the end of the render method. The details of the Renderable class are discussed in section 5.2.

5.1

Simple Renderer Example

It is possible to write a renderer with just a couple of methods: default and textDefault. The code below demonstrates how one might create a generic XML renderer that simply uses the node names as XML tag names. The text node renderer escapes the <, >, and & characters.
import string from plasTeX.Renderers import Renderer class Renderer(Renderer): def default(self, node): """ Rendering method for all non-text nodes """ s = [] # Handle characters like \&, \$, \%, etc. if len(node.nodeName) == 1 and node.nodeName not in string.letters: return self.textDefault(node.nodeName) # Start tag s.append(<%s> % node.nodeName) # See if we have any attributes to render if node.hasAttributes(): s.append(<attributes>) for key, value in node.attributes.items(): # If the key is self, dont render it # these nodes are the same as the child nodes if key == self: continue s.append(<%s>%s</%s> % (key, unicode(value), key)) s.append(</attributes>) # Invoke rendering on child nodes s.append(unicode(node)) # End tag s.append(</%s> % node.nodeName) return u\n.join(s) def textDefault(self, node): """ Rendering method for all text nodes """ return node.replace(&,&amp;).replace(<,&lt;).replace(>,&gt;)

A To use the renderer, simply parse a LTEX document and apply the renderer using the render method.
1

A mixin class is simply a class that is merely a collection of methods that are intended to be included in the namespace of another class.

36

Contents

# Import renderer from previous code sample from MyRenderer import Renderer from plasTeX.TeX import TeX # Instantiate a TeX processor and parse the input text tex = TeX() tex.ownerDocument.config[files][split-level] = -100 tex.ownerDocument.config[files][filename] = test.xml tex.input(r \documentclass{book} \begin{document} Previous paragraph. \section{My Section} \begin{center} Centered text with <, >, and \& charaters. \end{center} Next paragraph. \end{document} ) document = tex.parse() # Render the document renderer = Renderer() renderer.render(document)

The output from the renderer, located in test.xml, looks like the following.
<document> <par> Previous paragraph. </par><section> <attributes> <toc>None</toc> <*modifier*>None</*modifier*> <title>My Section</title> </attributes> <par> <center> Centered text with &lt;, &gt;, and &amp; charaters. </center> </par><par> Next paragraph. </par> </section> </document>

Contents

37

5.1.1

Extending the Simple Renderer

Now that we have a simple renderer working, it is very simple to extend it to do more specic operations. Lets say that the default renderer is ne for most nodes, but for the \section node we want to do something special. For the section node, we want the title argument to correspond to the title attribute in the output XML2 . To do this we need a method like the following.
def handle_section(node): return u\n\n<%s title="%s">\n%s\n</%s>\n % \ (node.nodeName, unicode(node.attributes[title]), unicode(node), node.nodeName)

Now we simply insert the rendering method into the renderer under the appropriate key. Remember that the key in the renderer should match the name of the node you want to render. Since the above rendering method will work for all A section types, well insert it into the renderer for each LTEX sectioning command.
renderer = Renderer() renderer[section] = handle_section renderer[subsection] = handle_section renderer[subsubsection] = handle_section renderer[paragraph] = handle_section renderer[subparagraph] = handle_section renderer.render(document)

A Running the same LTEX document as in the previous example, we now get this output.

<document> <par> Previous paragraph. </par> <section title="My Section"> <par> <center> Centered text with &lt;, &gt;, and &amp; charaters. </center> </par><par> Next paragraph. </par> </section> </document>

Of course, you arent limited to using just Python methods. Any function that accepts a node as an argument can be used. The Zope Page Template (ZPT) renderer included with plasTEX is an example of how to write a renderer that uses a templating language to render the nodes (see section 5.3).
2 This

will only work properly in XML if the content of the title is plain text since other nodes will generate markup.

38

Contents

5.2

Renderable Objects

The Renderable class is the real workhorse of the rendering process. It traverses the document object, looks up the appropriate rendering methods in the renderer, and generates the output les. It also invokes the image generating process when needed for parts of a document that cannot be rendered in the given output format. Most of the work of the Renderable class is done in the __unicode__ method. This is rather convenient since each of the rendering methods in the renderer are required to return a unicode object. When the unicode function is called with a renderable object as its argument, the document traversal begins for that node. This traversal includes iterating through each of the nodes child nodes, and looking up and calling the appropriate rendering method in the renderer. If the child node is congured to generate a new output le, the le is created and the rendered output is written to it; otherwise, the rendered output is appended to the rendered output of previous nodes. Once all of the child nodes have been rendered, the unicode object containing that output is returned. This recursive process continues until the entire document has been rendered. There are a few useful things to know about renderable objects such as how they determine which rendering method to use, when to generate new les, what the lenames will be, and how to generate images. These things are discussed below.

5.2.1

Determining the Correct Rendering Method

Looking up the correct rendering method is quite straight-forward. If the node is a text node, the textDefault attribute on the renderer is used. If it is not a text node, then the nodes name determines the key name in the renderer. A In most cases, the nodes name is the same name as the LTEX macro that created it. If the macro used some type of modier argument (i.e. *, +, -), a name with that modier applied to it is also searched for rst. For example, if you A used the tablular* environment in your LTEX document, the renderer will look for tabular* rst, then tabular. This allows you to use different rendering methods for modied and unmodied macros. If no rendering method is found, the method in the renderers default attribute is used.

5.2.2

Generating Files

Any node in a document has the ability to generate a new le. During document traversal, each node is queried for a lename. If a non-None is returned, a new le is created for the content of that node using the given lename. The querying for the lename is simply done by accessing the filename property of the node. This property is added to the nodes namespace during the mixin process. The default behavior for this property is to only return lenames for sections with a level less than the split-level given in the conguration (see section 2.1.5). The lenames generated by this routine are very exible. They can be statically given names, or names based on the ID and/or title, or simply generically numbered. For more information on conguring lenames see section 2.1.5. While the lenaming mechanism is very powerful, you may want to give your les names based on some other information. This is possible through the filenameoverride attribute. If the filenameoverride is set, the name returned by that attribute is used as the lename. The string in filenameoverride is still processed in the same way as the lename specier in the conguration so that you can use things like the ID or title of the section in the overridden lename. The string used to specify lenames can also contain directory paths. This is not terribly useful at the moment since there is no way to get the relative URLs between two nodes for linking purposes. If you want to use a lename override, but want to do it conditionally you can use a Python property to do this. Just calculate the lename however you wish, if you decide that you dont want to use that lename then raise an AttributeError exception. An example of this is shown below.

Contents

39

class mymacro{Command): args = [ filename:str ] self @property def filenameoverride(self): # See if the attributes dictionary has a filename if self.attributes[filename] is not None: return self.attributes[filename] raise AttributeError, filenameoverride

Note: The lename in the filenameoverride attribute must contain any directory paths as well as a le extension.

5.2.3

Generating Images

A Not all output types that you might render are going to support everything that LTEX is capable of. For example, A HTML has no way of representing equations, and most output types wont be capable of rendering LTEXs picture environment. In cases like these, you can let plasTEX generate images of the document node. Generating images is A done with a subclass of plasTeX.Imagers.Imager. The imager is responsible for creating a LTEX document from the requested document fragments, compiling the document and converting each page of the output document into individual images. Currently, there are two Imager subclasses included with plasTEX. Each of them use the A standard LTEX compiler to generate a DVI le. The DVI le is then converted into images using one of the available imagers (see section 2.1.6 on how to select different imagers).

To generate an image of a document node, simply access the image property during the rendering process. This property will return an plasTeX.Imagers.Image instance. In most cases, the image le will not be available A until the rendering process is nished since most renderers will need the generated LTEX document to be complete before compiling it and generating the nal images. The example below demonstrates how to generate an image for the equation environment.

40

Contents

# Import renderer from first renderer example from MyRenderer import Renderer from plasTeX.TeX import TeX def handle_equation(node): return u<div><img src="%s"/></div> % node.image.url # Instantiate a TeX processor and parse the input text tex = TeX() tex.input(r \documentclass{book} \begin{document} Previous paragraph. \begin{equation} \Sigma_{x=0}^{x+n} = \beta^2 \end{equation} Next paragraph. \end{document} ) document = tex.parse() # Instantiate the renderer renderer = Renderer() # Insert the rendering method into all of the environments that might need it renderer[equation] = handle_equation renderer[displaymath] = handle_equation renderer[eqnarray] = handle_equation # Render the document renderer.render(document)

The rendered output looks like the following, and the image is generated is located in images/img-0001.png.
<document> <par> Previous paragraph. </par><par> <div><img src="images/img-0001.png"/></div> </par><par> Next paragraph. </par> </document>

The names of the image les are determined by the documents conguration. The lename generator is very powerful, and is in fact, the same lename generator used to create the other output lenames. For more information on customizing the image lenames see section 2.1.6. In addition, the image types are customizable as well. plasTEX uses the Python Imaging Library (PIL) to do the nal cropping and saving of the image les, so any image format that PIL supports can be used. The format that PIL saves

Contents

41

the images in is determined by the le extension in the generated lenames, so you must use a le extension that PIL recognizes. It is possible to write your own Imager subclass if necessary. See the Imager API documentation for more information (see 6.7).

5.2.4

Generating Vector Images

If you have a vector imager congured (such as dvisvg or dvisvgm), you can generate a vector version of the requested image as well as a bitmap. The nice thing about vector versions of images is that they can scale innitely and not loose resolution. The bad thing about them is that they are not as well supported in the real world as bitmaps. Generating a vector image is just as easy as generating a bitmap image, you simply access the vectorImage property of the node that you want an image of. This will return an plasTeX.Imagers.Image instance that corresponds to the vector image. A bitmap version of the same image can be accessed through the image property of the document node or the bitmap variable of the vector image object. Everything that was described about generating images in the previous section is also true of vector images with the A exception of cropping. plasTEX does not attempt to crop vector images. The program that converts the LTEX output to a vector image is expected to crop the image down to the image content. plasTEX uses the information from the bitmap version of the image to determine the proper depth of the vector image.

5.2.5

Static Images

There are some images in a document that dont need to be generated, they simply need to be copied to the output directory and possibly converted to an appropriate formate. This is accomplished with the imageoverride attribute. When the image property is accessed, the imageoverride attribute is checked to see if an image is already available for that node. If there is, the image is copied to the image output directory using a name generated using the same method as described in the previous section. The image is copied to that new lename and converted to the appropriate image format if needed. While it would be possible to simply copy the image over using the same lename, this may cause lename collisions depending on the directory structure that the original images were store in. Below is an example of using imageoverride for copying stock icons that are used throughout the document.
from plasTeX import Command class dangericon(Command): imageoverride = danger.gif class warningicon(Command): imageoverride = warning.gif

It is also possible to make imageoverride a property so that the image override can done conditionally. In the case where no override is desired in a property implementation, simply raise an AttributeError exception.

5.3

Page Template Renderer

The Page Template (PT) renderer is a renderer for plasTEX document objects that supports various page template engines such as Zope Page Templates (ZPT), Cheetah templates, Kid templates, Genshi templates, Python string templates, as well as plain old Python string formatting. It is also possible to add support for other template engines. Note that all template engines except ZPT, Python formats, and Python string templates must be installed in your Python installation. They are not included. 42 Contents

ZPT is the most supported page template language at the moment. This is the template engine that is used for all of the plasTEX delivered templates in the XHTML renderer; however, the other templates work in a very similar way. The actual ZPT implementation used is SimpleTAL (http://www.owlfish.com/software/simpleTAL/). This implementation implements almost all of the ZPT API and is very stable. However, some changes were made to this package to make it more convenient to use within plasTEX. These changes are discussed in detail in the ZPT Tutorial (see section 5.3.3). Since the above template engines can be used to generate any form of XML or HTML, the PT renderer is a general solution for rendering XML or HTML from a plasTEX document object. When switching from one DTD to another, you simply need to use a different set of templates. As in all Renderer-based renderers, each key in the PT renderer returns a function. These functions are actually generated when the template les are parsed by the PT renderer. As is the case with all rendering methods, the only argument is the node to be rendered, and the output is a unicode object containing the rendered output. In addition to the rendering methods, the textDefault method escapes all characters that are special in XML and HTML (i.e. <, >, and &). The following sections describe how templates are loaded into the renderer, how to extend the set of templates with your own, as well as a theming mechanism that allows you to apply different looks to output types that are visual (e.g. HTML).

5.3.1

Dening and Using Templates

Note: If you are not familiar with the ZPT language, you should read the tutorial in section 5.3.3 before continuing in this section. See the links in the previous section for documentation on the other template engines. By default, templates are loaded from the directory where the renderer module was imported from. In addition, the templates from each of the parent renderer class modules are also loaded. This makes it very easy to extend a renderer and add just a few new templates to support the additions that were made. The template les in the module directories can have three different forms. The rst is HTML. HTML templates must have an extension of .htm or .html. These templates are compiled using SimpleTALs HTML compiler. XML templates, the second form of template, uses SimpleTALs XML compiler, so they must be well-formed XML fragments. XML templates must have the le extension .xml, .xhtml, or .xhtm. In any case, the basename of the template le is used as the key to store the template in the renderer. Keep in mind that the names of the keys in the renderer correspond to the node names in the document object. The extensions used for all templating engines are shown in the table below. Engine ZPT Python string formatting Python string templates Kid Cheetah Genshi Extension .html, .htm, .zpt .xhtml, .xhtm, .xml .pyt .st .kid .che .gen Output Type HTML XML/XHTML Any Any XML/XHTML XML/XHTML HTML

The le listing below is an example of a directory of template les. In this case the templates correspond to nodes in the document created by the description environment, the tabular environment, \textbf, and \textit.
description.xml tabular.xml textbf.html textit.html

Contents

43

Since there are a lot of templates that are merely one line, it would be inconvenient to have to create a new le for each template. In cases like this, you can use the .zpts extension for collections of ZPT templates, or more generally .pts for collections of various template types. Files with this extension have multiple templates in them. Each template is separated from the next by the template metadata which includes things like the name of the template, the type (xml, html, or text), and can also alias template names to another template in the renderer. The following metadata names are currently supported. Name engine Purpose the name of the templating engine to use. At the time of this writing, the value could be zpt, tal (same as zpt), html (ZPT HTML template), xml (ZPT XML template), python (Python formatted string), string (Python string template), kid, cheetah, or genshi. the name or names of the template that is to follow. This name is used as the key in the renderer, and also corresponds to the node name that will be rendered by the template. If more than one name is desired, they are simply separated by spaces. the type of the template: xml, html, or text. XML templates must contain a well-formed XML fragment. HTML templates are more forgiving, but do not support all features of ZPT (see the SimpleTAL documentation). species the name of another template that the given names should be aliased to. This allows you to simply reference another template to use rather than redening one. For example, you might create a new section heading called \introduction that should render the same way as \section. In this case, you would set the name to introduction and the alias to section.

name

type

alias

There are also some defaults that you can set at the top of the le that get applied to the entire le unles overridden by the meta-data on a particular template. Name default-engine default-type Purpose the name of the engine to use for all templates in the le. the default template type for all templates in the le.

The code sample below shows the basic format of a zpts le.
name: textbf bfseries <b tal:content="self">bold content</b> name: textit <i tal:content="self">italic content</i> name: introduction introduction* alias: section name: description type: xml <dl> <metal:block tal:repeat="item self"> <dt tal:content="item/attributes/term">definition term</dt> <dd tal:content="item">definition content</dd> </metal:block> </dl>

The code above is a zpts le that contains four templates. Each template begins when a line starts with name:. Other directives have the same format (i.e. the name of the directive followed by a colon) and must immediately follow 44 Contents

the name directive. The rst template denition actually applies to two types of nodes textbf and bfseries. You can specify ony number of names on the name line. The third template isnt a template at all; it is an alias. When an alias is specied, the name (or names) given use the same template as the one specied in the alias directive. Notice also that starred versions of a macro can be specied separately. This means that they can use a different template than the un-starred versions of the command. The last template is just a simple XML formatted template. By default, templates in a zpts le use the HTML compiler in SimpleTAL. You can specify that a template is an XML template by using the type directive. Here is an example of using various types of templates in a single le.
name: textbf type: python <b>%(self)s</b> name: textit type: string <i>${self}</i> name: textsc type: cheetah <span class="textsc">${here}</span> name: textrm type: kid <span class="textrm" py:content="XML(unicode(here))">normal text</span> name: textup type: genshi <span class="textup" py:content="markup(here)">upcase text</span>

There are several variables inserted into the template namespace. Here is a list of the variables and the templates that support them. Object document node parent node document cong template instance renderer instance ZPT/Python Formats/String Template self or here container cong template templates Cheetah here container cong templates Kid/Genshi here container cong templates

Youll notice that Kid and Genshi templates require some extra processing of the variables in order to get the proper markup. By default, these templates escape characters like <, >, and &. In order to get HTML/XML markup from the variables you must wrap them in the code shown in the example above. Hopefully, this limitation will be removed in the future. Template Overrides It is possible to override the templates located in a renderers directory with templates dened elsewhere. This is done using the *TEMPLATES environment variable. The * in the name *TEMPLATES is a wildcard and must be replaced by the name of the renderer. For example, if you are using the XHTML renderer, the environment variable would be XHTMLTEMPLATES. For the PageTemplate renderer, the environment variable would be PAGETEMPLATETEMPLATES. The format of this variable is the same as that of the PATH environment variable which means that you can put multiple directory names in this variable. In addition, the environment variables for each of the parent renderers is also used, so that you can use multiple layers of template directories. Contents 45

You can actually create an entire renderer just using overrides and the PT renderer. Since the PT renderer doesnt actually dene any templates, it is just a framework for dening other XML/HTML renderers, you can simply load the PT renderer and set the PAGETEMPLATETEMPLATES environment variable to the locations of your templates. This method of creating renderers will work for any XML/HTML that doesnt require any special post-processing.

5.3.2

Dening and Using Themes

In addition to the templates that dene how each node should be rendered, there are also templates that dene page layouts. Page layouts are used whenever a node in the document generates a new le. Page layouts generally include all of the markup required to make a complete document of the desired DTD, and may include things like navigation buttons, tables of contents, breadcrumb trails, etc. to link the current le to other les in the document. When rendering les, the content of the node is generated rst, then that content is wrapped in a page layout. The page layouts are dened the same way as regular templates; however, they all include -layout at the end of the template A name. For example the sectioning commands in LTEX would use the layout templates section-layout, subsectionlayout, subsubsection-layout, etc. Again, these templates can exist in les by themselves or multiply specied in a zpts le. If no layout template exists for a particular node, the template name default-layout is used. Since there can be several themes dened within a renderer, theme les are stored in a subdirectory of a renderer directory. This directory is named Themes. The Themes directory itself only contains directories that correspond to the themes themselves where the name of the directory corresponds to the name of the theme. These theme directories generally only consist of the layout les described above, but can override other templates as well. Below is a le listing demonstrating the structure of a renderer with multiple themese.
# Renderer directory: contains template files XHTML/ # Theme directory: contains theme directories XHTML/Themes/ # Theme directories: contain page layout templates XHTML/Themes/default/ XHTML/Themes/fancy/ XHTML/Themes/plain/

Note: If no theme is specied in the document conguration, a theme with the name default is used. Since all template directories are created equally, you can also dene themes in template directories specied by environment variables as described in section 5.3.1. Also, theme les are searched in the same way as regular templates, so any theme dened in a renderer superclass directory is valid as well.

5.3.3

Zope Page Template Tutorial

The Zope Page Template (ZPT) language is actually just a set of XML attributes that can be applied to markup of an DTD. These attributes tell the ZPT interpreter how to process the element. There are seven different attributes that you can use to direct the processing of an XML or HTML le (in order of evaluation): dene, condition, repeat, content, replace, attributes, and omit-tag. These attributes are described in section 5.3.3. For a more complete description, see the ofcial ZPT documentation at http://www.zope.org/Documentation/Books/ZopeBook/ 2_6Edition/ZPT.stx.

46

Contents

Template Attribute Language Expression Syntax (TALES) The Template Attribute Language Expression Syntax (TALES) is used by the attribute language described in the next section. The TALES syntax is used to evaluate expressions based on objects in the template namespace. The results of these expressions can be used to dene variables, produce output, or be used as booleans. There are also several operators used to modify the behavior or interpretation of an expression. The expressions and their modiers are described below. path: operator A path is the most basic form on an expression in ZPT. The basic form is shown below.
[path:]string [ | TALES expression ]

The path: operator is actually optional on all paths. Leaving it off makes no difference. The string in the above syntax is a / delimited string of names. Each name refers to a property of the previous name in the string. Properties can include attributes, methods, or keys in a dictionary. These properties can in turn have properties of their own. Some examples of paths are shown below.
# Access the parentNode attribute of chapter, then get its title chapter/parentNode/title # Get the key named foo from the dictionary bar bar/foo # Call the title method on the string in the variable booktitle booktitle/title

It is possible to specify multiple paths separated by a pipe (|). These paths are evaluated from left to right. The rst one to return a non-None value is used.
# Look for the title on the current chapter node as well as its parents chapter/title | chapter/parentNode/title | chapter/parentNode/parentNode/title # Look for the value of the option otherwise get its default value myoptions/encoding | myoptions/defaultencoding

There are a few keywords that can be used in place of a path in a TALES expression as well. Name nothing default options repeat attrs CONTEXTS Purpose same as None in Python keeps whatever the existing value of the element or attribute is dictionary of values passed in to the template when instatiated the repeat variable (see 5.3.3) dictonary of the original attributes of the element dictionary containing all of the above

exists: operator This operator returns true if the path exists. If the path does not exist, the operator returns false. The syntax is as follows.

Contents

47

exists:path

The path in the code above is a path as described in section 5.3.3. This operator is commonly combined with the not: operator. nocall: operator By default, if a property that is retrieved is callable, it will be called automatically. Using the nocall: operator, prevents this execution from happening. The syntax is shown below.
nocall:path

not: operator The not: operator simply negates the boolean result of the path. If the path is a boolean true, the not: operator will return false, and vice versa. The syntax is shown below.
not:path

string: operator The string: operator allows you to combine literal strings and paths into one string. Paths are inserted into the literal string using a syntax much like that of Python Templates: $path or ${path}. The general syntax is:
string:text

Here are some examples of using the string: operator.

string:Next - ${section/links/next} string:($pagenumber) string:[${figure/number}] ${figure/caption}

python: operator The python: operator allows you to evaluate a Python expression. The syntax is as follows.
python:python-code

The python-code in the expression above can include any of the Python built-in functions and operators as well as four new functions that correspond to the TALES operators: path, string, exists, and nocall. Each of these functions takes a string containing the path to be evaluated (e.g. path(foo/bar), exists(chapter/title), etc.). When using Python operators, you must escape any characters that would not be legal in an XML/HTML document (i.e. <>&). For example, to write an expression to test if a number was less than or greater than two numbers, you would need to do something like the following example.
# See if the figure number is less than 2 or greater than 4 python: path(figure/number) &lt; 2 or path(figure/number) &gt; 4

48

Contents

stripped: operator The stripped: operator only exists in the SimpleTAL distribution provided by plasTEX. It evaluates the given path and removes any markup from that path. Essentially, it is a way to get a plain text representation of the path. The syntax is as follows.
stripped:path

Template Attribute Language (TAL) Attributes tal:dene The tal:define attribute allows you to dene a variable for use later in the template. Variables can be species as local (only for use in the scope of the current element) or global (for use anywhere in the template). The syntax of the dene attribute is shown below.
tal:define="[ local | global ] name expression [; define-expression ]"

The dene attributes sets the value of name to expression. By default, the scope of the variable is local, but can be specied as global by including the global keyword before the name of the variable. As shown in the grammar above, you can specify multiple variables in one tal:define attribute by separating the dene expressions by semi-colons. Examples of using the tal:define attribute are shown belaw.
<p tal:define="global title document/title; next self/links/next; previous self/links/previous; length python:len(self); up string:Up - ${self/links/up}"> ... </p>

tal:condition The tal:condition attribute allows you to conditionally include an element. The syntax is shown below.
tal:condition="expression"

The tal:condition attribute is very simple. If the expression evaluates to true, the element and its children will be evaluated and included in the output. If the expression evaluates to false, the element and its children will not be evaluated or included in the output. Valid expressions for the tal:condition attribute are the same as those for the expressions in the tal:define attribute.
<p tal:condition="python:len(self)"> <b tal:condition="self/caption">Caption for paragraph</b> ... </p>

tal:repeat The tal:repeat attribute allows you to repeat an element multiple times; the syntax is shown below.

Contents

49

tal:repeat="name expression"

When the tal:repeat attribute is used on an element, the result ofexpression is iterated over, and a new element is generated for each item in the iteration. The value of the current item is set to name much like in the tal:define attribute. Within the scope of the repeated element, another variable is available: repeat. This variable contains several properties related to the loop. Name index number even odd start end length letter Letter roman Roman Purpose number of the current iteration starting from zero number of the current iteration starting from one is true if the iteration number is even is true if the iteration number is odd is true if this is the rst iteration is true if this is the last iteration; This is never true if the repeat expression returns an iterator the length of the sequence being iterated over; This is set to sys.maxint for iterators. lower case letter corresponding to the current iteration number starting with a upper case letter corresponding to the current iteration number starting with A lower case Roman numeral corresponding to the current iteration number starting with i upper case Roman numeral corresponding to the current iteration number starting with I

To access the properties listed above, you must use the property of the repeat variable that corresponds to the repeat variable name. For example, if your repeat variable name is item, you would access the above variables using the expressions repeat/item/index, repeat/item/number, repeat/item/even, etc. A simple example of the tal:repeat attribute is shown below.
<ol> <li tal:repeat="option options" tal:content="option/name">option name</li> </ol>

One commonly used feature of rendering tables is alternating row colors. This is a little bit tricky with ZPT since the tal:condition attribute is evaluated before the tal:repeat directive. You can get around this by using the metal: namespace. This is the namespace used by ZPTs macro language3 You can create another element around the element you want to be conditional. This wrapper element is simply there to do the iterating, but is not included in the output. The example below shows how to do alternating row colors in an HTML table.
3 The

macro language isnt discussed here. See the ofcial ZPT documentation for more information.

50

Contents

<table> <metal:block tal:repeat="employee employees"> <!-- even rows --> <tr tal:condition="repeat/employee/even" style="background-color: white"> <td tal:content="employee/name"></td> <td tal:content="employee/title"></td> </tr> <!-- odd rows --> <tr tal:condition="repeat/employee/odd" style="background-color: gray"> <td tal:content="employee/name"></td> <td tal:content="employee/title"></td> </tr> </metal:block> </table>

tal:content The tal:content attribute evaluates an expression and replaces the content of the element with the result of the expression. The syntax is shown below.
tal:content="[ text | structure ] expression"

The text and structure options in the tal:content attribute indicate whether or not the content returned by the expression should be escaped (i.e. "&<> replaced by &quot;, &amp;, &lt;, and &gt;, respectively). When the text option is used, these special characters are escaped; this is the default behavior. When the structure option is specied, the result of the expression is assumed to be valid markup and is not escaped. In SimpleTAL, the default behavior is the same as using the text option. However, in plasTEX, 99.9% of the time the content returned by the expression is valid markup, so the default was changed to structure in the SimpleTAL package distributed with plasTEX. tal:replace The tal:replace attribute is much like the tal:content attribute. They both evaluate an expression and include the content of that expression in the output, and they both have a text and structure option to indicate escaping of special characters. The difference is that when the tal:replace attribute is used, the element with the tal:replace attribute on it is not included in the output. Only the content of the evaluated expression is returned. The syntax of the tal:replace attribute is shown below.
tal:replace="[ text | structure ] expression"

tal:attributes The tal:attributes attribute allows you to programatically create attributes on the element. The syntax is shown below.
tal:attributes="name expression [; attribute-expression ]"

The syntax of the tal:attributes attribute is very similar to that of the tal:define attribute. However, in the case of the tal:attributes attribute, the name is the name of the attribute to be created on the element and the expression is evaluated to get the value of the attribute. If an error occurs or None is returned by the expression, then the attribute is removed from the element.

Contents

51

Just as in the case of the tal:define attribute, you can specify multiple attributes separated by semi-colons (;). If a semi-colon character is needed in the expression, then it must be represented by a double semi-colon (;;). An example of using the tal:attributes is shown below.
<a tal:attributes="href self/links/next/url; title self/links/next/title">link text</a>

tal:omit-tag The tal:omit-tag attribute allows you to conditionally omit an element. The syntax is shown below.
tal:omit-tag="expression"

If the value of expression evaluates to true (or is empty), the element is omitted; however, the content of the element is still sent to the output. If the expression evaluates to false, the element is included in the output.

5.4

XHTML Renderer

The XHTML renderer is a subclass of the ZPT renderer (section 5.3). Since the ZPT renderer can render any variant of XML or HTML, the XHTML renderer has very little to do in the Python code. Almost all of the additionaly A processing in the XHTML renderer has to do with generated images. Since HTML cannot render LTEXs vector graphics or equations natively, they are converted to images. In order for inline equations to line up correctly with the text around them, CSS attributes are used to adjust the vertical alignment. Since the images arent generated until after all of the document has been rendered, this CSS information is added in post-processing (i.e. the cleanup method). In addition to the processing of images, all characters with a ordinal greater than 127 are converted into numerical entities. This should prevent any rendering problems due to unknown encodings.
A Most of the work in this renderer was in creating the templates for every LTEX construct. Since this renderer was A intended to be the basis of all HTML-based renderers, it must be capable of rendering all LTEX constructs; therefore, A X command, and the commands in some common LT X packages. A there are ZPT templates for every LTE E A While the XHTML renderer is fairly complete when it comes to standard LTEX, there are many packages which are not currently supported. To add support for these packages, templates (and possibly Python based macros; section 4) must be created.

5.4.1

Themes

The theming support in the XHTML renderer is the same as that of the ZPT renderer. Any template directory can have a subdirectory called Themes which contains theme directories with sets of templates in them. The names of the directories in the Themes directory corresponds to the name of the theme. There are currently four themes included with plasTEX: default, plain, minimal, and python. The default theme is a minor variation of the one used in the Python 1.6 documentation. The plain theme is a theme with no extra navigation bars. The minimal theme contains nothing but what is required to generate a legal HTML document; it is mainly used in the unit tests. The python theme creates documentation that looks like the standard Python documentation at http://docs.python.org/.

52

Contents

5.5

DocBook Renderer

The DocBook renderer is new in plasTeX 0.9. Since there arent always macros in LaTeX that correspond to the extensive set of tags in DocBook, the rendered DocBook output is fairly simple. The DocBook renderer supports two themes: book and article. You can use these themes to use the book or article root element in the output XML.

5.6

ManPage and Text Renderers

The ManPage and Text renderers are very similar. The Text renderer simply the output in plain text. The ManPage renderer creates output for use in man pages as found on UNIX systems.

Contents

53

54

CHAPTER

SIX

PLASTEX Frameworks and APIs

6.1 plasTeX The Python Macro and Document Interfaces
A While plasTEX does a respectable job expanding LTEX macros, some macros may be too complicated for it to handle. These macros may have to be re-coded as Python objects. Another reason you may want to use Python-based macros A is for performance reasons. In most cases, macros coded using Python will be faster than those expanded as true LTEX macros. A The API for Python macros is much higher-level than that of LTEX macros. This has good and bad ramications. The A good is that most common forms of LTEX macros can be parsed and processed very easily using Python code which A is easier to read than LTEX code. The bad news is that if you are doing something that isnt common, you will have more work to do. Below is a basic example.

from plasTeX import Command class mycommand(Command): """ \mycommand[name]{title} """ args = [ name ] title

A The code above demonstrates how to create a Python-based macro corresponding to LTEX macro with the form \mycommand[name]{title} where name is an optional argument and title is a mandatory argument. In the Python version of the macro, you simply declare the arguments in the args attribute as they would be used in the A A LTEX macro, while leaving the braces off of the mandatory arguments. When parsed in a LTEX document, an instance of the class mycommand in created and the arguments corresponding to name and title are set in the attributes dictionary for that instance. This is very similar to the way an XML DOM works, and there are more DOM similarities yet to come. In addition, there are ways to handle casting of the arguments to various data types in Python. The API documentation below goes into more detail on these and many more aspects of the Python macro API.

6.1.1

Macro Objects

class Macro() The Macro class is the base class for all Python based macros although you will generally want to subclass from Command or Environment in real-world use. There are various attributes and methods that affect how Python macros are parsed, constructed and inserted into the resulting DOM. These are described below. args
A species the arguments to the LTEX macro and their data types. The args attribute gives you a very simple, A yet extremely powerful way of parsing LTEX macro arguments and converting them into Python objects. Once A parsed, each LTEX macro argument is set in the attributes dictionary of the Python instance using the name given in the args string. For example, the following args string will direct plasTEX to parse two mandatory

55

arguments, id and title, and put them into the attributes dictonary.
args = id title

You can also parse optional arguments, usually surrounded by square brackets ([ ]). However, in plasTEX, any arguments specied in the args string that arent mandatory (i.e. no braces surrounding it) are automatically considered optional. This may not truly be the case, but it doesnt make much difference. If they truly are A mandatory, then your LTEX source le will always have them and plasTEX will simply always nd them even though it considers them to be optional. Optional arguments in the args string are surround by matching square brackets ([ ]), angle brackets (< >), or parentheses (( )). The name for the attribute is placed between the matching symbols as follows:
args = [ toc ] title args = ( position ) object args = < markup > ref

You can have as many optional arguments as you wish. It is also possible to have optional arguments using braces ({ }), but this requires you to change TEXs category codes and is not common. Modiers such as asterisks (*) are also allowed in the args string. You can also use the plus (+) and minus (-) signs as modiers although these are not common. Using modiers can affect the incrementing of counters (see the parse() method for more information). In addition to specifying which arguments to parse, you can also specify what the data type should be. By default, all arguments are processed and stored as document fragments. However, some arguments may be simpler than that. They may contain an integer, a string, an ID, etc. Others may be collections like a list or dictionary. There are even more esoteric types for mostly internal use that allow you to get unexpanded tokens, TEX dimensions, and the like. Regardless, all of these directives are specied in the same way, using the typecast operator: :. To cast an argument, simply place a colon (:) and the name of the argument type immediately after the name of the argument. The following example casts the lename argument to a string.
args = filename:str

Parsing compound arguments such as lists and dictionaries is very similar.

args = filenames:list

By default, compound arguments are assumed to be comma separated. If you are using a different separator, it is specied in parentheses after the type.
args = filenames:list(;)

Again, each element element in the list, by default, is a document fragment. However, you can also give the data type of the elements with another typecast.
args = filenames:list(;):str

Parsing dictionaries is a bit more restrictive. plasTEX assumes that dictionary arguments are always key-value pairs, that the key is always a string and the separator between the key and value is an equals sign (=). Other than that, they operate in the same manner. A full list of the supported data types as well as more examples are discussed in section 4. argSource A the source for the LTEX arguments to this macro. This is a read-only attribute.

56

Contents

arguments gives the arguments in the args attribute in object form (i.e. Argument objects). Note: This is a read-only attribute. Note: This is generally an internal-use-only attribute. blockType indicates whether the macro node should be considered a block-level element. If true, this node will be put into its own paragraph node (which also has the blockType set to True) to make it easier to generate output that requires block-level to exist outside of paragraphs. counter species the name of the counter to associate with this macro. Each time an instance of this macro is created, this counter is incremented. The incrementing of this counter, of course, resets any child counters just like in A A LTEX. By default and LTEX convention, if the macros rst argument is an asterisk (i.e. *), the counter is not incremented. id species a unique ID for the object. If the object has an associated label (i.e. \label), that is its ID. You can also set the ID manually. Otherwise, an ID will be generated based on the result of Pythons id() function. idref a dictionary containing all of the objects referenced by idref type arguments. Each idref attribute is stored under the name of the argument in the idref dictionary. level species the hierarchical level of the node in the DOM. For most macros, this will be set to Node.COMMAND_LEVEL or Node.ENVIRONMENT_LEVEL by the Command and Environment macros, respectively. However, there are other levels that invoke special processing. In particular, sectioning commands such as \section and \subsection have levels set to Node.SECTION_LEVEL and Node.SUBSECTION_LEVEL. These levels assist in the building of an appropriate DOM. Unless you are creating a sectioning command or a command that should act like a paragraph, you should leave the value of this attribute alone. See section 6.3 for more information. macroName A species the name of the LTEX macro that this class corresponds to. By default, the Python class name is the A name that is used, but there are some legal LTEX macro names that are not legal Python class names. In those cases, you would use macroName to specify the correct name. Below is an example.
class _illegalname(Command): macroName = @illegalname

Note: This is a class attribute, not an instance attribute. macroMode species what the current parsing mode is for this macro. Macro classes are instantiated for every invocation including each \begin and \end. This attribute is set to Macro.MODE_NONE for normal commands, Macro.MODE_BEGIN for the beginning of an environment, and Macro.MODE_END for the end of an environment. These attributes are used in the invoke() method to determine the scope of macros used within the environment. They are also used in printing the source of the macro in the source attribute. Unless you really know what you are doing, this should be treated as a read-only attribute. mathMode boolean that indicates that the macro is in TEXs math mode. This is a read-only attribute. nodeName the name of the node in the DOM. This will either be the name given in macroName, if dened, or the name of the class itself. Note: This is a read-only attribute. ref

Contents

57

species the value to return when this macro is referenced (i.e. \ref). This is set automatically when the counter associated with the macro is incremented. source A species the LTEX source that was parsed to create the object. This is most useful in the renderer if you need A to generate an image of a document node. You can simply retrieve the LTEX source from this attribute, create a A LTEX document including the source, then convert the DVI le to the appropriate image type. style species style overrides, in CSS format, that should be applied to the output. This object is a dictionary, so style property names are given as the key and property values are given as the values.
inst.style[color] = red inst.style[background-color] = blue

Note: Not all renderers are going to support CSS styles. tagName same as nodeName title species the title of the current object. If the attributes dictionary contains a title, that object is returned. An AttributeError is thrown if there is no title key in that dictionary. A title can also be set manually by setting this attribute. digest(tokens) absorb the tokens from the given output stream that belong to the current object. In most commands, this does A nothing. However, LTEX environments have a \begin and an \end that surround content that belong to them. In this case, these environments need to absorb those tokens and construct them into the appropriate document object model (see the Environment class for more information). digestUntil(tokens, endclass) utility method to help macros like lists and tables digest their contents. In lists and tables, the items, rows, and cells are delimited by \begin and \end tokens. They are simply delimited by the occurrence of another item, row, or cell. This method allows you to absorb tokens until a particular class is reached. expand() the expand method is a thin wrapper around the invoke method. The expand method makes sure that all tokens are expanded and will not return a None value like invoke. invoke() invakes the macro. Invoking the macro, in the general case, includes creating a new context, parsing the options A of the macro, and removing the context. LTEX environments are slightly different. If macroMode is set to Macro.MODE_BEGIN, the new context is kept on the stack. If macroMode is set to Macro.MODE_END, no arguments are parsed, the context is simply popped. For most macros, the default implementation will work ne. The return value for this method is generally None (an empty return statement or simply no return statement). In this case, the current object is simply put into the resultant output stream. However, you can also return a list of tokens. In this case, the returned tokens will be put into the output stream in place of the current object. You can even return an empty list to indicate that you dont want anything to be inserted into the output stream. locals() A retrieves all of the LTEX macros that belong to the scope of the current Python based macro. paragraphs(force=True) group content into paragraphs. Paragraphs are grouped once all other content has been digested. The paragraph grouping routine works like TEXs, in that environments are included inside paragraphs. This is unlike HTMLs model, where lists and tables are not included inside paragraphs. The force argument allows you to decide whether or not paragraphs should be forced. By default, all content of the node is grouped into paragraphs

58

Contents

whether or not the content originally contained a paragraph node. However, with force set to False, a node will only be grouped into paragraphs if the original content contained at least one paragraph node. Even though the paragraph method follows TEXs model, it is still possible to generate valid HTML content. Any node with the blockType attribute set to True is considered to be a block-level node. This means that it will be contained in its own paragraph node. This paragraph node will also have the blockType attribute set to True so that in the renderer the paragraph can be inserted or ignored based on this attribute. parse(tex) parses the arguments dened in the args attribute from the given token stream. This method also calls several hooks as described in the table below. Description Method Name preParse() called at the beginning of the argument parsing process called before parsing each argument preArgument() postArgument() called after parsing each argument called at the end of the argument parsing process postParse() The methods are called to assist in labeling and counting. For example, by default, the counter associated with a macro is automatically incremented when the macro is parsed. However, if the rst argument is a modier (i.e. *, +, -), the counter will not be incremented. This is handled in the preArgument() and postArgument() methods. Each time an argument is parsed, the result is put into the attributes dictionary. The key in the dictionary is, of course, the name given to that argument in the args string. Modiers such as *, +, and - are stored under the special key *modier*. The return value for this method is simply a reference to the attributes dictionary. Note: If parse() is called on an instance with macroMode set to Macro.MODE_END, no parsing takes place. postArgument(arg, tex) called after parsing each argument. This is generally where label and counter mechanisms are handled. arg is the Argument instance that holds all argument meta-data including the arguments name, source, and options. tex is the TeX instance containing the current context postParse(tex) do any operations required immediately after parsing the arguments. This generally includes setting up the value that will be returned when referencing the object. preArgument(arg, tex) called before parsing each argument. This is generally where label and counter mechanisms are handled. arg is the Argument instance that holds all argument meta-data including the arguments name, source, and options. tex is the TeX instance containing the current context preParse(tex) do any operations required immediately before parsing the arguments. refstepcounter(tex) set the object as the current labellable object and increment its counter. When an object is set as the current labellable object, the next \label command will point to that object. stepcounter(tex) step the counter associated with the macro

Contents

59

6.2 plasTeX.ConfigManager plasTEX Conguration

The conguration system in plasTEX that parses the command-line options and conguration les is very exible. While many options are setup by the plasTEX framework, it is possible for you to add your own options. This is useful if you have macros that may need to be congured by congurable options, or if you write a renderer that surfaces special options to control it. The cong les that ConfigManager supports are standard INI-style les. This is the same format supported by Pythons ConfigParser. However, this API has been extended with some dictionary-like behaviors to make it more Python friendly. In addition to the cong les, ConfigManager can also parse command-line options and merge the options from the command-line into the options set by the given cong les. In fact, when adding options to a ConfigManager, you specify both how they appear in the cong le as well as how they appear on the command-line. Below is a basic example.
from plasTeX.ConfigManager import * c = ConfigManager() # # # d Create a new section in the config file. [ sectionname ] sections in an INI file. a reference to the new section = c.add_section(debugging) This corresponds to the The returned value is

# Add an option to the debugging section called verbose. # This corresponds to the config file setting: # # [debugging] # verbose = no # d[verbose] = BooleanOption( """ Increase level of debugging information """, options = -v --verbose !-q !--quiet, default = False, ) # Read system-level config file c.read(/etc/myconfig.ini) # Read user-level config file c.read(~/myconfig.ini) # Parse the current command-line arguments opts, args = c.getopt(sys.argv[1:]) # Print the value of the verbose option in the debugging section print c[debugging][verbose]

One interesting thing to note about retrieving values from a ConfigManager is that you get the value of the option rather than the option instance that you put in. For example, in the code above. A BooleanOption in put into the verbose option slot, but when it is retrieved in the print statement at the end, it prints out a boolean value. This is true of all option types. You can access the option instance in the data attribute of the section (e.g. c[debugging].data[verbose]).

60

Contents

6.2.1

CongManager Objects

class ConfigManager(defaults={ }) Instantiate a conguration class for plasTEX that parses the command-line options as well as reads the cong les. The optional argument, defaults, is a dictionary of default values for the conguration object. These values are used if a value is not found in the requested section. __add__(other) merge items from another ConfigManager. This allows you to add ConfigManager instances with syntax like: cong + other. This operation will modify the original instance. add_section(name) create a new section in the conguration with the given name. This name is the name used for the section heading in the INI le (i.e. the name used within square brackets ([ ]) to start a section). The return value of this method is a reference to the newly created section. categories() return the dictionary of categories copy() return a deep copy of the conguration defaults() return the dictionary of default values read(lenames) read conguration data contained in les specied by lenames. Files that cannot be opened are silently ignored. This is designed so that you can specify a list of potential conguration le locations (e.g. current directory, users home directory, system directory), and all existing conguration les in the list will be read. A single lename may also be given. get(section, option, raw=0, vars={ }) retrieve the value of option from the section section. Setting raw to true prevents any string interpolation from occurring in that value. vars is a dictionary of addition value to use when interpolating values into the option. Note: You can alsouse the alternative dictionary syntax: cong[section].get(option). getboolean(section, option) retrieve the specied value and cast it to a boolean get_category(key) return the title of the given category getfloat(section, option) retrieve the specied value and cast it to a oat getint(section, option) retrieve the specied value and cast it to and integer get_opt(section, option) return the option value with any leading and trailing quotes removed getopt(args=None, merge=True) parse the command-line options. If args is not given, the args are parsed from sys.argv[1:]. If merge is set to false, then the options are not merged into the conguration. The return value is a two element tuple. The rst value is a list of parsed options in the form (option, value), and the second value is the list of arguments. get_optlist(section, option, delim=,) return the option value as a list using delim as the delimiter getraw(section, option)

Contents

61

return the raw (i.e. un-interpolated) value of the option has_category(key, title) add a category to group options when printing the command-line help. Command-line options can be grouped into categories to make options easier to nd when printing the usage message for a program. Categories consist of two pieces: 1) the name, and 2) the title. The name is the key in the category dictionary and is the name used when specifying which category an option belongs to. The title is the actual text that you see as a section header when printing the usage message. has_option(section, name) return a boolean indicating whether or not an option with the given name exists in the given section has_section(name) return a boolean indicating whether or not a section with the given name exists __iadd__(other) merge items from another ConfigManager. This allows you to add ConfigManager instances with syntax like: cong += other. options(name) return a list of congured option names within a section. Options are all of the settings of a conguration le within a section (i.e. the lines that start with optionname=). __radd__(other) merge items from another ConfigManager. This allows you to add ConfigManager instances with syntax like: other + cong. This operation will modify the original instance. readfp(fp, lename=None) like read(), but the argument is a le object. The optional lename argument is used for printing error messages. remove_option(section, option) remove the specied option from the given section remove_section(section) remove the specied section __repr__() return the conguration as an INI formatted string; this also includes options that were set from Python code. sections() return a list of all section names in the conguration set(section, option, value) set the value of an option __str__() return the conguration as an INI formatted string; however, do not include options that were set from Python code. to_string(source=...) return the conguration as an INI formatted string. The source option indicates which source of information should be included in the resulting INI le. The possible values are: Description Name COMMANDLINE set from a command-line option CONFIGFILE set from a conguration le BUILTIN set from Python code ENVIRONMENT set from an environment variable write(fp) write the conguration as an INI formatted string to the given le object

62

Contents

usage(categories=[]) print the descriptions of all command-line options. If categories is specied, only the command-line options from those categories is printed.

6.2.2

CongSection Objects

class ConfigSection(name, data={ }) Instantiate a ConfigSection object. name is the name of the section. data, if specied, is the dictionary of data to initalize the section contents with. ConfigSection objects are rarely instantiated manually. They are generally created using the ConfigManager API (either the direct methods or the Python dictionary syntax). data dictionary that contains the option instances. This is only accessed if you want to retrieve the real option instances. Normally, you would use standard dictionary key access syntax on the section itself to retrieve the option values. name the name given to the section. copy() make a deep copy of the section object. defaults() return the dictionary of default options associated with the parent ConfigManager. get(option, raw=0, vars={ }) retrieve the value of option. Setting raw to true prevents any string interpolation from occurring in that value. vars is a dictionary of addition value to use when interpolating values into the option. Note: You can alsouse the alternative dictionary syntax: section.get(option). getboolean(section, option) retrieve the specied value and cast it to a boolean __getitem__(key) retrieve the value of an option. This method allows you to use Pythons dictionary syntax on a section as shown below.
# Print the value of the optionname option print mysection[optionname]

getint(section, option) retrieve the specied value and cast it to and integer getfloat(section, option) retrieve the specied value and cast it to a oat getraw(section, option) return the raw (i.e. un-interpolated) value of the option parent a reference to the parent ConfigManager object. __repr__() return a string containing an INI le representation of the section.

Contents

63

set(option, value) create a new option or set an existing option with the name option and the value of value. If the given value is already an option instance, it is simply inserted into the section. If it is not an option instance, an appropriate type of option is chosen for the given type. __setitem__(key, value) create a new option or set an existing option with the name key and the value of value. This method allows you to use Pythons dictionary syntax to set options as shown below.
# Create a new option called optionname mysection[optionname] = 10

__str__() return a string containing an INI le representation of the section. Options set from Python code are not included in this representation. to_string([source ]) return a string containing an INI le representation of the section. The source option allows you to only display options from certain sources. See the ConfigManager.source() method for more information.

6.2.3

Conguration Option Types

There are several option types that should cover just about any type of command-line and conguration option that you may have. However, in the spirit of object-orientedness, you can, of course, subclass one of these and create your own types. GenericOption is the base class for all options. It contains all of the underlying framework for options, but should never be instantiated directly. Only subclasses should be instantiated. class GenericOption( [docsTring, options, default, optional, values, category, callback, synopsis, environ, registry, mandatory, name, source ] ) Declare a command line option. Instances of subclasses of GenericOption must be placed in a ConfigManager instance to be used. See the documentation for ConfigManager for more details. docstring is a string in the format of Python documentation strings that describes the option and its usage. The rst line is assumed to be a one-line summary for the option. The following paragraphs are assumed to be a complete description of the option. You can give a paragraph with the label Valid Values: that contains a short description of the values that are valid for the current option. If this paragraph exists and an error is encountered while validating the option, this paragraph will be printed instead of the somewhat generic error message for that option type. options is a string containing all possible variants of the option. All variants should contain the -, , etc. at the beginning. For boolean options, the option can be preceded by a ! to mean that the option should be turned OFF rather than ON which is the default. default is a value for the option to take if it isnt specied on the command line optional is a value for the option if it is given without a value. This is only used for options that normally take a value, but you also want a default that indicates that the option was given without a value. values denes valid values for the option. This argument can take the following forms:

64

Contents

Type single value

range of values

tuple of values

Description for StringOption this this is a string, for IntegerOption this is an integer, for FloatOption this is a oat. The single value mode is most useful when the value is a regular expression. For example, to specify that a StringOption must be a string of characters followed by a digit, values would be set to re.compile(r\w+\d). a two element list can be given to specify the endpoints of a range of valid values. This is probably most useful on IntegerOption and FloatOption. For example, to specify that an IntegerOption can only take the values from 0 to 10, values would be set to [0,10]. Note: This mode must always use a Python list since using a tuple means something else entirely. a tuple of values can be used to specify a complete list of valid values. For example, to specify that an IntegerOption can take the values 1, 2, or 3, values would be set to (1,2,3). If a string value can only take the values, hi, bye, and any string of characters beginning with the letter z, values would be set to (hi,bye,re.compile(rz.*?)). Note: This mode must *always* use a Python tuple since using a list means something else entirely.

category is a category key which species which category the option belongs to (see the ConfigManager documentation on how to create categories). callback is a function to call after the value of the option has been validated. This function will be called with the validated option value as its only argument. environ is an environment variable to use as default value instead of specied value. If the environment variable exists, it will be used for the default value instead of the specied value. registry is a registry key to use as default value instead of specied value. If the registry key exists, it will be used for the default value instead of the specied value. A specied environment variable takes precedence over this value. Note: This is not implemented yet. name is a key used to get the option from its corresponding section. You do not need to specify this. It will be set automatically when you put the option into the ConfigManager instance. mandatory is a ag used to determine if the option itself is required to be present. The idea of a "mandatory option" is a little strange, but I have seen it done. source is a ag used to determine whether the option was set directly in the ConfigManager instance through Python, by a conguration le/command line option, etc. You do not need to specify this, it will be set automatically during parsing. This ag should have the value of BUILTIN, COMMANDLINE, CONFIGFILE, ENVIRONMENT, REGISTRY, or CODE. acceptsArgument() return a boolean indicating whether or not the option accepts an argument on the command-line. For example, boolean options do not accept an argument. cast(arg) cast the given value to the appropriate type. checkValues(value) check value against all possible valid values for the option. InvalidOptionError exception. clearValue() reset the value of the option as if it had never been set. getValue([default ]) return the current value of the option. If default is specied and a value cannot be gotten from any source, it is returned. Contents 65 If the value is invalid, raise an

__repr__() return a string containing a command-line representation of the option and its value. requiresArgument() return a boolean indicating whether or not the option requires an argument on the command-line. As mentioned previously, GenericOption is an abstract class (i.e. it should not be instantiated directly). Only subclasses of GenericOption should be instantiated. Below are some examples of use of some of these subclasses, followed by the descriptions of the subclasses themselves.
BooleanOption( Display help message , options = --help -h, callback = usage, # usage() function must exist prior to this )

BooleanOption( Set verbosity , options = -v --verbose !-q !--quiet, )

StringOption( IP address option This option accepts an IP address to connect to. Valid Values: #.#.#.# where # is a number from 1 to 255 , options = --ip-address, values = re.compile(r\d{1,3}(\.\d{1,3}){3}), default = 127.0.0.0, synopsis = #.#.#.#, category = network, # Assumes network category exists )

IntegerOption( Number of seconds to wait before timing out Valid Values: positive integer , options = --timeout -t, default = 300, values = [0,1e9], category = network, )

66

Contents

IntegerOption( Number of tries to connect to the host before giving up Valid Values: accepts 1, 2, or 3 retries , options = --tries, default = 1, values = (1,2,3), category = network, )

StringOption( Nonsense option for example purposes only Valid Values: accepts hi, bye, or any string beginning with the letter z , options = --nonsense -n, default = hi, values = (hi, bye, re.compile(rz.*?)), )

class BooleanOption([GenericOption arguments ]) Boolean options are simply options that allow you to specify an on or off state. The accepted values for a boolean option in a cong le are on, off, true, false, yes, no, 0, and 1. Boolean options on the command-line do not take an argument; simply specifying the option sets the state to true. One interesting feature of boolean options is in specifying the command-line options. Since you cannot specify a value on the command-line (the existence of the option indicates the state), there must be a way to set the state to false. This is done using the not operator (!). When specifying the options argument of the constructor, if you prex an command-line option with an exclamation point, the existence of that option indicates a false state rather than a true state. Below is an example of an options value that has a way to turn debugging information on (--debug) or off (--no-debug).
BooleanOption( options = --debug !--no-debug )

class CompoundOption([GenericOption arguments ]) Compound options are options that contain multiple elements on the command-line. They are simply groups of command-line arguments surrounded by a pair of grouping characters (e.g. ( ), [ ], { }, < >). This grouping can contain anything including other command-line arguments. However, all content between the grouping characters is unparsed. This can be useful if you have a program that wraps another program and you want to be able to forward the wrapped programs options on. An example of a compound option used on the command-line is shown below.
# Capture the --diff-opts options to send to another program mycommand --other-opt --diff-opts ( -ib --minimal ) file1 file2

class CountedOption([GenericOption arguments ]) Contents 67

A CountedOption is a boolean option that keeps track of how many times it has been specied. This is useful for options that control the verbosity of logging messages in a program where the number of times an option is specied, the more logging information is printed. class InputDirectoryOption([GenericOption arguments ]) An InputDirectoryOption is an option that accepts a directory name for input. This directory name is checked to make sure that it exists and that it is readable. If it is not, a InvalidOptionError exception is raised. class OutputDirectoryOption([GenericOption arguments ]) An OutputDirectoryOption is an option that accepts a directory name for output. If the directory exists, it is checked to make sure that it is readable. If it does not exist, it is created. class InputFileOption([GenericOption arguments ]) An InputFileOption is an option that accepts a le name for input. The lename is checked to make sure that it exists and is readable. If it isnt, an InvalidOptionError exception is raised. class OutputFileOption([GenericOption arguments ]) An OutputFileOption is an option that accepts a le name for output. If the le exists, it is checked to make sure that it is writable. If a name contains a directory, the path is checked to make sure that it is writable. If the directory does not exist, it is created. class FloatOption([GenericOption arguments ]) A FloatOption is an option that accepts a oating point number. class IntegerOption([GenericOption arguments ]) An IntegerOption is an option that accepts an integer value. class MultiOption([GenericOption arguments, [delim, range, template ]]) A MultiOption is an option that is intended to be used multiple times on the command-line, or take a list of values. Other options when specied more than once simply overwrite the previous value. MultiOptions will append the new values to a list. The delimiter used to separate multiple values is the comma (,). A different character can be specied in the delim argument. In addition, it is possible to specify the number of values that are legal in the range argument. The range argument takes a two element list. The rst element is the minimum number of times the argument is required. The second element is the maximum number of times it is required. You can use a * (in quotes) to mean an innite number. You can cast each element in the list of values to a particular type by using the template argument. The template argument takes a reference to the option class that you want the values to be converted to. class StringOption([GenericOption arguments ]) A StringOption is an option that accepts an arbitrary string.

6.3 plasTeX.DOM The plasTEX Document Object Model (DOM)

A While most LTEX processors use a stream model where the input is directly connected to the output, plasTEX actually A works in two phases. The rst phase reads in the LTEX document, expands macros, and constructs an object similar to an XML DOM. This object is then passed to the renderer which translates it into the appropriate output format. The benet to doing it this way is that you are not limited to a single output format. In addition, you can actually apply multiple renderers with only one parse step. This section describes the DOM used by plasTEX, its API, and the similarities and differences between the plasTEX DOM and the XML DOM.

68

Contents

6.3.1

plasTEX vs. XML

The plasTEX DOM and XML DOM have more similarities than differences. This similarity is purely intentional to reduce the learning curve and to prevent reinventing the wheel. However, the XML DOM can be a bit cumbersome especially when youre used to much simpler and more elegant Python code. Because of this, some Python behaviors were adopted into the plasTEX DOM. The good news is that these extensions do not break compatibility with the XML A DOM. There are, however, some differences due to conventions used LTEX. The only signicant difference between the plasTEX DOM and the XML DOM is that plasTEX nodes do not have true A attributes like in XML. Attributes in XML are more like arguments in LTEX, because they are similar the plasTEX A DOM actually puts the LTEX macro arguments into the attributes dictionary. This does create an incompatibility A though since XML DOM attributes can only be strings whereas LTEX arguments can contain lots of markup. In addition, plasTEX allows you to convert these arguments into Python strings, lists, dictionaries, etc., so essentially any type of object can occur in the attributes dictionary. Other than paying attention to the the attributes dictionary difference, you can use most other XML DOM methods on plasTEX document objects to create nodes, delete nodes, etc. The full API is described below. In most cases, you will not need to be concerned with instantiating nodes. The plasTEX framework does this. However, the API can be helpful if you want to modify the document object that plasTEX creates.

6.3.2

Node Objects

class Node() The Node class is the base class for all nodes in the plasTEX DOM inluding elements, text, etc. attributes A a dictionary containing the attributes, in the case of plasTEX the LTEX macro arguments childNodes A a list of the nodes that are contained by this one. In plasTEX, this generally contains the contents of a LTEX environment. isElementContentWhitespace boolean indicating whether or not the node only contains whitespace. lastChild the last node in the childNodes list. If there are no child nodes, the value is None. nodeName the name of the node. This is either the special node name as specied in the XML DOM (e.g. #documentfragment, #text, etc.), or, if the node corresponds to an element, it is the name of the element. nodeType integer indicating the type of the node. The node types are dened as: Node.ELEMENT_NODE Node.ATTRIBUTE_NODE Node.TEXT_NODE Node.CDATA_SECTION_NODE Node.ENTITY_REFERENCE_NODE Node.ENTITY_NODE Node.PROCESSING_INSTRUCTION_NODE Node.COMMENT_NODE Node.DOCUMENT_NODE Node.DOCUMENT_TYPE_NODE Contents 69

Node.DOCUMENT_FRAGMENT_NODE Node.NOTATION_NODE Note: These are dened by the XML DOM, not all of them are used by plasTEX. parentNode refers to the node that contains this node previousSibling the node in the document that is adjacent to and immediately before this node. If one does not exist, the value is None. nextSibling the node in the document that is adjacent to and immediately after this node. If one does not exist, the value is None. ownerDocument the node that owner of, and ultimate parent of, all nodes in the document textContent contains just the text content of this node unicode species a unicode string that could be used in place of the node. This unicode string will be converted into tokens in the plasTEX output stream. userdata dictionary used for holding user-dened data __add__(other) create a new node that is the sum of self and other. This allows you to use nodes in Python statements like: node + other. append(newChild) adds a new child to the end of the child nodes appendChild(newChild) same as append cloneNode(deep=False) create a clone of the current node. If deep is true, then the attributes and child nodes are cloned as well. Otherwise, all references to attributes and child nodes will be shared between the nodes. __cmp__(other) same as isEqualNode, but allows you to compare nodes using the Python statement: node == other. extend(other) appends other to list of children then returns self __getitem__(i) returns the child node at the index given by i. This allows you to use Pythons slicing syntax to retrieve child nodes: node[i]. getUserData(key) retrieves the data in the userdata dictionary under the name key hasAttributes() returns a boolean indicating whether or not this node has attributes dened hasChildNodes() returns a boolean indicating whether or not the node has child nodes __iadd__(other) same as extend. This allows you to use nodes in Python statements like: node += other. 70 Contents

insert(i, newChild) inserts node newChild into position i in the child nodes list insertBefore(newChild, refChild) inserts newChild before refChild in this node. If refChild is not found, a NotFoundErr exception is raised. isEqualNode(other) indicates whether the given node is equivalent to this one isSameNode(other) indicates whether the given node is the same node as this one __iter__() returns an iterator that iterates over the child nodes. This allows you to use Pythons iter() function on nodes. __len__() returns the number of child nodes. This allows you to use Pythons len() function on nodes. normalize() combine consecutive text nodes and remove comments in this node pop(index=-1) removes child node and the index given by index. If no index is specied, the last child is removed. __radd__(other) create a new node that is the sum of other and self . This allows you to use nodes in Python statements like: other + node. replaceChild(newChild, oldChild) replaces oldChild with newChild in this node. If oldChild is not found, a NotFoundErr exception is raised. removeChild(oldChild) removes oldChild from this node. If oldChild is not found, a NotFoundErr exception is raised. __setitem__(i, node) sets the item at index i to node. This allows you to use Pythons slicing syntax to insert child nodes; see the example below.
mynode[5] = othernode mynode[6:10] = [node1, node2]

setUserData(key, data) put data specied in data into the userdata dictionary under the name given by key toXML() return an XML representation of the node

6.3.3

DocumentFragment Objects

class DocumentFragment() A A collection of nodes that make up only part of a document. This is mainly used to hold the content of a LTEX macro argument.

6.3.4

Element Objects

class Element() A The base class for all element-type nodes in a document. Elements generally refer to nodes created by LTEX commands and environments.

Contents

71

getAttribute(name) returns the attribute specied by name getElementById(elementId) retrieve the element with the given ID getElementsByTagName(tagName) retrieve all nodes with the given name in the node hasAttribute(name) returns a boolean indicating whether or not the specied attribute exists removeAttribute(name) removes the attribute name from the attributes dictionary setAttribute(name, value) sets the attribute value in the attributes dictionary using the key name

6.3.5

Text Objects

class Text() This is the node type used for all text data in a document object. Unlike XML DOM text nodes, text nodes in plasTEX are not mutable. This is because they are a subclass of unicode. This means that they will respond to all of the standard Python string methods in addition to the Node methods and the methods described below. data the text content of the node length the length of the text content nodeValue the text content of the node wholeText returns the text content from the current text node as well as its siblings

6.3.6

Document Objects

class Document() The top-level node of a document that contains all other nodes. createDocumentFragment() instantiate a new document fragment createElement(tagName) instantiate a new element with the given name createTextNode(data) instantiate a new text node initialized with data importNode(importedNode, deep=False) import a node from another document. If deep is true, all nodes within importedNode are cloned. normalizeDocument() concatenate all consecutive text nodes and remove comments

72

Contents

6.3.7

Command Objects

class Command() The Command class is a subclass of Macro. This is the class that should be subclassed when creating Python A based macros that correspond to LTEX commands. For more information on the Command class API, see the Macro class.

6.3.8

Environment Objects

class Environment() The Environment class is a subclass of Macro. This is the class that should be subclassed when creating A Python based macros that correspond to LTEX environments. The main difference between the processing of A Commands and Environments is that the invoke() method does special handling of the LTEX document context, and the digest() method absorbs the output stream tokens that are encapsulated by the \begin and \end tokens. For more information on the Environment class API, see the Macro class.

6.3.9

TeXFragment Objects

class TeXFragment() A A fragment of a document. This class is used mainly to store the contents of LTEX macro arguments. source A the LTEX source representation of the document fragment

6.3.10

TeXDocument Objects

class TeXDocument() A A complete LTEX document. charsubs a list of two element tuples containing character substitutions for all text nodes in a document. This is used to convert charcter strings like --- into . The rst element in each tuple in the string to replace, the second element is the unicode character or sequence to replace the original string with. preamble A returns the LTEX source representation of the document preamble (i.e. \begin{document}) source A the LTEX source representation of the document everything before the

6.4 plasTeX.TeX The TEX Stream

A The TEX stream is the piece of plasTEX where the parsing of the LTEX document takes place. While the TeX class is fairly large, there are only a few methods and attributes designated in the public API. A The TEX stream is based on a Python generator. When you feed it a LTEX source le, it processes the le much like TEX itself. However, on the output end, rather than a DVI le, you get a plasTEX document object. The basic usage is shown in the code below.

Contents

73

from plasTeX.TeX import TeX doc = TeX(file=myfile.tex).parse()

6.4.1

TeX Objects

class TeX([ownerDocument, le ]) The TeX class is the central TEX engine that does all of the parsing, invoking of macros, and other document building tasks. You can pass in an owner document if you have a customized document node, or if it contains a customized conguration; otherwise, the default TeXDocument class is instantiated. The le argument is the A A name of a LTEX le. This le will be searched for using the standard LTEX technique and will be read using the default input encoding in the documents conguration. disableLogging() disables logging. This is useful if you are using the TeX object within another library and do not want all of the status information to be printed to the screen. Note: This is a class method. filename the current lename being processed jobname the name of the basename at the top of the input stack lineNumber the line number of the current le being processed expandTokens(tokens, normalize=False) expand a list of unexpanded tokens. This method can be used to expand tokens without having them sent to the output stream. The returned value is a TeXFragment populated with the expanded tokens. input(source) add a new input source to the input stack. source should be a Python le object. This can be used to add additional input sources to the stream after the TeX object has been instantiated. __iter__() return a generator that iterates through the tokens in the source. This method allows you to treat the TeX stream as an iterable and use it in looping constructs. While the looping is generally handled in the parse() method, you can manually expand the tokens in the source by looping over the TeX object as well.
for tok in TeX(open(myfile.tex)): print tok

itertokens() return an iterator that iterates over the unexpanded tokens in the input document. kpsewhich(name) locate the given le in a kpsewhich-like manner. The full path to the le is returned if it is found; otherwise, None is returned. Note: Currently, only the directories listed in the environment variable TEXINPUTS are searched. normalize(tokens) joins consecutive text tokens into a string. If the list of tokens contain tokens that are not text tokens, the original list of tokens is returned. parse(output=None) parse the sources currently in the input stack until they are empty. The output argument is an optional 74 Contents

Document node to put the resulting nodes into. If none is supplied, a TeXDocument instance will be created. The return value is the document from the output argument or the instantiated TeXDocument object. pushToken(token) pushes a token back into the input stream to be re-read. pushTokens(tokens) pushes a list of tokens back into the input stream to be re-read. readArgument(*args, **kwargs) A parse a macro argument without the LTEX source that created it. This method is just a thin wrapper around readArgumentAndSource. See that method for more information. readArgumentAndSource(spec=None, subtype=None, delim=,, expanded=False, default=None, parentNode=None, name=None) A parse a macro argument. Return the argument and the LTEX source that created it. The arguments are described below. Description Option spec string containing information about the type of argument to get. If it is None, the next token is returned. If it is a two-character string, a grouping delimited by those two characters is returned (i.e. []). If it is a single-character string, the stream is checked to see if the next character is the one specied. In all cases, if the specied argument is not found, None is returned. type data type to cast the argument to. New types can be added to the self.argtypes dictionary. The key should match this type argument and the value should be a callable object that takes a list of tokens as the rst argument and a list of unspecied keyword arguments (i.e. **kwargs) for type specic information such as list delimiters. subtype data type to use for elements of a list or dictionary item delimiter for list and dictionary types delim expanded boolean indicating whether the argument content should be expanded or just returned as an unexpanded text string default value to return if the argument doesnt exist parentNode the node that the argument belongs to name the name of the argument being parsed The return value is always a two-element tuple. The second value is always a string. However, the rst value can take the following values. Value None object of requested type list of tokens Condition the requested argument wasnt found if type was specied all other arguments

source(tokens) A return the LTEX representation of the tokens in tokens textTokens(text) convert a string of text into a series of tokens

6.5 plasTeX.Context The TEX Context

The Context class stores all of the information associated with the currently running document. This includes things like macros, counters, labels, references, etc. The context also makes sure that localized macros get popped off when processing leaves a macro or environment. The context of a document also has the power to create new counters, dimens, if commands, macros, as well as change token category codes.

Contents

75

Each time a TeX object is instantiated, it will create its own context. This context will load all of the base macros and initialize all of the context information described above.

6.5.1

Context Objects

class Context([load ]) Instantiate a new context. If the load argument is set to true, the context will load all of the base macros dened in plasTEX. This includes A all of the macros used in the standard TEX and LTEX distributions. contexts stack of all macro and category code collections currently in the document being processed. The item at index 0 include the global macro set and default category codes. counters a dictionary of counters. currentlabel the object that is given the label when a \label macro is invoked. isMathMode boolean that species if we are currently in TEXs math mode or not. labels a dictionary of labels and the objects that they refer to. addGlobal(key, value) add a macro value with name key to the global namespace. addLocal(key, value) add a macro value with name key to the current namespace. append([context ]) same as push() catcode(char, code) set the category code for a character in the current scope. char is the character that will have its category code changed. code is the TEX category code (0-15) to change it to. chardef(name, num) create a new TEX chardef like \chardef. name is the name of the command to create. num is the character number to use. __getitem__(key) look through the stack of macros and return the one with the name key. The return value is an instance of the requested macro, not a reference to the macro class. This method allows you to use Pythons dictionary syntax to retrieve the item from the context as shown below.
tex.context[section]

importMacros(context) import macros from another context into the global namespace. The argument, context, must be a dictionary of macros. label(label) set the given label to the currently labelable object. An object can only have one label associated with it.

76

Contents

let(dest, source) create a new TEX let like \let. dest is the command sequence to create. source is the token to set the command sequence equivalent to. Example
c.let(bgroup, BeginGroup({))

loadBaseMacros() imports all of the base macros dened by plasTEX. This includes all of the macros specied by the TEX and A LTEX systems. loadLanguage(language, document) loads a language package to congure names such as \figurename, \tablename, etc. language is a string containing the name of the language le to load. document is the document object being processed. loadINIPackage(inile) load an INI formatted package le (see section 4.3 for more information). loadPackage(tex, le, [options ]) A loads a LTEX package. tex is the TEX processor to use in parsing the package content le is the name of the package to load options is a dictionary containing the options to pass to the package. This generally comes from the optional argument on a \usepackage or \documentclass macro.
A The package being loaded by this method can be one of three type: 1) a native LTEX package, 2) a Python package, or 3) an INI formatted le. The Python version of the package is searched for rst. If it is found, it is A loaded and an INI version of the package is also loaded if it exists. If there is no Python version, the true LTEX A version of the package is loaded. If there is an INI version of the package in the same directory as the LTEX version, that le is loaded also.

newcommand(name[, nargs[, denition[, opt ]]]) A create a new LTEX command like \newcommand. name is the name of the macro to create. nargs is the number of arguments including optional arguments. denition is a string containing the macro denition. opt is a string containing the default optional value. Examples
c.newcommand(bold, 1, r\\textbf{#1}) c.newcommand(foo, 2, r{\\bf #1#2}, opt=myprefix)

newcount(name[, initial ]) create a new count like \newcount. newcounter(name, [resetby, initial, format ]) create a new counter like \newcounter. name is the name of the counter to create. resetby is the counter that, when incremented, will reset the new counter. initial is the initial value for the counter. Contents 77

format is the printed format of the counter. In addition to creating a new counter macro, another macro corresponding to the \thename is created which A prints the value of the counter just like in LTEX. newdef(name[, args[, denition[, local ]]]) create a new TEX denition like \def. name is the name of the denition to create. args is a string containing the TEX argument prole. denition is a string containing the macro code to expand when the denition is invoked. local is a boolean that species that the denition should only exist in the local scope. The default value is true. Examples
c.newdef(bold, #1, {\\bf #1}) c.newdef(put, (#1,#2)#3, \\dostuff{#1}{#2}{#3})

newdimen(name[, initial ]) create a new dimen like \newdimen. newenvironment(name[, nargs[, denition[, opt ]]]) A create a new LTEX environment like \newenvironment. This works exactly like the newcommand() method, except that the denition argument is a two element tuple where the rst element is a string containing the macro content to expand at the \begin, and the second element is the macro content to expand at the \end. Example
c.newenvironment(mylist, 0, (r\\begin{itemize}, r\\end{itemize}))

newif(name[, initial ]) create a new if like \newif. This also creates macros corresponding to \nametrue and \namefalse. newmuskip(name[, initial ]) create a new muskip like \newmuskip. newskip(name[, initial ]) create a new skip like \newskip. packages A a dictionary of LTEX packages. The keys are the names of the packages. The values are dictionaries containing the options that were specied when the package was loaded. pop([obj ]) pop the top scope off of the stack. If obj is specied, continue to pop scopes off of the context stack until the scope that was originally added by obj is found. push([context ]) add a new scope to the stack. If a macro instance context is specied, the new scopes namespace is given by that object. ref(obj, label) set up a reference for resolution. obj is the macro object that is doing the referencing. label is the label of the node that obj is looking for. If the item that obj is looking for has already been labeled, the idref attribute of obj is set to the abject. Otherwise, the reference is stored away to be resolved later.

78

Contents

setVerbatimCatcodes() set the current set of category codes to the set used for the verbatim environment. whichCode(char) return the character code that char belongs to. The category codes are the same codes used by TEX and are dened in the Token class.

6.6 plasTeX.Renderers The plasTEX Rendering Framework

The renderer is responsible for taking the information in a plasTEX document object and creating a another (usually visual) representation of it. This representation may be HTML, XML, RTF, etc. While this could be implemented in various ways. One rendering framework is included with plasTEX. The renderer is essentially just a dictionary of functions1 . The keys in this dictionary correspond to names of the nodes in the document object. The values are the functions that are called when a node in the document object needs to be rendered. The only argument to the function is the node itself. What this function does in the rendering process is completely up to it; however, it should refrain from changing the document object itself as other renderers may be using that same object. There are some responsibilities that all renderers share. Renderers are responsible for checking options in the conguration object. For instance, renderers are responsible for generating lenames, creating directories, writing les in the proper encoding, generating images, splitting the document into multiple output les, etc. Of course, how it accomplishes this is really renderer dependent. An example of a renderer based on Zope Page Templates (ZPT) is included with plasTEX. This renderer is capable of generating XML and HTML output.

6.6.1

Renderer Objects

class Renderer() Base class for all renderers. Renderer is a dictionary and contains functions that are called for each node in the plasTEX document object. The keys in the dictionary correspond to the names of the nodes. This renderer implementation uses a mixin called Renderable that is mixed into the Node class prior to rendering. Renderable adds various methods to the Node namespace to assist in the rendering process. The primary inclusion is the __unicode__() method. This method returns a unicode representation of the current node and all of its child nodes. For more information, see the Renderable class documentation. default the default renderer value. If a node is being rendered and no key in the renderer matches the name of the node being rendered, this function is used instead. fileExtension contains the le extension to use for generated les. This extension is only used if the lename generator does not supply a le extension. files a list of les created during rendering. imageAttrs contains a string template that renders the placeholder for the image attributes: width, height, and depth. This placeholder is inserted into the document where the width, height, and depth of an image is needed. The placeholder is needed because images are not generated until after the document is rendered. See the Imager API (section 6.7) for more information.
1 functions is being used loosely here. Actually, any Python callable object (i.e. function, method, or any object with the __call__ method implemented) can be used

Contents

79

imageUnits contains a string template that renders the placeholder for the image attribute units. This placeholder is inserted in the document any time an attribute of a particular unit is requested. This placeholder will always occur immediately after the string generated by imageAttrs. The placeholder is needed because images are not generated until after the document is rendered. See the Imager API (section 6.7) for more information. imager A a reference to an Imager implementation. Imagers are responsible for generating images from LTEX code. This A is needed for output types which arent capable of displaying equations, LTEX pictures, etc. such as HTML. imageTypes contains a list of le extensions of valid image types for the renderer. The rst element in the list is the default image format. This format is used when generating images (if the image type isnt specied by the lename generater). When static images are simply copied from the document, their format is checked against the list of supported image types. If the static image is not in the correct format it is converted to the default image format. Below is an example of a list of image types used in the HTML renderer. These image types are valid because web browsers all support these formats.
imageTypes = [.png,.gif,.jpg,.jpeg]

vectorImageTypes contains a list of le extensions of valid vector image types for the renderer. The rst element in the list is the default vector image format. This format is used when generating images. Static images are simply copied into the output document directory. Below is an example of a list of image types used in the HTML renderer. These image types are valid because there are plug-ins available for these formats.
vectorImageTypes = [.svg]

newFilename lename generator. This method generates a basename based on the options in the conguration. The generator has an attribute called namespace which contains the namespace used to resolve the variables in the lename string. This namespace should be populated prior to invoking the generator. After a successful lename is generated, the namespace is automatically cleared (with the exception of the variables sent in the namespace when the generator was instantiated). Note: This generator can be accessed in the usual generator fashion, or called like a function. outputType a function that converts the content returned from each rendered node to the appropriate value. textDefault the default renderer to use for text nodes. cleanup(document, les[, postProcess ]) this method is called once the entire rendering process is nished. Subclasses can use this method to run any post-rendering cleanup tasks. The rst argument, document, is the document instance that is being rendered. The second argument, les, is a list of all of the lenames that were created. This method opens each le, reads the content, and calls processFileContent on the le content. It is suggested that renderers override that method instead of cleanup. In addition to overriding processFileContent, you can post-process le content without having to subclass a renderer by using the postProcess argument. See the render method for more information. find(keys[, default ]) locate a rendering method from a list of possibilities. keys is a list of strings containing the requested name of a rendering method. This list is traversed in order. The rst renderer that is found is returned.

80

Contents

default is a default rendering method to return if none of the keys exists in the renderer. initialize() this routine is called after the renderer is instantiated. It can be used by subclasses to do any initialization routines before the rendering process. processFileContent(document, content) post-processing routine that allows renders to modify the output documents one last time before the rendering process is nished. document is the input document instance. content is the content of the le in a unicode object. The value returned from this method will be written to the output le in the appropriate encoding. render(document[, postProcess ]) invokes the rendering process on document. You can post-process each le after it is rendered by passing a function into the postProcess argument. This function must take two arguments: 1) the document object and 2) the content of a le as a unicode object. It should do whatever processing it needs to the le content and return a unicode object.

6.6.2

Renderable MixIn

class Renderable() The Renderable mixin is mixed into the Node namespace prior to the rendering process. The methods mixed in assist in the rendering process. filename the lename that this object will create. Objects that dont create new les should simply return None. The conguration determines which nodes should create new les. image generate an image of the object and return the image lename. See the Imager documentation in section 6.7 for more information. vectorImage generate a vector image of the object and return the image lename. See the Imager documentation in section 6.7 for more information. url return the relative URL of the object. If the object actually creates a le, just the lename will be returned (e.g. foo.html). If the object is within a le, both the lename and the anchor will be returned (e.g. foo.html#bar). __str__() same as __unicode__(). __unicode__() invoke the rendering process on all of the child nodes. The rendering process includes walking through the child nodes, looking up the appropriate rendering method from the renderer, and calling the method with the child node as its argument. In addition to the actual rendering process, this method also prints out some status information about the rendering process. For example, if the node being rendered has a non-empty filename attribute, that means that the node is generating a new le. This lename information is printed to the log. One problem with this methodology is that the lename is not actually created at this time. It is assumed that the rendering method will check for the filename attribute and actually create the le.

Contents

81

6.7 plasTeX.Imagers The plasTEX Imaging Framework

A The imager framework is used when an output format is incapable of representing part of a LTEX document natively. One example of this is equations in HTML. In cases like this you can use an Imager to generate images of the commands and environments that cannot be rendered in any other way.

Currently, plasTEX comes with several imager implementations based on dvi2bitmap (http://dvi2bitmap. sourceforge.net/), dvipng (http://savannah.nongnu.org/projects/dvipng/), and ghostscript with the PNG driver (http://www.cs.wisc.edu/~ghost/doc/GPL/index.htm) called gspdfpng and gspspng, as well as one that uses OS Xs CoreGraphics library. Creating imagers based on other programs is quite simple, and more are planned for future releases. In addition to imagers that generate bitmap images, it is also possible to generate vector images using programs like dvisvg (http://dvisvg.sourceforge.net/) or dvisvgm (http://dvisvgm.sourceforge.net/). The Imager framework does all of its work in temporary directories the one requirement that it has is that Imager subclasses need to generate images with the basenames img%d where %d is the number of the image. The only requirement by the plasTEX framework is that the imager class within the imager module is called Imager and should be installed in the plasTeX.Imagers package. The basename of the imager module is the name used when plasTEX looks for a specied imager.

6.7.1

Imager Objects

class Imager(document) Instantiate the imager class. document the document object that is being rendered.
A The Imager class is responsible for creating a LTEX document of requested images, compiling it, and generating images from each page in the document.

command A species the converter that translates the output from the LTEX document compiler (e.g. PDF, DVI, PS) into images (e.g. PNG, JPEG, GIF). The only requirement is that the basename of each image is of the form img%d where %d is the number of the image. Note: This is a class attribute. Writing a renderer requires you to at least override the command that creates images. It can be as simple as the example below.
import plasTeX.Imagers class DVIPNG(plasTeX.Imagers.Imager): """ Imager that uses dvipng """ command = dvipng -o img%d.png -D 110

compiler A species the LTEX document compiler (i.e. latex, pdatex) command. Note: This is a class attribute. config contains the images section of the document conguration. fileExtension contains the le extension to use if no extension is supplied by the lename generator. imageAttrs contains a string template that will be used as a placeholder in the output document for the image height, width, and depth. These attributes cannot be determined in real-time because images are not generated until after the 82 Contents

document has been fully rendered. This template generates a string that is put into the output document so that the image attributes can be post-processed in. For example, the default template (which is rather XML/HTML biased) is:
&${filename}-${attr};

The two variables available are lename, the lename of the image, and attr, the name of the attr (i.e. width, height, or depth). imageUnits contains a string template that will be used as a placeholder in the output document for the image units. This template generates a string that is put into the output document so that the image attribute units can be postprocessed in. For example, the default template (which is rather XML/HTML biased) is:
&${units);

The only variable available is units and contains the CSS unit that was requested. The generate string will always occur immediately after the string generated by imageAttrs. images dictionary that contains the Image objects corresponding to the requested images. The keys are the image lenames. newFilename callable iterator that generates lenames according to the lename template in the conguration. source A le object where the image LTEX document is written to. verification command that veries the existence of the image converter on the current machine. If verification is not specied, the executable specied in command is executed with the --help. If the return code is zero, the imager is considered valid. If the return code is anything else, the imager is not considered valid. close() A closes the generated LTEX document and starts the image generation routine. compileLatex(source) A the method responsible for compiling the LTEX source.
A source is a le object containing the LTEX document.

convert(output) sets up the temporary environment for the image converter, then executes executeConverter. It also moves the generated images into their nal location specied in the conguration. executeConverter(output) A executes the command that converts the output from the LTEX compiler into image les.
A output is a le object containing the compiled output of the LTEX document.

getImage(node) get an image for node in any way possible. The node is rst checked to see if the imageoverride attribute is set. If it is, that image is copied to the image directory. If imageoverride is not set, or there was a problem in saving the image in the correct format, an image is generated using the source of node. newImage(text, [context, lename ]) A invokes the creation of an image using the LTEX content in text.
A context is the LTEX code that sets up the context of the document. This generally includes the setting of counters so that counters used within the image code are correct.

lename is an optional lename for the output image. Generally, image lenames are generated automatically, Contents 83

but they can be overridden with this argument. verify() veries that the command in command is valid for the current machine. The verify method returns True if the command will work, or False if it will not. writeImage(lename, code, context) A writes the LTEX code to the generated document that creates the image content. lename is the nal lename of the image. This is not actually used in the document, but can be handy for debugging.
A code is the LTEX code that an image is needed of. A context is the LTEX code that sets up the context of the document. This generally includes the setting of counters so that counters used within the image code are correct.

writePreamble(document) this method is called when the imager is instantiated and is used to write any extra information to the preamble. If overridden, the subclass needs to make sure that document.preamble.source is the rst thing written to the preamble.

6.7.2

Image Objects

class Image(lename, cong, [width, height, alt, depth, longdesc ]) Instantiate an Image object. Image objects contain information about the generated images. This information includes things such as width, height, lename, absolute path, etc. Images objects also have the ability to crop the image that they reference and return information about the baseline of the image that can be used to properly align the image with surrounding text. lename is the input lename of the image. cong is the images section of the document conguration. width is the width of the image. This is usually extracted from the image le automatically. height is the height of the image. This is usually extracted from the image le automatically. alt is a text alternative of the image to be use by renderers such as HTML. depth is the depth of the image below the baseline of the surrounding text. This is generally calculated automatically when the image is cropped. longdesc is a long description used to describe the content of the image for renderers such as HTML. alt a text alternative of the image to be use by renderers such as HTML. config the images section of the documents conguration. depth the depth of the image below the baseline of the surrounding text. This is generally calculated automatically when the image is cropped. filename the lename of the image. height the heigt of the image in pixels. longdesc a long description used to describe the content of the image for renderers such as HTML.

84

Contents

path the absolute path of the image le. url the URL of the image. This may be used during rendering. width the width of the image in pixels. crop() crops the image so that the image edges are ush with the image content. It also sets the depth attribute of the image to the number of pixels that the image extends below the baseline of the surrounding text.

Contents

85

86

APPENDIX

About This Document

This document was writted using LaTeX (http://www.latex-project.org/). The documents use macros written for documenting the Python (http://www.python.org) language and Python packages. Generating the PDF version of the document is simply a matter of using the pdatex command. Generating the HTML version of the document, of course, uses plasTeX. The wonderful thing about the HTML version is that it was generated from the LaTeX source and Python style les without customization1 ! In fact, in its current state, plasTeX can generate the HTML versions of the Python documentation found on their website, http://www.python.org/doc/. Without customization of plasTeX, the only remaining issues are that the module index is missing and there are some formatting differences. Not bad, considering plasTeX is doing actually expanding the LaTeX document natively.

Ok, there was one customization to \var for a whitespace issue, but the change works both in the PDF and HTML version

87

88

APPENDIX

Frequently Asked Questions

B.1
B.1.1
A Parsing LTEX

How can I make plasTEX work with my complicated macros?

A While plasTEX makes a valiant effort to expand all LTEX macros, it isnt TEX and may have problems if your macros are complicated. There are things that you can do to remedy the situation. If you are getting failures or warnings, you can do one of two things: 1) you can create a simplied version of the macro that plasTEX uses for its work, while A LTEX uses the more complicated one, or 2) you can implement the macro as a Python class. A In the rst solution, you can use the \ifplastex construct to wrap your plasTEX and LTEX versions of the macros. You can even just remove parts of the macros. See the example below.

% Print a double line, then bold the text. % In plasTeX, leave the lines out. \newcommand{\mymacro}[1]{\ifplastex\else\vspace*{1in}\fi\textbf{#1}}

A Depending on how complicated you macro is, you may want to implement it as a Python class instead of a LTEX macro. Using a Python class gives you full access to all of the plasTEX internal mechanisms to do whatever you need to do in your macro. To read more about writing Python class macros, see the section 4.

B.1.2

A How can I get plasTEX to nd my LTEX packages?

A There are two types of packages that can be loaded by plasTEX: 1) native LTEX packages, and 2) packages written entirely in Python. plasTEX rst looks for packages written in Python. Packages such as this are written specically for plasTEX and will yield better parsing performance as well as better looking output. Python-based packages are valid Python packages as well. So to load them, you must add the directory where your Python packages are to your PYTHONPATH environment variable. For more information about Python-based packages, see the section 4.3. A A If you have a true LTEX package, plasTEX will try to locate it using the kpsewhich program just like LTEX does.

89

90

INDEX

__add__() (CongManager method), 61 __add__() (Node method), 70 __cmp__() (Node method), 70 __getitem__() (CongSection method), 63 __getitem__() (Context method), 76 __getitem__() (Node method), 70 __iadd__() (CongManager method), 62 __iadd__() (Node method), 70 __iter__() (Node method), 71 __iter__() (TeX method), 74 __len__() (Node method), 71 __radd__() (CongManager method), 62 __radd__() (Node method), 71 __repr__() (CongManager method), 62 __repr__() (CongSection method), 63 __repr__() (GenericOption method), 66 __setitem__() (CongSection method), 64 __setitem__() (Node method), 71 __str__() (CongManager method), 62 __str__() (CongSection method), 64 __str__() (Renderable method), 81 __unicode__() (Renderable method), 81 acceptsArgument() (GenericOption method), 65 add_section() (CongManager method), 61 addGlobal() (Context method), 76 addLocal() (Context method), 76 alt (Image attribute), 84 append() (Context method), 76 append() (Node method), 70 appendChild() (Node method), 70 args (Macro attribute), 55 argSource (Macro attribute), 56 arguments (Macro attribute), 57 attributes (Node attribute), 69

blockType (Macro attribute), 57 BooleanOption (class in plasTeX.CongManager), data (CongSection attribute), 63 67 data (Text attribute), 72 default (Renderer attribute), 79 cast() (GenericOption method), 65 defaults() (CongManager method), 61 catcode() (Context method), 76 defaults() (CongSection method), 63

categories() (CongManager method), 61 chardef() (Context method), 76 charsubs (TeXDocument attribute), 73 checkValues() (GenericOption method), 65 childNodes (Node attribute), 69 cleanup() (Renderer method), 80 clearValue() (GenericOption method), 65 cloneNode() (Node method), 70 close() (Imager method), 83 Command (class in plasTeX.DOM), 73 command (Imager attribute), 82 compileLatex() (Imager method), 83 compiler (Imager attribute), 82 CompoundOption (class in plasTeX.CongManager), 67 config (Image attribute), 84 config (Imager attribute), 82 ConfigManager (class in plasTeX.CongManager), 61 ConfigSection (class in plasTeX.CongManager), 63 Context (class in plasTeX.Context), 76 contexts (Context attribute), 76 convert() (Imager method), 83 copy() (CongManager method), 61 copy() (CongSection method), 63 CountedOption (class in plasTeX.CongManager), 67 counter (Macro attribute), 57 counters (Context attribute), 76 createDocumentFragment() (Document method), 72 createElement() (Document method), 72 createTextNode() (Document method), 72 crop() (Image method), 85 currentlabel (Context attribute), 76

91

image (Renderable attribute), 81 imageAttrs (Imager attribute), 82 imageAttrs (Renderer attribute), 79 Imager (class in plasTeX.Imagers), 82 imager (Renderer attribute), 80 images (Imager attribute), 83 imageTypes (Renderer attribute), 80 Element (class in plasTeX.DOM), 71 imageUnits (Imager attribute), 83 Environment (class in plasTeX.DOM), 73 imageUnits (Renderer attribute), 80 environment variables importMacros() (Context method), 76 PYTHONPATH, 89 importNode() (Document method), 72 TEXINPUTS, 74 initialize() (Renderer method), 81 executeConverter() (Imager method), 83 input() (TeX method), 74 expand() (Macro method), 58 InputDirectoryOption (class in plasexpandTokens() (TeX method), 74 TeX.CongManager), 68 extend() (Node method), 70 InputFileOption (class in plasTeX.CongManager), 68 fileExtension (Imager attribute), 82 insert() (Node method), 71 fileExtension (Renderer attribute), 79 insertBefore() (Node method), 71 filename (Image attribute), 84 IntegerOption (class in plasTeX.CongManager), filename (Renderable attribute), 81 68 filename (TeX attribute), 74 invoke() (Macro method), 58 files (Renderer attribute), 79 isElementContentWhitespace (Node attribute), find() (Renderer method), 80 69 FloatOption (class in plasTeX.CongManager), 68 isEqualNode() (Node method), 71 isMathMode (Context attribute), 76 GenericOption (class in plasTeX.CongManager), isSameNode() (Node method), 71 64 itertokens() (TeX method), 74 get() (CongManager method), 61, 63 get_category() (CongManager method), 61 jobname (TeX attribute), 74 get_opt() (CongManager method), 61 get_optlist() (CongManager method), 61 kpsewhich() (TeX method), 74 getAttribute() (Element method), 72 getboolean() (CongManager method), 61, 63 label() (Context method), 76 getElementById() (Element method), 72 labels (Context attribute), 76 getElementsByTagName() (Element method), 72 lastChild (Node attribute), 69 getfloat() (CongManager method), 61, 63 length (Text attribute), 72 getImage() (Imager method), 83 let() (Context method), 77 getint() (CongManager method), 61, 63 level (Macro attribute), 57 getopt() (CongManager method), 61 lineNumber (TeX attribute), 74 getraw() (CongManager method), 61, 63 loadBaseMacros() (Context method), 77 getUserData() (Node method), 70 loadINIPackage() (Context method), 77 getValue() (GenericOption method), 65 loadLanguage() (Context method), 77 loadPackage() (Context method), 77 has_category() (CongManager method), 62 locals() (Macro method), 58 has_option() (CongManager method), 62 longdesc (Image attribute), 84 has_section() (CongManager method), 62 hasAttribute() (Element method), 72 Macro (class in plasTeX), 55 hasAttributes() (Node method), 70 macroMode (Macro attribute), 57 hasChildNodes() (Node method), 70 macroName (Macro attribute), 57 height (Image attribute), 84 mathMode (Macro attribute), 57 MultiOption (class in plasTeX.CongManager), 68 id (Macro attribute), 57 idref (Macro attribute), 57 name (CongSection attribute), 63 Image (class in plasTeX.Imagers), 84 newcommand() (Context method), 77 92 Index

depth (Image attribute), 84 digest() (Macro method), 58 digestUntil() (Macro method), 58 disableLogging() (TeX method), 74 Document (class in plasTeX.DOM), 72 DocumentFragment (class in plasTeX.DOM), 71

newcount() (Context method), 77 newcounter() (Context method), 77 newdef() (Context method), 78 newdimen() (Context method), 78 newenvironment() (Context method), 78 newFilename (Imager attribute), 83 newFilename (Renderer attribute), 80 newif() (Context method), 78 newImage() (Imager method), 83 newmuskip() (Context method), 78 newskip() (Context method), 78 nextSibling (Node attribute), 70 Node (class in plasTeX.DOM), 69 nodeName (Macro attribute), 57 nodeName (Node attribute), 69 nodeType (Node attribute), 69 nodeValue (Text attribute), 72 normalize() (Node method), 71 normalize() (TeX method), 74 normalizeDocument() (Document method), 72 options() (CongManager method), 62 OutputDirectoryOption (class in TeX.CongManager), 68 OutputFileOption (class in TeX.CongManager), 68 outputType (Renderer attribute), 80 ownerDocument (Node attribute), 70

pushTokens() (TeX method), 75 PYTHONPATH, 89 read() (CongManager method), 61 readArgument() (TeX method), 75 readArgumentAndSource() (TeX method), 75 readfp() (CongManager method), 62 ref() (Context method), 78 ref (Macro attribute), 57 refstepcounter() (Macro method), 59 remove_option() (CongManager method), 62 remove_section() (CongManager method), 62 removeAttribute() (Element method), 72 removeChild() (Node method), 71 render() (Renderer method), 81 Renderable (class in plasTeX.Renderers), 81 Renderer (class in plasTeX.Renderers), 79 replaceChild() (Node method), 71 requiresArgument() (GenericOption method), 66

packages (Context attribute), 78 paragraphs() (Macro method), 58 parent (CongSection attribute), 63 parentNode (Node attribute), 70 parse() (Macro method), 59 parse() (TeX method), 74 path (Image attribute), 85 plasTeX (standard module), 55 plasTeX.ConfigManager (standard module), 60 plasTeX.Context (standard module), 75 plasTeX.DOM (standard module), 68 plasTeX.Imagers (standard module), 82 plasTeX.Renderers (standard module), 79 plasTeX.TeX (standard module), 73 pop() (Context method), 78 pop() (Node method), 71 postArgument() (Macro method), 59 postParse() (Macro method), 59 preamble (TeXDocument attribute), 73 preArgument() (Macro method), 59 preParse() (Macro method), 59 previousSibling (Node attribute), 70 processFileContent() (Renderer method), 81 push() (Context method), 78 pushToken() (TeX method), 75

sections() (CongManager method), 62 set() (CongManager method), 62 plas- set() (CongSection method), 64 setAttribute() (Element method), 72 plas- setUserData() (Node method), 71 setVerbatimCatcodes() (Context method), 79 source() (TeX method), 75 source (Imager attribute), 83 source (Macro attribute), 58 source (TeXDocument attribute), 73 source (TeXFragment attribute), 73 stepcounter() (Macro method), 59 StringOption (class in plasTeX.CongManager), 68 style (Macro attribute), 58 tagName (Macro attribute), 58 TeX (class in plasTeX.TeX), 74 TeXDocument (class in plasTeX.DOM), 73 TeXFragment (class in plasTeX.DOM), 73 TEXINPUTS, 74 Text (class in plasTeX.DOM), 72 textContent (Node attribute), 70 textDefault (Renderer attribute), 80 textTokens() (TeX method), 75 title (Macro attribute), 58 to_string() (CongManager method), 62 to_string() (CongSection method), 64 toXML() (Node method), 71 unicode (Node attribute), 70 url (Image attribute), 85 url (Renderable attribute), 81 usage() (CongManager method), 63 userdata (Node attribute), 70

Index

93

vectorImage (Renderable attribute), 81 vectorImageTypes (Renderer attribute), 80 verification (Imager attribute), 83 verify() (Imager method), 84 whichCode() (Context method), 79 wholeText (Text attribute), 72 width (Image attribute), 85 write() (CongManager method), 62 writeImage() (Imager method), 84 writePreamble() (Imager method), 84

94

Index