Re: Multiple --table options for other commands - Mailing list pgsql-hackers

On 12/13/2012 07:37:27 PM, Josh Kupershmidt wrote:
> On Thu, Dec 13, 2012 at 6:05 AM, Karl O. Pinc <kop@meme.com> wrote:
> > On 12/13/2012 12:35:14 AM, Karl O. Pinc wrote:
> >
> >> On 12/12/2012 11:04:53 PM, Josh Kupershmidt wrote:
> >> > On Wed, Dec 12, 2012 at 8:14 AM, Karl O. Pinc <kop@meme.com>
> wrote:
> >> > > On 12/11/2012 10:25:43 PM, Josh Kupershmidt wrote:
> >> > >> On Tue, Dec 11, 2012 at 11:46 AM, Karl O. Pinc <kop@meme.com>
> >> > wrote:
> >> > >> >> I believe you need ellipses behind --table in the syntax
> >> > summaries
> >> > >> >> of the command reference docs.
> >>
> >>
> >> > > Yes.  I see.  I didn't look at all the command's reference
> pages
> >> > > but did happen to look at clusterdb, which does have --table
> >> > > in the syntax summary.  I just checked and you need to fix
> >> > > clusterdb, reindexdb, and vacuumdb.
> >> >
> >> > OK, I made some changes to the command synopses for these three
> >> > commands.
> >
> >> I want the ... outside the square braces, because the --table (or
> -t)
> >> must repeat for each table specified.  Like:
> >>
> >> vacuumdb [connection-option...] [option...] [ --table | -t table
> >> [( column [,...] )] ]... [dbname]
> >>
> >> reindexdb [connection-option...] [ --table | -t table ]... [
> --index
> >> |
> >>
> >> -i index ]... [dbname]
> >
> >> Have you had trouble getting this to work?
> >
> > Perhaps <arg choice="opt"><arg rep="repeat"> ... would work?
>
> Well, I fooled around with the SGML for a bit and came up with
> something which has the ellipses in brackets:
>
>   [ --table | -t table ] [...]
>
> which I like a little better than not having the second set of
> brackets. New version attached.

The problem is that the pg man pages would then have a
syntax different from all the other man pages in the system,
which all have ... outside of square braces.
See "man cat", e.g.
(I wonder if the problem is because the style sheets
have been tweaked to work well with sql?)

Because I don't see the traditional man page ellipsis syntax
anywhere in the pg docs, and because all the pg
client command line programs that use repeating arguments
all have a simplified syntax summary with just [options ...]
or some such, I suspect that there may be a problem
putting the ellipsis outside of the square braces.

It would be nice if we could get some guidance from someone
more familiar with the pg docbook stylesheets.

As a fallback I'd do to the clusterdb, reindexdb, and vacuumdb
syntax summaries what was done to the pg_dump and pg_restore
syntax summaries.  Remove all the detail.  This is sucky,
and _still_ leaves the reference pages with a syntax summary syntax
that differs from regular man pages, but because the text
is relatively information free nobody notices.

My inclination, since you can't make it work
and we don't seem to be getting any help here,
is to remove all the detail in the syntax summaries,
push it through to a committer, and get some feedback that way.

Regards,

Karl <kop@meme.com>
Free Software:  "You don't pay back, you pay forward."                -- Robert A. Heinlein