The class synopsis XML source has a little bit of redundancy built into it:
<classsynopsis>
<ooclass><classname>Imagick</classname></ooclass>
<classsynopsisinfo>
<ooclass><classname>Imagick</classname></ooclass>
<oointerface>
<interfacename>Iterator</interfacename>
</oointerface>
<oointerface>
<interfacename>Traversable</interfacename>
</oointerface>
</classsynopsisinfo>
In particular, ooclass is duplicated in two different contexts. The
docbook specification defines classsynopsisinfo to be supplemental
verbatim non-meta information for classsynopsisinfo
<http://www.docbook.org/tdg/en/html/classsynopsisinfo.html>, whereas
classsynopsis is a semantic syntax summary.
<http://www.docbook.org/tdg/en/html/classsynopsis.html>
HOWEVER, the current version of PhD utilizes the classsynopsis info to
generate the PHP-style class synopsis, to the point where the required
ooclass outside of classsynopsisinfo is auxiliary. (Notice how
ImagickPixelIterator is sort of just hanging out in its white box).
My vision of the class synopsis has this extra Imagick removed, however,
we cannot achieve this on the markup level without breaking the content
model for classsynopsis (as mentioned above ooclass or a similar tag is
required):
classsynopsis ::=
((ooclass|oointerface|ooexception)+,
(classsynopsisinfo|fieldsynopsis|constructorsynopsis|
destructorsynopsis|methodsynopsis)*)
This leaves us with two choices:
1. Maintain the redundancy, instructing PhD to hide the redundant
declaration or rewrite it into some form that doesn't look like it's
just there for the ride. This adheres to the philosophy of fixing layout
problems at the markup level.
2. Delete the ooclass inside classsynopsisinfo, removing the redundancy,
and then when constructing the PHP-style Class Synopsis automagically
find the data from the previous ooclass metadata (the corresponding
temporary variable probably could be used for the original problem.)
This philosophy is that the XML source should be as minimal as possible,
and make the generation layer do the heavy lifting.
I personally prefer choice 2, but I realize Hannes has stated that he
prefers fixing things at the markup level (it's probably faster to do
things that way too).
Some other markup questions I'd like to field:
1. On the subject of meta and non-meta data in Docbook, information
placed directly in classsynopsis is meant to model the OOP, while
classsynopsisinfo is verbatim. The implication is that we should be able
to do neat meta-analysis on classsynopsis data, such as "All classes
implementing this interface" or "Classes extended from this class".
Understandably, this isn't very common in PHP core code, but it's a
thought. (Next up, dependency graphs! (Joking: That would probably be
feature creep.))
2. The RFC document describes a custom namespace for performing
inclusion. Will this be used to compact the currently quite verbose
XInclude declarations for properties/methods/inherited methods? As far
as I can tell, the only necessary information to pass is
class.classname/class.baseclassname which, in theory, can be derived
from earlier declarations in classsynopsis. That may be a little too
magical, though.
3. The plain HTML output of the class synopsis looks quite ugly, because
there is no indentation, coloring, etc. We may want to consider having a
simple, default style for these output formats. It could be a module of
the larger PHP.net style, in that the phpweb theme uses both the simple
HTML style and the PHP.net style, while chunkedhtml/bightml only uses
the simple HTML style.
4. Should we also compact the method links in Table of Contents?
--
Edward Z. Yang GnuPG: 0x869C48DA
HTML Purifier <http://htmlpurifier.org> Anti-XSS Filter
[[ 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA ]]
