\section{\module{plasTeX.Renderers} --- The \plasTeX\ Rendering Framework}

\declaremodule{standard}{plasTeX.Renderers}
\modulesynopsis{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 functions\footnote{
``functions'' is being used loosely here.  Actually, any Python callable
object (i.e. function, method, or any object with the \method{__call__}
method implemented) can be used}.  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 configuration object.
For instance, renderers are responsible for generating filenames, 
creating directories, writing files in the proper encoding, generating
images, splitting the document into multiple output files, 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.


\subsection{Renderer Objects}

\begin{classdesc}{Renderer}{}
Base class for all renderers.  \class{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.
\end{classdesc}

This renderer implementation uses a mixin called \class{Renderable} that
is mixed into the \class{Node} class prior to rendering.  \class{Renderable}
adds various methods to the \class{Node} namespace to assist in the
rendering process.  The primary inclusion is the \method{\_\_str\_\_()}
method.  This method returns a string representation of the current node
and all of its child nodes.  For more information, see the \class{Renderable}
class documentation.

\begin{memberdesc}[Renderer]{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.
\end{memberdesc}

\begin{memberdesc}[Renderer]{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.
\end{memberdesc}

\begin{memberdesc}[Renderer]{files}
a list of files created during rendering.
\end{memberdesc}

\begin{memberdesc}[Renderer]{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 \class{Imager} API 
(section \ref{sec:imager-api}) for more information.
\end{memberdesc}

\begin{memberdesc}[Renderer]{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 \member{imageAttrs}.
The placeholder is needed because images are not generated until after
the document is rendered.  See the \class{Imager} API 
(section \ref{sec:imager-api}) for more information.
\end{memberdesc}

\begin{memberdesc}[Renderer]{imager}
a reference to an \class{Imager} implementation.  Imagers are responsible
for generating images from \LaTeX\ code.  This is needed for output types 
which aren't capable of displaying equations, \LaTeX\ pictures, etc. such
as HTML.
\end{memberdesc}

\begin{memberdesc}[Renderer]{vectorBitmap}
a boolean indicating whether bitmap versions should be generated for vector
images. The bitmap version is used to read off the height, width and depth of
the image. If such information is not used by the renderer, we can skip
producing the bitmap, which may take a long time.

This defaults to \code{True}.
\end{memberdesc}

\begin{memberdesc}[Renderer]{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.
\begin{verbatim}
imageTypes = ['.png','.gif','.jpg','.jpeg']
\end{verbatim}
\end{memberdesc}

\begin{memberdesc}[Renderer]{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.
\begin{verbatim}
vectorImageTypes = ['.svg']
\end{verbatim}
\end{memberdesc}

\begin{memberdesc}[Renderer]{newFilename}
filename generator.  This method generates a basename based on the options
in the configuration.  

The generator has an attribute called \member{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.}
\end{memberdesc}

\begin{memberdesc}[Renderer]{outputType}
a function that converts the content returned from each rendered
node to the appropriate value.
\end{memberdesc}

\begin{memberdesc}[Renderer]{textDefault}
the default renderer to use for text nodes.
\end{memberdesc}


\begin{methoddesc}[Renderer]{cleanup}{document, files\optional{, 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, \var{document}, is the document instance that is
being rendered.  The second argument, \var{files}, is a list of all of the
filenames that were created.

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

In addition to overriding \method{processFileContent}, you can post-process
file content without having to subclass a renderer by using the 
\var{postProcess} argument.  See the \method{render} method for more information.
\end{methoddesc}

\begin{methoddesc}[Renderer]{find}{keys\optional{, default}}
locate a rendering method from a list of possibilities.  

\var{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.

\var{default} is a default rendering method to return if none of the keys
exists in the renderer.
\end{methoddesc}

\begin{methoddesc}[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.
\end{methoddesc}

\begin{methoddesc}[Renderer]{processFileContent}{document, content}
post-processing routine that allows renders to modify the output documents
one last time before the rendering process is finished.  \var{document}
is the input document instance.  \var{content} is the content of the 
file in a string object.  The value returned from this method will be
written to the output file in the appropriate encoding.
\end{methoddesc}

\begin{methoddesc}[Renderer]{render}{document\optional{, postProcess}}
invokes the rendering process on \var{document}.  You can post-process each
file after it is rendered by passing a function into the \var{postProcess}
argument.  This function must take two arguments: 1) the document object and
2) the content of a file as a string object.  It should do whatever 
processing it needs to the file content and return a string object.
\end{methoddesc}


\subsection{Renderable MixIn}

\begin{classdesc}{Renderable}{}
The \class{Renderable} mixin is mixed into the \class{Node} namespace
prior to the rendering process.  The methods mixed in assist in the 
rendering process.
\end{classdesc}

\begin{memberdesc}[Renderable]{filename}
the filename that this object will create.  Objects that don't create 
new files should simply return \var{None}.   The configuration determines
which nodes should create new files. 
\end{memberdesc}

\begin{memberdesc}[Renderable]{image}
generate an image of the object and return the image filename.  See
the \class{Imager} documentation in section \ref{sec:imager-api} for
more information.
\end{memberdesc}

\begin{memberdesc}[Renderable]{vectorImage}
generate a vector image of the object and return the image filename.  See
the \class{Imager} documentation in section \ref{sec:imager-api} for
more information.
\end{memberdesc}

\begin{memberdesc}[Renderable]{url}
return the relative URL of the object.  

If the object actually creates a file, just the filename will
be returned (e.g. \file{foo.html}).  If the object is within a file, 
both the filename and the anchor will be returned 
(e.g. \file{foo.html\#bar}).
\end{memberdesc}

\begin{methoddesc}[Renderable]{__str__}{}
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 \member{filename} attribute, that
means that the node is generating a new file.  This filename information
is printed to the log.  One problem with this methodology is that the 
filename is not actually created at this time.  It is assumed that the
rendering method will check for the \member{filename} attribute and actually
create the file.
\end{methoddesc}