Re: Conventions

On Wed, Jan 26, 2022 at 09:33:58PM -0500, Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)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(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

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