phpDocumentor tutorials/extended documentation implementation

Hello, I am in the process of implementing the new tutorial/extended documentation feature of phpDocumentor and would like some feedback on the choices that have been made. HISTORY/PROBLEM: people want to put links to tutorials and other documentation in the api documentation, and also want to be able to link to the api documentation from the tutorials/extended docs, so as to generate a more complete documentation from the source code. SOLUTION: put tutorials in a special directory tutorials/packagename/[subpackagename/]. tutorials is a subdirectory of any directory parsed. allow linking to tutorials through tag @tutorial and inline tag {@tutorial}. The syntax will be the same as @see with a few tutorial-specific differences: -tutorialname.ext is the way to link to tutorials/package/subpackage/tutorialname.ext -if more than 1 tutorial has the same name, use package#tutorialname.ext -if more than 1 tutorial in a subpackage/package group has the same name use package%subpackage#tutorialname.ext tutorials/package/tutorial.pkg -and- tutorials/package/subpackage/tutorial.pkg must be differentiated by: @tutorial package#tutorial.pkg @tutorial package%subpackage#tutorial.pkg linking to subsections of a tutorial would be accomplished by: @tutorial tutorial.pkg!subsection and sub-subsections by: @tutorial tutorial.pkg!subsection1!subsection2 Tutorials may be associated and automatically linked with: -packages (will replace the old package-level documentation in HTML converters) -subpackage (new subpackage-level documentation) -classes -procedural pages where the tutorial file name is : tutorialfilename.pkg tutorialfilename.cls tutorialfilename.proc Backward compatibility with package-level documentation will be maintained for the html converters only, the new converters (pdf/xml/chm) will only recognize tutorials/extended docs. The file format of tutorials will be in an abbreviated form of docbook, and currently supported as refentry for the top-level tag. This is flexible, and could be changed if people would rather allow article. I chose refentry because it is easy to plug it into the peardoc2 templates of the docbook converter unmodified, and also simple to convert to html. To process the docbook, I elected to avoid any of the more powerful tools out there and just do a basic translation using a version of the parser included with phpDocumentor. It understands <title> for almost all elements, and can do relatively complex conversion of attributes (all role converted to class, for example, or all id="id" attributes converted to a name="id"). It can't yet convert tables because I haven't gotten around to this. If you really want tables in your tutorials, please email right away and it will become a higher priority. itemizedlist and orderedlist is supported to unspecified nesting levels, and so on. I converted the phpDocumentor package-level docs over to the new format and it was very easy. Like package-level docs, the docbook ones would use {@link} and {@tutorial} in favor of <link> <ulink> and <olink> Take care, Greg -- phpDocumentor http://www.phpdoc.org