Horton

Thread

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. doc: Change xref style to number only

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-14T17:30:07Z

    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

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

    David G. Johnston <david.g.johnston@gmail.com> — 2025-12-14T17:35:17Z

    On Sun, Dec 14, 2025 at 10:30 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

> 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.
>

That would be great.  I don't think it's intentional, just not everyone
knowing and thus failing to add the additional attribute.

David J.

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

    Isaac Morland <isaac.morland@gmail.com> — 2025-12-14T18:21:40Z

    On Sun, 14 Dec 2025 at 12:35, David G. Johnston <david.g.johnston@gmail.com>
wrote:

> On Sun, Dec 14, 2025 at 10:30 AM Marcos Pegoraro <marcos@f10.com.br>
> wrote:
>
>> 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.
>>
>
> That would be great.  I don't think it's intentional, just not everyone
> knowing and thus failing to add the additional attribute.
>

Is there any way to do this automatically, not by editing all the
references, but by changing how they're formatted? It seems to me that all
links to the same section should have the same link text, which should be
some combination of the section number and/or title/description. So ideally
this would be a matter of changing how the link text is computed. If we
rename a section, we presumably want all references to it to update
accordingly.

  4. 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

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-15T12:12:57Z

    Em seg., 15 de dez. de 2025 às 03:49, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

>   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].
>

I'm aware of that and I think in this case we need to change both
sides. The source needs to have the tag to be displayed, and on the pages
where it's used, we need to adapt it so that it's displayed accordingly.

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.

regards
Marcos

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

    Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-15T12:19:10Z

    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

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

    Peter Eisentraut <peter@eisentraut.org> — 2025-12-15T19:33:42Z

    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.

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-19T18:56:04Z

    Em seg., 15 de dez. de 2025 às 09:19, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

> 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.
>

Are you sure we need to backpatch all these changes ?
I'm not talking about the job I'll have but the job the committer will have.
There are almost 300 different section numbers and more than 700 places
will be changed,
so will be 700 multiplied by how many versions of it. Are you sure ?

I changed 8 or 10 just for testing and sending two as an example, just to
see if it's worthwhile.
Environment Variables need to change source and target, 30 places.
String constants just source part, easy to change but harder to verify all
related parts.

regards
Marcos

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

    David G. Johnston <david.g.johnston@gmail.com> — 2025-12-19T19:10:56Z

    On Fri, Dec 19, 2025 at 11:56 AM Marcos Pegoraro <marcos@f10.com.br> wrote:

> Em seg., 15 de dez. de 2025 às 09:19, Laurenz Albe <
> laurenz.albe@cybertec.at> escreveu:
>
>> 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.
>>
>
> Are you sure we need to backpatch all these changes ?
> I'm not talking about the job I'll have but the job the committer will
> have.
> There are almost 300 different section numbers and more than 700 places
> will be changed,
> so will be 700 multiplied by how many versions of it. Are you sure ?
>
> I changed 8 or 10 just for testing and sending two as an example, just to
> see if it's worthwhile.
> Environment Variables need to change source and target, 30 places.
> String constants just source part, easy to change but harder to verify all
> related parts.
>
>
These changes aren't going to be back-patched.  The concern stated is that
given all the places being touched, the odds of future back-patches hitting
one of them and resulting in a conflict has increased substantially.

David J.

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-21T10:55:41Z

    Em seg., 15 de dez. de 2025 às 16:33, Peter Eisentraut <peter@eisentraut.org>
escreveu:

>      doc: Change xref style to number only
>

If I understood correctly that would not help because if we revert that
commit
it'll put section number and text, but we now want only text, not section
numbers, right ?

Now we have - "Section 23.3.1"
Changing back that commit will show - "Section 23.3.1, “Supported Character
Sets”."
But we want only - "Supported Character Sets"

regards
Marcos

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-22T13:28:43Z

    First version of all files replaced.
