Обсуждение: Get rid of "Section.N.N.N" on DOCs

On Sun, 2025-12-14 at 14:30 -0300, Marcos Pegoraro wrote:
> When reading documentation all the time we get something like
> See Section 27.4.5 and Section 27.4.2 for details.
> The only way to know what it is that Section is opening and reading its title.
>
> Wouldn't it be better if we print somethink for better reading like this ?
> See VACUUM Progress Reporting and CLUSTER Progress Reporting for details.
>
> There are places where links are mixed, some of them are auto explanatory, some don't, like on See Also of VACUUM
> vacuumdb, Section 19.10.2, Section 24.1.6, Section 27.4.5, Section 27.4.2
>
> For that we need only put a "xreflabel" tag on that target link. 
>
> I can create a patch for all of them, but I would like to know why it's done this way.

Don't ask "why".  It probably just grew that way.

However, even though that would be an improvement in some cases, I a wary of a sweeping
change like that.  In most places, the wording of the documentation is quite aware of
the way it is rendered.  As a random example, look at this sentence in
https://www.postgresql.org/docs/current/sql-altertable.html :

  For more information on the use of statistics by the PostgreSQL query planner,
  refer to [Section 14.2].

With the change you propose, that would become

  For more information on the use of statistics by the PostgreSQL query planner,
  refer to [Statistics Used By The Planner].

Perhaps I am old-fashioned, but the original looks better to me.  The wording makes
sufficiently clear what to expect in section 14.2.  In addition, I can always hover
over the link to see a bubble with the name of the chapter.

I would suggest that you identify instances in the documentation where the current
practice is confusing and propose a patch to change only those.

Yours,
Laurenz Albe

On Mon, 2025-12-15 at 09:12 -0300, Marcos Pegoraro wrote:
> But we can start by changing the ones we're sure of. If I haven't miscounted,
> there are about 1,500 places in the documentation where a Section n.n.n exists,
> but changing one source will correct 20 or 50 links of it. I'll change a few
> and see how it goes.

Right.  But you'd have to look at all the places with a reference and check
if the rendered text still makes sense, and if the change is actually an
improvement.

If we don't perceive the change as an improvement, you will meet resistance.
Apart from the effort of the change, there is also the increased effort of
backpatching documentation changes, and those efforts have to be outbalanced
by the benefits.

Yours,
Laurenz Albe

On 14.12.25 18:30, Marcos Pegoraro wrote:
> When reading documentation all the time we get something like
> See Section 27.4.5 <https://www.postgresql.org/docs/18/progress- 
> reporting.html#VACUUM-PROGRESS-REPORTING> and Section 27.4.2 <https:// 
> www.postgresql.org/docs/18/progress-reporting.html#CLUSTER-PROGRESS- 
> REPORTING> for details.
> The only way to know what it is that Section is opening and reading its 
> title.
> 
> Wouldn't it be better if we print somethink for better reading like this ?
> See VACUUM <https://www.postgresql.org/docs/18/progress- 
> reporting.html#VACUUM-PROGRESS-REPORTING>Progress Reporting <https:// 
> www.postgresql.org/docs/18/progress-reporting.html#VACUUM-PROGRESS- 
> REPORTING> and CLUSTER Progress Reporting <https://www.postgresql.org/ 
> docs/18/progress-reporting.html#CLUSTER-PROGRESS-REPORTING> for details.
> 
> There are places where links are mixed, some of them are auto 
> explanatory, some don't, like on See Also of VACUUM
> vacuumdb <https://www.postgresql.org/docs/18/app-vacuumdb.html>, 
> Section 19.10.2 <https://www.postgresql.org/docs/18/runtime-config- 
> vacuum.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST>, Section 24.1.6 
> <https://www.postgresql.org/docs/18/routine-vacuuming.html#AUTOVACUUM>, 
> Section 27.4.5 <https://www.postgresql.org/docs/18/progress- 
> reporting.html#VACUUM-PROGRESS-REPORTING>, Section 27.4.2 <https:// 
> www.postgresql.org/docs/18/progress-reporting.html#CLUSTER-PROGRESS- 
> REPORTING>
> 
> For that we need only put a "xreflabel" tag on that target link.
> 
> I can create a patch for all of them, but I would like to know why it's 
> done this way.

See this commit:

commit 70da87d334e
Author: Peter Eisentraut <peter_e@gmx.net>
Date:   Mon Apr 3 16:50:32 2017

     doc: Change xref style to number only

     Change the style of links generated by xrefs to section number only, as
     it was with DSSSL, instead of number and title, as is the default 
of the
     XSLT stylesheets.

     Our documentation is mostly written expecting the old style, so keep
     that for the time being, per discussion.

