Thread

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