On Sun, Oct 01, 2000 at 09:49:31AM -0500, Frank Tobin wrote:
> Adam Turoff, at 03:22 -0400 on Sun, 1 Oct 2000, wrote:
> > POD has three mighty significant advantages over XML:
> > - it is easy to learn
>
> True, but XML is also easy to learn, and is more in-line with what the
> user will probably already know, as covered in the RFC.
Who needs to learn it, the user or the module author?
The benefit of POD is more focused on the module author, leaving the
use a minorly strange markup language to be read. POD is intended
to be read as-is as a last case measure. Presumably, users will
be reading -man or HTML rendered versions of the docs and can also
read the raw docs pretty easily if need be.
> > - it is easy to write
>
> True, but XML is not hard to write; if you want, you could make a real
> simple DTD with very small tags.
Then you're advocating a small XML DTD, not XML. Advocating raw
XML using a hypothetically small DTD is misleading. Advocating a
hypothetically small DTD and calling it XML is equally misleading.
Two of POD's deficiencies are list handling and table handling. POD
doesn't handle tables right now, but calling this easy to write
or easy to read is ludicrous:
<table>
<tr>
<th>Column 1</th>
<th>Column 2</th>
<th>Column 3</th>
</tr>
<tr>
<td>Item1a</td>
<td>Item1b</td>
<td>Item1c</td>
</td>
<tr>
<td>Item2a</td>
<td>Item2b</td>
<td>Item2c</td>
</td>
</table>
That was [X]HTML. Here's an unordered list in DocBook:
<itemizedlist>
<listitem>
<para>
Element 1
</para>
</listitem>
<listitem>
<para>
Element 2
</para>
</listitem>
<listitem>
<para>
Element 3
</para>
</listitem>
</itemizedlist>
I think POD's list handling is full of warts, but what follows
is much better than HTML/DocBook itemized lists:
=over 4
=item *
Element 1
=item *
Element 2
=item *
Element 3
=back
> > - it is easy to ignore, if you're spelunking for Perl code
> > Try and do that, when <body> interferes with <STDIN> syntactically.
>
> No reason there couldn't be a perl-style delimiter, with __*__.
Perl already understands =foo...=cut.
> > 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'.
>
> I'm not supporting DocBook. The concept of <h1>foo</h1>, I would guess,
> is not that hard to grasp.
And Google has an index of over 1 Billion pages where the semantic
meaning of H1 is most likely ignored.
> Furthermore, the same syntax is used
> consistently throughout the document; there is no separate syntax between
> 'headers' and 'body'.
One of the problems with POD is that it separates block markup from
inline markup.
One of the benefits of POD is that it separates block markup from
inline markup. This is the clearest way of distinguising semantic
structure from presentation. =head1 is not equivalent to <h1>
but rather DocBook's <section><title>...</title> start block.
section tags aren't as easily abused as H1 tags for REEELY BIG LETTERS.
True, C<> and E<> are pretty warty, but they clearly identify
something more presentational in nature.
> As covered, I'm worried POD will continually outgrow it's original design,
> and become messier and messier.
Then help work on a POD-NextGeneration that still adheres to the P
in POD.
> > You must be kidding if you're seriously recommending XHTML as a
> > replacement for POD.
>
> I never stated I specifically supported using XHTML over pod; it was just
> an example of a DTD.
It's also an example of soemthing that's far from small as DTDs go.
> > Moving towards a system that adds any friction to the documentation
> > process is a *>HUGE<* mistake.
>
> If this is a valid argument, then why not just use comments insetad of
> POD? XML does require some more work, granted. But it pays off.
Comments don't provide enough context for embedded documentation. POD
does.
XML creates too much friction compared to the status quo when it
comes to getting authors to write docs. POD *is* the status quo
and therefore isn't adding *more* friction to the process.
Perhaps I should have stated that more clearly.
Z.
