On Thu, Dec 13, 2012 at 7:24 PM, Karl O. Pinc <kop@meme.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