I used a regex to get title tag which was on following line and added it as
xreflabel of of that sec1.

Simple one.
<sect1 id="parser-stage" xreflabel="The Parser Stage">
 <title>The Parser Stage</title>

Removed <productname>, <literal>, <acronym> tags
 <sect1 id="rule-system" xreflabel="The PostgreSQL Rule System">
   <title>The <productname>PostgreSQL</productname> Rule System</title>

Maybe some of them are huge, like "Continuous Archiving and Point-in-Time
Recovery (PITR)" but I didn't change any of them.

This version I did not read all places where this changes affect, so
obviously will have a lot of places to be rewritten.

regards
Marcos

>

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

    Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-22T17:44:43Z

    On Mon, 2025-12-22 at 10:28 -0300, Marcos Pegoraro wrote:
> First version of all files replaced. 
> I used a regex to get title tag which was on following line and added it as xreflabel of of that sec1.
> 
> Simple one.
> <sect1 id="parser-stage" xreflabel="The Parser Stage">
>  <title>The Parser Stage</title>
> 
> Removed <productname>, <literal>, <acronym> tags
>   <sect1 id="rule-system" xreflabel="The PostgreSQL Rule System">
>    <title>The <productname>PostgreSQL</productname> Rule System</title>
> 
> Maybe some of them are huge, like "Continuous Archiving and Point-in-Time Recovery (PITR)" but I didn't change any of them.
> 
> This version I did not read all places where this changes affect, so obviously will have a lot of places to be rewritten.

The changes I looked at look good to me, but I didn't scrutinize everything.

Yours,
Laurenz Albe

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-22T19:08:48Z

    Em seg., 22 de dez. de 2025 às 14:44, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

> The changes I looked at look good to me, but I didn't scrutinize
> everything.
>

Thanks for reviewing it.
There are 1,150 affected html files and 1,700 changes, so are a lot of
places to see if something need some change

regards
Marcos

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-23T14:39:35Z

    Em seg., 22 de dez. de 2025 às 16:08, Marcos Pegoraro <marcos@f10.com.br>
escreveu:

There are a few more files that my regular expression couldn't find
initially, now I think they've all been affected.

Even many that don't have any links pointing to them also have the tag, so
that when someone links to them, they automatically display the Title and
not the section number.

If everything is okay, we can start rewriting all places that sounds
strange in the HTML file.
But this is a much slower process, as it requires reading all the affected
pages.

regards
Marcos

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

    Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-23T14:51:54Z

    On Tue, 2025-12-23 at 11:39 -0300, Marcos Pegoraro wrote:
> If everything is okay, we can start rewriting all places that sounds strange in the HTML file.
> But this is a much slower process, as it requires reading all the affected pages.

Perhaps you should wait for other's opinions, before you start that effort.

Yours,
Laurenz Albe

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-23T15:58:47Z

    Em ter., 23 de dez. de 2025 às 11:51, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

> Perhaps you should wait for other's opinions, before you start that effort.
>

Sure, I'll.

Many places will look much better, but some will become redundant and
others will seem confusing.
So yes, we have to make this change carefully, if we do.

regards
Marcos

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

    Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-25T21:41:29Z

    I had a look at your patch, starting from the end and up to "xfunc".
I looked at all the references in the documentation to see if I can spot
any oddities.  I don't think I'll be able to look through the whole patch
at that level, but I wanted to get an idea.

Overall, I have the impression that the patch is an improvement.

Here are some general comments:

1. You seem to have taken the chapter heading as label automatically.
   That leads to labels like "Author" and "Deprecation Notice" that are not
   descriptive enough without a reference to the chapter.
   These lables need going over.

2. I notice that you added labels to the sections, but not to the chapters, so
   the references to the chapters still read like "Chapter 63".  Is that deliberate,
   an oversight, or are there problems adding labels to the chapters?

