Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 > > might want to be used can be embedded. (=for XML) > > Now, if I could use POD to get the job done more lazily, but switch to XML You can! That's what Mr. Barnette was just saying. =begin XML unreadable verbosity... =end XML You would just need a pod converter to process it. And you could probably whip that up yourself in no time. -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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.
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 would have the disadvantage of not being able to be inline, which is a huge advantage with pod. Graham.
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 of the structuring capabilities of other languages like man or html. It should be possible to translate pod into *ANY* other document structuring language. If you add (e.g.) support for tables, then pod is only translatable into languages which also support tables. THAT's why pod has to give you an escape into other languages, via =for/=begin. > People are looking for POD alternatives because doing complex things in POD > is so hard and/or annoying. Complex things should not be done in POD. > some standard format that is rich enough to be converted to anything: But you've got it wrong: only a SIMPLE format can be translated into "anything". > format that can handle complex items like tables and hyperlinks and embedded > images and all that good stuff. Well, it's not pod that does that; it's the converter. And a converter to handle L, IMG, etc., could be written. > So people > stick to Plain Old POD, sans fancy =for business, 90% of the time. Yes - as it was meant to be. -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 died out, and for good reason imho. -- robin b. Don't panic.
Re: RFC 357 (v1) Perl should use XML for documentation instead ofPOD
On 10/3/00 10:59 AM, John Porter wrote: > 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. Well yeah, that too. > 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? ASCII sure does. Let the translators worry about how, exactly, to down-convert to simpler formats. Let *them* do the special-cases. Again, this doesn't mean POD has to be massively complex or use "heavy" markup like XML or anything silly like that. Heck, define POD tables any way you want, just make sure there *is* a standard way to make POD tables. Then let pod2html convert them to HTML tables and pod2text convert them to ASCII art tables, etc. etc. >> People are looking for POD alternatives because doing complex things in POD >> is so hard and/or annoying. > > Complex things should not be done in POD. I contend that good documentation *is* a complex thing...well, more complex than the set of things that can be done in "standard" POD, anyway. > only a SIMPLE format can be translated into "anything". See above. >> So people stick to Plain Old POD, sans fancy =for business, 90% of the time. > > Yes - as it was meant to be. I disagree. That's *too* "plain" and "old", IMO. -John
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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? > there's the "everyone else is doing it" argument for XML. Pod's easier to learn than xml; and besides, "everyone's doing it" is not a good reason (not to mention that it's false). > - Pod can be translated into XML and vice versa Sounds like a reason NOT to replace pod with xml. > - Standard elements could be defined and utilized with the > same or greater ease than pod for build and configuration. False. The only thing missing from pod is the definition of these "standard elements" in the pod spec. The way to fix it is to add these definitions, not replace pod with xml. -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v1) Perl should use XML for documentation instead ofPOD
John Porter (Today): > 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 > > > might want to be used can be embedded. (=for XML) > > > > Now, if I could use POD to get the job done more lazily, but switch to XML > You can! That's what Mr. Barnette was just saying. > > =begin XML > > unreadable verbosity... > > > > =end XML > > You would just need a pod converter to process it. > And you could probably whip that up yourself in no time. Yup. Like I said, it'd be fairly easy to write xmlpod2[man | et al.] equivalents for translation. These applications could act just like their pure-pod equivalents, but optionally parse XML blocks. So you could do anything from =pod =begin XML =end XML =cut ...to =pod (lotsa normal podtext) =begin XML =end XML And I'm sure that someone would write an xmlpod2pod at some point. ;-) ~ j. // "The eleventh commandment was `Thou Shalt Compute' or // `Thou Shalt Not Compute' -- I forget which." // -- Epigrams in Programming, ACM SIGPLAN Sept. 1982
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 ? The thread eventually died out, and for good reason imho. Ah, good reading. Thanks. (And I hope you don't blame me for not subscribing to p5p...) -- John Porter By pressing down a special key It plays a little melody
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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. O.k., how about mathematical formulas. Doable in XHTML and LaTeX, NOT doable in HTML 3.2. Not really doable in ASCII, either. > Let the > translators worry about how, exactly, to down-convert to simpler formats. > Let *them* do the special-cases. 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 (e.g. emacs modes). > I contend that good documentation *is* a complex thing...well, more complex > than the set of things that can be done in "standard" POD, anyway. Well, you have a simple notion of complex. :-) > [POD] is *too* "plain" and "old", IMO. If it is sufficient for 99% of documentation needs, it is none too plain, despite its age. -- John Porter By pressing down a special key It plays a little melody
Re: 184 (v3): Perl should support an interactive mode
Christian Soeller wrote: > > Very little discussion was generated by this RFC. Several people noted that perl >-de 42 and the Perl shell psh already provide some > > of what the RFC requests; this is noted in the RFC. > > > > The RFC is not being withdrawn, since 2 other people expressed (mild) interest in >it. > > I'd like to add that multiline shell capabilities would be *extremly* > useful for the perldl shell Well, the psh shell could use some additions, too. Right now psh does some rather primitive parsing for completeness of a line and has to guess wether some input is intended to be Perl or e.g. calling of an executable or whatever. To be more specific, the functionality we could need is. - Determine wether an expression could be a complete Perl expression (that means, no more open braces, qq blocks etc.) - The ability to check via the symboltable wether a certain core function exists without using a hard coded list, as well as gaining a string representation of their prototypes - Syntax checking perl code without forking and execing a new perl instance with -c - Ability to store and later retrieve all eval sideeffects like $1,$2,... current package etc. without handling every variable/condition yourself. One could argue that we should use the existing parser modules to gain the necessary information as far as possible, on the other hand these facilities are already there somewhere, hidden in the Perl executable. I have to admit though that I somehow doubt that only one applications(psh and perhaps the perldl shell, too) justifies such additions to perl. -- Markus Peter - SPiN GmbH [EMAIL PROTECTED]
Re: RFC 357 (v1) Perl should use XML for documentation instead ofPOD
On 10/3/00 12:01 PM, John Porter wrote: > John Siracusa 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. > O.k., how about mathematical formulas. Doable in XHTML and LaTeX, NOT > doable in HTML 3.2. Not really doable in ASCII, either. Who said anything about equations? (Well, I didn't anyway :) Is that useful in most documentation? Maybe for stats packages, but something like tables is useful in a heck of a lot more common documentation situations. There are certainly things that are either too complex or too specialized to belong in POD, but there are plenty of things that are very useful but that currently have to be hacked in via duplicating a bunch of =for sections and hoping for the best. 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. The current support requires too much guessing on the part of the pod2* translators and provides too little control for the author, IMO. -John
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 in ? And don't tell me to get > some fangle dangled editor. Which would have the disadvantage of not > being able to be inline, which is a huge advantage with pod. POD, presumably. Or maybe son-of-POD; it would be nice to have better support for tables and lists. - Damien
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 won't be difficult -- nothing that would make XML seem like an attractive alternative. -- John Porter By pressing down a special key It plays a little melody
Re: Variable attributes (was Re: RFC 355 (v1) Leave $[ alone.)
Dan Sugalski wrote:
>
> At 04:39 PM 10/1/00 -0700, Peter Scott wrote:
> > What are the chances of the internals supporting user-defined
> >attributes? What would the API look like?
>
> Well, yeah, it'll sort of have to if we allow user-defined types. If you do:
>
>my Dog $spot : male;
>
> then the Dog package needs to be able to fetch the attributes. I've no idea
> how that'd look--perhaps an attributes() function, a method in UNIVERSAL,
> or something like that.
if attributes are stored as one hash per attribute, with somthing intransient
about the target objects used as the keys (like its reference stringification)
rather than being stored with the object, requiring larger objects, the entire
attribute syntax might be possible to convert into an access to those hashes.
The only sticky part I can see is what to call them.
%UNIVERSAL::ATTRIBUTES::your_attribute_name_here
perhaps?
This would make Dan's example expand to:
my Dog $spot; $UNIVERSAL::ATTRIBUTES::male{\$spot} = 1;
Magic would be required to delete an objects attribtes on destruction;
the requirement to store this magic might invalidate any gains from doing
it this way.
--
David Nicol 816.235.1187 [EMAIL PROTECTED]
"After jotting these points down, we felt better."
RE: RFC 357 (v1) Perl should use XML for documentation instead of POD
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.
RE: RFC 357 (v1) Perl should use XML for documentation instead of POD
> > 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 ;-) > > - Why make people learn pod, when everyone's learning XML? > > there's the "everyone else is doing it" argument for XML. > Pod's easier to learn than xml; and besides, "everyone's > doing it" is not a good reason (not to mention that it's false). Exactly... XML is *NOT* a "tried and true" format IMHO. I have yet to be convinced that XML won't be ditched sometime in the near future for the "Next Big Thing" (tm) No offence meant to XML fans... ;-) > > - Standard elements could be defined and utilized with the > > same or greater ease than pod for build and configuration. > False. The only thing missing from pod is the definition of > these "standard elements" in the pod spec. The way to fix > it is to add these definitions, not replace pod with xml. Just be careful not to expand POD too much. One of its greatest strengths is its simplicity. Greg
Re: RFC 357 (v1) Perl should use XML for documentation instead of POD
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 (e.g. emacs modes). Arrgh, you're giving me WEB flashbacks... I nearly went blind trying to read that stuff... 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? -- Peter Scott Pacific Systems Design Technologies
