3,897
edits
Changes
Jump to navigation
Jump to search
→Implementation notes
== Implementation notes ==
=== XML parser ===
The extension uses a hardwritten simple XML parser implemented in pure Lus. The parser is expat-style and based on string.find() and string.sub(). The advantage of this approach is that it can handle bad XML input by throwing an appropriate (and understandable) error. Neither the Lpeg-based Lua parser from the 13th ConTeXt meeting nor the ConTeXt built-in parser allows for that, both assume well-formed XML as input.
A tailored parser also allowed for easy extension for the CDATA issue mentioned below.
But the main motivation for a private dedicated parser written in Lua is that we want to be able to not only check the well-formedness of the XML, but also its adherence to a set of extra rules:
# The documentation should not modify the argument structure of the command’s formal specification, only add explanations to it. Theoretically, each of the 3900+ formal specifications has its own private XML Schema.
# The documentation should be easily parseable by an external system, meaning that use of wiki code and HTML tags need to be governed.
These additional rules made using the DOM-based parser in php unwieldy, for me. I am sure a good php programmer could implement these extra checks, but not me. At least not in a reasonable amout of time. But I knew how to tackle both requirements using Lua, and could write an implementation quite quickly and effortlessly.
The first point is handled like this:
*While a fresh set of ‘virgin’ XML files is created from <code>context-en.xml</code>, each separate file is parsed using a set of expat callback functions that create a lua table representing the ‘virginal’ parse tree of the XML file. This Lua table is dumped to disk and distributed along with the XML file.
*When a wiki user presses the ‘Save’ button in the page editor, their edited XML is parsed using a slightly different set of expat callback functions from the ones for viewing. These altered callbacks skip all documentation content while building the parse tree. The two lua tables representing the parse trees are then compared. They should be identical. If not, an error is raised and the save action aborted with a user-visible error message.
The second point is taken care of during that same XML parse step of the user page revision. It uses a combination of a tag lookup table and string text matching to make sure the user followed the rules (as explained in [[Help:Command]]).
=== About those extension tags ===
