Check out the stuff I did with Pod for Mastering Perl. There's a chapter on messing with and extending Pod, and I wrote the book in O'Reilly's PseudoPod format (see Pod::PseudoPod), an extension of Pod that includes footnotes.

The Pod chapter also talks about writing your own Pod translator. It's not as hard as you think. You start with one that's close to what you want and override the parts that you want to change. Look into Pod::Simple.

Good luck :)

What's with those p tags? Do I have to go tinker with POD::HTML?

You can adjust the visual representation using CSS, if that's the problem.

/* No margin for P inside of LI */
li p {
   margin: 0;
}
[download]

eg:

<ul>
<li><p>foo</p></li>
<li><p>foo1</p></li>
<li>foo2</li>
<li>foo3</li>
</ul>
[download]

∙ foo

∙ foo1

∙ foo2
∙ foo3

And, as ikegami said, you can control the presentation with css -- http://www.w3schools.com/ has a decent tutorial if you're unfamiliar with style sheets. Once you have the basics, you may find it worthwhile to read the various css specs at http://www.w3.org/Style/CSS/.

For a example (anything more is well outside the scope of the Monastery), change the display of those updated for clarity the content of the list-items with something like this (inline for ease of display):

<ul>
<li><p style="color: red; background-color: transparent; font-size: 1.
+1em; font-weight:bold;">foo</p></li>
<li><p style="color: #000000; background-color: #dddddd;; font-size: 1
+.1em; font-weight:bold;">foo1</p></li>
<li style="color: blue; background-color: transparent; font-size: 1.1e
+m; font-weight:bold;">foo2</li>
<li style="font-size: 1.1em; font-weight:bold;">foo3</li>
</ul>
[download]

which would give you bold, slightly larger than normal-font-size type, with "foo" in red; "foo1" in black on a silver background; "foo2" in blue, and "foo3" in black again (assuming you had not used some other color as a default for the page.

Update ikegami provides a more technical (and CORRECT) answer; however, if you're just starting with css the code and descriptions of the rendering are correct; the statement re the placement of the blank lines is imprecise ok, admit it! wrong.

The blank space appears before the bullet instead of after because of collapsing margins.

The bullet doesn't count as content, so the bottom margin of the previous P, the bottom margin of the previous LI, the top margin of the LI and the top margin of the P are collapsed into one margin whose size is the biggest of the 4 margins.

( Contrary to his claims, there's nothing wrong with what ww said. I was just expanding on it. )

I may be way off base here, but...

Personally, I recommend Doxygen.

Doxygen generates JavaDoc-like documentation (all nicely linked) for projects in many languages, including C and C++. DoxygenFilter is a new take on an old project (DoxyFilt) that also handles ("filters") Perl code (including POD), and now promises support for multi-programming-language projects. See Examples of output generated by doxygen.

When I was expressing a desire above for better documentation, I actually had Doxygen in mind. However, as far as I recalled, Doxygen did not work for Perl/Pod. Seems like I have something new to discover here. Yes, Doxygen generated docs are really quite good. Thanks for the tip.
--

when small people start casting long shadows, it is time to go to bed

Hello punkish,

I am not sure that this will really address any of your concerns and it is a completely different approach, but have you had a look at literate programming? I am no expert, but Literate Programming, simply put, allows the programmer to order code and comments in a way that makes most sense to him or her (rather than to the interpreter or compiler), and to print the resulting program out very prettily. Unfortunately there has not been much development in this area since the early 90s, which was when I discovered and tinkered around with it, although I did find this slightly more recent article, which contains an example using Perl.

HTH or is at least of interest

loris