Re: Conventions

On Wed, Jan 26, 2022 at 09:33:58PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > OK, updated patch attached.  I don't think we even show TCL syntax
> > anywhere anymore, so I removed that text, rather than moving it.
> 
> I really don't care for this phrasing at all:
> 
> -     the body of a PL/Tcl function:
> +     the body of a PL/Tcl function (brackets (<literal>[</literal> and
> +     <literal>]</literal>) are represented here as question marks):
> 
> It's unclear whether you mean actual brackets or metasyntactic brackets;
> somebody who hasn't completely internalized the notion of brackets as
> indicating optional elements would be particularly likely to
> misunderstand.
> 
> I'd also suggest that wedging this into a parenthetic remark between a
> sentence and the example the sentence is talking about is awkward.
> 
> I'd suggest a separate para at some point before the first usage,
> along the lines of
> 
>    In this section, we follow the usual Tcl convention of using question
>    marks, rather than brackets, to indicate an optional element in a
>    syntax synopsis.

Oh, then I didn't understand it either.  I know Tcl uses brackets for
stuff so I thought there was some weird syntax that represented brackets
as something else.  Anyway, updated patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  If only the physical world exists, free will is an illusion.