3. Similarly, you didn't add labels to subsections, so there are still references
   like "Section 66.6.1".  I understand that that might be too much code churn for
   your patch, but the inconsistency is deplorable.

Comments for the individual changes I scrutinized:

- Chapter 36.3 now has:

    PostgreSQL provides four kinds of functions:

     • query language functions (functions written in SQL) (Query Language (SQL) Functions)

     • procedural language functions (functions written in, for example, PL/pgSQL or PL/Tcl) (Procedural Language Functions)

     • internal functions (Internal Functions)

     • C-language functions (C-Language Functions) 

  That is overly repetitive and should be simplified.

- "xtypes-toast":

  The reference in the CREATE TYPE page becomes:

    All storage values other than plain imply that the functions of the data type
    can handle values that have been toasted, as described in Section 66.2 and
    TOAST Considerations.

  That sounds odd.  Either do the magic for both references or for none of them.

- "xml2-author":

  The label is "Author", see point #1 above.
  Suggestions: xml2 Extension Author / Author of xml2

- "xml2-functions":

  The label should be "Description of xml2 Functions".

- "xml2-deprecation":

  "Deprecatoin Notice" is too little, see #1 above.
  The label should be "xml2 Deprecation Notice".

- "xindex-example":

  The label is "An Example"; see #1 above.
  The label should be "Example for Creating an Operator Class".

- "xfunc-sql":

  Perhaps the label should be "SQL-Language Functions".

  But then the reference in chapter 5.16 becomes

    (See SQL-Language Functions for an explanation of SQL-language functions.)

  which is somewhat repetitive and could be improved.


Yours,
Laurenz Albe

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-26T13:16:04Z

    Em qui., 25 de dez. de 2025 às 18:41, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

> Overall, I have the impression that the patch is an improvement.
>
Cool

1. You seem to have taken the chapter heading as label automatically.
>    That leads to labels like "Author" and "Deprecation Notice" that are not
>    descriptive enough without a reference to the chapter.
>    These lables need going over.
>

Well, I noticed that if the xreflabel tag existed next to the section
identifier, then it would be used in the HTML, so all I did was create a
regular expression that takes the title from the line below and puts it on
the line above. That was the only thing I did. As I wrote before, we need
to carefully read and adapt item by item.

>
> 2. I notice that you added labels to the sections, but not to the
> chapters, so
>    the references to the chapters still read like "Chapter 63".  Is that
> deliberate,
>    an oversight, or are there problems adding labels to the chapters?
>
Correct, I didn't do it for Chapters and Tables. I think it would be better
to have the word Chapter and then the Title.
See Chapter 14 for information about how to find out whether an index is
used
for this
See Chapter Performance Tips for information about how to find out whether
an index is used
So, this replacement would always have the Chapter word before, what do you
think ?

And about Tables, do the same ?
The built-in general-purpose aggregate functions are listed in Table 9.62
would be
The built-in general-purpose aggregate functions are listed in Table
General-Purpose Aggregate Functions

>
> 3. Similarly, you didn't add labels to subsections, so there are still
> references
>    like "Section 66.6.1".  I understand that that might be too much code
> churn for
>    your patch, but the inconsistency is deplorable.
>
I didn't find this 66.6.1 on my files, are you sure of it ?
My search hadn't found any identifiers with numbers in them, but I improved
the expression already.

Comments for the individual changes I scrutinized:
>
As I mentioned, you need to read it item by item to catch these
inconsistencies. And the work is even greater because there's no clear
relationship between which SGML file you're editing and which HTML file
will be generated, so the task is even more demanding.

regards
Marcos

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

    Laurenz Albe <laurenz.albe@cybertec.at> — 2025-12-27T12:15:58Z

    On Fri, 2025-12-26 at 10:16 -0300, Marcos Pegoraro wrote:
