Обсуждение: Index / glossary adjustments for Git & GUC

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

> 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

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

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

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

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