Re: Get rid of "Section.N.N.N" on DOCs - Mailing list pgsql-hackers

On Sun, Dec 28, 2025 at 12:15 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Peter Eisentraut <peter@eisentraut.org> writes:
> > On 21.12.25 11:55, Marcos Pegoraro wrote:
> >> Now we have - "Section 23.3.1"
> >> Changing back that commit will show - "Section 23.3.1, “Supported
> >> Character Sets”."
> >> But we want only - "Supported Character Sets"
>
> > Personally, I don't want that.  I think changing to section number plus
> > title could have some merit, but just the title seems inferior to me.
> > But that's just me.
>
> I'm mildly in favor of title-only for output formats where the title
> is a hyperlink: the section number seems like unnecessary verbiage
> if you have something you can click on.  However, if there's anyone
> out there still printing on dead trees, or using ancient PDF readers
> that don't do hyperlinks, loss of the section number would be pretty
> catastrophic for following the link.  So this really needs to be
> output-format-dependent, which suggests that we could make it adapt
> to readers' preferences too: provide some option to decide whether to
> include title or section number or both.
>

FWIW, I also lean towards Peter's feeling that if we are going to make
the change, (and I'm not particularly sold on it), that section number
+ title would be my choice.

The surrounding text already gives context as to what we will find in
those linked references, so I don't feel like the title adds much. But
the numbers do provide some subtle clues as to the relationship of the
linked references to the page we are on AND other references within
that page. For example, on a (random) page like
https://www.postgresql.org/docs/current/runtime-config-statistics.html,
I can see that I am in 19.9, and the first reference is for "Refer to
Chapter 27 for more information."; that's a much different section
than the one I am in which implies much more than "Refer to Monitoring
Database Activity for more information." would imply.
Similarly,further down the page when it suggests "see Section
19.10.2", that's a rather local piece of information relative to the
section I am already in. This may not seem like something that
important or that people even notice, but think of it as a structural
device like "royal order of adjectives" that people understand and
make use of even if they don't realize that is what they are doing.
This also comes in to play in sections like the index or glossary,
where we are linking to different sections of the docs for the same
term, with the chapter/section numbers providing hints at the general
proximity of data within the overall documentation. So as Tom notices
that for folks working from non-hyperlinked the need for these
markers, I think they are also quite helpful for folks navigating
hyperlink driven materials as well.


Robert Treat
https://xzilla.net