From: Jonathan Scott Duff [mailto:[EMAIL PROTECTED]]
>
> 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
>
> I'll just add my voice to the others. POD is more readable than XML.
> As Nathan Wiger said, just read the HTML vs the POD for the RFCs.
XML is not HTML. Someone could make DTD which defines XML elements using the
pod =commands. Then again, if you're using XML, why not have it keep track
of nested =head and get rid of =over and =back?
Some arguments for XML:
- Done right, it could be easier to write and maintain
- Why make people learn pod, when everyone's learning XML?
- Pod can be translated into XML and vice versa
- Standard elements could be defined and utilized with the
same or greater ease than pod for build and configuration.
</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>
> But, why not suggest SDF instead of XML? SDF addresses most of POD's
> deficiencies whill still retaining readability. (I don't have a URL
> for SDF handy, but I'm sure a quick search on google.com would turn it
> up)
http://www.mincom.com/mtr/sdf/
Why change anything at all? POD is good enough. Sure, it requires a
learning curve... but it is a small one. I'd never heard of SDF until you
mentioned it, but there's the "everyone else is doing it" argument form XML.
And XML/DocBook does look set to be the lingua franca documentation format.
In the end, all that I'd like to see is the ability to churn out DocBook
documentation from whatever intermediary notation is used. That doesn't
require changing anything, just adding a new pod2docbook tool. So while I
"like" the idea of adopting XML as an addition to POD... There's no driving
need that it fulfills.
Garrett
