public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedIndex / glossary adjustments for Git & GUC
9+ messages / 3 participants
[nested] [flat]
* Index / glossary adjustments for Git & GUC
@ 2025-08-12 23:16 Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 9+ messages in thread
From: Robert Treat @ 2025-08-12 23:16 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Howdy folks,
Two small "clean up" patches. These are against HEAD, though could
likely be backpatched to v18 if one were inclined.
The first patch removes the term "Git" from the acronyms section and
instead creates an index entry that points to our source repository
information.
For the second, ISTM we use the term GUC to refer to parameters pretty
liberally, but the term is not that easy to find in the docs (and
website search gives what is probably the best answer as result #7 of
8). This creates an index entry for the term, as well as a glossary
entry which explains how it is commonly used.
Robert Treat
https://xzilla.net
Attachments:
[application/octet-stream] v1-0001-Remove-git-from-the-acronyms-section-since-it-is-.patch (1.5K, 2-v1-0001-Remove-git-from-the-acronyms-section-since-it-is-.patch)
download | inline diff:
From c184bf7e715e52f138b5e3809bd65a9294b23d8b Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Tue, 12 Aug 2025 18:11:40 -0400
Subject: [PATCH v1 1/2] Remove git from the acronyms section, since it is not
one. Add entry in the index, pointing towards our repo info.
Content-Type: text/patch; charset="utf-8"
---
doc/src/sgml/acronyms.sgml | 10 ----------
doc/src/sgml/sourcerepo.sgml | 2 ++
2 files changed, 2 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 2f906e9f018..511c7fd1a5d 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -273,16 +273,6 @@
</listitem>
</varlistentry>
- <varlistentry>
- <term><acronym>Git</acronym></term>
- <listitem>
- <para>
- <ulink
- url="https://en.wikipedia.org/wiki/Git">Git</ulink>
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><acronym>GMT</acronym></term>
<listitem>
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 6c13c5a30cd..3ecb4cd7f76 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -3,6 +3,8 @@
<appendix id="sourcerepo">
<title>The Source Code Repository</title>
+ <indexterm zone="sourcerepo"><primary>Git</primary></indexterm>
+
<para>
The <productname>PostgreSQL</productname> source code is stored and managed
using the <productname>Git</productname> version control system. A public
--
2.24.3 (Apple Git-128)
[application/octet-stream] v1-0002-GUC-is-a-pretty-common-term-which-currently-only-.patch (1.7K, 3-v1-0002-GUC-is-a-pretty-common-term-which-currently-only-.patch)
download | inline diff:
From 48d09cd2c6fef78592b570a9458e41512dbb445e Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Tue, 12 Aug 2025 19:05:02 -0400
Subject: [PATCH v1 2/2] GUC is a pretty common term, which currently only
shows up in acronym, and #7 search term on website, so add index and glossary
entries.
Content-Type: text/patch; charset="utf-8"
---
doc/src/sgml/config.sgml | 2 ++
doc/src/sgml/glossary.sgml | 15 +++++++++++++++
2 files changed, 17 insertions(+)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 20ccb2d6b54..e12d1ff3087 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -18,6 +18,8 @@
<sect1 id="config-setting">
<title>Setting Parameters</title>
+ <indexterm><primary>GUC</primary></indexterm>
+
<sect2 id="config-setting-names-values">
<title>Parameter Names and Values</title>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index b88cac598e9..086909c7305 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -897,6 +897,21 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-guc">
+ <glossterm>GUC</glossterm>
+ <glossdef>
+ <para>
+ Commonly used term within <productname>PostgreSQL</productname> for
+ configuration parameters. Typically meant to refer to user settable
+ parameters, but it can also refer to internal or build-time parameters.
+ </para>
+ <para>
+ For information on working with configuration parameters, see
+ <xref linkend="config-setting"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-heap">
<glossterm>Heap</glossterm>
<glossdef>
--
2.24.3 (Apple Git-128)
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-08-13 08:03 Daniel Gustafsson <daniel@yesql.se>
parent: Robert Treat <rob@xzilla.net>
0 siblings, 2 replies; 9+ messages in thread
From: Daniel Gustafsson @ 2025-08-13 08:03 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: pgsql-docs@lists.postgresql.org
> On 13 Aug 2025, at 01:16, Robert Treat <rob@xzilla.net> wrote:
> The first patch removes the term "Git" from the acronyms section and
> instead creates an index entry that points to our source repository
> information.
This was previously discussed in this thread:
https://postgr.es/m/8241CED6-F408-4660-A1AA-F3393AA26219%40yesql.se
> For the second, ISTM we use the term GUC to refer to parameters pretty
> liberally, but the term is not that easy to find in the docs (and
> website search gives what is probably the best answer as result #7 of
> 8). This creates an index entry for the term, as well as a glossary
> entry which explains how it is commonly used.
This seems like a good idea.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-08-13 14:23 Robert Treat <rob@xzilla.net>
parent: Daniel Gustafsson <daniel@yesql.se>
1 sibling, 1 reply; 9+ messages in thread
From: Robert Treat @ 2025-08-13 14:23 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, Aug 13, 2025 at 4:03 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 13 Aug 2025, at 01:16, Robert Treat <rob@xzilla.net> wrote:
>
> > The first patch removes the term "Git" from the acronyms section and
> > instead creates an index entry that points to our source repository
> > information.
>
> This was previously discussed in this thread:
>
> https://postgr.es/m/8241CED6-F408-4660-A1AA-F3393AA26219%40yesql.se
>
If people feel strongly that users are getting real benefit from our
docs providing a link to wikipedia to explain what git is, I don't see
it but okay... but the true value add for me was adding the index
entry for the source repository information, so I'd like to see that
added either way.
Robert Treat
https://xzilla.net
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-08-14 02:48 Fujii Masao <masao.fujii@gmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
1 sibling, 1 reply; 9+ messages in thread
From: Fujii Masao @ 2025-08-14 02:48 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Robert Treat <rob@xzilla.net>; pgsql-docs@lists.postgresql.org
On Wed, Aug 13, 2025 at 5:04 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 13 Aug 2025, at 01:16, Robert Treat <rob@xzilla.net> wrote:
>
> > The first patch removes the term "Git" from the acronyms section and
> > instead creates an index entry that points to our source repository
> > information.
>
> This was previously discussed in this thread:
>
> https://postgr.es/m/8241CED6-F408-4660-A1AA-F3393AA26219%40yesql.se
>
> > For the second, ISTM we use the term GUC to refer to parameters pretty
> > liberally, but the term is not that easy to find in the docs (and
> > website search gives what is probably the best answer as result #7 of
> > 8). This creates an index entry for the term, as well as a glossary
> > entry which explains how it is commonly used.
>
> This seems like a good idea.
+1
+ <glossentry id="glossary-guc">
+ <glossterm>GUC</glossterm>
Should we also include the full term "Grand Unified Configuration" here, e.g.,
"Grand unified configuration (GUC)", similar to how "Log sequence number (LSN)"
is shown in the glossary? Even though it's already in the acronyms docs,
it might be helpful to include it in the glossary as well.
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-08-14 02:49 Fujii Masao <masao.fujii@gmail.com>
parent: Robert Treat <rob@xzilla.net>
0 siblings, 0 replies; 9+ messages in thread
From: Fujii Masao @ 2025-08-14 02:49 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On Wed, Aug 13, 2025 at 11:23 PM Robert Treat <rob@xzilla.net> wrote:
> it but okay... but the true value add for me was adding the index
> entry for the source repository information, so I'd like to see that
> added either way.
+1 to add the index entry.
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-08-15 04:12 Robert Treat <rob@xzilla.net>
parent: Fujii Masao <masao.fujii@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Robert Treat @ 2025-08-15 04:12 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On Wed, Aug 13, 2025 at 10:48 PM Fujii Masao <masao.fujii@gmail.com> wrote:
> On Wed, Aug 13, 2025 at 5:04 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> > > On 13 Aug 2025, at 01:16, Robert Treat <rob@xzilla.net> wrote:
> >
> > > The first patch removes the term "Git" from the acronyms section and
> > > instead creates an index entry that points to our source repository
> > > information.
> >
> > This was previously discussed in this thread:
> >
> > https://postgr.es/m/8241CED6-F408-4660-A1AA-F3393AA26219%40yesql.se
> >
> > > For the second, ISTM we use the term GUC to refer to parameters pretty
> > > liberally, but the term is not that easy to find in the docs (and
> > > website search gives what is probably the best answer as result #7 of
> > > 8). This creates an index entry for the term, as well as a glossary
> > > entry which explains how it is commonly used.
> >
> > This seems like a good idea.
>
> +1
>
> + <glossentry id="glossary-guc">
> + <glossterm>GUC</glossterm>
>
> Should we also include the full term "Grand Unified Configuration" here, e.g.,
> "Grand unified configuration (GUC)", similar to how "Log sequence number (LSN)"
> is shown in the glossary? Even though it's already in the acronyms docs,
> it might be helpful to include it in the glossary as well.
>
So when I first wrote this, I wrote the following:
Originally a short-hand for Grand Unified Configuration, the subsystem
which controls PostgreSQL server configuration, it is now a commonly
used term for the individual configuration parameters themselves.
While typically meant to refer to user settable parameters, it can
also refer to internal or build-time parameters.
That felt a little verbose, and ISTM the more important part was
focusing on GUCs as postgres jargon for parameters rather than
explaining the history (which as you noted is explained elsewhere),
but I can see the argument for completeness over clarity.
Robert Treat
https://xzilla.net
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2025-12-31 15:39 Robert Treat <rob@xzilla.net>
parent: Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 9+ messages in thread
From: Robert Treat @ 2025-12-31 15:39 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On Fri, Aug 15, 2025 at 12:12 AM Robert Treat <rob@xzilla.net> wrote:
> On Wed, Aug 13, 2025 at 10:48 PM Fujii Masao <masao.fujii@gmail.com> wrote:
> > On Wed, Aug 13, 2025 at 5:04 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> > > > On 13 Aug 2025, at 01:16, Robert Treat <rob@xzilla.net> wrote:
> > >
> > > > The first patch removes the term "Git" from the acronyms section and
> > > > instead creates an index entry that points to our source repository
> > > > information.
> > >
> > > This was previously discussed in this thread:
> > >
> > > https://postgr.es/m/8241CED6-F408-4660-A1AA-F3393AA26219%40yesql.se
> > >
> > > > For the second, ISTM we use the term GUC to refer to parameters pretty
> > > > liberally, but the term is not that easy to find in the docs (and
> > > > website search gives what is probably the best answer as result #7 of
> > > > 8). This creates an index entry for the term, as well as a glossary
> > > > entry which explains how it is commonly used.
> > >
> > > This seems like a good idea.
> >
> > +1
> >
> > + <glossentry id="glossary-guc">
> > + <glossterm>GUC</glossterm>
> >
> > Should we also include the full term "Grand Unified Configuration" here, e.g.,
> > "Grand unified configuration (GUC)", similar to how "Log sequence number (LSN)"
> > is shown in the glossary? Even though it's already in the acronyms docs,
> > it might be helpful to include it in the glossary as well.
> >
>
Howdy folks,
While doing some end of year clean up, I noticed I hadn't followed up
on this thread, so attached is an updated set of patches, the first of
which adds the index entry for git, and the second which adds the
glossary entry for GUC, both in accordance with the above feedback.
Robert Treat
https://xzilla.net
Attachments:
[application/octet-stream] v2-0001-Add-Git-to-the-index-pointing-towards-repo-info.patch (869B, 2-v2-0001-Add-Git-to-the-index-pointing-towards-repo-info.patch)
download | inline diff:
From c635f54f30fe71c98c243cb895051f04ea04210e Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Tue, 12 Aug 2025 18:11:40 -0400
Subject: [PATCH v2 1/2] Add Git to the index, pointing towards repo info.
Content-Type: text/plain; charset="utf-8"
---
doc/src/sgml/sourcerepo.sgml | 2 ++
1 file changed, 2 insertions(+)
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index f4368e83ab3..b9ea59ae329 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -3,6 +3,8 @@
<appendix id="sourcerepo">
<title>The Source Code Repository</title>
+ <indexterm zone="sourcerepo"><primary>Git</primary></indexterm>
+
<para>
The <productname>PostgreSQL</productname> source code is stored and managed
using the <productname>Git</productname> version control system. A public
--
2.24.3 (Apple Git-128)
[application/octet-stream] v2-0002-GUC-is-a-pretty-common-term-which-currently-only-.patch (1.8K, 3-v2-0002-GUC-is-a-pretty-common-term-which-currently-only-.patch)
download | inline diff:
From 4349ceb7f94a166d4274b054f580be92bc26808c Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Tue, 12 Aug 2025 19:05:02 -0400
Subject: [PATCH v2 2/2] GUC is a pretty common term, which currently only
shows up in acronym, and #7 search term on website, so add index and glossary
entries.
Content-Type: text/plain; charset="utf-8"
---
doc/src/sgml/config.sgml | 2 ++
doc/src/sgml/glossary.sgml | 17 +++++++++++++++++
2 files changed, 19 insertions(+)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cdfe8e376f0..755a6e19af7 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -18,6 +18,8 @@
<sect1 id="config-setting">
<title>Setting Parameters</title>
+ <indexterm><primary>GUC</primary></indexterm>
+
<sect2 id="config-setting-names-values">
<title>Parameter Names and Values</title>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index a76cf5c383f..e2db5bcc78c 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -912,6 +912,23 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-guc">
+ <glossterm>GUC</glossterm>
+ <glossdef>
+ <para>
+ Based on a short-hand for Grand Unified Configuration, the subsystem
+ which controls server configuration, it is now a commonly used term
+ for the individual configuration parameters themselves. Typically meant
+ to refer to user settable parameters, it can also refer to internal or
+ build-time parameters.
+ </para>
+ <para>
+ For information on working with configuration parameters, see
+ <xref linkend="config-setting"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-heap">
<glossterm>Heap</glossterm>
<glossdef>
--
2.24.3 (Apple Git-128)
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2026-01-06 06:30 Fujii Masao <masao.fujii@gmail.com>
parent: Robert Treat <rob@xzilla.net>
0 siblings, 1 reply; 9+ messages in thread
From: Fujii Masao @ 2026-01-06 06:30 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On Thu, Jan 1, 2026 at 12:39 AM Robert Treat <rob@xzilla.net> wrote:
> While doing some end of year clean up, I noticed I hadn't followed up
> on this thread, so attached is an updated set of patches, the first of
> which adds the index entry for git, and the second which adds the
> glossary entry for GUC, both in accordance with the above feedback.
Thanks for updating the patches! LGTM.
Barring any objections, I'll commit them.
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Index / glossary adjustments for Git & GUC
@ 2026-01-07 05:00 Fujii Masao <masao.fujii@gmail.com>
parent: Fujii Masao <masao.fujii@gmail.com>
0 siblings, 0 replies; 9+ messages in thread
From: Fujii Masao @ 2026-01-07 05:00 UTC (permalink / raw)
To: Robert Treat <rob@xzilla.net>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
On Tue, Jan 6, 2026 at 3:30 PM Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Thu, Jan 1, 2026 at 12:39 AM Robert Treat <rob@xzilla.net> wrote:
> > While doing some end of year clean up, I noticed I hadn't followed up
> > on this thread, so attached is an updated set of patches, the first of
> > which adds the index entry for git, and the second which adds the
> > glossary entry for GUC, both in accordance with the above feedback.
>
> Thanks for updating the patches! LGTM.
>
> Barring any objections, I'll commit them.
I've pushed the patches. Thanks!
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2026-01-07 05:00 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-08-12 23:16 Index / glossary adjustments for Git & GUC Robert Treat <rob@xzilla.net>
2025-08-13 08:03 ` Daniel Gustafsson <daniel@yesql.se>
2025-08-13 14:23 ` Robert Treat <rob@xzilla.net>
2025-08-14 02:49 ` Fujii Masao <masao.fujii@gmail.com>
2025-08-14 02:48 ` Fujii Masao <masao.fujii@gmail.com>
2025-08-15 04:12 ` Robert Treat <rob@xzilla.net>
2025-12-31 15:39 ` Robert Treat <rob@xzilla.net>
2026-01-06 06:30 ` Fujii Masao <masao.fujii@gmail.com>
2026-01-07 05:00 ` Fujii Masao <masao.fujii@gmail.com>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox