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

Ken Williams wrote:
> 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.
---
	That seems reasonable.  Wasn't familiar with the "=for" 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.
===
	Conceptually, I agree, but numbers are short and clear and can be
as easily mapped to their appropriate semantic meanings.  Could you give an 
example of a Perl supporting platform that doesn't have manpage sections?
I can see people mispelling semantic names or thinking that a particular
routine may not be exactly described by "Semantic-label-X".  So it may come
to people constantly requiring new semantic descriptors for new library
routines.  For example, if we just said "entertainment" or "games" for
section 6, then people might wonder where to put "Educational" (which,
historically has also, usually, been put under 6).  But in the case of
adding a new semantic label, we'd have to verify that whatever
platform you are thinking of that supports "semantic" labeled
documentation, supports that label....	(*ding*; lightbulb goes on);

	Hey: how about mansec[,label1[,label2[,label3...]]], where a
"man page" production routine: (to produce all manpages from a current
perl-tree containing "pod" and ".pm" sources) would only pay
attention to the parts it needs (mansec).  Formatting routines for other
systems could use as many keywords as supported.  Excess keywords would be
ignored.


>  5) Module::Build has an extensible mechanism for installing various 
> kinds of stuff.  ...
----
	I'm conceiving of running a tools long after the build&install
routines have come and gone.  For whatever reason, many of the .pod/.pm
files in my "/usr/<libperl" tree haven't made it into any mantree.
Whatever the reason, I'm trying to produce a perl script to scan the
<perllib> tree and populate a target man-tree with converted man pages.

>  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."
---
	Not arbitrary.  Based on efficiency.  The meta-tool called to
generate all docs from perllib tree to mantree needs to know the target
section before we open the output file.  The section number is also
included on the first line of the output file.  So having it occur
first allows the tree generator to scan as little as possible of the
input file before it is passed on to the "per-file" generator.

	_If_ it is a significant performance penalty to open the file twice,
I would even consider the tree generator passing off the 1st line to the
pod2man generator, and passing the file handle to the per-file generator (
or perhaps rewinding the filehandle, then passing it off).


>  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.
----
	Yup.  That's the current state of affairs.  I'm "used" to it
as well, but most of the stuff in section 1 isn't a "User command".
I.e. -- I'm proposing we get w/the picture and fix it.

	I'm contemplating the idea that generated manpages (and perhaps
internal man-sec numbers put on the manpages themselves), besides being
located by numeric section, have a "p" or "pm" suffix added to the number
for easier conceptual grouping of perl commands.  I'm very use to "p" being
used for perl man-docs right now, and admit, if it were not for my own
"coloring" (bias) I might suggest adding "pl/pm", but that just looks
ugly to my eyes.  Resulting files would still be in section "N", but the
files in, say man3, would have names of the format <name>.3pm[.xZx] or
<name>.3p[.xZx].

> 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.
---
	For most library routines there'd be no need for changes.  They
default to "3" now and would in the future.  It's mostly the perl-system
level documentation, which thankfully, less disperse and of less volume.

	Both the library-based user commands "GET" and "perltidy" already
"do the right thing" and install their documentation in (1).  If there are
any user-level commands that don't put their manpages in (1), maybe they
should be encouraged to?

	Thanks for the comments/input! :-)

-linda