On Sat, Aug 21, 2004 at 12:03:10AM -0600, Luke Palmer wrote: : I've already had my epiphany about POD, though, so I'll spare doing it : again. In short, there are two things that I see about POD that need to : change: : : =over : : =item 1) : : C<=directive> lines shouldn't have to be in their own paragraph, in : order to condense lists and make them more readable from POD source.
Yes, I plan to bless that one, though I don't think I've said it publicly. : =item 2) : : (The one that has been made clear several times) When an =end foo closes : a =begin foo that opened the POD section, the =end should close the POD : section. Likewise a bare =for in the middle of Perl code should revert to Perl code at the end. : No tables. Keep the number of things that I can distract myself with : when I should be writing documentation down to a clean 565. I don't : need 566. However. It's possible to make really clean pod tables by processing verbatim lines as tab-separated values. We did the tables in Camel 3 that way, though it took a special preprocessor/postprocessor that understood C<=begin table> and C<=end table>, and also understood that lines consisting of all ---- fields are special, and that consecutive verbatim paragraphs are part of the same table. The main trick is to split not on /\t/ but on /\t+/. That way you can use multiple tabs to keep your columns aligned. The main downside is sometimes your tables get too wide for 80 columns. A secondary downside is that people's formatting gets off when they quote your table in email. I think our table processor also allowed a bit of font modification, which verbatim paragraphs don't normally allow. That was a necessary luxury in our case. But you can make some rather pretty POD tables that actually have enough information to keep the columns straight. Larry Larry
