On Mon, 18 Nov 2019 at 22:24, Peter J. Holzer <hjp-pgsql@hjp.at> wrote:
>
> On 2019-11-18 12:24:40 +0000, Geoff Winkless wrote:
> > On Mon, 18 Nov 2019 at 11:46, Michael Paquier <michael@paquier.xyz> wrote:
> > > On Mon, Nov 18, 2019 at 10:27:24AM +0100, Josef Šimánek wrote:
> > > > This is clear once you understand what does it mean. I was aware of VERBOSE
> > > > option of EXPLAIN and tried to use it without needed parentheses (the same
> > > > way EXPLAIN can understand it). In the parameter list of REINDEX, it is
> > > > still called VERBOSE (not "( VERBOSE )") and there's no info
> > > > that parentheses are needed.
> [...]
> > But if the parentheses are part of the parameter, I think putting the
> > parentheses in the parameter list might be a good compromise.
>
> The parentheses aren't part of the parameter. They are part of the
> syntax of the command.
Then at the very least draw attention to the fact that the parentheses
are required in the description of the parameter in the notes.
It's bad enough that you have the inconsistency that REINDEX VERBOSE
requires parentheses while the more recent REINDEX CONCURRENTLY does
not (presumably to match the syntax of CREATE INDEX CONCURRENTLY),
without insisting that the user parse the difference between { and (
in the manual (not the easiest difference to scan) before they can use
the command.
> How about this?
>
> * Terminals (stuff that has to be typed as shown) in bold.
>
> * Non-Terminals (stuff which has to be replaced) in italic.
>
> * Meta-characters ([, ], |, ...) in regular type.
Even if you do that you're still requiring the user to parse syntax
according to esoteric rules. I'm not sure that changing the rules
helps that much.
Geoff