phpDocumentor/phpDocumentor2 — pull request #625 by boenrobot (2012-09-29 23:36:23+00:00)
Title: Making descriptions parsable [part 1 - structure.xml]

Hi.

I've done what I talked abut at #624, addressing #615 and phpDocumentor/ReflectionDocBlock#23 in the process.

Before we continue with the template updates though, we should probably first agree on the structure.xml format.

As written currently, this adds a separate element for each description, in which there is a "div" under the XHTML namespace, with the full XHTML description being there.

Due to some odd quirk in libxml (at least in PHP 5.3.8, in which I've tested this), there's a "default" prefix on the description elements, and the elements are prefixed with it, rather than there being just an "xmlns" with the div. Still, from XSLT's point of view, it's still non-namespaced description with XHTML namespaced elements inside.

Pros:
- Allows embedding of custom information within the XHTML for templates' sake, rather than having everything resolved at export time.
- SVG, MathML and other stuff like that which may or may not be useful inline.
- Less woes when using XSLT to generate XHTML.

Cons:
- More woes when using XSLT to generate HTML.
- Some "simple" XML parsers might be confused by the stupid prefix.

There's also the option of placing the XHTML namespace at the description element itself (and removing the wrapping div), in which case the prefix is not there.
Pros - all of the above.
Cons:
- Because the description element itself is considered part of the namespace, this creates the awkward situation of people accessing a non-XHTML element as if they were targeting XHTML. In other words, it's just dirty on an XSLT/XPath level.

The last option is obviously no prefix at all, and all XHTML elements being directly in the description, without being wrapped in a div:
Pros:
- No problems with "simple" XML parsers.
Cons:
- None of the above pros.
- More woes when using XSLT to generate *either* HTML or XHTML.