I was just reading in ziggy's journal that some people wanted to replace POD with XML because XML is sexier. And well, I'm an XML guy, so you'd think I'd be all for that.
I'm not. But not why you might think I'm not.
Let me just say right out that POD sucks. It really really sucks. It is fantastic though for what it was designed for, unfortunately it was really designed in Perl 4's day, and so while it's kinda good at documenting a module or script with a few functions, it's pretty bad at documenting an OO module with parameters and a class hierarchy, and so on.
POD is also pretty bad for extensibility - so many people have tried to add things like footnotes or tables to POD, and most have failed pretty badly.
Finally, and this really is the biggy: the POD spec is like the Perl spec. Non-existant. And yet there's many POD parsers (and only one Perl parser - perl), and they probably all get it wrong (despite the release of perlpodspec.pod). Take L<>... you can actually parse the same L<> different ways depending on what spec you read. And if you parse it the way perlpodspec says, you break documents in the wild...
XML solves all of these problems. But, it doesn't solve some of the problems that POD *does* solve, such as being easy to author (I know *I* find XML easy to author, but most other people don't (and you don't count, robin!)).
What I'd personally advocate is a better plugability layer for docs than =begin. That would allow us XML geeks to have tons of metadata that most people couldn't give a shit about. The plugability layer should work like an XML parser in many ways - where you get more information if more information is available, and it should work like SAX in some ways - it should present the same API to the user no matter what "plugin" doc format they've decided to use.
Anyway, I guess I've become one of ziggy's hated "ideas" people rather than an implementor :-)
Considering that one has to write documentation *first* in order to use POD. Too much complexity in what should be simple isn't really addressing the problem of not enough people document their modules. It's like people bitching about CPAN.pm yet they are usually the ones who either don't have a version or never bothered to read the documentation on what the appropriate version string is supposed to be. Close to 40% of the modules on CPAN either lack a version or POD or both. This isn't something XML is really going to fix.
Adding complexity never solves a problem, it just adds more complexity.
Re:POD isnt' so bad
darobin on 2001-12-15T18:29:23
I don't think Matt's idea was to add complexity. He wants to add power. Now, I know that the two often walk in pairs, the latter as the intention and the former as the result.
I'm not in the camp of people that want to make Perl's documentation XML-based (though I've come closer to it since that post, mostly for "enterprise" stuff and not for core Perl) but I could definitely use some extra metadata. The ActiveState people have been working on that (IIRC) and I'd love to hear about the output of their attempts.
The basic idea, for me, is that it would be great to be able to document more precisely method signatures and class relationships, so that Perl editors could offer better autocomplete and so that docs could be usefully cross-linked in an automatic manner. Anyone who has looked up something in the LWP docs and subsequently had to go to HTTP::Response/Request, and then to HTTP::Message, and then $DEITY knows where will probably know what I mean
:-) This doesn't mean adding more complexity. It simply means providing a standard way in POD to do that (standard as in "we all agree on it") so that people that want to use that kind of feature can. It really doesn't have to get in the way of those that don't want it.
If, however, someone would give me a Wx POD editor, I'd be endlessly happy.
Re:POD isnt' so bad
TorgoX on 2001-12-19T06:01:53
There's always writing HTML in the editor of your choice, and feeding it to Pod::HTML2Pod. It's crazy, but aren't we all?
Try it some time!
I remember a couple of years ago falling into the "Replace POD to XML" camp, until tchrist set me straight. I've also been painfully aware whenever that argument resurfaces, along with a couple of other latent memes that circulate through the Perl community. Like replacing Perl's syntax with XML, so we don't have to worry about maintaining a parser anymore (duh!), or the more recent resurgent meme that Parrot is a folly and we should just use a Scheme VM for Perl6...
It's important to keep a beginner's mind here, otherwise we'd be a pretty boring and exceptionally stagnant development community. But a room full of beginner's minds generally won't get threading done right, fix the thread safety of regexes, integrate Unicode into the core or reintegrate EBCDIC. So we need both, and Perl6's release valve offers a way for the two groups to coexist more peacefully than before.
Replace Parrot with a scheme engine?
pdcawley on 2001-12-14T19:18:41
Can't say I've come across that meme in the wild.
Plenty of scepticism about the whole Perl 6 enterprise, but I've not seen the 'use scheme' thing.Re:Replace Parrot with a scheme engine?
Elian on 2001-12-14T19:29:01
The 'use scheme' stuff's part of the aftermath of the LL1 workshop held at MIT in November. links off of the website for it somewhere.
Re:Maybe we need to nail the problem
ziggy on 2001-12-14T18:39:46
Let's get a few things straight.
- Usage of POD across CPAN is a separate issue, as is proper versioning of modules.
- POD is designed to simplify writing manpages
- *roff syntax really sucks. Kudos to the folks at Bell Labs for writing classic texts directly using *roff.
- POD sucks as a documentation format and as an authoring format
- POD sucks much less than *roff as an authoring format
- HTML is about 5 steps backwards, even starting with *roff
- TeX, TexInfo and TeX variants are pretty darn bad, too
- JavaDoc, Python's Docstrings and C#'s "XML Comments" are pretty bad, too
So where does that leave us? There are lots of bad documentation formats -- both in terms of reading as source and authoring. So the best you can possibly hope for is to separate the display from the authoring, which is basically re-inventing SGML or XML (your choice). Even those options aren't wart-free.
So taking all that into account, POD sucks, but it sucks much less than all of the other alternatives. Put another way, 20 well-written pages trumps 3 beautifully formatted pages or 5 metadata rich (and reusable) pages.
But sometimes 20 pages of well-written text need the occasional table, hyperlink or bulleted list. POD goes about 80% of the way of hitting the 80/20 rule.
So, anyone up for addressing POD's deficiencies in its well-defined area of applicability?
We're working on it, and in a POD-friendly manner.
Re:Maybe we need to nail the problem
Matts on 2001-12-16T17:04:36
Yeah, I think we're in total agreement...
The way I see addressing the problem is to create a POD API (not sure if POM is the right thing - I think we'd miss a streaming API) such that we could rip out POD and replace it with XML, when we needed that sort of power (or choose markup language X). It would have to cope with some sort of extensibility mechanism like XML Namespaces, so that we could define metadata tags (I use tags in the loosest sense of the word - they could be POD formatting constructs) in a consistent manner.
Anyway, I have way too many other things to be working on, so I'll get back to being an implementation type, rather than an ideas type:-)
