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.
