New man pages

I've posted a tarball of new man pages at

ftp://postgresql.org/pub/doc/man.tar.gz

which were generated from the sgml sources used in the other docs.
There are a few new pages corresponding to applications like pgtclsh,
ipcclean, etc which were not documented in reference pages previously.

Also, the old man pages have been removed from the main branch of the
cvs repository (to take effect for the v6.6 release). All information
from those man pages appears somewhere else in the new docs; usually
in the reference pages but sometimes in a more suitable place.

Great. Good job.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Bruce Momjian wrote:

All information
from those man pages appears somewhere else in the new docs; usually
in the reference pages but sometimes in a more suitable place.

Great. Good job.

Thanks. So, at the moment we have man pages for section one (1) and
section ell (l). Is this the right section numbering for the future?
How did we choose the "ell"? Should we consider having some utilities
like initdb documented in, say, section eight (8)? How about having
sections like one-sql (1sql) or something similar?

It's easy to move things around, and I'm wondering if the current
scheme works for people. I don't have a strong opinion on this...

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

Bruce Momjian wrote:

All information
from those man pages appears somewhere else in the new docs; usually
in the reference pages but sometimes in a more suitable place.

Great. Good job.

Thanks. So, at the moment we have man pages for section one (1) and
section ell (l). Is this the right section numbering for the future?
How did we choose the "ell"? Should we consider having some utilities

It is very confusing. I think they chose 'l' for language. Does
someone want to suggest a better section number. Maybe just put them
all in 1.

like initdb documented in, say, section eight (8)? How about having
sections like one-sql (1sql) or something similar?

Oh, I get it. Can everyone handle multi-character man sections?

It's easy to move things around, and I'm wondering if the current
scheme works for people. I don't have a strong opinion on this...

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

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

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

Yes, that is a consideration. It is easy to automate adding a new
section (like "1sql" or "1p" or ??) for packages, but is something the
admin needs to remember to do on a from-source installation.

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

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

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

SCO does that. Section 1M.

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

Yes, that is a consideration. It is easy to automate adding a new
section (like "1sql" or "1p" or ??) for packages, but is something the
admin needs to remember to do on a from-source installation.

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

Oh, good point. How do we get around that. I don't see another
existing section that looks appropriate for SQL commands.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Thomas Lockhart wrote:

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

Pages from multi-character sections are stored in the directory for the
first character. For instance: /usr/man/man7/select.7l.gz

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

For Debian, I have relocated the SQL pages to section 7l and commands such
as psql and createuser go in section 1. Policy requires me to use one of
the numbered sections (1-8), though I can use a suffix to ensure uniqueness.

On Debian GNU/Linux, the sections are:
1 User commands
2 System calls
3 Library routines
4 Devices
5 File formats
6 Games
7 Miscellaneous
8 System administration

...

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.

As of course we do; for example, select is also in section 2.

*That* would be a bad thing. And in general adding ~75 man pages to
existing sections is a pretty big load...

I'm not sure that's much of a problem. These are the figures from my
system for /usr/man, /usr/share/man, /usr/X11R6/man and /usr/local/man
combined:

Section Count
1 2258
2 236
3 6554
4 39
5 236
6 26
7 128
8 517

--
Vote against SPAM: http://www.politik-digital.de/spam/
========================================
Oliver Elphick Oliver.Elphick@lfix.co.uk
Isle of Wight http://www.lfix.co.uk/oliver
PGP key from public servers; key ID 32B8FAA1
========================================
"If ye abide in me, and my words abide in you, ye shall
ask what ye will, and it shall be done unto you."
John 15:7

Pages from multi-character sections are stored in the directory for the
first character. For instance: /usr/man/man7/select.7l.gz

Oh! afaik that is one option; the man system in general could also
handle man7l/select.7.gz right? You would update /etc/man.config to
add, say, "7l" to the list of sections.

But is is against Debian policy to invent new directories for pages? I
see that my RH linux system actually does about the same as Debian;
there are some ".1x" files in the /usr/man/man1 directory.

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

For Debian, I have relocated the SQL pages to section 7l and commands such
as psql and createuser go in section 1. Policy requires me to use one of
the numbered sections (1-8), though I can use a suffix to ensure uniqueness.
On Debian GNU/Linux, the sections are:
1 User commands
2 System calls
3 Library routines
4 Devices
5 File formats
6 Games
7 Miscellaneous
8 System administration