diff --git a/doc/src/sgml/stylesheet-common.xsl 
b/doc/src/sgml/stylesheet-common.xsl
index 3d0651a8234..658a5ac5e17 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -39,6 +39,7 @@
  <xsl:param name="punct.honorific" select="''"></xsl:param>
  <xsl:param name="variablelist.term.break.after">1</xsl:param>
  <xsl:param name="variablelist.term.separator"></xsl:param>
+<xsl:param name="xref.with.number.and.title" select="0"></xsl:param>



You could try to change that back, but you then probably would need to 
go through and check that the new link text fits everywhere, as the 
commit message is suggesting.

On Mon, 2025-12-22 at 10:28 -0300, Marcos Pegoraro wrote:
> First version of all files replaced.
> I used a regex to get title tag which was on following line and added it as xreflabel of of that sec1.
>
> Simple one.
> <sect1 id="parser-stage" xreflabel="The Parser Stage">
>  <title>The Parser Stage</title>
>
> Removed <productname>, <literal>, <acronym> tags
>   <sect1 id="rule-system" xreflabel="The PostgreSQL Rule System">
>    <title>The <productname>PostgreSQL</productname> Rule System</title>
>
> Maybe some of them are huge, like "Continuous Archiving and Point-in-Time Recovery (PITR)" but I didn't change any of
them.
>
> This version I did not read all places where this changes affect, so obviously will have a lot of places to be
rewritten.

The changes I looked at look good to me, but I didn't scrutinize everything.

Yours,
Laurenz Albe

On Tue, 2025-12-23 at 11:39 -0300, Marcos Pegoraro wrote:
> If everything is okay, we can start rewriting all places that sounds strange in the HTML file.
> But this is a much slower process, as it requires reading all the affected pages.

Perhaps you should wait for other's opinions, before you start that effort.

Yours,
Laurenz Albe

I had a look at your patch, starting from the end and up to "xfunc".
I looked at all the references in the documentation to see if I can spot
any oddities.  I don't think I'll be able to look through the whole patch
at that level, but I wanted to get an idea.

Overall, I have the impression that the patch is an improvement.

Here are some general comments:

1. You seem to have taken the chapter heading as label automatically.
   That leads to labels like "Author" and "Deprecation Notice" that are not
   descriptive enough without a reference to the chapter.
   These lables need going over.

2. I notice that you added labels to the sections, but not to the chapters, so
   the references to the chapters still read like "Chapter 63".  Is that deliberate,
   an oversight, or are there problems adding labels to the chapters?

3. Similarly, you didn't add labels to subsections, so there are still references
   like "Section 66.6.1".  I understand that that might be too much code churn for
   your patch, but the inconsistency is deplorable.

Comments for the individual changes I scrutinized:

- Chapter 36.3 now has:

    PostgreSQL provides four kinds of functions:

     • query language functions (functions written in SQL) (Query Language (SQL) Functions)

     • procedural language functions (functions written in, for example, PL/pgSQL or PL/Tcl) (Procedural Language
Functions)

     • internal functions (Internal Functions)

     • C-language functions (C-Language Functions)

  That is overly repetitive and should be simplified.

- "xtypes-toast":

  The reference in the CREATE TYPE page becomes:

    All storage values other than plain imply that the functions of the data type
    can handle values that have been toasted, as described in Section 66.2 and
    TOAST Considerations.

  That sounds odd.  Either do the magic for both references or for none of them.

- "xml2-author":

  The label is "Author", see point #1 above.
  Suggestions: xml2 Extension Author / Author of xml2

- "xml2-functions":

  The label should be "Description of xml2 Functions".

- "xml2-deprecation":

  "Deprecatoin Notice" is too little, see #1 above.
  The label should be "xml2 Deprecation Notice".

- "xindex-example":

  The label is "An Example"; see #1 above.
  The label should be "Example for Creating an Operator Class".

- "xfunc-sql":

  Perhaps the label should be "SQL-Language Functions".

  But then the reference in chapter 5.16 becomes

    (See SQL-Language Functions for an explanation of SQL-language functions.)

  which is somewhat repetitive and could be improved.


Yours,
Laurenz Albe

On Fri, 2025-12-26 at 10:16 -0300, Marcos Pegoraro wrote:
>
> > 2. I notice that you added labels to the sections, but not to the chapters, so
> >    the references to the chapters still read like "Chapter 63".  Is that deliberate,
> >    an oversight, or are there problems adding labels to the chapters?
>
> Correct, I didn't do it for Chapters and Tables. I think it would be better to have the
> word Chapter and then the Title. 
> See Chapter 14 for information about how to find out whether an index is used 
> for this
> See Chapter Performance Tips for information about how to find out whether an index is used 
> So, this replacement would always have the Chapter word before, what do you think ?

That makes sense to me.

> And about Tables, do the same ?

I'd leave them alone, but I have no strong opinion about that.
Usually, references to the tables are right next to the table anyway.

