This and other RFCs are available on the web at
http://dev.perl.org/rfc/
=head1 TITLE
Perl should use XML for documentation instead of POD
=head1 VERSION
Maintainer: Frank Tobin <[EMAIL PROTECTED]>
Date: 30 Sep 2000
Mailing List: [EMAIL PROTECTED]
Number: 357
Version: 1
Status: D
On Sun, Oct 01, 2000 at 06:34:12AM -, 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,
>
Realize that you are trying to convince a group who uses POD at the command
line (no, not everybody) to use a complete markup language. We're talking about
self-commenting code, sir, not a strict documentation system with indices and
the likes in any formal sense. Even if a documentation system
Frank Tobin wrote:
>
> As covered, I'm worried POD will continually outgrow its original design,
> and become messier and messier.
I'd be interested to know what has caused you to be concerned about this.
>From what I can tell, the pod spec itself has changed very little over
the years; only the
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 proba
> 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 be
Nathan Wiger writes:
> > 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 c
On Sun, Oct 01, 2000 at 02:30:39PM -0600, Nathan Torkington wrote:
> Nathan Wiger writes:
> > > 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 - t
Nicholas Clark wrote:
>
> No-one ever did suggest adding « and » to the list of matched delimiters
> that q() etc support, did they? :-)
Yes, Larry did. Though not here, not recently.
Sorry I don't have a reference.
--
John Porter
On Sun, Oct 01, 2000 at 03:39:51PM -0400, Adam Turoff wrote:
> I think POD's list handling is full of warts, but what follows
> is much better than HTML/DocBook itemized lists:
For me, they're about the same.
Actually, I'd rather read an XHTML/HTML itemized list than a POD one;
they both look ug
On Sun, Oct 01, 2000 at 06:34:12AM -, Perl6 RFC Librarian wrote:
> =head1 TITLE
>
> Perl should use XML for documentation instead of POD
Wow.
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.
But, why
On Mon, 2 Oct 2000 08:29:09 -0500, Jonathan Scott Duff wrote:
>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://w
From: Jonathan Scott Duff [mailto:[EMAIL PROTECTED]]
>
> On Sun, Oct 01, 2000 at 06:34:12AM -, 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
Damien Neil wrote:
> Having said that, I'm not fond of writing XML/HTML by hand. I'd far
> rather write an author-friendly language and have that translated to
> XML.
Indeed, this is the key problem with human use of XML. HTML was originally
simple enough to be human writable, its later, more
On Mon, Oct 02, 2000 at 09:21:51AM -0700, Glenn Linderman wrote:
> Indeed, this is the key problem with human use of XML. HTML was originally
> simple enough to be human writable, its later, more powerful incarnations
> start losing that (but you can always use a subset for simple things, and
> X
On Mon, 2 Oct 2000 10:51:28 -0700, Damien Neil wrote:
>> XML never had human writable simplicity and never will.
>
>XML is intrinsically no more or less difficult to write than HTML.
The problem with XML is that it is so unforgiving; I think somebody
already mentioned that. Improperly nested tag
At 03:53 PM 10/2/00 +0200, Bart Lateur wrote:
>On Mon, 2 Oct 2000 08:29:09 -0500, Jonathan Scott Duff wrote:
>
> >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 sea
Garrett Goebel <[EMAIL PROTECTED]> writes:
>
> Module::Name
> 0.01
> short description
>
> =head1 long description
>
> =head2 heading
>
> foo
>
> Type in some text here...
>
>
> Eliott P. Squibb
> Joe Blogg
> none
> Distributed
On Mon, Oct 02, 2000 at 07:56:45PM +0200, Bart Lateur wrote:
> On Mon, 2 Oct 2000 10:51:28 -0700, Damien Neil wrote:
>
> >> XML never had human writable simplicity and never will.
> >
> >XML is intrinsically no more or less difficult to write than HTML.
>
> The problem with XML is that it is so
>No-one ever did suggest adding « and » to the list of matched delimiters
>that q() etc support, did they? :-)
I did.
>Does Unicode define bracket pairings for character sets?
$ grep ^Prop /usr/local/lib/perl5/5.6.0/unicode/Props.txt
does not seem very helpful, but this may not be much of a p
>- Done right, it could be easier to write and maintain
Strongly disagree.
>- Why make people learn pod, when everyone's learning XML?
Because it is simple. It is supposed to be simple.
It is not supposed to do what you want to do.
In fact, it is suppose to NOT DO what you want to do.
>- Pod
>XML is intrinsically no more or less difficult to write than HTML.
Wrong.
>Comparing XML to HTML is pointless, however; they are not the same
>thing.
Wrong. And you only say that because you will not like the answer.
Go back to the posted example and count bytes of data versus
bytes of met
>The problem with XML is that it is so unforgiving;
No, the problem is verbosity.
''tom
On Mon, Oct 02, 2000 at 01:24:37PM -0600, Tom Christiansen wrote:
> >XML is intrinsically no more or less difficult to write than HTML.
>
> Wrong.
I beg your pardon?
> >Comparing XML to HTML is pointless, however; they are not the same
> >thing.
>
> Wrong. And you only say that because you
Jonathan Scott Duff <[EMAIL PROTECTED]> writes:
> I'll just add my voice to the others. POD is more readable than XML.
Don't forget: more _writable_ as well.
-- Johan
From: Tom Christiansen [mailto:[EMAIL PROTECTED]]
>
> >- Done right, it could be easier to write and maintain
>
> Strongly disagree.
Ok, you disagree. There are differing opinions here. Can we agree to
disagree? Or must all people who believe XML is easier to write and maintain
leave the room?
Garrett Goebel (Today):
> Horror of horrors: why not support both? Long live: TMTOWTDI. If XML
> documentation fails to thrive, cut it from Perl 6.1. If both thrive, keep
> 'em. As everyone has said XML can be converted to pod and vice versa. Pod
> tools could be made to coexist with XML.
But why
On Mon, Oct 02, 2000 at 02:44:56PM -0600, John Barnette wrote:
> But why extend the syntax for such a niche application?
>
> * POD can be easily converted to XML.
> * POD can contain XML.
> * Advanced concepts that POD cannot contain that the XML junkies
> might want to
> > same or greater ease than pod for build and configuration.
> >
> > >
> [...]
> > >
> >
> > That is an excellent description of why THIS IS COMPLETE
> > MADNESS.
Maybe I'm reading too much into the comment, but I thought the big deal was
that the example given was not only verbose, but w
On 10/2/00 4:44 PM, John Barnette wrote:
> * Advanced concepts that POD cannot contain that the XML junkies
> might want to be used can be embedded. (=for XML)
Yeah, but then you get =for HTML, =for XML, =for 3DHOLOGRAM, whatever. No
one does that because no one wants to make 50 versions of the
On Mon, 2 Oct 2000 13:54:47 -0400, Tad McClellan wrote:
>> Improperly nested tags, or one character it
>> doesn't recognize... and the parser says "nyet".
>
>I read that as "the machine will tell me when I messed up".
>
>I'd rather have a machine tell me than have to figure it
>out myself. I thin
From: Myers, Dirk [mailto:[EMAIL PROTECTED]]
>
> Maybe I'm reading too much into the comment, but I thought
> the big deal was that the example given was not only
> verbose, but wouldn't parse correctly:
>
> (from the section you elided:)
>
> > > > Eliott P. Squibb
> > > > Joe Blogg
>
> Who
On Mon, Oct 02, 2000 at 10:59:46PM +0200, Bart Lateur wrote:
> On Mon, 2 Oct 2000 13:54:47 -0400, Tad McClellan wrote:
>
> >> Improperly nested tags, or one character it
> >> doesn't recognize... and the parser says "nyet".
> >
> >I read that as "the machine will tell me when I messed up".
> >
>
On Mon, Oct 02, 2000 at 03:36:20PM -0500, Garrett Goebel wrote:
> From: Tom Christiansen [mailto:[EMAIL PROTECTED]]
> > >- Done right, it could be easier to write and maintain
> >
> > Strongly disagree.
>
> Ok, you disagree. There are differing opinions here. Can we agree to
> disagree?
No.
A
Nicholas Clark wrote:
> On Mon, Oct 02, 2000 at 02:44:56PM -0600, John Barnette wrote:
> > But why extend the syntax for such a niche application?
> >
> > * POD can be easily converted to XML.
> > * POD can contain XML.
> > * Advanced concepts that POD cannot contain that the XML junk
On Mon, Oct 02, 2000 at 01:22:47PM -0600, Tom Christiansen wrote:
> > Eliott P. Squibb
> > Joe Blogg
>
> That is an excellent description of why THIS IS COMPLETE
> MADNESS.
It also shows how easy it is to get wrong
Graham.
On Mon, Oct 02, 2000 at 12:58:37PM -0700, Damien Neil wrote:
> What? I don't think people should be writing either XML or HTML
> as the source documentation format. I said that, quite clearly.
Then what are they going to write it in ? And don't tell me to get
some fangle dangled editor. Which w
John Siracusa wrote:
>
> POD is supposed
> to be the common format that can be transformed into other representations.
> Instead, you have to add the different representations yourself if you do
> anything remotely complex.
No, POD is supposed to be simple. It addresses a very small, common sub
At 10:59 03/10/2000 -0400, John Porter wrote:
>Complex things should not be done in POD.
Indeed. This debate has been done to death. Have any of the would-be
pod-killers read the thread at
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1999-08/thrd11.html#0
1078 ? The thread eventually di
Garrett Goebel wrote:
>
> Some arguments for XML:
>
> - Done right, it could be easier to write and maintain
Pod is already "done right", and it's already spectacularly
easy to write and maintain. XML is a hammer in search of nail.
> - Why make people learn pod, when everyone's learning XML?
Robin Berjon wrote:
> At 10:59 03/10/2000 -0400, John Porter wrote:
> >Complex things should not be done in POD.
>
> Indeed. This debate has been done to death. Have any of the would-be
> pod-killers read the thread at
> http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/1999-08/thrd11.html#0
John Siracusa wrote:
> On 10/3/00 10:59 AM, John Porter wrote:
>
> > If you add (e.g.) support for tables, then pod is only translatable
> > into languages which also support tables.
>
> What languages *don't* support tables?
I knew that was a bad example of my point. Think of something compl
On Tue, Oct 03, 2000 at 03:42:49PM +0100, Graham Barr wrote:
> On Mon, Oct 02, 2000 at 12:58:37PM -0700, Damien Neil wrote:
> > What? I don't think people should be writing either XML or HTML
> > as the source documentation format. I said that, quite clearly.
>
> Then what are they going to wri
John Siracusa wrote:
>
> Tables are my personal peeve, but I'm sure you can think of many more common
> documentation features that POD should support natively. Hypertext is
> another example, off the top of my head.
I agree that pod could support these thing better. I believe it will,
and it
From: Peter Scott [mailto:[EMAIL PROTECTED]]
>
> As I said earlier, why don't we just define a syntax for
> *anything* to be used as an extension language, and let
> the, er, market decide?
Here, here!
Peaceful coexistance... what a concept.
> > Some arguments for XML:
> >
> > - Done right, it could be easier to write and maintain
> Pod is already "done right", and it's already spectacularly
> easy to write and maintain. XML is a hammer in search of nail.
Actually, a better analogy would be a its a sledge hammer
in search of a fin
>POD, presumably. Or maybe son-of-POD; it would be nice to have better
>support for tables and lists.
We did this for the camel. Which, I remind the world, was
written in pod.
''tom
On Wed, 04 Oct 2000 03:15:22 -0600, Tom Christiansen wrote:
>We did this for the camel. Which, I remind the world, was
>written in pod.
You, masochist.
(duck, and run)
--
Bart.
Garrett Goebel wrote:
> From: Peter Scott [mailto:[EMAIL PROTECTED]]
> >
> > As I said earlier, why don't we just define a syntax for
> > *anything* to be used as an extension language, and let
> > the, er, market decide?
>
> Peaceful coexistance... what a concept.
Sounds to me like the real i
On Wednesday, October 04, 2000 4:15 AM, Tom Christiansen
[SMTP:[EMAIL PROTECTED]] wrote:
> >POD, presumably. Or maybe son-of-POD; it would be nice to have better
> >support for tables and lists.
>
> We did this for the camel. Which, I remind the world, was
> written in pod.
>
> ''tom
Uh...
w
On 2 Oct 2000, at 21:04, Adam Turoff wrote:
> If you want to use XML, Latex, Texinfo or raw *roff for your docs,
> then by all means do so. Understand that Perl can't be made to
> magically ignore embedded Texinfo, and Perl contributors realistically
> can't be made to understand/patch/correct m
On Wed, Oct 04, 2000 at 03:15:22AM -0600, Tom Christiansen wrote:
> >POD, presumably. Or maybe son-of-POD; it would be nice to have better
> >support for tables and lists.
>
> We did this for the camel. Which, I remind the world, was
> written in pod.
What kinds of things got added for the c
Philip Newton wrote:
>
> I'm not sure that this bit of the third quoted paragraphs is correct:
> "It's quite possible that switching to an XML docset produces a beautiful,
> unmaintained set of documentation that is of no use to anyone." I think
> it's more likely that switching to an XML docset
David Grove <[EMAIL PROTECTED]> writes:
> > We did this for the camel. Which, I remind the world, was
> > written in pod.
>
> seriously, that impresses me.
POD is not suitable for producing books. It can be used, however, to
provide the information that a (human) typesetter can turn into a
pr
On 04 Oct 2000 18:43:43 +0200, Johan Vromans wrote:
>POD is not suitable for producing books. It can be used, however, to
>provide the information that a (human) typesetter can turn into a
>printed book.
If a typesetter knows enough with just the POD, it is possible to
completely typeset the en
On 4 Oct 2000, at 14:06, John Porter wrote:
> I am of the opinion that any documentation which requires, or at least
> would significantly benefit from, the use of something heavy like SGML
> is best done OUTSIDE THE CODE. There's no reason you can't have
> document files accompanying the perl
Philip Newton wrote:
> On 4 Oct 2000, at 14:06, John Porter wrote:
>
> > I am of the opinion that any documentation which requires, or at least
> > would significantly benefit from, the use of something heavy like SGML
> > is best done OUTSIDE THE CODE. There's no reason you can't have
> > docum
Bart Lateur <[EMAIL PROTECTED]> writes:
> On 04 Oct 2000 18:43:43 +0200, Johan Vromans wrote:
>
> >POD is not suitable for producing books. It can be used, however, to
> >provide the information that a (human) typesetter can turn into a
> >printed book.
>
> If a typesetter knows enough with ju
Philip Newton wrote:
> If the pod (or whatever) is in a
> separate file, this advantage is lost.
Of course; I'd *never* say that there should be NO documentation
in the perl code file. That would be absurd.
--
John Porter
By pressing down a special key It plays a little melody
On Thu, Oct 05, 2000 at 11:47:46AM +0200, Philip Newton wrote:
> On 4 Oct 2000, at 14:06, John Porter wrote:
>
> > I am of the opinion that any documentation which requires, or at least
> > would significantly benefit from, the use of something heavy like SGML
> > is best done OUTSIDE THE CODE.
It's time for the XML vs POD discussion to end. The RFCs are in
limbo now, and this conversation is serving no visible purpose.
Thanks,
Nat
At 12:01 PM 10/3/00 -0400, John Porter wrote:
>How would you down-convert a complex math formula to ascii from, say, xhtml?
>
>You know, I'm thinking TeX would make a great extension language for pod.
>Simple, powerful, text-based, with translators to lots of other formats,
>and good tool support
I'd be all for the XML documentation idea, either as a replacement
for or as a substitute for POD. However, I'd like to note that if you
want XML documentation in your Perl code, POD really makes it easy:
=for XML (or DocBook, or whatever)
Simply require yourself to use only POD sections lik
We must not forget that pod has one other requirement, which pure
embedded XML would violate: namely, perl (that's the perl interpreter)
must be able to detect and skip over pod sections very quickly.
It would be very detrimental to perl's performance to have to do an
XML parse of every input sour
On Sun, Oct 01, 2000 at 02:00:20PM -0500, J. David Blackstone wrote:
> While POD hasn't changed for several years, the QA group has a
> couple of ideas in the works to morph it in desireable ways that might
> be easier if POD were replaced with an XML DTD.
^
From: John Porter [mailto:[EMAIL PROTECTED]]
>
> It would be very detrimental to perl's performance to have to do an
> XML parse of every input source file.
if the parser can skip between:
=pod
=cut
it can certainly be made to skip between:
On 2 Oct 2000, at 10:35, Garrett Goebel wrote:
> From: John Porter [mailto:[EMAIL PROTECTED]]
> >
> > It would be very detrimental to perl's performance to have to do an
> > XML parse of every input source file.
>
> if the parser can skip between:
>
> =pod
>
> =cut
>
> it can certainly be m
67 matches
Mail list logo
