Обсуждение: rc1 tarball contains partially outdated/missing man pages
I noticed that the rc1 tarball does not contain man pages for CREATE/ALTER/DROP FOREIGN DATA WRAPPER/SERVER/USER MAPPING. But it does contain man pages for TABLE and WITH, so it appears to be 8.4 material. Can someone check, or remind me how the man pages end up in the tarball?
Peter Eisentraut <peter_e@gmx.net> writes:
> Can someone check, or remind me how the man pages end up in the tarball?
They're supposed to be built on the fly, and the file dates in the rc1
tarball do appear to match the time of tarball building. Do you get
what you expect if you build the man pages locally?
One thing I notice is that the "table" and "with" entries are not coming
out as intended. The file names are all caps:
-rw-r--r-- 1 tgl users 18 Jun 12 01:37 WITH.7
-rw-r--r-- 1 tgl users 18 Jun 12 01:37 TABLE.7
and the content surely isn't what was meant:
$ more TABLE.7
.so man7/SELECT.7
$ more WITH.7
.so man7/SELECT.7
regards, tom lane
Peter Eisentraut <peter_e@gmx.net> writes:
> I noticed that the rc1 tarball does not contain man pages for
> CREATE/ALTER/DROP FOREIGN DATA WRAPPER/SERVER/USER MAPPING.
Just eyeballing the files, I notice that those ref pages seem not
to contain this boilerplate:
<manvolnum>7</manvolnum>
which is mostly(?) present in others. Maybe the cause?
regards, tom lane
I wrote:
> One thing I notice is that the "table" and "with" entries are not coming
> out as intended. The file names are all caps:
> -rw-r--r-- 1 tgl users 18 Jun 12 01:37 WITH.7
> -rw-r--r-- 1 tgl users 18 Jun 12 01:37 TABLE.7
> and the content surely isn't what was meant:
> $ more TABLE.7
> .so man7/SELECT.7
> $ more WITH.7
> .so man7/SELECT.7
BTW, as far as that particular point goes: maybe we could fix the tools
issues underlying this, but I'm tempted to think that it's not worth the
trouble, because making these man pages be aliases for SELECT is just
the Wrong Thing anyway. I think we should just split them off and have
them be documented as separate top-level reference pages. Doing that
for TABLE is clearly fairly sensible; and as for WITH, the current
approach is going to fail miserably anyhow as soon as we allow WITH
to be prefixed to INSERT/UPDATE/DELETE. Which is something that was
already requested, and I see no semantic or implementation reason not
to allow (in 8.5 of course, not now). So I'm thinking we make a man
page for WITH as such, and cross-reference it from SELECT, moving the
current discussion of CTEs over.
regards, tom lane
On Thursday 18 June 2009 22:48:53 Tom Lane wrote: > Peter Eisentraut <peter_e@gmx.net> writes: > > I noticed that the rc1 tarball does not contain man pages for > > CREATE/ALTER/DROP FOREIGN DATA WRAPPER/SERVER/USER MAPPING. > > Just eyeballing the files, I notice that those ref pages seem not > to contain this boilerplate: > > <manvolnum>7</manvolnum> > > which is mostly(?) present in others. Maybe the cause? Great find. -- Fixed.
On Thursday 18 June 2009 23:15:53 Tom Lane wrote: > I wrote: > > One thing I notice is that the "table" and "with" entries are not coming > > out as intended. The file names are all caps: > > > > -rw-r--r-- 1 tgl users 18 Jun 12 01:37 WITH.7 > > -rw-r--r-- 1 tgl users 18 Jun 12 01:37 TABLE.7 > > > > and the content surely isn't what was meant: > > > > $ more TABLE.7 > > .so man7/SELECT.7 > > $ more WITH.7 > > .so man7/SELECT.7 The content is pretty much what was meant, except that the case is wrong. Typing "man SELECT" will find a lower case select.7 man page, but the .so mechanism apparently doesn't. The simple fix is to convert all man page names to upper case, which is the default in the tools anyway. > BTW, as far as that particular point goes: maybe we could fix the tools > issues underlying this, but I'm tempted to think that it's not worth the > trouble, because making these man pages be aliases for SELECT is just > the Wrong Thing anyway. I think we should just split them off and have > them be documented as separate top-level reference pages. Umm, the reason why it is that way now is that you did not want them to be separate top-level man pages: http://archives.postgresql.org/message-id/19886.1226171409@sss.pgh.pa.us
Peter Eisentraut <peter_e@gmx.net> writes: > On Thursday 18 June 2009 23:15:53 Tom Lane wrote: >> BTW, as far as that particular point goes: maybe we could fix the tools >> issues underlying this, but I'm tempted to think that it's not worth the >> trouble, because making these man pages be aliases for SELECT is just >> the Wrong Thing anyway. I think we should just split them off and have >> them be documented as separate top-level reference pages. > Umm, the reason why it is that way now is that you did not want them to be > separate top-level man pages: > http://archives.postgresql.org/message-id/19886.1226171409@sss.pgh.pa.us Well, at the time I thought that WITH would only be a sub-clause of SELECT. The idea that we might allow it to be attached to INSERT etc causes me to revise my opinion a bit. Do you have a preference one way or the other about how to do this? regards, tom lane
On Friday 19 June 2009 19:12:50 Tom Lane wrote: > Well, at the time I thought that WITH would only be a sub-clause of > SELECT. The idea that we might allow it to be attached to INSERT etc > causes me to revise my opinion a bit. Do you have a preference one > way or the other about how to do this? I can't really imagine it right now, but when INSERT actually supports this, I'm sure we can come up with something. At the moment I'm concentrating on tweaking it so that the current setup works in 8.4. Which I think it does now, but it would be good if others could give the man pages themselves and their installation some extra testing in rc2.