The textmacros Module

Using Macros in Text



Macros in Firedrop2 are provided through the 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 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, and a bit about how to write your own.


The textmacros module could be useful in many situations. It is bundled here with the 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).


Download it here : (43k)

Module Contents

The zip file contains :


    This module uses 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 :


      The file from docutils. It turns reST files (with a .txt file ending) into html files.


      Does Python source colouring.


      Used by


      Used by the smiley macro. Smile


      The module that does macro processing.


      This is the user macro file. Edit this to add or change macros.


You don't need to install textmacros - unpack the zipfile and then use in the same way that you use

It does require the pythonutils module - which you'll need to install first. does the same job as the docutils program That means it's very easy to use Very Happy .

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).


Because buildhtml outputs on stderr the logfile generated will look like it has lots of errors.


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

    This text is untouched
    by docutils.

    But *is* processed by

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 file. Thankfully learning Python is both fun and easy Laughing .

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.


The textmacros module is the creation of Hans Nowak.

For credits for the modules used by the example macros, see the macros page.


[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 Smile .
Support This Project Logo

Hosted by Webfaction

Return to Top

Page rendered with rest2web the Site Builder

Last edited Fri Feb 15 13:42:08 2008.