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

On Tue, Dec 20, 2022 at 3:47 AM Alvaro Herrera <alvherre@alvh.no-ip.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