On Sun, Oct 01, 2000 at 06:34:12AM -0000, Perl6 RFC Librarian wrote:
> =head1 TITLE
>
> Perl should use XML for documentation instead of POD
No, it shouldn't. And I say that as an XML Evangelist.
> =head1 ABSTRACT
>
> Perl documentation should move to using XML as the formatting language,
> instead of using POD. XML has many advantages over POD, and would
> address several problems POD is reaching as it expands beyond its
> original designs.
POD has three mighty significant advantages over XML:
- it is easy to learn
- it is to write
- it is easy to ignore, if you're spelunking for Perl code
Try and do that, when <body> interferes with <STDIN> syntactically.
DocBook, my doctype of choice, comes with a handy-dandy 600 page reference.
Terms like %qandaset.mix; and "entity reference" are far from easy to
understand to the beginner. Especially when compared to '=head1' and
'=head2'.
> =head1 DESCRIPTION
>
> However, POD can be confusing to learn, and has many limitations.
These are deficiencies in the POD language definition and the POD
toolchain. It can be fixed by tweaking the definition of POD
and writing better tools. It's not a reason to throw out POD
entirely because something more hyped is available to replace it.
> XML, on
> the other hand, is a document language that is designed for high
> extensibility, and little ambiguity. XML is flexible, relying on Document
> Type Definitions, DTD's, (recently, also XML Schemas), which define the
> document structure being used by the author. For example, a copy of the
> DTD for XHTML may be found at
> C<http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd>.
You must be kidding if you're seriously recommending XHTML as a
replacement for POD.
POD has many flaws (and I'd list them if I had the time right now),
but at the very least it provides a modicum of structural markup.
Moving to XHTML is one huge step backwards, because it is presentational
markup instead of structural markup. XHTML+CSS as a structural
model is a sick joke.
Moving to any XML based markup today should make it stupidly easy
to target DocBook and DockBook's structural model directly. And it
should do so with a minimum of pain to the author.
> Knowledge of how to
> write or work with DTD's is not necessary for an XML-author; the author
> need only know the effect of the DTD or XML Schema.
[...]
> POD has the advantage in that it has syntax that is quick and easy
> to type, such as CE<lt>$var++E<gt> instead of an XML/XHTML
> E<lt>codeE<gt>var++E<lt>codeE<gt>.
>
> However, author effort pays off immensely on the reader's end.
Moving towards a system that adds any friction to the documentation
process is a *>HUGE<* mistake.
XML adds more friction to the authoring process by refusing malformed
documents, while POD complains and muddles forward, typically
formatting them poorly but still rendering.
Increasing author effort may make for more beautiful documentation
for the reader, but it also inhibits authoring content in the first
place. It's quite possible that switching to an XML docset produces
a beautiful, unmaintained set of documentation that is of no use
to anyone.
The answer is to fix POD, fix the tools, not to use XML.
Z.
