Обсуждение: Adding an explaining title to Notes on SGML
I noticed that a "This" was missing when reading the Notes of the Aggregates page, so I thought... wouldn't it be better if we had a title in some of the Notes ?
Because in many cases, like this example, you have a huge table and below it a Notes. But what is this Notes talking about ?
If we had a title specifying exactly what it's about, it would be easier for the user. In this example, there are dozens of aggregates but Notes talks only for 2 of them.
There are 300 Notes on SGML files, I did these 2 Notes only to ask you if this way is fine. And obviously would do them all if you think it's fine.
And additionally the title tag needs to have only
<title>bool_and and bool_or</title>
<title>bool_and and bool_or</title>
not
<title>Note on bool_and and bool_or</title>
But this I can change on XSL files to automatically add a title when it exists.
Regards
Marcos
Вложения
> On 22 Apr 2026, at 20:59, Marcos Pegoraro <marcos@f10.com.br> wrote: > > I noticed that a "This" was missing when reading the Notes of the Aggregates page, so I thought... wouldn't it be betterif we had a title in some of the Notes ? > Because in many cases, like this example, you have a huge table and below it a Notes. But what is this Notes talking about? Notes are IMHO useful when they cause the reader to reflect on the <para> they just read. I think it's an antipattern to have notes so far removed from the relevant <para> that we need a title for it. A reader looking for info on count() will find it in the table and read it - we can't really expect them to keep scrolling a few pages down to see if there might be more info that wasn't linked to. Wouldn't it make more sense to refactor to move the information in the note closer to what the note is regarding? -- Daniel Gustafsson
Em qui., 23 de abr. de 2026 às 04:55, Daniel Gustafsson <daniel@yesql.se> escreveu:
Wouldn't it make more sense to refactor to move the information in the note
closer to what the note is regarding?
Fine, I agree that that Note is probably not read because it is so far. And we could do the same thing for footnotes, these appear very, very far from the text they refer to. But the problem is how to display these notes.
In this example, the aggregates table is huge, and it wouldn't be interesting to break it up just because of a note.
Also, a note refers to two items in the table, which are bool_and and bool_or, so what do we do ? Repeat the information ?
regards
Marcos
On Thursday, April 23, 2026, Marcos Pegoraro <marcos@f10.com.br> wrote:
Em qui., 23 de abr. de 2026 às 04:55, Daniel Gustafsson <daniel@yesql.se> escreveu:Wouldn't it make more sense to refactor to move the information in the note
closer to what the note is regarding?Also, a note refers to two items in the table, which are bool_and and bool_or, so what do we do ? Repeat the information ?
Personally, I’d like to do two things here instead of a note. Use a footnote, but add entries for any/some to the table and use the description to say they are not implemented and to use bool_and/bool_or instead, then anchor the footnote at these entries.
That way, people looking for these SQL standard functions actually find them where they expect and understand why they are missing. Index entries wouldn’t hurt.
The note actually seems counter-productive for the typical PostgreSQL user who doesn’t even know what is in the standard. And an unintuitive place to look if you know the function names already.
David J.
Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston <david.g.johnston@gmail.com> escreveu:
Use a footnote, but add entries for any/some to the table and use the description to say they are not implemented and to use bool_and/bool_or instead, then anchor the footnote at these entries.
Honestly, I'd like to remove all footnotes. The watermark identifying them is so small that many people don't even see that it's a link, and the fact that it's at the bottom of the page makes it even more isolated from the text it refers to.
Another thing I've been thinking about is the "see below". Because it doesn't have a link and in some cases is placed within a large paragraph, that "see below" appears very far away, and the user also doesn't know how to find it.
Perhaps we can find a better way to display notes, footnotes, and see below.
regards
Marcos
On Thu, Apr 23, 2026 at 6:34 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston <david.g.johnston@gmail.com> escreveu:Use a footnote, but add entries for any/some to the table and use the description to say they are not implemented and to use bool_and/bool_or instead, then anchor the footnote at these entries.Honestly, I'd like to remove all footnotes. The watermark identifying them is so small that many people don't even see that it's a link, and the fact that it's at the bottom of the page makes it even more isolated from the text it refers to.
This seems solvable in the xslt/CSS. Instead of traditional superscript print the link at normal-ish size with normal underline indicator for it being a link. On the website we could possibly even code in a tooltip on hover to show the note content without clicking or scrolling the page. And in this case choosing not to follow the footnote only means one loses out on understanding why we didn't implement any/some aggregates, not that main info, which is repeated for each, that they are not implemented. I'd call that a top-tier example of when to use a footnote. And agree we can do better styling it.
David J.
Em qui., 23 de abr. de 2026 às 10:51, David G. Johnston <david.g.johnston@gmail.com> escreveu:
On the website we could possibly even code in a tooltip on hover to show the note content without clicking or scrolling the page.
That's fine, but you need to remember that when using tablets and phones we don't have a mouse, therefore hovering isn't an option.
regards
Marcos
On 23.04.26 15:33, Marcos Pegoraro wrote: > Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston > <david.g.johnston@gmail.com <mailto:david.g.johnston@gmail.com>> escreveu: > > Use a footnote, but add entries for any/some to the table and > use the description to say they are not implemented and to use > bool_and/bool_or instead, then anchor the footnote at these entries. > > > Honestly, I'd like to remove all footnotes. The watermark identifying > them is so small that many people don't even see that it's a link, and > the fact that it's at the bottom of the page makes it even more isolated > from the text it refers to. > Another thing I've been thinking about is the "see below". Because it > doesn't have a link and in some cases is placed within a large > paragraph, that "see below" appears very far away, and the user also > doesn't know how to find it. I agree, new footnotes should be avoided.