Thread

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