NOTE: I went on too long. You can skip to "ACTUAL QUESTION" if you hate it when I ramble.
So, I go and spend several weeks or months of my life writing something so that I never need to use Pod::Simple, and here I am learning about how Pod::Simple works so that I don't need to implement formatting codes. Life is funny. My "Advent calendar" of Perl module articles uses Pod to mark up the documents. I use Pod::Elemental transformers to produce Pod suitable for feeding to Pod::Simple::XHTML, which produces all the HTML of the article bodies save for the code samples. You can see the output here: http://advent.rjbs.manxome.org/2009-12-08.html I've had to do more hacking around than I think is reasonable to get it to work how I'd like, largely (I think) due to weirdness in how regions are handled in Pod::Simple. Regions, in fact, are what led me to write my own Pod handling code in the first place, way back when! Sadly, figuring how how to do stuff is a pain because the documentation is weird and scattered. It's also hilarious at times. Earlier tonight I chuckled at this: CAVEATS: This is just a beta release -- there are a good number of things still left to do. Notably, support for EBCDIC platforms is still half-done, an untested. If I was going to name what was most notably missing from Pod::Simple... yeah, not EBCDIC. Anyway, I'm digressing far more than I meant to. I'd like to (a) document more of what I've learned and (b) fix the fixable problems that I've encountered. Documenting things now is silly, because most of what I've learned is what to fix, not what to document. ACTUAL QUESTION: Is there any strong feeling that Pod::Simple needs to have so many things done either apparently or clearly in the interest of speed? I found a number of methods that I could barely track down because they're generated strangely, explicitly in the name of speed. There's a good bit of code to allow debugging output to be optimized away, which leads to stupid method of using "DEBUG" which leads to stupid bugs. And so on. I would like to refactor the code as I work so that methods are easier to find, use, and replace as needed. Maybe I can fill in some of the "to do" documentation, once I understand what the hell is going on. Is anyone going to be put off by these kinds of changes *in general*? The first one I hope to make is to add $self->debug($level, $msg) to replace the use of "print" which is broken when there's a non-STDOUT handle select-ed. That's also a good taste of the kind of changes I think I'll end up wanting to make. -- rjbs
