Thread

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

Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-15T06:49:03Z

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