[prev in list] [next in list] [prev in thread] [next in thread] 

List:       pear-doc
Subject:    update: phpDocumentor development
From:       "Greg Beaver" <greg () chiaraquartet ! net>
Date:       2002-12-16 7:22:20
[Download RAW message or body]

Hello all,

It's been a slower week than last due to exams on Josh's part and some major
concerts on my part, but we managed to get the groundwork laid for a complex
tutorial/manual system.

The requests we've had for linking to external documentation, and to link to
a specific part of external documentation has been answered.  In our quest
to make phpDocumentor multiple output format-capable, we have implemented a
system of parsing external documentation in docbook format as I described in
an earlier post.  external documentation is associated with API
documentation via package and subpackage.  There are three kinds of external
documentation supported: package- and subpackage-level, class-level, and
procedural-level.  Class and Procedural-evel documentation will be attached
to API elements via the filename of the documentation.  If it a
tutorial/manual file is in directory
packagename/subpackagename/classname.cls and there is a class in package
packagename, subpackage subpackagename named "classname," the tutorial and
the class will be linked so that the Converter can do whatever final output
is needed to link them together.  Very soon, we will have an online example
of this kind of documentation.

To remain flexible, documentation may be spread across several different
files.  phpDocumentor makes this convenient by providing both links in the
left-hand side of the screen (for HTML converters) and next/prev/up links
(for HTML Converters) similar to the php manual.  The PDF Converter will use
this information to generate a hierarchical table of contents.  The use of
an external .ini file to specify tutorial file order and hierarchy maintains
easy order switching without modifying any package-level documentation.
These choices also make it very easy to write high-quality documentation for
peardoc2 without worrying about order - the order of files can be switched
without having to touch the entities that determine this order (they are
automatically generated by the peardoc2 template of the DocBook converter).

The output format of tutorial/manual files has been greatly improved by the
addition of a template file in which the output is fit into.  In this way,
special formatting instructions can be specified to allow prettier output
for those who need it.  By default, the tutorial/manual files will use the
same stylesheet as the API docs to keep a consistent look across the project
documentation.  This is a major upgrade in appearance over 1.1.0's
package-level documentation.

This style of external documentation will also easily allow the creation of
special extended converters that only output tutorial/manual documentation,
as requested by one user (this has not yet been added, but will be).

sample output from the new phpedit template is available at
http://www.joshuaeichorn.com/~CelloG/out and is updated nearly every day
based on the current cvs build.

Thanks for all of your input, it's been very helpful.

Take care,
Greg



[prev in list] [next in list] [prev in thread] [next in thread]