From: Tom Lane <tgl@sss.pgh.pa.us>
To: mjf@mjf.cz
cc: pgsql-docs@lists.postgresql.org
Subject: Re: Documentation on pgdump(1) uses "regular expression" instead of
 "psql pattern"
In-reply-to: <166384399811.653.17044611374895108084@wrigleys.postgresql.org>
References: <166384399811.653.17044611374895108084@wrigleys.postgresql.org>
Comments: In-reply-to PG Doc comments form <noreply@postgresql.org>
	message dated "Thu, 22 Sep 2022 10:53:18 -0000"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <2030442.1663899436.1@sss.pgh.pa.us>
Date: Thu, 22 Sep 2022 22:17:16 -0400
Message-ID: <2030443.1663899436@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/2030443.1663899436%40sss.pgh.pa.us>
Precedence: bulk

PG Doc comments form <noreply@postgresql.org> writes:
> the [1] uses term "regular expression" where "psql pattern" [2] should be
> used instead which
> may be misleading (and might cause even some harm in some edge usage
> cases).

> I therefor propose to improve the documentation by emphasizing (strongly)
> the fact that the
> "regular expression" is in fact (psql) "pattern" and have nothing to do with
> *common* regular
> expressions and therefor extra care should be taken when using them.

Hmm.  I looked at this but I think that the existing wording is fine.
The definitions of the switches, earlier on the same page, correctly
state that they use psql-style patterns, and provide cross-references
to that documentation.  Moreover, the context of this is that the
preceding example already uses shell-pattern notation:

    To dump all schemas whose names start with east or west and end in
    gsm, excluding any schemas whose names contain the word test:

    $ pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql

    The same, using regular expression notation to consolidate the switches:

    $ pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql

We could write something wishy-washy like "additional pattern-matching
notation", but the psql Patterns section specifically uses "regular
expression notation" to describe these extensions to normal shell
patterns, and that's completely correct because they *are* standard
regular expression notations.  So I think being consistent with that
is more useful than writing something else.  Also, we have five
cross-references to Patterns on that page already, so I don't think
a sixth would add much.

			regards, tom lane