From: | Peter Smith <smithpb2250(at)gmail(dot)com> |
---|---|
To: | Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> |
Cc: | Amit Kapila <akapila(at)postgresql(dot)org>, pgsql-hackers(at)lists(dot)postgresql(dot)org |
Subject: | Re: pgsql: Doc: Explain about Column List feature. |
Date: | 2022-12-20 04:27:58 |
Message-ID: | CAHut+Pu+m_U6VoZBiLkr+d9K05CtX8XjepzqECpFEzYyd17t-w@mail.gmail.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-committers pgsql-hackers |
On Tue, Dec 20, 2022 at 3:47 AM Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> wrote:
>
> On 2022-Sep-15, Alvaro Herrera wrote:
>
> > On 2022-Sep-15, Alvaro Herrera wrote:
> >
> > > Looking at the rendered docs again, I notice that section "31.4.5.
> > > Combining Multiple Column Lists" is *only* the red-tinted Warning block.
> > > That seems quite odd. I am tempted to remove the sect2 heading for that
> > > one too.
> >
> > Pushed. I didn't modify this part; I spent too much time looking at it
> > trying to figure out how to do it. I think this bit really belongs in
> > the CREATE/ALTER docs rather than this chapter. But in order to support
> > having a separate <para> for the restriction on combination, we need a
> > separate <varlistentry> for the column_name parameter. So I'm going to
> > edit that one and I'll throw this change in.
>
> I figured out how to fix this one -- just remove the <sect2> tags, and
> add a <title> tag to the <warning> box. The attached yields the
> explanatory text in a separate box that doesn't have the silly
> otherwise-empty section title. We add the 'id' that was in the sect2 to
> the warning; with this, at the referencing end the full title is
> rendered, which looks quite reasonable. I have attached screenshots of
> both sides of this.
>
> Compare the existing
> https://www.postgresql.org/docs/15/logical-replication-col-lists.html#LOGICAL-REPLICATION-COL-LIST-COMBINING
>
> Unless there are objections, I'll get this pushed to 15 and master.
>
Not quite an objection, but...
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.
Maybe a safer way to fix this "silly otherwise-empty section title"
would be to just add some explanatory text so it is no longer empty.
------
Kind Regards,
Peter Smith.
Fujitsu Australia
From | Date | Subject | |
---|---|---|---|
Next Message | Michael Paquier | 2022-12-20 04:38:27 | pgsql: Add pg_dissect_walfile_name() |
Previous Message | Amit Kapila | 2022-12-20 03:27:55 | Re: pgsql: Doc: Explain about Column List feature. |
From | Date | Subject | |
---|---|---|---|
Next Message | Michael Paquier | 2022-12-20 04:40:00 | Re: Add LSN along with offset to error messages reported for WAL file read/write/validate header failures |
Previous Message | Dilip Kumar | 2022-12-20 04:23:02 | Re: Add sub-transaction overflow status in pg_stat_activity |