Re: Guidelines for listing functions/methods in POD?

The major reason the =head2 style came into vogue, you probably had it recommended to you at some point, is that it gives navigation entries on the CPAN sites for documentation page. So, you can click down to a method easily from the top. I disagree that POD semantics should be disregarded and assert that doing it with =item and such is proper. The fault, to me, lies in the presentation layer (CPAN view), not the data (the POD).

Up to you which is right for you.

Comment on Re: Guidelines for listing functions/methods in POD? Select or Download Code

Replies are listed 'Best First'.
Re^2: Guidelines for listing functions/methods in POD? by Anonymous Monk on Dec 07, 2017 at 23:28 UTC
Pod semantics arent being disregarded.	[reply]
Re^3: Guidelines for listing functions/methods in POD? by Your Mother (Archbishop) on Dec 08, 2017 at 02:01 UTC
I was arguing the semantics are being misused. If you have head1, head2, head3... they correspond to something like book, chapter, verse. A single method or function, to me, never rises to the level of chapter. Item is a much better library match for a function than head2. It's a FOSS world, lots of hackers disagree, do what you like, etc. Promoting list items to chapter titles breaks reasonable semantics in my view and promotes lousy hierarchies and slap-dash documentation. But I will cogitate on your thorough and incisive rebuttal since it contains so much to consider.	[reply]