Yesterday, I posted a rant about Docbook, Wikis, and how they're fundamentally different, on the PHP documentation list.
Since the audience of that list is fairly limited, and its participants generally of the same mind, concerning Docbook's virtues, I thought I'd re-post it here for all to see.
I'd like to know your opinion. Especially if you're proficient in Docbook, but disagree with me. ---- There is a recurring idea in the PEAR community that they'll set up a wiki and fix all of the PEARdoc problems. "Don't worry," they say, "we'll write a Docbook exporter for our wiki markup."
I am of the opinion that this is simply impossible without comprimising either 1) Docbook's robustness or 2) Wiki's simplicity
In (1), I think we phpdoc'ers would agree that docbook is robust. It allows very detailed parsing that allows us to generate things like PDF and CHM. It allows us to parse the document tree and determine which extensions exist, constants in said extensions, functions in said extensions, the prototypes for said functions. Docbook is primarily focused on meta-data, and while visual markup is considered in meta-data markup, docbook prefers to remain output-ignorant. Docbook is _not_ what-you-think-is-what-you-get, as Wikis often claim to be. Docbook is extremely structured, by nature.
In (2), Wikis are known (and consequentially popular) for their simplicity. Anyone who's tried to create a *||Multi|Column|Table||* would agree that they're meant for simple markup only (but often have certain "complicated" functionality). Sure, it would be possible to implement wiki-specific markup for things like <classname> and &entities; but for each one, additional wiki syntax would need to be added. Once enough new syntax was added to accomplish similar goals (robust wiki->docbook conversion), you'd have a toolbox that's no simpler than docbook. Wikis are unstructured, by nature.
I believe that anyone who REALLY thinks this should be done has never written a <methodsynopsis> block.
Now, don't get me wrong. I think wikis have a purpose. I even run one for the doc-folk, but IMO, that purpose is NOT documentation.
Docbook isn't magic; it's just XML. Once you get past the mental block of "this is hard", it really isn't.
</rant>
