Introduction

This page explains the macro system used in Firedrop2. It assumes you are using the realmacros.py macro set [1].

In order to use them you will have to put realmacros.py somewhere on your Python search path [2]. This can either be in your firedrop2 directory, or in your site-packages folder. You should put the modules directory in the same place (or elsewhere in the Python search path).

If you want to use the smiley macro, you'll need to put the path from realmacros.py to the smilies directory. The smilies page has more details.

About Macros

Macros allow you to use a shorthand for often-used text or HTML.

As a simple example, Let's say that I use a certain link a lot. I don’t want to type it over and over again. I can define a macro foo to include this link every time I type {foo} :

foo = '<a href="somepage.html>My link</a>'

In this case, the “macro definition” is simply a string that contains the HTML we want to substitute. We can use more sophisticated macros, though.

Let's assume that I use acronyms a lot, and I’m getting tired of having to type that tag again and again. It would be nice if I could type something like {acronym;IMO;In My Opinion}

This becomes IMO. (Move your mouse over the “IMO” to see the effect. Not all browsers may support this.)

To achieve this, we define a simple Python function:

{acronym;IMO;In My Opinion} is equivalent to the function call acronym(“IMO”, “In My Opinion”).

These macros can also be used to do more complex things, like insert pictures, include whole files, and so on.

Where Are Macros Defined?

In the options you can specify a path to a macros module. This can have any name - but it should be a module that Python can import. Basically that means the filename has to end in '.py' [3]. In this case, you should put in the path to realmacros.py.

If you wanted to start from scratch, here's what you need to do :

• Create a file called macros.py. You probably want to start with a copy of the example one.
• Add definitions to it. (It helps if you know some Python, of course, but even without that you can enter simple string macros of the form name = ‘text’.)
• Put the location of this file in the build.ini for your site.

Things You Should Know

• Macros are string-based. If a macro’s return value isn't a string, then it'’s turned into one (if at all possible).
• Arguments for a function call are strings too;``{foobar;42}`` is the function call foobar(“42”), not foobar(42). If you want a different type, you'll have to explicitly convert it inside your function.
• Functions with no arguments are called by their name: {baz} is equivalent to baz(), if baz is a callable object. If not, then the value is taken.
• If a macro name isn't found, it is left alone. In fact, this piece of documentation exists as it is because of this rule. Text like {knarf} would be replaced… if it were a macro. Since we didn't define a macro by that name, it is left alone and shows up in text with curly braces and all.
• If an error occurs in a macro (function call), it is left alone as well. So are macros containing newlines.
• If you want to include a semicolon (;) or a curly brace in your arguments, you're out of luck. There are currently no ways to do this. You can always define escape sequences in your functions of course.
• Ditto if you want to suppress a macro call that would normally be substituted. other than the {curlyl}, and {curlyr}, macros. See The Example Macros below.
• Macros map to Python objects. Usually you'll want to use strings or functions, but other objects are possible as well.
• If you define a function you can also give it a shorter name. For example, to give our smiley function the shorter name sm, I included the line sm = smiley after the function definition.

Advanced Macros

As well as the normal macros discussed above, there is a more advanced system of macros as well. This allows you to apply a macro to a whole chunk of text. Unlike the simple macros, these macros can be nested to apply several effects to passages.

The advanced macros work by enclosing a passage of text between a {+macro} and a {-macro}. The macro is applied to all the text between the + and the -. In this case it would be applied to and a.

You can also nest them So you can do things like :

{+second}{+first} The text {-second}{-first}

{+whole} Some text {+part} a bit in the middle {-part}
more text{-whole}

These macros aren't the same as normal macros though. Here's the idea. While a regular macro {f;x;y} translates to a function call f("x", "y"), the + and - versions use a class definition. A simple example :

Once this is defined, in your macros file (or just imported into it), you can use it as follows :

The solution is {+rot13}not for your eyes{-rot13}.

Upon execution, this will convert the text between the rot13 tags. This becomes :

The solution is abg sbe lbhe rlrf.

In your class the +tag corresponds to the class's open(text) method, the -tag to the close() method.

Note that if you are using docutils to process your text then it will be processed by docutils before it is processed by the macro. If you want to bypass this, and pass the text to your macro only, then you need to use the .. raw:: html directive. e.g. :

.. raw:: html

    {+somemacro}
    this text will not be processed as reST
    {-somemacro}

The Example Macros

The realmacros.py module has several useful macros. Feel free to experiment with this file. You can modify the macros in it, or use them as examples to create your own.

some text here
the contents of
somefile.txt

.pysrc {
    border: #c0c0ff 2px dotted;  padding:10px;
    font-weight: normal; background: #e0e0ff; margin: 20px;
    padding:10px;
}

.pykeyword {
    font-weight: bold;
    color: orange;
}
.pystring {
    color: green
}
.pycomment {
    color: red
}
.pynumber {
    color:purple;
}
.pyoperator {
    color:purple;
}
.pytext {
    color:black;
}
.pyerror {
    font-wieght: bold;
    color: red;
}

.. raw:: html

    {+coloring}
    class coloring:
        """A Macro for coloring chunks of text."""
        def open(self, data):
            p = color.Parser(data)
            p.format(None, None)
            src = p.getvalue()
            src = src.replace('\n', '<br />\n')
            return src.replace('  ', '&nbsp;&nbsp;')

        def close(self, *args):
            pass
    {-coloring}

Credits

The realmacros.py file uses various Python modules. These are included in the modules directory that comes with the distribution.They come from the following people and places :

• A lot of the text in this page comes from the document Firedrop macros by Hans Nowak
• The macros module [5] comes from Firedrop by Hans Nowak
• The smilies use smiley.py by Mark Andrews.
• smiley.py depends on path.py by Jason Orendorff.
• smiley.py uses smiley sets that follow the phpbb convention, you can download alternative sets from stylesdb.
• The smiley set included is by a gentleman called Spider.
• The colorize macro uses a module called colorize.py. It originated as part of the MoinMoin project. The version we use is the one from the Python Cookbook.

Footnotes

[3]	And the filename must only consist of alphanumerics and the underscore character. It should start with a letter, not a number, and is case sensitive, got all that ?