On Thu, Dec 13, 2012 at 7:24 PM, Karl O. Pinc <k...@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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers