> 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:
[horrendous XHTML and DocBook notations deleted]
> I think POD's list handling is full of warts, but what follows
> is much better than HTML/DocBook itemized lists:
[wonderously beautiful POD deleted]
> 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.
I'll just throw my $.02 in and support Ziggy, David, John, and all the
other silent majority members completely. The simple proof that POD is
far superior is that you can read the RFC's on this list in POD without
too much trouble. Try reading the source code of the HTML versions of
the RFC's. Bleech.
I'd much rather write:
=head1 ABSTRACT
This RFC proposes ...
Than:
<HR>
<H1><A NAME="ABSTRACT">ABSTRACT</A></H1>
<P>
This RFC proposes ...
Any day of the week.
SGML and its descendants are a whole nasty can of worms with a steep
learning curve. Making documentation any harder is just going to result
in less documentation with more mistakes, especially for CPAN modules.
> True, C<> and E<> are pretty warty, but they clearly identify
> something more presentational in nature.
Yes, this is true. I think it's pretty apparent that the <> syntax is
broken - there's too much stuff (like -> and <>) that uses duplicate
characters. This could be solved if escapes worked:
C<foo-\>bar>
But that's still nasty. Maybe plain ol' braces would work better:
C{ foo-> bar }
Since not many people seem to use braces inline anyways, and if you do,
there's got to be an opening one first:
C{ if ($stuff) { ... } }
So they can easily and reliably nest. Sure makes these more readable:
C{print while (<>);}
C{die if $x > 5;}
C{my $foo = bar->baz;}
I might RFC this later in the process towards the documentation end of
things.
-Nate
