Horton
Menu

Thread

  1. Adding an explaining title to Notes on SGML

    Marcos Pegoraro <marcos@f10.com.br> — 2026-04-22T18:59:47Z

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

  2. Re: Adding an explaining title to Notes on SGML

    Daniel Gustafsson <daniel@yesql.se> — 2026-04-23T07:55:28Z

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

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

  3. Re: Adding an explaining title to Notes on SGML

    Marcos Pegoraro <marcos@f10.com.br> — 2026-04-23T12:13:50Z

    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

  4. Re: Adding an explaining title to Notes on SGML

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-23T12:27:08Z

    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.

  5. Re: Adding an explaining title to Notes on SGML

    Marcos Pegoraro <marcos@f10.com.br> — 2026-04-23T13:33:37Z

    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

  6. Re: Adding an explaining title to Notes on SGML

    David G. Johnston <david.g.johnston@gmail.com> — 2026-04-23T13:50:31Z

    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.

  7. Re: Adding an explaining title to Notes on SGML

    Marcos Pegoraro <marcos@f10.com.br> — 2026-04-23T14:09:11Z

    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

  8. Re: Adding an explaining title to Notes on SGML

    Peter Eisentraut <peter@eisentraut.org> — 2026-04-25T13:35:39Z

    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.