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
