Re: pgsql: Doc: Explain about Column List feature.

On 2022-Dec-20, Peter Smith wrote:

> If you change this warning title then it becomes the odd one out -
> every other warning in all the pg docs just says "Warning". IMO
> maintaining consistency throughout is best. e.g. I can imagine maybe
> someone searching for "Warning" in the docs, and now they are not
> going to find this one.

Hmm, how do you propose that people search for warnings, and fail to
notice one that is not titled "Warning"? In my mind, it is much more
likely that they scan a page visually until they hit a red box ("eh
look, a red box that I can ignore because its title is not Warning" does
not sound very credible). On the other hand, if you're going over the
source .sgml files, you're going to grep for the warning tag, and that's
going to be there.

(Maybe you'd say somebody would grep for "<warning>" and not find this
one because the > is not there anymore. I grant you that that could
happen. But then they're doing it wrong already. I don't think we need
to cater to that.)

Now, I did notice that we don't have any other titled warning boxes,
because I had a quick look at all the other warnings we have. I was
surprised to find out that we have very few, which I think is good,
because warnings are annoying. I was also surprised that most of them
are right not to have a title, because they are very quick one-para
boxes. But I did find two others that should probably have a title:

https://www.postgresql.org/docs/15/app-pgrewind.html
Maybe "Failures while rewinding"

https://www.postgresql.org/docs/15/applevel-consistency.html
Maybe "Serializable Transactions and Data Replication"
(and patch it to mention logical replication)

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/