Обсуждение: 31.7.1. Initial Snapshot

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/16/logical-replication-architecture.html
Description:

There are dublicated section named "31.7.1. Initial Snapshot" on
https://www.postgresql.org/docs/16/logical-replication-architecture.html

On 2023-Oct-11, PG Doc comments form wrote:

> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/16/logical-replication-architecture.html
> Description:
> 
> There are dublicated section named "31.7.1. Initial Snapshot" on
> https://www.postgresql.org/docs/16/logical-replication-architecture.html

Yeah, that looks a bit ugly ... but actually the first line you see with
that text is the table-of-contents for the page.  Since there's a single
section in that chapter, the TOC looks like a section title.  You can
probably find several pages in the docs where this happens.

Maybe a fix for this would be to style chapter TOCs in some way that
makes it clear that they are TOCs -- for example, add a (subtly) visible
bounding box, or something.  Or maybe if a chapter has a single section,
just do not print the TOC at all.  I have no idea how to implement such
a fix, or whether it'd be really acceptable after all.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
"After a quick R of TFM, all I can say is HOLY CR** THAT IS COOL! PostgreSQL was
amazing when I first started using it at 7.2, and I'm continually astounded by
learning new features and techniques made available by the continuing work of
the development team."
Berend Tober, http://archives.postgresql.org/pgsql-hackers/2007-08/msg01009.php

On 2023-Oct-11, David G. Johnston wrote:

> Or move 4 paragraphs of introductory material into its own section so that
> there are two sections and a brief sentence for an intro.

We have lots of other places where this (single-entry TOCs) happens.  I
don't think we want to add spurious <section> tags in all those places
is going to be a good idea.

> I don't see a special case for a single section to be a productive use of
> time.

Well, it's the only case where it's not obvious what is going on, but I
agree it's not a great fix -- maybe we have some place where the
introductory material is very long and the first section is several
pagefuls below, and not having a TOC in that case wouldn't be great.

> Improved formatting overall for the chapter ToC has merit.

Great ...

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"Crear es tan difícil como ser libre" (Elsa Triolet)

Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
> On 2023-Oct-11, David G. Johnston wrote:
>> Improved formatting overall for the chapter ToC has merit.

> Great ...

+1.  I've been annoyed by this ambiguity too.  I agree that
artificially forcing pages to have at least two subsections
isn't a good fix.

            regards, tom lane