The textmacros Module

Using Macros in Text

 

 

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

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

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

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

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.

Hosted by Webfaction

Return to Top

Page rendered with rest2web the Site Builder

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


Counter...


Voidspace: Cyberpunk, Technology, Fiction and More
Search this Site:
 
Web Site

IronPython in ActionIronPython in Action

Blogads

Follow me on:

Twitter

Del.icio.us

Shared Feeds

s

Hosting for an agile web