Re: [HACKERS] Re: [ANNOUNCE] New man pages

Thomas Lockhart <lockhart@alumni.caltech.edu> writes:
>> Oh, I get it.  Can everyone handle multi-character man sections?
>
> That is how, for example, the X system does their man pages. There are
> sections "1x", etc. Except that now that I look on my RH linux system
> they are squirreled away in /usr/X11/man/man1/, etc so I must have
> seen that on another system. Perhaps my old Alpha boxes??

HPUX, as usual, is off in left field somewhere: they use 1m for sysadmin
commands, but everything else just goes into the single-digit-named
subdirectories (man1, man3, etc).  There is no separate namespace for
section 3c vs. section 3m, for example --- all those man pages live in
man3.  And sections named by a bare letter don't work at all.  AFAICT
this section search logic is implemented by hardwired hacks in the guts
of man(1) --- there is no way to affect it with MANPATH, for example,
because MANPATH determines where the manual root directories are, not
which subdirectories get looked at.

Newer implementations of man(1) are probably cleaner, but I fear that
HPUX's may be representative of what you'll find on older Unixes.

I'd like to see us change away from putting SQL commands in section l
(ell), simply because that doesn't work on HPUX.  Something like 8l
or 8s would work a lot better for me.  However, I'm not sure which
major section to use --- there doesn't seem to be very much cross-
platform standardization about the meanings of the sections beyond 4.
On BSD, section 8 seems to contain admin programs (the stuff HPUX
keeps in 1m).  I don't see any sections on either my HPUX box or
a nearby BSD box that contain pages for individual keywords of
a programming language...

> otoh, it does eliminate the possibility of man page pollution if we
> manage to have the same man page name as some other existing page.
> *That* would be a bad thing. And in general adding ~75 man pages to
> existing sections is a pretty big load...

As long as we install into /usr/local/pgsql/man/man*, naming conflicts
with other packages aren't too big a deal --- there's no physical file
conflict, and people can just add or remove /usr/local/pgsql/man/ in
their MANPATH settings to see or not see Postgres manpages.
        regards, tom lane