calin has asked for the wisdom of the Perl Monks concerning the following question:

I'm writing a business letter in POD, and, while I've managed to bend things into shape visually, I'm still left with a few questions unanswered and some confusion, so I'm seeking wisdom.

Suppose I have a POD section like this:

=pod =head1 Our special offer =over =item foobearings Z<> =item quuxbearings Employing revolutionary quantum metallurgy, our novel quuxbearings reduce friction and wear by 110 to 120 per cent over standard foobearings. =item surescrews surescrews is the only make of screw available on the market that is independently certified to do the screw job well. =back =cut

The foobearings item is an established commodity in our trade and does not have a description paragraph ; everybody is supposed to know what a foobearing is and what it does. But I want to mix it with items that have a description in an =over .. =back span. If I simply continue with the next =item, the two items are crammed together without a paragraph break between them. This seems to be a known quirk, exploited in the Perl manpages to make a single description for multiple items. However, this is not what I want, so I got the idea of putting empty description paragraphs containing only Z<>. This works, with the reserve that the formatting creates too much vertical space (two lines in man, HTML is better but still creates a <dl> with an empty <dd></dd>).

I'm wondering - is this the correct way of doing bare items with no description? Is there a better way?

My second issue is that I'd like these items to act like headings, that is, appear in the Table of Contents. Or, thinking the other way around, I'd like to have headings contents to be indented like item descriptions.

My first take looks correct pod-wise to the best of my knowledge, however, while it indents in man, it doesn't indent in HTML (!). Why? Here's the code:

=pod =head1 Our special offer =head2 foobearings =head2 quuxbearings =over Employing revolutionary quantum metallurgy, our novel quuxbearings reduce friction and wear by 110 to 120 per cent over standard foobearings. =back =head2 surescrews =over surescrews is the only make of screw available on the market that is independently certified to do the screw job well. =back =cut

Adding a bare =item after =over makes the pod2html rendering acceptable, but the man output suffers from spurious bullets. Adding =item Z<> instead of =item makes both the man and HTML outputs acceptable (but not perfect). Z<> comes to help again.

Again I'm asking, what is correct? What else do I need to know?

Replies are listed 'Best First'.
Re: POD: advice sought over correct usage
by jryan (Vicar) on Sep 09, 2004 at 23:35 UTC

    Which POD parser/formatter are you using? Have you tried Pod::Simple?

      Thanks for the Pod::Simple tip.

      I'm currently trying out Pod::Simpe::HTML, and it looks more spiffy than pod2html. It does blockquote right when it encounters =over ... =back spans without enclosed =items.

      pod2html currently does line-by-line processing (no deferred output), so it can't go back and add a starting <blockquote> tag when it arrives at the =back without seeing any =item in between. (without modification of program logic and data flow, of course, so there's not a matter of a simple patch).

      FYI, here's what perlpodspec is saying (though it doesn't read as a requirement to put blockquotes in HTML formatting):

      An "=over" ... "=back" region containing no "=item" paragraphs at all, and containing only some number of ordinary/verbatim paragraphs, and possibly also some nested "=over" ... "=back" regions, "=for..." paragraphs, and "=begin"..."=end" regions. Such an itemless "=over" ... "=back" region in Pod is equivalent in meaning to a "<blockquote>...</blockquote>" element in HTML.
Re: POD: advice sought over correct usage
by Anonymous Monk on Sep 10, 2004 at 09:25 UTC
    Make yourself famous, and patch pod2html so it will output HTML with appropriate classes, divs and spans, in such a way that all the formatting can be done by a stylesheet. Then it's simply a matter of writing your own style sheet.
Re: POD: advice sought over correct usage
by PodMaster (Abbot) on Sep 09, 2004 at 23:05 UTC
    If you don't like how certain formatters format your pod, write your own.

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.