Re: pgsql: Doc: Explain about Column List feature. - Mailing list pgsql-hackers

On Tue, Dec 20, 2022 at 7:21 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> 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.)
>

By "searching" I also meant just scanning visually, although I was
thinking more about scanning the PDF.

Right now, the intention of any text box is obvious at a glance
because of those titles like "Caution", "Tip", "Note", "Warning".
Sure, the HTML rendering also uses colours to convey the purpose, but
in the PDF version [1] everything is black-and-white so apart from the
title all boxes look the same. That's why I felt using non-standard
box titles might be throwing away some of the meaning - e.g. the
reader of the PDF won't know anymore at a glance are they looking at a
warning or a tip.

>
> 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)
>

------
[1] PDF docs - https://www.postgresql.org/files/documentation/pdf/15/postgresql-15-A4.pdf

Kind Regards,
Peter Smith.
Fujitsu Australia