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.
Some ideas for section usages,
Sec# Ideas/Suggestions for use
==== =========================
1 commands that can be entered at the command line (perhaps perl,
perlrun and some Module-created commands like "GET" (alias for
lwp-request) or "perltidy"
2 I'd see this reserved for Core language functions; I'm a bit
undecided if this should be limited to builtin's or if it should
also include Core library functions. It may not be important to
differentiate built-ins from included CORE functions, but I do
think it is important to differentiate Core functions from CPAN
library functions (despite CORE modules often starting out as
library functions). I think it might be useful to know if a
function is included in a standard perl distribution, or if
someone would need CPAN access. It might be desirable to create a
program built solely from the official Perl distribution.
3 CPAN functions (perhaps distinguished with a 3pm extension). If
CORE functions reside in "3" as well, using a "3pm" extension
might be a good differentiator. Ideally, from a classification
sense, the CORE library modules would be under section 3 just as
the standard C-library calls are included here.
4 <we don't have too many special files in Perl>;
5 <file formats & conventions>; perhaps pod format; installation
customs (what might be good usage for Product-, Vendor- and Site-
include directory structures); etc.
6 scripts and library routines designed for amusement (not giving
examples of library routines I think would go here, in case author
designed said routines with a serious purpose in mind...:-)
7 "Miscellaneous" information; Howto's, FAQ's, Programming Guides
8? Maybe administration or setup of CPAN?
9 Perl internals and interpreter API
These were ones I came up with. My main motivation was to see all non
".pm" doc files lumped under (1) User Commands.
Comments? Too much work for too little benefit? Not informative enough?
Would never get anyone to use it? Useless because "man" is outdated, and
we should use a different document spec for every new tool or tool
provider? Everything should be in ".info" format and only usable by
academics who learned lisp & Emacs at MIT? Everything should be in HTML
because it's so easy to use from a console and is so easily
searchable...(*cough*); Everything should be in XML (see HTML
benefits);...etc...
Are these the right lists for this discussion? Would this be
more appropriately titled an "RFC"?
Linda