> 
> > 2. I notice that you added labels to the sections, but not to the chapters, so
> >    the references to the chapters still read like "Chapter 63".  Is that deliberate,
> >    an oversight, or are there problems adding labels to the chapters?
> 
> Correct, I didn't do it for Chapters and Tables. I think it would be better to have the
> word Chapter and then the Title. 
> See Chapter 14 for information about how to find out whether an index is used 
> for this
> See Chapter Performance Tips for information about how to find out whether an index is used 
> So, this replacement would always have the Chapter word before, what do you think ?

That makes sense to me.

> And about Tables, do the same ?

I'd leave them alone, but I have no strong opinion about that.
Usually, references to the tables are right next to the table anyway.

> > 3. Similarly, you didn't add labels to subsections, so there are still references
> >    like "Section 66.6.1".  I understand that that might be too much code churn for
> >    your patch, but the inconsistency is deplorable.
> 
> I didn't find this 66.6.1 on my files, are you sure of it ?
> My search hadn't found any identifiers with numbers in them, but I improved the expression already.

I find a reference to "Section 66.6.1" (for example) in
https://www.postgresql.org/docs/current/jit-reason.html#JIT-ACCELERATED-OPERATIONS

> > Comments for the individual changes I scrutinized:
> 
> As I mentioned, you need to read it item by item to catch these inconsistencies. And the work
> is even greater because there's no clear relationship between which SGML file you're editing
> and which HTML file will be generated, so the task is even more demanding.

I looked at all the references in the part that I went over.

Yours,
Laurenz Albe

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-27T13:55:44Z

    Em sáb., 27 de dez. de 2025 às 09:16, Laurenz Albe <laurenz.albe@cybertec.at>
escreveu:

> That makes sense to me.
>
Fine.

And what about those xreflabel that already exists, what do we do with them
?
<refsec and <varlistentry are fine but <sec is not done or done poorly.
If you search without my patch with this regex you'll get only 58
occurrences.
(^\s*<sect\d\sid)(="(?=\S*)([a-zA-Z0-9_-]+))(" xreflabel=)(".+?")(>)
and see $3 and $5 parts of regex you'll get something very similar between
id and xreflabel.
27 of them are the same and the others are just small replacements. None
capitalized, none as separate words.
id="auth-delay" reflabel="auth_delay"
id="basic-archive" reflabel="basic_archive"
and so on

Only two of them are replaced carefully
id="standby-server-operation" reflabel="Standby Server Operation"
id="jit-configuration" reflabel="JIT Configuration"

I think these places need to be replaced carefully too.

You'll get more or less 600 occurrences on config, libpq, select,
create_table and monitoring.sgml but there are always params of these
specific places, so it's not a problem to reflabel be the same as its
config name.

regards
Marcos

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

    Peter Eisentraut <peter@eisentraut.org> — 2025-12-28T13:55:04Z

    On 21.12.25 11:55, Marcos Pegoraro wrote:
> Em seg., 15 de dez. de 2025 às 16:33, Peter Eisentraut 
> <peter@eisentraut.org <mailto:peter@eisentraut.org>> escreveu:
> 
>           doc: Change xref style to number only
> 
> 
> If I understood correctly that would not help because if we revert that 
> commit
> it'll put section number and text, but we now want only text, not 
> section numbers, right ?
> 
> Now we have - "Section 23.3.1"
> Changing back that commit will show - "Section 23.3.1, “Supported 
> Character Sets”."
> But we want only - "Supported Character Sets"

Personally, I don't want that.  I think changing to section number plus 
title could have some merit, but just the title seems inferior to me. 
But that's just me.

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

    Peter Eisentraut <peter@eisentraut.org> — 2025-12-28T13:59:47Z

    On 23.12.25 15:39, Marcos Pegoraro wrote:
> There are a few more files that my regular expression couldn't find 
> initially, now I think they've all been affected.
> 
> Even many that don't have any links pointing to them also have the tag, 
> so that when someone links to them, they automatically display the Title 
> and not the section number.
> 
> If everything is okay, we can start rewriting all places that sounds 
> strange in the HTML file.
> But this is a much slower process, as it requires reading all the 
> affected pages.

