Re: phpDocumentor tutorials/extended documentation implementation

After a few suggestions, I'm thinking the best way to do @tutorial is more like a URI: @tutorial package/subpackage/tutorial.ext#section.subsection Any opinions? Greg -- phpDocumentor http://www.phpdoc.org "Greg Beaver" <greg@chiaraquartet.net> wrote in message news:20021211003027.4801.qmail@pb1.pair.com... > 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 > >