POD question and usage

John M. Dlugosz has asked for the wisdom of the Perl Monks concerning the following question:

In perlpod, it shows =head1 and =head2, but not 3 or higher. Do they exist (that is, will common tools swollow them OK?) Some of you even write books using POD -- how do you organize a larger document?

When documenting a module, which standard modules are "good examples" I should follow, and which are "bad examples" that I should refrain from drawing inspiration on?

Any pet peeves or general advice about documenting a module?

—John

Comment on POD question and usage

Replies are listed 'Best First'.
Re: POD question and usage by jmcnamara (Monsignor) on Oct 25, 2002 at 22:24 UTC
perlpodspec and more recent versions of perlpod say that `=head3` and `=head4` are also valid. However, as an arbitrary test, the perl 5.6.0 version of pod2text doesn't support `=head3` and pod2html supports up to `=head6` !!. -- John.	[reply]
Re: Re: POD question and usage by John M. Dlugosz (Monsignor) on Oct 27, 2002 at 18:47 UTC
Thanks very much. The docs that come with ActiveState doesn't have that one. I take it that this will come with the 5.8 release? Interesting that pod2html supports different than pod2text if they use the same parser module. Maybe it parses, but the logic simply is unaware to expect it.	[reply]
Re: POD question and usage by mojotoad (Monsignor) on Oct 25, 2002 at 20:36 UTC
I don't know the answer to your =head? question, but I can offer a pet peeve. In POD, lines with leading whitespace are interpreted literally; that is, no formatting is applied to sections of text with leading whitespace. This is primarily for code examples and the like. However, sometimes it is abused, and the entire POD is fixed width and generally painful to read. For example: Astro::Coord Don't do that! Matt P.S. The html via search.cpan.org masks the horror. Try it via `perldoc` on a 80-character wide terminal session to truly feel the pain.	[reply] [d/l]