> > 3. Similarly, you didn't add labels to subsections, so there are still references
> >    like "Section 66.6.1".  I understand that that might be too much code churn for
> >    your patch, but the inconsistency is deplorable.
>
> I didn't find this 66.6.1 on my files, are you sure of it ?
> My search hadn't found any identifiers with numbers in them, but I improved the expression already.

I find a reference to "Section 66.6.1" (for example) in
https://www.postgresql.org/docs/current/jit-reason.html#JIT-ACCELERATED-OPERATIONS

> > Comments for the individual changes I scrutinized:
>
> As I mentioned, you need to read it item by item to catch these inconsistencies. And the work
> is even greater because there's no clear relationship between which SGML file you're editing
> and which HTML file will be generated, so the task is even more demanding.

I looked at all the references in the part that I went over.

Yours,
Laurenz Albe

On 21.12.25 11:55, Marcos Pegoraro wrote:
> Em seg., 15 de dez. de 2025 às 16:33, Peter Eisentraut 
> <peter@eisentraut.org <mailto:peter@eisentraut.org>> escreveu:
> 
>           doc: Change xref style to number only
> 
> 
> If I understood correctly that would not help because if we revert that 
> commit
> it'll put section number and text, but we now want only text, not 
> section numbers, right ?
> 
> 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.

On 23.12.25 15:39, Marcos Pegoraro wrote:
> There are a few more files that my regular expression couldn't find 
> initially, now I think they've all been affected.
> 
> Even many that don't have any links pointing to them also have the tag, 
> so that when someone links to them, they automatically display the Title 
> and not the section number.
> 
> If everything is okay, we can start rewriting all places that sounds 
> strange in the HTML file.
> But this is a much slower process, as it requires reading all the 
> affected pages.

Independent of what link text style you prefer, manually maintaining 
xreflabel attributes is the wrong solution.  The XSL stylesheets 
automatically compute the link title from the section number or title, 
and there are parameters to choose between different styles.  If you 
don't like the styles offered by the parameters, the fix will be to 
override the XSL code that computes the link text.

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.

            regards, tom lane

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

On Thu, Jan 1, 2026 at 7:21 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> Em qua., 31 de dez. de 2025 às 21:03, Robert Treat <rob@xzilla.net> escreveu:
>>
>> The surrounding text already gives context as to what we will find in
>> those linked references,
>
>
> My intention here is to read and rewrite all texts that need revision, so the surrounding text will probably change
aswell. When reading documents, we need to open the link or hover the mouse over it to read the link to see that that
isnot what we want, before returning to reading, so it's quite common to get lost in the text because of this back and
forth.
> Instead of
> There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQL (Chapter
41),PL/Tcl (Chapter 42), PL/Perl (Chapter 43), and PL/Python (PL/Python). 
> Wouldn't it be better to have a paragraph like this ?
> There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQL, PL/Tcl,
PL/Perland PL/Python. 
>
> So I don't care if that link is a section, a appendix, a chapter, I'm sure I'll go there only if I really want.
>

I do understand your intention, and I don't think it is better. You
say you will only go there if you really want, but it's harder for
readers to know if they really want to go there when you remove the
information delivered via those chapter numbers. We help the reader
understand that things like plpgsql and pltcl are so close to our
current topic that they are in the very next chapters, but writing
your own pl isn't as relevant to the current reading given we've put
it farther away; in other words there is a lot of material between
here (chapter 40) and writing your own procedural language (chapter
57) that we think you'd probably want to read about first if you are
just reading through rather than searching for something specific. And
while you say you don't care if the material is in another chapter or
appendix, it does convey something to the reader that we think this
information can be completely sectioned off from the main manual by
itself. And I would note, even you did not remove the appendix heading
in your previous example ("Appendix H: External Projects has
information..."), and it seems clear to me there would be information
loss if you had done so.

>>
>> 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.
>
>
> Well, if a link was written on that page, independently if it's a chapter, a GUC, a section, it's important for the
userto know. And again, I don't care if I'm jumping to a distant section or chapter, it's important to understand
entirelythe page I'm reading. 
>
> So, my intention here is to provide the user with continuous reading. If I read a paragraph with links but it's
displayedas if it were in a book without footnotes, it gives me a much faster and easier reading experience. If I have
tostop my reading to open other links because I don't know if they're important or not, or also bad ignore some words,
thereading isn't as productive. 
>

What you're proposing makes more sense if we were writing prose or
blog posts or similar works, but we're making educational
documentation that serves as a user manual and reference guide.
On the web, where a link can take you to any other place in the world,
giving the reader some sense of directions can be extremely grounding,
and chapters, sections, and appendexis aren't some kind of
afterthought; for what we're building, all those pieces matter.


Robert Treat
https://xzilla.net