Thread

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

Peter Eisentraut <peter@eisentraut.org> — 2025-12-15T19:33:42Z

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.