Independent of what link text style you prefer, manually maintaining 
xreflabel attributes is the wrong solution.  The XSL stylesheets 
automatically compute the link title from the section number or title, 
and there are parameters to choose between different styles.  If you 
don't like the styles offered by the parameters, the fix will be to 
override the XSL code that computes the link text.

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-28T15:26:19Z

    Em dom., 28 de dez. de 2025 às 10:55, Peter Eisentraut <peter@eisentraut.org>
escreveu:

> Personally, I don't want that.  I think changing to section number plus
> title could have some merit, but just the title seems inferior to me.
> But that's just me.


But this way it wouldn't be too polluted for the Chapters ?
For more information on logical replication, see Chapter 29. Through the
logical decoding interface (Chapter 47)
would be
For more information on logical replication, see Chapter 29. Logical
Replication. Through the logical decoding interface (Chapter 47. Logical
Decoding)

regards
Marcos

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-28T15:32:13Z

    Em dom., 28 de dez. de 2025 às 10:59, Peter Eisentraut <peter@eisentraut.org>
escreveu:

> Independent of what link text style you prefer, manually maintaining
> xreflabel attributes is the wrong solution.  The XSL stylesheets
> automatically compute the link title from the section number or title,
> and there are parameters to choose between different styles.  If you
> don't like the styles offered by the parameters, the fix will be to
> override the XSL code that computes the link text.
>

ok, I'll see how this can be accomplished, but even with that some of them
need to be manually changed because examples Laurenz pointed out like
"Author" and "Deprecation Notice" doesn't explain what is needed.

regards
Marcos

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

    Tom Lane <tgl@sss.pgh.pa.us> — 2025-12-28T17:15:28Z

    Peter Eisentraut <peter@eisentraut.org> writes:
> On 21.12.25 11:55, Marcos Pegoraro wrote:
>> Now we have - "Section 23.3.1"
>> Changing back that commit will show - "Section 23.3.1, “Supported 
>> Character Sets”."
>> But we want only - "Supported Character Sets"

> Personally, I don't want that.  I think changing to section number plus 
> title could have some merit, but just the title seems inferior to me. 
> But that's just me.

I'm mildly in favor of title-only for output formats where the title
is a hyperlink: the section number seems like unnecessary verbiage
if you have something you can click on.  However, if there's anyone
out there still printing on dead trees, or using ancient PDF readers
that don't do hyperlinks, loss of the section number would be pretty
catastrophic for following the link.  So this really needs to be
output-format-dependent, which suggests that we could make it adapt
to readers' preferences too: provide some option to decide whether to
include title or section number or both.

			regards, tom lane

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

    Marcos Pegoraro <marcos@f10.com.br> — 2025-12-31T18:18:41Z

    Em dom., 28 de dez. de 2025 às 10:59, Peter Eisentraut <peter@eisentraut.org>
escreveu:

> Independent of what link text style you prefer, manually maintaining
> xreflabel attributes is the wrong solution.  The XSL stylesheets
> automatically compute the link title from the section number or title,
> and there are parameters to choose between different styles.  If you
> don't like the styles offered by the parameters, the fix will be to
> override the XSL code that computes the link text.
>

As you pointed out, I discovered how to customize those items on XSL and
it's done for all.
As you can see in the image, the differences between old and new are huge.
And as you can see on image, it does not make sense to have PL/pgSQL,
PL/Perl, etc duplicated.

This is just an example of how to do it, so it's not covered for all other
items like example, item, refsect and so on.
Appendix is written differently too as a test. But then it is just a
decision if we want and how we want each of them.

And if we want then is to start the harder part, read and modify every item
that is not properly written.

[image: image.png]
regards
Marcos