phpDocumentor development update

Hello all, work has slowed slightly, but is going quite well. The peardoc2 templates for the DocBook converter have been written, but are not nearly powerful enough yet. This has been stalled by work on the tutorial parsing. We have gone ahead and implemented a tentative version of the tutorial system based on the previous emails. Any strong ideas on how better to organize things should be voiced soon if you want them in the next release. It should be noted that the use of the term "tutorial" does not require one to write a tutorial. You can write any legal docbook refentry-based document and if properly named and placed in a directory, phpDocumentor will parse and include it in output. You could translate the Count of Monte Cristo into this format, and phpDocumentor wouldn't complain. I don't recommend doing that, as you may get carpal tunnel syndrome ;). The implementation is: all tutorials/ directories are parsed by subdirectory and file name with the following formula: package-level tutorials (tutorials that apply to the entire thing. Introductory or general information should go here) are distinguished by .pkg file extension class-level tutorials (tutorials that apply to single classes. Specific implementation or usage issues should go here) are distinguished by .cls file extension procedural-level tutorials (tutorials for functions/global variables/defines go here) are distinguished by .proc phpDocumentor associates tutorials with packages and subpackages based on their subdirectory. tutorials/foo/ <-- all tutorials in this directory belong to the main package named "foo" tutorials/foo/bar/ <-- all tutorials in this directory belong to the subpackage "bar" of the main package "foo" In addition, phpDocumentor can automatically associate tutorials with elements. The primary tutorial for a package should be named "packagename.pkg," so the package-level documentation for package "foo" will be "tutorials/foo/foo.pkg." Note that this is designed to replace the old package-level docs foo.html. This new design also allowed sub-package level docs "tutorials/foo/bar/bar.pkg" The primary tutorial for a class should be named "tutorials/packagename/classname.cls" where classname is the name of the class (duh), and packagename is the package the class is found in. For procedural, the best I can come up with is giving it the filename, so "tutorials/packagename/file.php.proc" would be the tutorial. Anyone with a better idea please contact me. One of the nice things about peardoc is the ability to chain related files together, so that generated HTML (for example) has nice "next" and "prev" buttons. This capacity will also be included, but I am not sure what the best way to do this might be. All ideas are appreciated. Some that I'm entertaining include: -have a file named "tutorials/package/package.pkg.extras" with the ordering of other tutorials that should be linked to the main tutorial "package.pkg" -parse &package.blah ids from the main tutorial file, allowing 100% peardoc2 Either way, phpDocumentor will be able to generate the format peardoc2 is expecting easily, as well as make nice chained-together docs for the other converters. In cvs, the parsing and conversion of all tutorials is now implemented for the HTMLframesConverter, and it is smart enough to find the main package-level and subpackage-level documentation, but more work needs to be done. linking to tutorials via @tutorial and the inline {@tutorial} has been implemented as well, with the suggested URI-like format package/subpackage/tutorial.ext#section.subsection syntax. Sample output from the new phpedit-based template is at http://www.joshuaeichorn.com/~CelloG/out for those who want to see a current cvs parse of phpDocumentor to see what we're up to. As things get developed, this output will change and show the state of affairs. Take care, Greg -- phpDocumentor http://www.phpdoc.org