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
(http://txt2tags.sourceforge.net/userguide/InsertingMultipleLineswithPostProclikeCSSrules.html#9_1)
trick, you can modify the default template.
This is for example what
is done by Eric for
TeXtallion
(http://anamnese.online.fr/site2/textallion/samples/sample_en.html)
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
txt2tags.
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
block
lines
%!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
block
lines
%!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
block
lines
%!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
example)
%!begin: txt2png
a cool name
imgname
%!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
plugins).
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® 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.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
txt2tags-list mailing list
https://lists.sourceforge.net/lists/listinfo/txt2tags-list
