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

From: Marcos Pegoraro <marcos(at)f10(dot)com(dot)br>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Get rid of "Section.N.N.N" on DOCs
Date: 2025-12-14 17:30:07
Message-ID: CAB-JLwa7XLuMBH5sqwue+tFEDyPWDVMk9ufBGjCB6fAOAUTQ4A@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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.

regards
Marcos

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message David G. Johnston 2025-12-14 17:35:17 Re: Get rid of "Section.N.N.N" on DOCs
Previous Message Jelte Fennema-Nio 2025-12-14 16:56:23 Re: Make copyObject work in C++