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

Brook Milligan <brook@biology.nmsu.edu> writes:
> Thus, it seems that documentation for user commands, e.g., CREATE
> TABLE, SELECT, UPDATE, ... should go into section 1,

No.  Section 1 is exclusively for *programs*, ie, commands available
at a shell command line.  There isn't really anyplace in the standard
man conventions to put a separate man page for each command accepted
by a single program, which is what SQL language constructs are.
We're usurping more "man page namespace" than we ought to by putting
each SQL construct on its own man page.  However, one man page for
the whole of SQL isn't too appealing, so we have little choice.
The proposal to put 'em in section 7 sounded reasonable to me.

> 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.

These would make sense, but you start to run into some of the
cross-platform idiosyncracies in section usage as soon as you go past
section 3.  For example, on HPUX file format docs live in section 4,
and admin commands live in section 1m.  I don't think HP invented those
conventions on their own --- they are probably common to a lot of
old-line SysV-derived Unixes.  The Debian conventions that Oliver
mentioned look like they descend from BSD Unix.

I agree with putting the libpq etc. APIs in section 3, assuming we still
have man pages for them at all (at one time there was talk of dropping
those manpages in favor of the chapters in the SGML docs).  I'd be
inclined to just put createdb and friends in section 1, rather than
worrying about where they should go to classify them as admin commands...
        regards, tom lane