The textmacros Module
Using Macros in Text
Contents
Introduction
Macros in Firedrop2 are provided through the texmacros.py module. The same module is also used for macros in rest2web. This module is useful anywhere you are processing text for presentation. Macros insert text or html into your page, or can process whole chunks of text.
The concept used by textmacros.py is very simple. Expressions in your text, surrounded by curly braces {like;this} are replaced with expanded versions. You define your own module with functions and classes. The macros map to function calls (or to method calls) on the text between the macros.
This allows you to add things like smilies, Python source coloring, acronyms, and other features to docutils.
For a full explanation of how it works, see the macros page. This documents how to use the example macros that come in macros.py, and a bit about how to write your own.
Note
The textmacros module could be useful in many situations. It is bundled here with the buildhtml.py from docutils. It is specifically targetted at the html output of docutils.
It would be very easy to adapt it for other situations (for example the latex output of docutils).
Downloading
Download it here : textmacros.zip (43k)
Module Contents
The zip file contains :
FuzzyBuilder.py
This module uses buildhtml.py and applies the macros in the output. It behaves like buildhtml - it attempts to process every text file in the current directory and any sub-directories.
docutils.conf
The config file for docutils.
smilies
A directory containing smiley icons used by the macros.
stylesheets
A directory containing :
default.css
The docutils stylesheet.
pysrc.css
The stylesheet used by the {+coloring} macro.
voidspace_docutils.css
My custom stylesheet. It uses (and modifies) the standard docutils stylesheet.
modules
A directory containing modules that do the work :
buildhtml.py
The file from docutils. It turns reST files (with a .txt file ending) into html files.
colorize.py
Does Python source colouring.
path.py
Used by smiley.py
smiley.py
Used by the smiley macro.
textmacros.py
The module that does macro processing.
macro.py
This is the user macro file. Edit this to add or change macros.
Installing
You don't need to install textmacros - unpack the zipfile and then use FuzzyBuilder.py in the same way that you use buildhtml.py.
It does require the pythonutils module - which you'll need to install first.
FuzzyBuilder.py
FuzzyBuilder.py does the same job as the docutils program buildhtml.py.
That means it's very easy to use 
.
This means that it processes every text file in the current directory (and recursively down any subdirectories) into html files.
After processing as ReST, the macros are expanded [1].
There are a couple of values at the start of the source code that you can edit - these affect logging, and whether the script pauses after running (useful on windoze).
Note
Because buildhtml outputs on stderr the logfile generated will look like it has lots of errors.
reStructuredText
textmacros works very well with docutils. docutils ignores the curly braces used for macros, they pass through the HTMLWriter untouched [2].
The raw Directive
The advanced macro system allows you to have a whole passage of text processed by the macros sytem. For example Python Source Coloring is obviously applied to passages of Python code. You will often not want that processing by docutils first - but including untouched in the output.
The way to do this is to use the raw directive :
.. raw:: html
{+some_macro}
This text is untouched
by docutils.
But *is* processed by
``some_macro``.
{-some_macro}
Using and Writing Macros
The most important thing of course is using macros, and writing your own.
This is done using the Python programming language - in the macros.py file.
Thankfully learning Python is both fun and easy 
.
The textmacros module is the same one used in firedrop2 and rest2web (did I already mention this ?). This means that I've already written a separate doc explaining how to use the example macros - and how to write your own.
For all the details on this - visit the macros page.
Credits
The textmacros module is the creation of Hans Nowak.
For credits for the modules used by the example macros, see the macros page.
Footnotes
| [1] | As an added bonus, any restindex at the start of the file will be removed first. This means you can use textmacros to process individual files from a rest2web site. |
| [2] | It may be entirely reasonable to use macros on the Latex output of
docutils as well. It's just not something I've ever done . |
For buying techie books, science fiction, computer hardware or the latest gadgets: visit The Voidspace Amazon Store. If you're looking for a new techie job, try the Voidspace Tech Job Board. This is part of the Hidden Network of technology and programming jobs.
Last edited Fri Feb 15 13:42:08 2008.
Counter...
IronPython in ActionFollow me on:
s
