Hello everybody,

This is a proposition to be discussed. Note that I am more looking for 
comments about the general architecture/concepts than on the precise 
syntax (that will improve obviously). Does it corresponds to what you 
had in mind? Does it enable what you are expecting to do with plugins?

I first present the current extension mechanism. Finally I will propose 
a plugin syntax to have a fully usable extensions mechanism.
Did I say that comments were very welcomed ? :)

   1. Extensions
   2. Current mechanism
     2.1. Pre/postproc
       2.1.1. Examples
       2.1.2. Use
     2.2. Templates
   3. New mechanism (Plugin Proposition)
     3.1. Environments
     3.2. Environments Syntax
     3.3. Plugins
     3.4. Loading
     3.5. Options
     3.6. Precision on the Processing
     3.7. Examples
   4. Real Extensions
     4.1. What is an Extension
     4.2. Example

   1. Extensions

An extension is a way to extend the possibility of txt2tags. It can be
seen as a collection of files (howto to locate these files is not for
the moment, let's say it is in a subdirectory exname of the working
directory). When an extension is loaded, every relevant file of the
exname directory is read (see also [#newext]).
There could be different ways of loading:

- %!extension: exname
- --extension exname
- --exname

The latter is interesting because it would enable to integrate usefull
extentions in the core of txt2tags without changing the user UI. Or
equivalently to put some current features into an extension.

   2. Current mechanism

        2.1. Pre/postproc

                2.1.1. Examples

If you want to extend txt2tags, you can use preproc and postprocs.
It is quite powerfull already as you can

1. create macros
2. create smart macros
3. create new environment by reusing txt2tags ones
4. modify the underlying target template

Let's see some examples.

1. you can have a %!preproc: :-) [smileys/smile.png] to have the
(long awaited) smileys extension
2. there is the macro to protect email addresses from spam robots
(the mask-email extension)
3. you can use the tagged environment to create a maths environment
where you can put latex maths code. This can be used in Latex
obviously, but also in html with the jsmath javascript library
(the maths extension)
4. using the
   Inserting Multiple Lines with  %!PostProc 
   trick, you can modify the default template.
   This is for example what
   is done by Eric for
   Using the easy input from txt2tags and the power of latex and
   nicely designed css, this outputs pretty looking literary texts.

Actually this latter work, not only modify the template, but also
introduce new environments and macros. This is a complete extension of

                2.1.2. Use

To use these previous extensions, you can

- insert the pre/postprocs in the config area of your file
- write them on a separate file and insert a
   %!includeconf:file.conf.t2t in your config area
- use a -C file.conf.t2t on the invocation of txt2tags

The two latter are obviously the cleaner way to load the extension,
the document author has not to be the extension writer.

        2.2. Templates

This is a pending patch.

It is a way to replace the default templates that txt2tags uses by a
customized template.target file.
It gives a simpler and more robust way of creating extensions of the
number 4 type.

A template can be choosen by

- %!template: custom
- --template custom

Note that the actual template files are custom.tex,
custom.html, ... This way, one can design a suite of templates that
have the same look and feel (like textallion does).

   3. New mechanism (Plugin Proposition)

It has been suggested, despite the KISS aim, to enable the use of
plugins, that is the possibility to delegate part of the processing to
external python code.

We propose here two different notions in order to have a flexible and
robust way of using plugins.

        3.1. Environments

An environment is a block that is specially processed by a plugin.

   %!begin: environment
   %!end: environment

the parser feeds all the line to the plugin that returns a list of
lines. This is done instead of the txt2tags syntax processing.
These blocks can be nested.

        3.2. Environments Syntax

It is of course possible to define a more simple syntax to insert an
environment using preprocs. If you prefer to use <<< and >>>.
You will add in your extension

   %!preproc: "^<<<$" "%!begin: myenv\n"
   %!preproc: "^>>>$" "%!end: myenv\n"

Note that to have environment that starts and ends with the same tags
(as it is the case for the txt2tags syntax) you can alternatively use

   %!div: myenv
   %!div: myenv

        3.3. Plugins

A plugin is simply a python module. On loading, a plugin register a
collection of environments (their name and the function that processed
them). Then anything inside the %!begin/%!end is sent to the
corresponding function, with also the current target. The plugin's
function processes it and it is then inserted in
the processed file.

        3.4. Loading

A plugin is loaded by

- %!plugin: module
- --plugin module

        3.5. Options

Options for an environment can be formatted this way.

   %!begin: environment
   %!options: optionline
   %!end: environment

Not that since the plugin has access to all the lines of the block, it
can also have its proper formatting, like the first line are always
the options...

Options for a plugin could be given like this

   %!plugin: module pluginoptions

or with approriate preprocs.

        3.6. Precision on the Processing

The architecture for processing would be the following:

1. read header and config area
   - handling of %!includeconf directives
2. load pre/postprocs, plugins and define template
3. apply preprocs
4. core processing
   - txt2tags syntax processing,
   - handling of %!include directives,
   - processing of environment blocks is deferred to the corresponding
   plugin functions
   - escaping
5. fill template (%%body is replaced by what was produced at the
previous step)
6. apply postprocs

        3.7. Examples

People will probably come with a lot of ideas for plugins. Consider
this example that converts text into images (using imagemagick for

   %!begin: txt2png
   a cool name
   %!end: txt2png

So the function of the plugin will call convert with the "a cool
name" line as parameter. One will obtain a imgname.png file that
reads "a cool name" in a nice graphical way (like a logo). Note
that in this case the plugin will just output no new lines.

   4. Real Extensions

        4.1. What is an Extension

Finally, we can see that an extension is a collection of pre/postprocs, a
suite of templates, and a collection of environments (implemented by

The loading mechanism
may be precised: we can load any config files in the exname
directory, or just the manifest.conf.t2t, that will use
%!includeconf: directives to load all the relevant configs, and
%!template and %!plugin directives to define the relevant
templates and load plugins module.

        4.2. Example

One can for example think about a new mask-email extension,
relying on the imagemagick plugin to compute an image with the email
address and integrate it in the file instead of the email address.

So this extension could be defined this way (roughly, just to get the idea):

   %% this plugin defines the txt2png environment
   %!plugin: imagemagick
   %!preproc: "regexfor(username)@(isp)" 
"[\1.png]\n%!begin:txt2png\...@\2\n\1\n%!end: txt2png\n"

Download Intel&#174; Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
txt2tags-list mailing list

Reply via email to