pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feed31.7.1. Initial Snapshot
6+ messages / 4 participants
[nested] [flat]
* 31.7.1. Initial Snapshot
@ 2023-10-11 16:30 PG Doc comments form <noreply@postgresql.org>
0 siblings, 2 replies; 6+ messages in thread
From: PG Doc comments form @ 2023-10-11 16:30 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: splarv@ya.ru
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: 31.7.1. Initial Snapshot
@ 2023-10-11 16:36 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 0 replies; 6+ messages in thread
From: David G. Johnston @ 2023-10-11 16:36 UTC (permalink / raw)
To: splarv@ya.ru; pgsql-docs@lists.postgresql.org
On Wed, Oct 11, 2023 at 9:32 AM PG Doc comments form <noreply@postgresql.org>
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
What you are seeing is the first instance of 31.7.1 is a table of contents
entry (hyperlink too) for the section. Then you have the chapter
introductory material. Then you have section 31.7.1 itself.
David J.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: 31.7.1. Initial Snapshot
@ 2023-10-11 16:39 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 1 reply; 6+ messages in thread
From: Alvaro Herrera @ 2023-10-11 16:39 UTC (permalink / raw)
To: splarv@ya.ru; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: 31.7.1. Initial Snapshot
@ 2023-10-11 16:45 David G. Johnston <david.g.johnston@gmail.com>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 6+ messages in thread
From: David G. Johnston @ 2023-10-11 16:45 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: splarv@ya.ru; pgsql-docs@lists.postgresql.org
On Wed, Oct 11, 2023 at 9:41 AM Alvaro Herrera <alvherre@alvh.no-ip.org>
wrote:
> 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.
>
Or move 4 paragraphs of introductory material into its own section so that
there are two sections and a brief sentence for an intro.
I don't see a special case for a single section to be a productive use of
time. Improved formatting overall for the chapter ToC has merit.
David J.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: 31.7.1. Initial Snapshot
@ 2023-10-11 17:19 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 6+ messages in thread
From: Alvaro Herrera @ 2023-10-11 17:19 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: splarv@ya.ru; pgsql-docs@lists.postgresql.org
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)
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: 31.7.1. Initial Snapshot
@ 2023-10-11 17:57 Tom Lane <tgl@sss.pgh.pa.us>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 0 replies; 6+ messages in thread
From: Tom Lane @ 2023-10-11 17:57 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; splarv@ya.ru; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2023-10-11 17:57 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-10-11 16:30 31.7.1. Initial Snapshot PG Doc comments form <noreply@postgresql.org>
2023-10-11 16:36 ` David G. Johnston <david.g.johnston@gmail.com>
2023-10-11 16:39 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-10-11 16:45 ` David G. Johnston <david.g.johnston@gmail.com>
2023-10-11 17:19 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-10-11 17:57 ` Tom Lane <tgl@sss.pgh.pa.us>
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