Earthquake in Text_Wiki

Hi, all, My fears have been independently confirmed by Lukas Smith: the current class structure of Text_Wiki does not support easy addition or modification of rendering options. Because the parsing and rendering routines are part of the same class, if you want to change just rendering or just parsing, you have to worry about both. When I set up the current system, it seemed like a good idea, as the renderer depends on the way the parser saves tokens, and having the token notes in the same place as the rendered, well, seemed to make sense. It is now apparent that this model does not extend well. So, there are going to be some "earthquakes" in the Text_Wiki class structure. Although I have a plan in mind, I wanted to hear what the voice of experience might be on the list regarding my ideas. Brainstorming in public, if you will. If Text_Wiki is not your thing, please ignore. :-) ---- ++ Overview Currently, Text_Wiki is set up like this (I will use the "bold", "code", and "wikilink" rules as examples): Text/Wiki.php Text/Wiki/Rule.php Text/Wiki/Rule/bold.php Text/Wiki/Rule/code.php Text/Wiki/Rule/wikilink.php Each rule class has a parse() method to find matching text, a process() method to convert matched text into tokens, and a series of render*() methods to render the tokens to an output format (e.g., renderXhtml(), renderPlain(), etc.). As noted above, this structure does not lend itself to easy extension for new output formats; you have to extend the whole rule class (parser **and** renderers) to add a new renderer. Alternatively, if you only want to edit the parsing routing, you still have to extend the entire class. In addition, it turns out that some rendering methods need their own configuration options. RTF, for example, needs font names and sizes. PDF needs page layout information. DocBook needs a location in the book hierarchy. The current Text_Wiki system makes no allowance for this (due to my own ignorance of the various planned output formats). ++ Changes To remedy these flaws, I plan to use a class structure more like this: Text/Wiki.php Text/Wiki/Parse.php Text/Wiki/Parse/Bold.php Text/Wiki/Parse/Code.php Text/Wiki/Parse/Wikilink.php Text/Wiki/Render.php Text/Wiki/Render/DocBook.php Text/Wiki/Render/DocBook/Bold.php Text/Wiki/Render/DocBook/Code.php Text/Wiki/Render/DocBook/Wikilink.php Text/Wiki/Render/RTF.php Text/Wiki/Render/RTF/Bold.php Text/Wiki/Render/RTF/Code.php Text/Wiki/Render/RTF/Wikilink.php Text/Wiki/Render/Plain.php Text/Wiki/Render/Plain/Bold.php Text/Wiki/Render/Plain/Code.php Text/Wiki/Render/Plain/Wikilink.php Text/Wiki/Render/XHTML.php Text/Wiki/Render/XHTML/Bold.php Text/Wiki/Render/XHTML/Code.php Text/Wiki/Render/XHTML/Wikilink.php Parsing and rendering are separate entities under this structure. The rendering formats themselves are classes, so it will be possible to store configuration specific to the renderer itself and not the tokens being rendered. ++ What does this mean for user-defined rules? Currently, to define a new rule, users must specify the file location and the class name of the rule. I didn't like going to that model, but again, it appeared the best thing to do based on circumstances at time, as well as user requests. Under the new directory structure, it appears to me that the old way of assigning user-defined rules is not going to work well (i.e., independent file name and class name). Instead, the new system will require that rule class names follow the standard PEAR naming convention, whether the rules are from Text_Wiki or user-defined. However, there is a system I use in Savant that may help with this. In Savant, you can define multiple search paths for templates, plugins, and filters; then, when it tries to auto-load a file, it searches those paths and uses the first matching file. This means that user-defined plugins take precedence over the default plugins. This has the added advantage that it can "fall back" to the default file on an arbitrary basis. I plan on implementing something like that for Text_Wiki. Yes, user-defined rules will have to follow a naming and directory-structure convention, but one or more user-defined rules can then mix into the default rules without having to extend both parsing and rendering routines from the same class. (Does that make sense?) ++ How will this affect the exposed API of Text_Wiki? I'm hoping "not much." With any luck, this will affect only the internals, and the way user-defined rules are implemented. However, I don't know, and won't know until I start re-coding. Comments on this message will help me discover what's best. Sorry for all the changes in Text_Wiki since its acceptance into PEAR; it appears I did not know what I was getting into when I started the project. Typical. ;-) -- Paul M. Jones Savant: the simple alternative to Smarty for PHP. http://phpsavant.com/ DB_Table: build RDBMS tables and XHTML forms in one PHP class. http://wiki.ciaweb.net/yawiki/index.php?area=DB_Table Yawiki: your collaborative online documentation system. http://yawiki.com/ Yawp: a single-file foundation for PHP applications. http://phpyawp.com/