So it is far from trivial to safely output text from a plugin that looks like aXML but is not interpreted as aXML again.

I would reconsider this design choice because you might end up with problems ranging from annoying problems like not being able to use aXML to generate XML and aXML, to really big security holes like user generated content triggering internal aXML code.

Of course, proper documentation on how to generate various output would also help, and also the replacement rules when aXML turns &amp; into &, &lt; into < and when it passes them through.

So it is far from trivial...

Whatever is output from a tag goes back into the document and is treated exactly the same as everything else. The tags input aXML and output aXML, there is no distinction and it's upto the designer how to deal with that. I've found through experience a set of abstractions that exist in harmony with each other and I'll be giving those as a suggested default set because you can build just about anything with them.

When it comes to writing your own plugins, a sound understanding of how the plugins interact and how you intend to use the new plugin and how it relates to other plugins will be needed.

Having said that, it really isn't as hard as it may seem because the rules are very simple. Any programmer worth their salt will be able to master it in a matter of hours or maybe even minutes in some cases.



I would reconsider this design choice...

I wouldn't it works great exactly as it is.



not being able to use aXML to generate XML and aXML

There is no problem with that at all since you have complete control over the plugins their names and definitions.



security holes like user generated content triggering internal aXML code.

I went into this before somewhere. There are basically only two vectors; the query data and the cookies. Putting the cookies aside for a moment as there is little scope for insertion there, the solution I found to this problem was to sanitize the query data prior to starting the document.

What I'm going to do is add a key to the conf hash in the Conf.pm file, that is an array of allowed tags. If anything else exists in the query data it will be converted so that it cannot be recognised by the parser and thus passes through without the possibility of effecting anything else. I'm making the list an allowed list instead of a disallowed list so if the list is empty it will not allow any tags through at all.



proper documentation

Gotta finish writing the thing first!! The new version is almost ready just got a few rough edges to sort out, some more plugins to port from the old version and then it should be just about ready to rock.



& < etc

In the vast majority of cases an aXML programmer won't actually need to worry about that stuff at all, they are rare special case features which "close the circle" so to speak. Understanding them will only be required if you have an application which can't live without them, for instance feeding very specific XML data to another system which will throw exceptions unless special chars are encoded right.

not being able to use aXML to generate XML and aXML

There is no problem with that at all since you have complete control over the plugins their names and definitions.

Ugh. So if I discover that I have to output (or worse, pass through and modify) XML that contains <d> elements, I have to review all my aXML code to make sure that I don't use any plugin named/responding to <d>? I'm still not convinced that this is a sound design choice. That you don't immediately spot this problem makes me think that you haven't encountered the problem ,but that is to be expected if all you are doing is generate web pages and work alone. That way, you have a good overview of the admissible names. This mechanism will horribly fail once one of these two parameters changes.

for instance feeding very specific XML data to another system which will throw exceptions unless special chars are encoded right.

Also known as valid xml

XML really shouldn't be part of the name for this thing

You've lost me there dude.. what basics is it that you feel are next to impossible? In the last 5 years I have yet to find any problem which I have not been able to solve, nor have I found any problem to which the solution is not quite straight forward.

Safely returning a "<" from a plugin.

To be safe, a plugin needs to look like

sub plugin_name {
   my $text_to_return = ...;
   $text_to_return =~ s{<}{<post_include>path/to/lt</post_include>}g;
   return $text_to_return;
}
[download]

Even then, that's not enough to make a reusable plugin because it hardcodes the path to a template.

By the way, since every plugin (except <post_include>) returns template code, this design is slow because there are soooo many templates to process, and none of them can be precompiled.