pg.ddx.io pgsql-docs@postgresql.org mailing list archivehelp / color / mirror / Atom feed
Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" 2+ messages / 2 participants [nested] [flat]
* Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" @ 2022-09-22 10:53 PG Doc comments form <noreply@postgresql.org> 2022-09-23 02:17 ` Re: Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" Tom Lane <tgl@sss.pgh.pa.us> 0 siblings, 1 reply; 2+ messages in thread From: PG Doc comments form @ 2022-09-22 10:53 UTC (permalink / raw) To: pgsql-docs@lists.postgresql.org; +Cc: mjf@mjf.cz The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/app-pgdump.html Description: Hello. 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. (From my point of view, the best would be to lead the reader directly to the [2], preferably somewhere at the beginning of the document/page, and also mention it again in the section with the examples by replacing the wrong term "regular expressions" with "patterns" hyperlinked to [2].) - [1] https://www.postgresql.org/docs/current/app-pgdump.html#PG-DUMP-EXAMPLES - [2] https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-PATTERNS Sincerely, -- mjf ^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" 2022-09-22 10:53 Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" PG Doc comments form <noreply@postgresql.org> @ 2022-09-23 02:17 ` Tom Lane <tgl@sss.pgh.pa.us> 0 siblings, 0 replies; 2+ messages in thread From: Tom Lane @ 2022-09-23 02:17 UTC (permalink / raw) To: mjf@mjf.cz; +Cc: pgsql-docs@lists.postgresql.org 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 ^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2022-09-23 02:17 UTC | newest] Thread overview: 2+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2022-09-22 10:53 Documentation on pgdump(1) uses "regular expression" instead of "psql pattern" PG Doc comments form <noreply@postgresql.org> 2022-09-23 02:17 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions for how to clone and mirror all data and code used for this inbox