Re: REINDEX VERBOSE iso-8859-1 option - Mailing list pgsql-general

On 2019-11-21 09:43:26 +0000, Geoff Winkless wrote:
> On Wed, 20 Nov 2019 at 22:48, Peter J. Holzer <hjp-pgsql@hjp.at> wrote:
> >
> > On 2019-11-19 11:37:04 +0000, Geoff Winkless wrote:
> > > Even if you do that you're still requiring the user to parse syntax
> > > according to esoteric rules.
> >
> > Oh, please. Those "esoteric rules" have been in wide-spread use for
> > decades.
>
> It wasn't meant to be insulting, I meant "esoteric" in the strict
> sense: that you need to have specific knowledge to parse them.

I didn't understand it as insulting (why would I?), but don't think this
convention is "requiring ... knowledge that is restricted to a small
group" (Merriam-Webster). This specific convention for conveying grammar
rules is in my experience by far the most common (before BNF and
diagrams). Anybody who has read any documentation about any formal
language (e.g., a programming language, a query language, a markup or
configuration language) has very likely encountered it before.

Yes, you need specific knowledge to understand the PostgreSQL
documentation. For starters, you need to know English (or one the
handful languages in which it has been translated). You need to know
what a relational database is and why and how you would use one. You
need some generic knowledge about computing (what is a "client/server
model"? How do I start a command line tool?), etc. The convention for
describing the grammar is probably the least concern, and besides, it is
explained in the manual (unlike some concepts which are assumed to be
known).


> My point was that modifying the rules (by making certain things bold
> or italic) wouldn't really solve the problem - if you don't know what
> the rules are, you're unlikely to be any better off if someone adds to
> them.

Man is a pattern-matching animal. Even without an explicit explanation,
humans are quite good at deriving meaning from repeated patterns. So if
the parts you have to type verbatim are always printed in bold and parts
which have a meta-meaning are always printed in italic and optional
parts are always enclosed in (italic) square brackets, people are very
likely to understand that
    <i>[</i> <b>( VERBOSE )</b> <i>]</i>
means that "( VERBOSE )" must be typed as is, but is optional. Even if
they can't tell you the rules. Simply because they have seen it a few
dozen times before. There is a reason why almost any technical
documentation uses some typographical convention and why those
conventions are almost always very similar.

The PostgreSQL manual unfortunately uses the same typographic convention
for meta-characters ([], {}, |, ...) and terminals, which isn't as clear
as it could be.

        hp

--
   _  | Peter J. Holzer    | Story must make more sense than reality.
|_|_) |                    |
| |   | hjp@hjp.at         |    -- Charles Stross, "Creative writing
__/   | http://www.hjp.at/ |       challenge!"