Re: Get rid of "Section.N.N.N" on DOCs - Mailing list pgsql-hackers

From Marcos Pegoraro
Subject Re: Get rid of "Section.N.N.N" on DOCs
Date
Msg-id CAB-JLwY5WOjP2z81S+Gk-RNNs8Tu00DmO1zngeZA7F8MeEpPyw@mail.gmail.com
Whole thread Raw
In response to Re: Get rid of "Section.N.N.N" on DOCs  (Robert Treat <rob@xzilla.net>)
Responses Re: Get rid of "Section.N.N.N" on DOCs
List pgsql-hackers
Em qua., 31 de dez. de 2025 às 21:03, Robert Treat <rob@xzilla.net> escreveu:
The surrounding text already gives context as to what we will find in
those linked references,
 
My intention here is to read and rewrite all texts that need revision, so the surrounding text will probably change as well. When reading documents, we need to open the link or hover the mouse over it to read the link to see that that is not what we want, before returning to reading, so it's quite common to get lost in the text because of this back and forth. 
Instead of 
There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQL (Chapter 41), PL/Tcl (Chapter 42), PL/Perl (Chapter 43), and PL/Python (PL/Python). 
Wouldn't it be better to have a paragraph like this ?
There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQLPL/TclPL/Perl and PL/Python. 

So I don't care if that link is a section, a appendix, a chapter, I'm sure I'll go there only if I really want.
 
But the numbers do provide some subtle clues as to the relationship of the
linked references to the page we are on AND other references within
that page.

Well, if a link was written on that page, independently if it's a chapter, a GUC, a section, it's important for the user to know. And again, I don't care if I'm jumping to a distant section or chapter, it's important to understand entirely the page I'm reading.

So, my intention here is to provide the user with continuous reading. If I read a paragraph with links but it's displayed as if it were in a book without footnotes, it gives me a much faster and easier reading experience. If I have to stop my reading to open other links because I don't know if they're important or not, or also bad ignore some words, the reading isn't as productive.

regards
Marcos

pgsql-hackers by date:

Previous
From: Henson Choi
Date:
Subject: Re: SQL Property Graph Queries (SQL/PGQ)
Next
From: Jelte Fennema-Nio
Date:
Subject: Re: Add "format" target to make and ninja to run pgindent and pgperltidy