Get rid of "Section.N.N.N" on DOCs

On Sun, Dec 14, 2025 at 10:30 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

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&gt;,
Section 19.10.2
<https://www.postgresql.org/docs/18/runtime-config-vacuum.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST&gt;
, Section 24.1.6
<https://www.postgresql.org/docs/18/routine-vacuuming.html#AUTOVACUUM&gt;,
Section 27.4.5
<https://www.postgresql.org/docs/18/progress-reporting.html#VACUUM-PROGRESS-REPORTING&gt;
, Section 27.4.2
<https://www.postgresql.org/docs/18/progress-reporting.html#CLUSTER-PROGRESS-REPORTING&gt;

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.

That would be great. I don't think it's intentional, just not everyone
knowing and thus failing to add the additional attribute.

David J.

On Sun, 14 Dec 2025 at 12:35, David G. Johnston <david.g.johnston@gmail.com>
wrote:

On Sun, Dec 14, 2025 at 10:30 AM Marcos Pegoraro <marcos@f10.com.br>
wrote:

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&gt;,
Section 19.10.2
<https://www.postgresql.org/docs/18/runtime-config-vacuum.html#RUNTIME-CONFIG-RESOURCE-VACUUM-COST&gt;
, Section 24.1.6
<https://www.postgresql.org/docs/18/routine-vacuuming.html#AUTOVACUUM&gt;,
Section 27.4.5
<https://www.postgresql.org/docs/18/progress-reporting.html#VACUUM-PROGRESS-REPORTING&gt;
, Section 27.4.2
<https://www.postgresql.org/docs/18/progress-reporting.html#CLUSTER-PROGRESS-REPORTING&gt;

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.

That would be great. I don't think it's intentional, just not everyone
knowing and thus failing to add the additional attribute.

Is there any way to do this automatically, not by editing all the
references, but by changing how they're formatted? It seems to me that all
links to the same section should have the same link text, which should be
some combination of the section number and/or title/description. So ideally
this would be a matter of changing how the link text is computed. If we
rename a section, we presumably want all references to it to update
accordingly.

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

Em seg., 15 de dez. de 2025 às 03:49, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

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].

I'm aware of that and I think in this case we need to change both
sides. The source needs to have the tag to be displayed, and on the pages
where it's used, we need to adapt it so that it's displayed accordingly.

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.

regards
Marcos

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&gt;,
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&gt;,
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.

Em seg., 15 de dez. de 2025 às 09:19, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

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.

Are you sure we need to backpatch all these changes ?
I'm not talking about the job I'll have but the job the committer will have.
There are almost 300 different section numbers and more than 700 places
will be changed,
so will be 700 multiplied by how many versions of it. Are you sure ?

I changed 8 or 10 just for testing and sending two as an example, just to
see if it's worthwhile.
Environment Variables need to change source and target, 30 places.
String constants just source part, easy to change but harder to verify all
related parts.

regards
Marcos

On Fri, Dec 19, 2025 at 11:56 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

Em seg., 15 de dez. de 2025 às 09:19, Laurenz Albe <
laurenz.albe@cybertec.at> escreveu:

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.

Are you sure we need to backpatch all these changes ?
I'm not talking about the job I'll have but the job the committer will
have.
There are almost 300 different section numbers and more than 700 places
will be changed,
so will be 700 multiplied by how many versions of it. Are you sure ?

I changed 8 or 10 just for testing and sending two as an example, just to
see if it's worthwhile.
Environment Variables need to change source and target, 30 places.
String constants just source part, easy to change but harder to verify all
related parts.

These changes aren't going to be back-patched. The concern stated is that
given all the places being touched, the odds of future back-patches hitting
one of them and resulting in a conflict has increased substantially.

David J.

Em seg., 15 de dez. de 2025 às 16:33, Peter Eisentraut <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"

regards
Marcos

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.

regards
Marcos

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

Em seg., 22 de dez. de 2025 às 14:44, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

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

Thanks for reviewing it.
There are 1,150 affected html files and 1,700 changes, so are a lot of
places to see if something need some change

regards
Marcos

Em seg., 22 de dez. de 2025 às 16:08, Marcos Pegoraro <marcos@f10.com.br>
escreveu:

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.

regards
Marcos

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

Em ter., 23 de dez. de 2025 às 11:51, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

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

Sure, I'll.

Many places will look much better, but some will become redundant and
others will seem confusing.
So yes, we have to make this change carefully, if we do.

regards
Marcos

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

Em qui., 25 de dez. de 2025 às 18:41, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

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

Cool

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.

Well, I noticed that if the xreflabel tag existed next to the section
identifier, then it would be used in the HTML, so all I did was create a
regular expression that takes the title from the line below and puts it on
the line above. That was the only thing I did. As I wrote before, we need
to carefully read and adapt item by item.

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 ?

And about Tables, do the same ?
The built-in general-purpose aggregate functions are listed in Table 9.62
would be
The built-in general-purpose aggregate functions are listed in Table
General-Purpose Aggregate Functions

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.

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.

regards
Marcos

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

Em sáb., 27 de dez. de 2025 às 09:16, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

That makes sense to me.

Fine.

And what about those xreflabel that already exists, what do we do with them
?
<refsec and <varlistentry are fine but <sec is not done or done poorly.
If you search without my patch with this regex you'll get only 58
occurrences.
(^\s*<sect\d\sid)(="(?=\S*)([a-zA-Z0-9_-]+))(" xreflabel=)(".+?")(>)
and see $3 and $5 parts of regex you'll get something very similar between
id and xreflabel.
27 of them are the same and the others are just small replacements. None
capitalized, none as separate words.
id="auth-delay" reflabel="auth_delay"
id="basic-archive" reflabel="basic_archive"
and so on

Only two of them are replaced carefully
id="standby-server-operation" reflabel="Standby Server Operation"
id="jit-configuration" reflabel="JIT Configuration"

I think these places need to be replaced carefully too.

You'll get more or less 600 occurrences on config, libpq, select,
create_table and monitoring.sgml but there are always params of these
specific places, so it's not a problem to reflabel be the same as its
config name.

regards
Marcos