On Sun, Dec 28, 2025 at 12:15 PM Tom Lane <[email protected]> wrote: > Peter Eisentraut <[email protected]> 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
