Nuno Lopes wrote:
It allows a 'normal' user to see a manual in html, pdf, ..., but it
builds all that off-line. In the display area, I think livedocs is better.
In the edit mode, it allows an editor to edit a file in text, xml, html
or Latex mode. This can be good if a translator doesn't know how to work
with xml, and is an expert in one of the others. The program will then
convert the edited text into docbook.
Thanks for confirming my exact thoughts on Wiki->Docbook conversion.
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>
S
