\documentclass{article} \usepackage{mathptmx} \usepackage{hyperref} \begin{document} \title{Getting Started with plasTeX} \author{Tim Arnold} \maketitle \section{Overview} This document is part one of a ``Getting Started with plasTeX'' series to explain how to extend plasTeX so it can understand, parse, and render your customized LaTeX source. If you have standard 'plain-vanilla' LaTeX files, plasTeX will work for you already (see the main user documentation to use the \texttt{plastex} command). And if you have simple customizations, plasTeX can read your package files and work as-is. But when you have more complex styles or classes, you'll need to extend plasTeX to work with your customized files. It's quite easily done: there are two tasks to get started: \begin{enumerate} \item add a Python class corresponding to each macro you have defined. You'll inherit from a standard plasTeX class; often there's little more to it than that. You define the classes so plasTeX can understand how to parse your new commands. \item add a template to render the content resulting from plasTex parsing. Your command will have some data or text that needs to be handled in some way in order to display itself correctly, depending on what format you want to render to. The template tells the renderer how to do that. \end{enumerate} Once you have those tasks completed, you set your environment PATHs and run plastex. That's all there is to it. We'll do a silly start-up example just to run through the steps. Afterwards we'll do some more interesting things. Note that this example is so simple, plasTeX could easily understand the customization with no action on your part--it can often recognize new commands and deal with their definitions by itself. However, sometimes you'll have new commands or environments that more easily handled by writing your own classes. Let's get started and go through this step-by-step so you can see how plasTeX works. \section{Getting Started: Setting Up} To get started, we'll set up a workspace so we can scale it up with increasingly complex needs and new commands. First, create directories hold the new Python classes and the html templates corresponding to those classes. Also create a corresponding directory to hold containers for the LaTeX packages. That's three new directories: \begin{description} \item[src/] contains python classes corresponding to new packages\\ \textbf{Action:} create a file called \texttt{mypackage.py} \item[render/] contains html template files corresponding to new packages\\ \textbf{Action:} create a file called \texttt{mypackage.zpts} \item[tex/] contains style files corresponding to new packages\\ \textbf{Action:} create a file called \texttt{mypackage.sty} \end{description} Finally set three environment variables to tell plasTeX where to look for instructions: \begin{itemize} \item set PYTHONPATH to include the \texttt{src} directory \item set TEXINPUTS to include the \texttt{tex} (and current '.') directory \item set XHTMLTEMPLATES to the \texttt{render} directory \end{itemize} How you do that depends on what operating system you use. On my machine, the commands look like this: \begin{verbatim} setenv PYTHONPATH ~/example/src setenv TEXINPUTS ~/example/tex:.:: setenv XHTMLTEMPLATES ~/example/render \end{verbatim} \subsection{Example for Testing: the LaTeX source} To get started, we'll create a new command \verb+myBold+ that will render its text as bold. Create a file in the current directory called \texttt{testing.tex} with the following lines: \begin{verbatim} \documentclass{article} \usepackage{mypackage} \begin{document} Hello \myBold{World} \end{document} \end{verbatim} \subsection{mypackage.sty} In the \texttt{tex} directory, write the \texttt{mypackage.sty} file to contain these lines: \begin{verbatim} \ProvidesPackage{mypackage} \newcommand{\myBold}[1]{\textbf{#1}} \end{verbatim} \textbf{Note:} Recall that at the beginning I said that if you have very simple customizations, plasTeX can read your package files and work as-is. Our example certainly falls into that category. We're only using this as an example to focus on the steps involved in extending plasTeX. \textbf{Note:} This LaTeX code is not necessary as far as plasTeX is concerned; I include it here since you probably want to use LaTeX to create a pdf or postscript file from your sources, and LaTeX has to have the definition. But as long as plasTeX can find your definitions (i.e., classes) corresponding to the commands in your source, this file could just as well be blank. In fact, sometimes it's quite useful to spoof plasTeX in that way, but that's a trick for another article. \section{Getting Started: Coding} There are two parts to code: the Python class called \texttt{myBold} and the HTML template called \texttt{myBold}. These names match the new command we're defining. Since this command takes a single argument, we'll inherit from the plasTeX \texttt{Base.Command} class. The only thing the python class needs to do is to parse the command and its arguments so we can get to the data it contains when we need to render it. \subsection{Create the \texttt{myBold} class} In mypackage.py: \begin{verbatim} from plasTeX import Base class myBold(Base.Command): args = 'text:str' def invoke(self, tex): Base.Command.invoke(self, tex) \end{verbatim} Once plasTeX sees the \texttt{myBold} command in your source, it will parse it and the node will contain a string attribute called 'text'. See the main user documentation for details. For now that's really all we need to know--we only need the text argument given to the \texttt{myBold} command. \subsection{Create the \texttt{myBold} Renderer} The renderer takes the data from the node and renders it according to the template. Here we set the argument in a \texttt{b} tag. I like to set the class on my tags to the name of the command they came from. \begin{verbatim} name:myBold \end{verbatim} Each node you want to render has the same structure: the \texttt{name:} specifies the name of the command you're rendering, followed immediately by a template defining how to render the command and its data. \subsection{Parse and Render with plastex} That's it for setting up and coding. Now plasTeX knows enough to parse the tex file, create a document object and render the nodes of that object. \begin{verbatim} plastex testing.tex \end{verbatim} \section{Results} In your \texttt{work} directory, you'll see these entries: \begin{verbatim} testing/ testing.paux testing.tex \end{verbatim} The subdirectory \texttt{testing} contains a number of things, but for now focus on the main file, \texttt{index.html}. That file contains the results of rendering our simple LaTeX source. It was rendered using the \texttt{default} theme; inside it you'll see the result of the \texttt{myBold} command: \begin{verbatim} Hello World \end{verbatim} We'll talk about the other items in that directory as well as the \texttt{testing.paux} file later on. \section{Getting Deeper} To add more functionality in terms of new commands and environments, you add more classes to your package.py file, plus the corresponding render templates in the package.zpts file. There are a lot of questions remaining; how do you use a different theme, what kinds of things can you do in the template, what is the \texttt{zpts} extension mean, how do you get DocBook XML from your LaTeX sources, etc. Future articles will deal with those questions and more. Comments are welcome: a\_jtim at bellsouth dot net \end{document}