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
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
document files
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. There's
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.
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 made to skip
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
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 camel?
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
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 junkies
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 subset
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
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
1078
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 complex.
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 write it
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 fingernail
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
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)
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
XML
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 tags,
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 search on
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? ducks
$ grep ^Prop /usr/local/lib/perl5/5.6.0/unicode/Props.txt
does not seem very helpful, but this may not be much of
- 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
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 will not
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
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 think I
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:)
AuthorEliott P. Squibb/Author
MaintainerJoe
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".
I'd rather
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.
Agreeing to
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,
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
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
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 - there's too much
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
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:
41 matches
Mail list logo
