pg.ddx.io  pgsql-committers@postgresql.org mailing list archive  
help / color / mirror / Atom feed
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Peter Smith <smithpb2250@gmail.com>
Cc: Amit Kapila <akapila@postgresql.org>
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: pgsql: Doc: Explain about Column List feature.
Date: Tue, 20 Dec 2022 09:21:38 +0100
Message-ID: <20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql> (raw)
In-Reply-To: <CAHut+Pu+m_U6VoZBiLkr+d9K05CtX8XjepzqECpFEzYyd17t-w@mail.gmail.com>

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/





view thread (17+ messages)  latest in thread

Message-ID: <20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql>
Permalink:  ../20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql/
Also on:    postgresql.org/message-id/20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql

 · 

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients from your mail client; the link fills in
  the headers below: reply via email
  Some clients, webmail especially, drop In-Reply-To and References from
  a link, and the reply then starts a new thread: use the mbox below.

  To: pgsql-committers@postgresql.org
  Cc: alvherre@alvh.no-ip.org, smithpb2250@gmail.com, akapila@postgresql.org, pgsql-hackers@lists.postgresql.org
  Subject: Re: pgsql: Doc: Explain about Column List feature.
  In-Reply-To: <20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql>
  References: <CAHut+Pu+m_U6VoZBiLkr+d9K05CtX8XjepzqECpFEzYyd17t-w@mail.gmail.com> <20221220082138.mmyd3hklvrkdib4s@alvherre.pgsql>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

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