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 plasT_eX 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 file extension to use for generated files. This extension is only used if the filename generator does not supply a file extension.

files

a list of files 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.

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 reference to an Imager implementation. Imagers are responsible for generating images from L^aT_eX code. This is needed for output types which aren’t capable of displaying equations, L^aT_eX pictures, etc. such as HTML.

imageTypes

contains a list of file extensions of valid image types for the renderer. The first element in the list is the default image format. This format is used when generating images (if the image type isn’t specified by the filename 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 file extensions of valid vector image types for the renderer. The first 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

filename generator. This method generates a basename based on the options in the configuration.

The generator has an attribute called namespace which contains the namespace used to resolve the variables in the filename string. This namespace should be populated prior to invoking the generator. After a successful filename 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, files[, postProcess])

this method is called once the entire rendering process is finished. Subclasses can use this method to run any post-rendering cleanup tasks. The first argument, document, is the document instance that is being rendered. The second argument, files, is a list of all of the filenames that were created.

This method opens each file, reads the content, and calls processFileContent on the file content. It is suggested that renderers override that method instead of cleanup.

In addition to overriding processFileContent, you can post-process file 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 first renderer that is found is returned.

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 finished. document is the input document instance. content is the content of the file in a unicode object. The value returned from this method will be written to the output file in the appropriate encoding.

render(document[, postProcess])

invokes the rendering process on document. You can post-process each file 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 file as a unicode object. It should do whatever processing it needs to the file content and return a unicode object.