public inbox for [email protected]help / color / mirror / Atom feed
Adding an explaining title to Notes on SGML 8+ messages / 4 participants [nested] [flat]
* Adding an explaining title to Notes on SGML @ 2026-04-22 18:59 Marcos Pegoraro <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Marcos Pegoraro @ 2026-04-22 18:59 UTC (permalink / raw) To: pgsql-hackers 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 Attachments: [application/octet-stream] Adding an explaining title to Notes.diff (1.6K, 3-Adding%20an%20explaining%20title%20to%20Notes.diff) download | inline diff: From c4819f375b032ed18b3d1c39a4d781a3ea70c04a Mon Sep 17 00:00:00 2001 From: PegoraroF10 <[email protected]> Date: Wed, 22 Apr 2026 15:37:41 -0300 Subject: [PATCH] Sometimes we have a Notes tag but it doesn't specify about what it is talking. So if we add a <title> to it then user doesn't need to read all that Note to see if it's important or not. --- doc/src/sgml/func/func-aggregate.sgml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/func/func-aggregate.sgml b/doc/src/sgml/func/func-aggregate.sgml index 8b5eaeb2e94..6f92f737d58 100644 --- a/doc/src/sgml/func/func-aggregate.sgml +++ b/doc/src/sgml/func/func-aggregate.sgml @@ -696,6 +696,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; </para> <note> + <title>Note on bool_and and bool_or</title> <indexterm> <primary>ANY</primary> </indexterm> @@ -722,6 +723,7 @@ SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...; </note> <note> + <title>Note on count(*)</title> <para> Users accustomed to working with other SQL database management systems might be disappointed by the performance of the @@ -730,7 +732,7 @@ SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...; <programlisting> SELECT count(*) FROM sometable; </programlisting> - will require effort proportional to the size of the table: + This will require effort proportional to the size of the table: <productname>PostgreSQL</productname> will need to scan either the entire table or the entirety of an index that includes all rows in the table. -- 2.51.2.windows.1 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 07:55 Daniel Gustafsson <[email protected]> parent: Marcos Pegoraro <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Daniel Gustafsson @ 2026-04-23 07:55 UTC (permalink / raw) To: Marcos Pegoraro <[email protected]>; +Cc: pgsql-hackers > On 22 Apr 2026, at 20:59, Marcos Pegoraro <[email protected]> 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 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 12:13 Marcos Pegoraro <[email protected]> parent: Daniel Gustafsson <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: Marcos Pegoraro @ 2026-04-23 12:13 UTC (permalink / raw) To: Daniel Gustafsson <[email protected]>; +Cc: pgsql-hackers Em qui., 23 de abr. de 2026 às 04:55, Daniel Gustafsson <[email protected]> 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 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 12:27 David G. Johnston <[email protected]> parent: Marcos Pegoraro <[email protected]> 0 siblings, 1 reply; 8+ messages in thread From: David G. Johnston @ 2026-04-23 12:27 UTC (permalink / raw) To: Marcos Pegoraro <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; pgsql-hackers On Thursday, April 23, 2026, Marcos Pegoraro <[email protected]> wrote: > Em qui., 23 de abr. de 2026 às 04:55, Daniel Gustafsson <[email protected]> > 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. ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 13:33 Marcos Pegoraro <[email protected]> parent: David G. Johnston <[email protected]> 0 siblings, 2 replies; 8+ messages in thread From: Marcos Pegoraro @ 2026-04-23 13:33 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; pgsql-hackers Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston < [email protected]> 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 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 13:50 David G. Johnston <[email protected]> parent: Marcos Pegoraro <[email protected]> 1 sibling, 1 reply; 8+ messages in thread From: David G. Johnston @ 2026-04-23 13:50 UTC (permalink / raw) To: Marcos Pegoraro <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; pgsql-hackers On Thu, Apr 23, 2026 at 6:34 AM Marcos Pegoraro <[email protected]> wrote: > Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston < > [email protected]> 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. ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-23 14:09 Marcos Pegoraro <[email protected]> parent: David G. Johnston <[email protected]> 0 siblings, 0 replies; 8+ messages in thread From: Marcos Pegoraro @ 2026-04-23 14:09 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; pgsql-hackers Em qui., 23 de abr. de 2026 às 10:51, David G. Johnston < [email protected]> 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 ^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Adding an explaining title to Notes on SGML @ 2026-04-25 13:35 Peter Eisentraut <[email protected]> parent: Marcos Pegoraro <[email protected]> 1 sibling, 0 replies; 8+ messages in thread From: Peter Eisentraut @ 2026-04-25 13:35 UTC (permalink / raw) To: Marcos Pegoraro <[email protected]>; David G. Johnston <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>; pgsql-hackers On 23.04.26 15:33, Marcos Pegoraro wrote: > Em qui., 23 de abr. de 2026 às 09:27, David G. Johnston > <[email protected] <mailto:[email protected]>> 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. ^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2026-04-25 13:35 UTC | newest] Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-04-22 18:59 Adding an explaining title to Notes on SGML Marcos Pegoraro <[email protected]> 2026-04-23 07:55 ` Daniel Gustafsson <[email protected]> 2026-04-23 12:13 ` Marcos Pegoraro <[email protected]> 2026-04-23 12:27 ` David G. Johnston <[email protected]> 2026-04-23 13:33 ` Marcos Pegoraro <[email protected]> 2026-04-23 13:50 ` David G. Johnston <[email protected]> 2026-04-23 14:09 ` Marcos Pegoraro <[email protected]> 2026-04-25 13:35 ` Peter Eisentraut <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox