Re: RFC 357 (v1) Perl should use XML for documentation instead of POD

[Russ Allbery]

Garrett Goebel <[EMAIL PROTECTED]> writes:

> </pod>
>   <Name>Module::Name</Name>
>   <Version>0.01</Version>
>   <Synopsis>short description</Synopsis>
>   <Description>
>     <name>=head1 long description</name>
>     <section>
>       <name>=head2 heading</name>
>       <list type="ordered" symbol="1">
>         <item>foo</item>
>       </list>
>       Type in some text here...
>     </section>
>   </Description>
>   <Author>Eliott P. Squibb</Author>
>   <Maintainer>Joe Blogg</Author>
>   <Bugs>none</Bugs>
>   <Copyright>Distributed under same terms as Perl</Copyright>
>   <section>
>     <name>define your own section</name>
>     blab here
>   </section>
> </pod>

Wow, that's completely unreadable.  That's more unreadable than *roff.

(This is due to the fundamental flaw in SGML syntax, namely that at a
glance it's impossible to distinguish the tags from the content because
the delimiters are horribly constructed and you need too many tags.  This
is a fundamental flaw in the entire way that SGML syntax was designed, and
I don't think it's possible to fix.  As far as I'm concerned, *any*
SGML-derived markup language is write-only and usable only as an output
format.  It's slightly more readable than PostScript, and that's about all
I can say for it.)

-- 
Russ Allbery ([EMAIL PROTECTED])             <http://www.eyrie.org/~eagle/>