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

------- Start of forwarded message -------
So, do Oliver's conventions make sense for most platforms? istm that
they do. Would folks have problems with a mapping similar to what
Oliver uses? We would use section one (1) and section seven (7), with
a qualifier of ell (l) on each of the man page names. I won't do
anything about it right now, but would like to get a consensus now
that the subject has come up. Speak up now or forever hold your...

OK, I'll speak up. :)

This doesn't make too much sense to me based on my experience with
zillions of other man pages.

A quick look through all of my system-supplied, X11, and locally
installed man pages in section 1 shows none with any suffix other than
.1 or .1.gz. What exactly is the point of a .1l or whatever? Is it
just to avoid name collisions? If so, why not use something more
meaningful, like .1sql? Note that the downside of any "odd" suffix,
though, is that the man system will likely need reconfiguring so as to
recognize it. This will add an extra installation step, one that
probably cannot be easily automated. Perhaps a relevant question here
is, how likely is a name collision anyway? Is it likely enough to
require reconfiguration of the man system for all users?

As far as sections go, I think the following conventions apply for
sections of relevance to PostgreSQL:

1 - most of the commands which comprise the user environment
3 - an overview of the library functions, their error returns and
other common definitions and concepts
5 - documentation on binary and configuration file formats
8 - information related to system operation and maintenance

Thus, it seems that documentation for user commands, e.g., CREATE
TABLE, SELECT, UPDATE, ... should go into section 1, the API to
libpq/libpq++/libpgtcl/... should go into section 3, configuration
files like pg_hba.conf should go into section 5, and admin commands,
e.g., createdb, createuser, pg_dump, ... should go into section 8.

Cheers,
Brook