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
