Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 code files, for gosh sakes. I disagree slightly. One of the benefits of Pod is that it can be intermingled with Perl code; there's no need to have it be all in one piece. This can be used to good advantage by having the pod for each function be places just above that function, thus simultaneously helping to document the code. If the pod (or whatever) is in a separate file, this advantage is lost. However, I don't think this is necessarily a strong reason against abandoning pod if there are other advantages to other solutions; I just think it should be kept in mind. Cheers, Philip -- Philip Newton [EMAIL PROTECTED] I appreciate copies of replies to my messages to Perl6 lists.
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 accompanying the perl code files, for gosh sakes. I disagree slightly. One of the benefits of Pod is that it can be intermingled with Perl code; [snip] why not just use a literate programming tool like noweb? this allows you to document right next to your code. it allows you (currently) to use latex or html (might be simple to extend to sgml and xml). it allows you to rearrange your code in a more explainable order. Mark-Jason Dominus wrote an article on perl.com explaining why pod is not a literate programming tool. people seem to want a super-funky documentation tool. they _already_ exist, and there is no reason to change perl, let someone else do the dirty work. peter -- I'm free to speak my mind anywhere And I'll never mind anywhere Anywhere I roam Where I lay my head is home -- "Wherever I May Roam" Metallica
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
Peter Scott wrote: nor is any author obliged to include ideas he/she doesn't agree with; that's why others can (or could) submit RFCs that contradict it, if they want to. The author is no more obliged to include opposing opinions in their RFC than the proposer of a bill in the House is required to include contrary views. No, that's *wrong*. RFCs are written to help Larry review the issues, and present some new ones. Much knowledge (for lack of better term) comes out of the lengthy email discussions; we do him a great disservice by not summarizing it in the relevant RFC. (Remember, the author of an RFC is not simply its champion; he is called its "maintainer".) So it would be better for Larry to see the arguments against a proposal in an appendix of that RFC, than to have to hunt for other RFC's which might contradict it. Not every harebrained RFC needs to be met by a contradicting RFC. That leads (and has lead many times already) to RFC bloat. RFCs like "330: Global dynamic variables should remain the default" should not need to be written! (No disrespect to you, Nate.) the idea is to be an extension of Larry's creative thinking process. Neither of us is deciding what goes into Perl 6, and neither is the community - I hope. Larry is. Uh, then why did Larry say "perl 5 was my rewrite, perl 6 is the community's rewrite"? Clearly he does not think of himself as the community. He has said it: this is *our* rewrite. -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
On Thu, Oct 05, 2000 at 01:38:18PM -0400, Dan Sugalski wrote: Perl 6 is going to be the community's rewrite. His design to start, but the community's rewrite. (The alternative is to have the thing be *my* rewrite, and I don't think we want that... :) Will no preprocessor symbols defined the main source will compile perfectly on VMS, the vms/ subdirectory will go, replaced with unix/ and there will be lots of ported bits wrapped with #ifdef (UNIX) #endif You might even get approval from some prominent non-VMS fans provided there's a linux/ directory that only contains instructions on how to install BSD Nicholas Clark
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
At 01:38 PM 10/5/00 -0400, Dan Sugalski wrote: On Thu, 5 Oct 2000, John Porter wrote: Peter Scott wrote: the idea is to be an extension of Larry's creative thinking process. Neither of us is deciding what goes into Perl 6, and neither is the community - I hope. Larry is. Uh, then why did Larry say "perl 5 was my rewrite, perl 6 is the community's rewrite"? Clearly he does not think of himself as the community. He has said it: this is *our* rewrite. Perl 6 is going to be the community's rewrite. His design to start, but the community's rewrite. 'rewrite' is not the same as 'design', fortunately. I fervently hope that the language design will be the product only of ideas Larry either came up with or agreed with; if we get into some voting scenario, that spells doom. May I point out that COBOL was designed by a committee. See http://dev.perl.org/rfc/meta/larry-1.txt and http://dev.perl.org/rfc/meta/larry-3.txt for some reassurance in this regard though. -- Peter Scott Pacific Systems Design Technologies
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
At 11:08 AM 10/5/00 -0700, Peter Scott wrote: At 01:38 PM 10/5/00 -0400, Dan Sugalski wrote: On Thu, 5 Oct 2000, John Porter wrote: Peter Scott wrote: the idea is to be an extension of Larry's creative thinking process. Neither of us is deciding what goes into Perl 6, and neither is the community - I hope. Larry is. Uh, then why did Larry say "perl 5 was my rewrite, perl 6 is the community's rewrite"? Clearly he does not think of himself as the community. He has said it: this is *our* rewrite. Perl 6 is going to be the community's rewrite. His design to start, but the community's rewrite. 'rewrite' is not the same as 'design', fortunately. I fervently hope that the language design will be the product only of ideas Larry either came up with or agreed with; if we get into some voting scenario, that spells doom. May I point out that COBOL was designed by a committee. I'm not sure I'd really hold COBOL up as a bad example--for all that people loathe it (and I really dislike it myself) it does what it's supposed to do rather well, and it is an *old* language, predating 95% of the current art. (Heck, it spawned a good chunk of the current art) Anyway, at some point I expect the language design will get handed off to someone else. That's what's happened already with perl 5--the current pumpking is responsible for changes in the language. Granted they're not huge changes, but they are changes, for better or worse. Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
At 06:40 PM 10/5/00 +0100, Nicholas Clark wrote: On Thu, Oct 05, 2000 at 01:38:18PM -0400, Dan Sugalski wrote: Perl 6 is going to be the community's rewrite. His design to start, but the community's rewrite. (The alternative is to have the thing be *my* rewrite, and I don't think we want that... :) With no preprocessor symbols defined the main source will compile perfectly on VMS, the vms/ subdirectory will go, replaced with unix/ and there will be lots of ported bits wrapped with #ifdef (UNIX) #endif Nah, nothing that obvious. The capabilities of VMS 7.2 will just be the default... :) You might even get approval from some prominent non-VMS fans provided there's a linux/ directory that only contains instructions on how to install BSD Or Solaris, HP/UX, and AIX directories with instructions on how to install Linux. :-) It's actually an interesting exercise. I'm familiar with both VMS and Unix, and I'm trying hard to keep track of the unique good bits of both systems so it all can be wedged into perl. I'd really like to incorporate the good bits of VMS' async I/O and event handling into perl, for example. Dan --"it's like this"--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 no reason you can't have document files accompanying the perl code files, for gosh sakes. I disagree slightly. One of the benefits of Pod is that it can be intermingled with Perl code; I don't think you're disagreeing here. What he said (as I read it) is Pod is good for when you want to add documentation beside your code. If you want to anything heavier than Pod allows, then use an external file - but leave Pod alone. there's no need to have it be all in one piece. This can be used to good advantage by having the pod for each function be places just above that function, thus simultaneously helping to document the code. If the pod (or whatever) is in a separate file, this advantage is lost. John wasn't saying abandon Pod, he was saying if you want to use XML or whatever then there's nothing to stop you putting it in another file. Cheers Andrew
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
"DS" == Dan Sugalski [EMAIL PROTECTED] writes: DS bits of both systems so it all can be wedged into perl. I'd really DS like to incorporate the good bits of VMS' async I/O and event DS handling into perl, for example. hear! hear! as the author/maintainer of the event loop and async/advanced i/o rfc's, i am gladdened by your support for these things. i can't wait until we get down to some more meaty design and then coding. i can't imagine what larry has in store. just digesting all the rfc's is enough to give anyone indigestion and he is known for having food restrictions. :-) uri -- Uri Guttman - [EMAIL PROTECTED] -- http://www.sysarch.com SYStems ARCHitecture, Software Engineering, Perl, Internet, UNIX Consulting The Perl Books Page --- http://www.sysarch.com/cgi-bin/perl_books The Best Search Engine on the Net -- http://www.northernlight.com
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
On Thu, 05 Oct 2000 11:08:00 -0700, Peter Scott wrote: May I point out that COBOL was designed by a committee. That ain't bad enough. Let me point out that we don't need another Ada or PL/1. -- Bart.
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
Peter Scott wrote: 'rewrite' is not the same as 'design', fortunately. I fervently hope that the language design will be the product only of ideas Larry either came up with or agreed with; if we get into some voting scenario, that spells doom. May I point out that COBOL was designed by a committee. May I point out that "the camel was designed by committee"*, too? Really, I'd like to see this Designed By Committee Considered Harmful myth put to rest. *according to one famous epigram. -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v2) Perl should use XML for documentation instead of POD
Simon Cozens wrote: (Incidentally, has anyone noticed that John Porter and I appear to have *completely* different opinions about *everything*?) Good thing you're both on the committee... O O \/ -- Glenn = Even if you're on the right track, you'll get run over if you just sit there. -- Will Rogers NetZero Free Internet Access and Email_ Download Now http://www.netzero.net/download/index.html Request a CDROM 1-800-333-3633 ___
