Re: Multiple --table options for other commands

On Thu, Dec 13, 2012 at 7:24 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:

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

FWIW, `man cat` on my OS X machine has synopsis:

cat [-benstuv] [file ...]

though I see:

cat [OPTION] [FILE]...

on Debian.

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

Yeah, I tried a few different ways and didn't manage to get:
[ --table | -t table ] ...

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

That should be how the v2 patch has it.

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

If someone out there feels that the formatting of these commands'
synopses should look like:
[ --table | -t table ] ...

and knows how to massage the SGML to get that, I'm happy to
accommodate the change. Otherwise, I think either the v4 or v2 patch
should be acceptable.

Josh