Let me preface this by saying I realize it isn't really the best place to be saying this. I'm posting here more as an exercise of letting off steam than any expectation of real change.
Recently I was playing around with doing some automatic generation of various pieces of information from the copious documentation that comes with perl. For example, one of things I was playing with was attempting to make perldoc -X $var work in the same way that perldoc -f func works. It sounded simple and fairly easy to do. So I opened up perlvar.pod. Good lord, do they ever use the same convention twice? Head 1 tags there, head 2 tags here, random lists, etc. It was really not very nice to parse.
I realize at the time they came up with pod, they wanted a simple language anyone could use that would produce nicely formatted documentation. In that respect, it reminds me a lot of say, HTML2. Quick and simple, combining content and presentation. Well HTML has moved on, can POD move on also?
I hate to jump on the XML bandwagon and pointlessly use it, but it does seem like the best way for documentation to be self documenting, as it were. I suppose we could also solve this by just mandating a specific POD layout, or perhaps a version of POD with a higher emphasis on the metadata instead of the presentation.
Regardless of how we do it, can we please god get it done?!
20050913 Unconsidered by Corion. Was at "keep: 19 edit: 19 delete: 0" by monsieur_champs: "Please adjust title to something more aligned with your text, Its an interesting and needed proposal." |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by castaway (Parson) on Sep 10, 2005 at 11:27 UTC
|
Have you looked at http://pugs.kwiki.org/?KwidSynopsis, which is what the Pugs project is using? Otherwise, yes, sure you can, invent/improve one, then go suggest it on p5p, then work to help implement it (after convincing everyone) ..
IMO, btw. XML sucks for this kind of thing, its much too easy to typo, and thus isnt good for handtyped docs at all. POD is nice and simple to use, if it makes the parsing harder, thats just tough, internals generally are more complex than externals, to support those simple externals.
C. | [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by demerphq (Chancellor) on Sep 10, 2005 at 11:10 UTC
|
I'm sure p5p would be happy to have you submit a version of perlop that is more easily parsable by tools like perldoc, and would be even happier to get a code patch to do the extraction.
---
$world=~s/war/peace/g
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by itub (Priest) on Sep 10, 2005 at 14:56 UTC
|
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by raptnor2 (Beadle) on Sep 10, 2005 at 14:53 UTC
|
The problem won't go away if we use XML over POD. Both formats are display orientated, not data oriented. XML doesn't have to be, but in this context it is. There are other ways to do do this. We, the community, could impose a standard, which won't work. We could also build on the POD test suites.
I actually discovered these last weekend after using Module::Starter::PBP for the fist time. All the sudden I had 14 failues. Once I figured out that there were POD test suites in there, I got the motivation to finish up my documentation.
Test driven development works for developers because we can see what we have accomplished, and what we have left to do. In fact tests help us remember that we're not done yet. The same works for a certain class of POD, too. Why not extend it?
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by Ctrl-z (Friar) on Sep 10, 2005 at 10:59 UTC
|
Does Perl6 cover documentation? I dont recall reading about it, but I would be surprised if it was overlooked.
time was, I could move my arms like a bird and...
| [reply] |
|
|
| [reply] |
|
|
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by GrandFather (Saint) on Sep 10, 2005 at 23:42 UTC
|
Yet another manafestation of TIMTOWTDI. The fault isn't with POD, which is just a form of mark up, but with inconsistency with its use. You can't avoid people using the richness that is provided in ways you didn't anticipate; that's what people do.
Changing from one type of markup to another doesn't solve the fundamental problem, and in the case of POD to XML, probably makes it worse!
Remember the context for POD. It is to help provide documentation in the source, so any markup that is used to manage formatting in some other context has to be pretty light weight or the documentation just doesn't fit with being in the source in the first place.
Probably the only solution is to provide a good set of guidelines for the use of POD (or whatever markup may be used) so that both usage and apperance are consistent.
Perl is Huffman encoded by design.
| [reply] |
|
|
Probably the only solution is to provide a good set of guidelines for the use of POD (or whatever markup may be used) so that both usage and apperance are consistent.
Yes...and no.
The OP was specifically working with perlvar.pod, and complained about the inconsistency of POD usage therein. If a single document is legitimately judged inconsistent, guidelines won't help.
However, it may be that the nature of perlvar.pod is such that POD is overly taxed (or POD writers are overly taxed commenting it).
I'm curious to see whether perlvar.pod is judged to be well formatted (POD-wise) or not, and whether the blame or kudos can be lain at the feet of an individual or an anonymous horde.
-QM
--
Quantum Mechanics: The dreams stuff is made of
| [reply] |
a 'strict' POD tester
by chanio (Priest) on Sep 11, 2005 at 02:43 UTC
|
Perhaps upgrading a 'strict' POD tester module included in every new distribution... Developers should see their errors when upgrading their modules.
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by wazoox (Prior) on Sep 13, 2005 at 11:29 UTC
|
I'm trying to get around this by switching my documentation to robodoc. The main advantage is to be somewhat more compatible with ctags; it also is compatible with many languages, and not only perl; and the default formatters (robodoc to html, etc) give better looking results than corresponding POD translations.
What I still miss is a practical robodoc-to-POD (and reverse) translator, though :)
update: I've finally made it ! It's fa for perfect but it works fine with all my code. See ROBODoc to Pod translator
| [reply] |
Re: Please for the love of god, can I get a documentation format that doesn't suck?
by herveus (Prior) on Sep 12, 2005 at 11:52 UTC
|
Howdy!
++ for trying to make perldoc -X work. -- for suggesting
XML. Several -- for that, even.
POD has a powerful advantage in that it is light on the
markup. You can read POD without requiring a 'viewer' to
make visual sense of it. XML is almost the antithesis of
that ease of use.
Perhaps you could rejigger perlvar in the same manner as
perlfunc, to regularize the usage. You have the power...
| [reply] |
|
|
Yes, I could rewrite perlvar so it's slighty easier to parse. I could also just write a parser that deals with it. Neither of those solutions accounts for the other 10,000 modules on CPAN.
| [reply] |
|
|
