pg.ddx.io pgsql-docs@postgresql.org mailing list archivehelp / color / mirror / Atom feed
Section 9.7.3.2. Bracket Expressions should be rewritten 2+ messages / 2 participants [nested] [flat]
* Section 9.7.3.2. Bracket Expressions should be rewritten @ 2022-10-12 14:08 PG Doc comments form <noreply@postgresql.org> 2022-10-13 00:11 ` Re: Section 9.7.3.2. Bracket Expressions should be rewritten Tom Lane <tgl@sss.pgh.pa.us> 0 siblings, 1 reply; 2+ messages in thread From: PG Doc comments form @ 2022-10-12 14:08 UTC (permalink / raw) To: pgsql-docs@lists.postgresql.org; +Cc: zack02469@yahoo.com The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/functions-matching.html Description: I am a Postgres newbie, and I find this part of what is generally excellent documentation quite confusing. It contains the following disclaimer: Note PostgreSQL currently does not support multi-character collating elements. This information describes possible future behavior. I am very skeptical of the idea of documentation describing "possible future behavior." Unless carefully done, this is guaranteed to cause confusion to newbies such as myself. In this case, it is very unclear as to what the disclaimer refers to. Is it referring to the previous 3 paragraphs, the following 3 paragraphs, some subset of those paragraphs, or the entire section? If reference to possible future behavior is deemed absolutely necessary, then IMHO that portion of the docs should be blockquoted and clearly marked as being forward-looking and not part of present behavior. Furthermore, it appears that this disclaimer has been part of the docs since at least version 10, so it's not even clear that this feature is even currently being seriously considered for implementation. ^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Section 9.7.3.2. Bracket Expressions should be rewritten 2022-10-12 14:08 Section 9.7.3.2. Bracket Expressions should be rewritten PG Doc comments form <noreply@postgresql.org> @ 2022-10-13 00:11 ` Tom Lane <tgl@sss.pgh.pa.us> 0 siblings, 0 replies; 2+ messages in thread From: Tom Lane @ 2022-10-13 00:11 UTC (permalink / raw) To: zack02469@yahoo.com; +Cc: pgsql-docs@lists.postgresql.org PG Doc comments form <noreply@postgresql.org> writes: > I am a Postgres newbie, and I find this part of what is generally excellent > documentation quite confusing. It contains the following disclaimer: > Note > PostgreSQL currently does not support multi-character collating elements. > This information describes possible future behavior. > I am very skeptical of the idea of documentation describing "possible future > behavior." What that means is "we don't implement this, but it's required by POSIX, so we really ought to get around to it someday". I have considered the idea of deleting mention of multi-character collating elements from the preceding paragraph, but then we'd be left with nothing but a statement that "[.x.]" means the same thing as "x" inside a bracket expression. Which is weird and confusing enough that we'd still have to talk about multi-character collating elements in order to explain why it's like that. > Furthermore, it appears that this disclaimer has been part of the docs since > at least version 10, so it's not even clear that this feature is even > currently being seriously considered for implementation. Hah! Look a bit further back :-( regards, tom lane ^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2022-10-13 00:11 UTC | newest] Thread overview: 2+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2022-10-12 14:08 Section 9.7.3.2. Bracket Expressions should be rewritten PG Doc comments form <noreply@postgresql.org> 2022-10-13 00:11 ` 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