Обсуждение: 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.