Same for Linux ("man 7 man" has a summary).

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.

As of course we do; for example, select is also in section 2.

A near miss, since we weren't likely to have chosen section 2 for
*our* select. But it does illustrate the risk.

*That* would be a bad thing. And in general adding ~75 man pages to
existing sections is a pretty big load...

I'm not sure that's much of a problem. These are the figures from my
system for /usr/man, /usr/share/man, /usr/X11R6/man and /usr/local/man
combined:

Right.

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

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

Thomas Lockhart wrote:

Pages from multi-character sections are stored in the directory for the
first character. For instance: /usr/man/man7/select.7l.gz

Oh! afaik that is one option; the man system in general could also
handle man7l/select.7.gz right? You would update /etc/man.config to
add, say, "7l" to the list of sections.

But is is against Debian policy to invent new directories for pages?

6.1 Manual pages

You must install manual pages in nroff source form, in appropriate places
under /usr/share/man. You should only use sections 1 to 9 (see the FHS
^^^
FHS only defines 1 to 8; this may be an error

for more details). You must not install a preformatted `cat page'.

The FHS has a section (4.8.2) on manual pages, which we ought to follow
if possible: <http://www.pathname.com/fhs/2.0/fhs-4.8.2.html&gt;

--
Vote against SPAM: http://www.politik-digital.de/spam/
========================================
Oliver Elphick Oliver.Elphick@lfix.co.uk
Isle of Wight http://www.lfix.co.uk/oliver
PGP key from public servers; key ID 32B8FAA1
========================================
"If ye abide in me, and my words abide in you, ye shall
ask what ye will, and it shall be done unto you."
John 15:7

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

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

Oliver uses section 7 (miscellaneous...) for SQL commands, which seems
to be the right choice given the guidelines for Debian, RedHat, FHS,
and my imprecise impression of what is typical.

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.

Yeah, but "we" don't always install into /usr/local/pgsql, though we
can suggest that as a possibility.

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Is there any concern about using "l" (ell) for the section
discriminator?

So, I'll count you as not objecting to sections "1l" (one-ell) and
"7l" (seven-ell), ok?

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

On Tue, Aug 10, 1999 at 12:47:53PM +0000, Thomas Lockhart wrote:

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

Well, they make sense for _me_ but then, I run Debian and use Oliver's
packages ;-) As to the general proposal: put them in the nubmered sections
witha unique suffix. I'd suggest, however, at least a two character suffix:
how about pg? or sql? (tcl/tk uses section 3 with foo.3tcl and bar.3tk)

Ross
--
Ross J. Reedstrom, Ph.D., <reedstrm@rice.edu>
NSBRI Research Scientist/Programmer
Computer and Information Technology Institute
Rice University, 6100 S. Main St., Houston, TX 77005

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

Thomas Lockhart <lockhart@alumni.caltech.edu> writes:

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

Oliver uses section 7 (miscellaneous...) for SQL commands, which seems
to be the right choice given the guidelines for Debian, RedHat, FHS,
and my imprecise impression of what is typical.

7 works for me; there's not much there except a few kernel device
driver manpages on my box.

Is there any concern about using "l" (ell) for the section
discriminator?
So, I'll count you as not objecting to sections "1l" (one-ell) and
"7l" (seven-ell), ok?

How about "s" for "SQL"? ell is too easily mistaken for one; we'd
have to put "no, it's not section eleven" in the FAQ ...

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Er, why not "MANPATH=/usr/local/pgsql/man:$MANPATH" ?

regards, tom lane

Tom Lane wrote:

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.

But do remember us poor distribution maintainers. It makes life a lot
easier for us if upstream writers make an effort not to conflict with the
rest of the world!

If some local user or administrator puts PostgreSQL on his machine, it
may be appropriate to use /usr/local, but a PostgreSQL package installed as
part of a distribution should never use it.

--
Vote against SPAM: http://www.politik-digital.de/spam/
========================================
Oliver Elphick Oliver.Elphick@lfix.co.uk
Isle of Wight http://www.lfix.co.uk/oliver
PGP key from public servers; key ID 32B8FAA1
========================================
"If ye abide in me, and my words abide in you, ye shall
ask what ye will, and it shall be done unto you."
John 15:7

"Ross J. Reedstrom" <reedstrm@wallace.ece.rice.edu> writes:

I'd suggest, however, at least a two character suffix:

Doesn't work with the standard man(1) on either HPUX or SunOS...

regards, tom lane

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

Pages from multi-character sections are stored in the directory for the
first character. For instance: /usr/man/man7/select.7l.gz

Oh! afaik that is one option; the man system in general could also
handle man7l/select.7.gz right? You would update /etc/man.config to
add, say, "7l" to the list of sections.

But is is against Debian policy to invent new directories for pages? I
see that my RH linux system actually does about the same as Debian;
there are some ".1x" files in the /usr/man/man1 directory.

I have never seen a 'name.1x' or anything with a more than
single-character file prefix, and once it is formatted, it becomes
name.0. I don't see it buys us anything to do this. What we could do
is to put throw them in section 7, assuming there is no conflict. I
only have two pgp man pages in my 7.

I would like to use existing sections, rather than do our own. I found
I had to modify the man page search to look in a manl, and others may
have the same problem.

For Debian, I have relocated the SQL pages to section 7l and commands such
as psql and createuser go in section 1. Policy requires me to use one of
the numbered sections (1-8), though I can use a suffix to ensure uniqueness.
On Debian GNU/Linux, the sections are:
1 User commands
2 System calls
3 Library routines
4 Devices
5 File formats
6 Games
7 Miscellaneous
8 System administration

Same for Linux ("man 7 man" has a summary).

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.

As of course we do; for example, select is also in section 2.

A near miss, since we weren't likely to have chosen section 2 for
*our* select. But it does illustrate the risk.

*That* would be a bad thing. And in general adding ~75 man pages to
existing sections is a pretty big load...

I'm not sure that's much of a problem. These are the figures from my
system for /usr/man, /usr/share/man, /usr/X11R6/man and /usr/local/man
combined:

Right.

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

I agree with the 7, but see no need for the additional qualifier. I
think that could cause more problems than it is worth.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Is there any concern about using "l" (ell) for the section
discriminator?

So, I'll count you as not objecting to sections "1l" (one-ell) and
"7l" (seven-ell), ok?

Why not just put it in section 7, not 7l.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

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

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Er, why not "MANPATH=/usr/local/pgsql/man:$MANPATH" ?

'Cause MANPATH is not defined to start with. My point was that man
does a great job just using its configuration file, but if you start
using MANPATH you have to (apparently) figure out what paths were in
the config file and put those in too...

- Thomas

--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Er, why not "MANPATH=/usr/local/pgsql/man:$MANPATH" ?

'Cause MANPATH is not defined to start with. My point was that man
does a great job just using its configuration file, but if you start
using MANPATH you have to (apparently) figure out what paths were in
the config file and put those in too...

Yes, I have seen this too.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

On Tue, 10 Aug 1999, Tom Lane wrote:

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.

Jumping in mid-stream and a week late (love holidays, eh? *grin*) ... My
opinion is to make the default ${PREFIX}/man and have a --manpath=
variable set to configure to move it to a different place...

I *believe* that Oracle installs its man pages under its install
directory, but can't confirm right now...

Marc G. Fournier ICQ#7615664 IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org secondary: scrappy@{freebsd|postgresql}.org

On Tue, 10 Aug 1999, Brook Milligan wrote:

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

Just a quick note, but, under FreeBSD *at least*, X11 puts its man pages
in /usr/X11R6/man/* ... so it doesn't conflict with "system" man pages...

Marc G. Fournier ICQ#7615664 IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org secondary: scrappy@{freebsd|postgresql}.org

On Wed, 11 Aug 1999, Thomas Lockhart wrote:

btw, on my Solaris boxes MANPATH is worse than useless; if you specify
it then none of the other paths mentioned in /etc/man.config (or
wherever that is on Solaris) get used. So you have to recreate all of
the default MANPATH settings in your environment variable. Of course,
now that I've whined about this perhaps someone knows a way around
this?

Er, why not "MANPATH=/usr/local/pgsql/man:$MANPATH" ?

'Cause MANPATH is not defined to start with. My point was that man
does a great job just using its configuration file, but if you start
using MANPATH you have to (apparently) figure out what paths were in
the config file and put those in too...

Okay, I run Solaris at work (2.5.x -> 7) and have yet to find a
/etc/man.config file...I've always used MANPATH here :(

Marc G. Fournier ICQ#7615664 IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org secondary: scrappy@{freebsd|postgresql}.org