public inbox for [email protected]  

help / color / mirror / Atom feed

From: Marcos Pegoraro <[email protected]>
To: pgsql-hackers <[email protected]>
Subject: Adding an explaining title to Notes on SGML
Date: Wed, 22 Apr 2026 15:59:47 -0300
Message-ID: <CAB-JLwY4izzCHDjS=Xb0KMc7uXbg6JjuMdRA2ri2CqYbeMDMEw@mail.gmail.com> (raw)

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

view thread (8+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected]
  Subject: Re: Adding an explaining title to Notes on SGML
  In-Reply-To: <CAB-JLwY4izzCHDjS=Xb0KMc7uXbg6JjuMdRA2ri2CqYbeMDMEw@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox