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 | |
by calin (Deacon) on Sep 10, 2004 at 16:36 UTC | |
|
Re: POD: advice sought over correct usage
by Anonymous Monk on Sep 10, 2004 at 09:25 UTC | |
|
Re: POD: advice sought over correct usage
by PodMaster (Abbot) on Sep 09, 2004 at 23:05 UTC |