Re: Proposal: =mansec PoD extension & manpage section usage

Hi Linda,

A couple comments:

  2) It might be better to use an existing directive like "=for  
mansection" rather than creating a new top-level directive.

  3) I'd rather see semantic values rather than numeric.  Some  
platforms don't have anything like "manual section 3" but they might  
still have a place to stick "library" documentation.

  5) Module::Build has an extensible mechanism for installing various  
kinds of stuff.  For man pages, there are "libdoc" and "bindoc" types  
corresponding to sections 3 and 1 ($Config{man3dir} and $Config 
{man1dir}).  That mechanism can be added to fairly easily for an  
individual distribution, without having to introduce new POD syntax.

  8) The requirement to be the first directive in the POD seems  
arbitrary - someone else might be working on a "=foo" directive that  
*they* want to be the first directive too, also for "ease of  
processing."

  12) For better or worse, lots of tools (e.g. my brain, when I grep  
for something in my man pages) assume that all perl docs are sitting  
in sections 1 and 3 in the manual.

My gut feeling is that it's going to be difficult to achieve decent  
adoption rates of a new tag for manual sections, I think most people  
feel like it works fine now and won't want to update their pod2man,  
etc. unless they feel like they're getting something else out of it.

  -Ken


On May 28, 2006, at 2:30 PM, Linda W wrote:

> In order to provide for a better integration of Perl documentation  
> into
> man page sections, I would like to propose adding a "=mansec" POD
> directive and some vague attempt at appropriate section number  
> assignment.
>
> In the _absence_ of a specified section, I would like to propose using
> section "7" (Miscellaneous) for pod2man output (instead of the current
> mansec, "1" (Commands), by default.  A standard exception would be
> manpages produced directly from .pm files and .pod files that have an
> equivalently named ".pm" file in the same directory as the .pod  
> file.  As
> .pm files are considered library modules, they would default to  
> mansec "3"
> (library functions).
>
> Gradually, system/Core documents could have =mansec directives  
> added as
> time would allow, to more appropriately classify them if desired.  In
> order to simplify processing, I would like to suggest that the  
> "=mansec"
> directive be included as the first text line within Pod documentation.