pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedsome new glossary entries
5+ messages / 3 participants
[nested] [flat]
* some new glossary entries
@ 2023-05-02 07:05 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 1 reply; 5+ messages in thread
From: Peter Eisentraut @ 2023-05-02 07:05 UTC (permalink / raw)
To: pgsql-docs
I wrote glossary entries for some terms I wanted to look up there but
didn't find: "restartpoint" and "LSN". I put this together based on
existing text. "LSN" was already in the acronyms list but I think it's
more appropriate in the glossary, so I moved things around a bit.
From 8ef8a2f08bc4225bfb3528db78e57021d682ec93 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 2 May 2023 08:54:54 +0200
Subject: [PATCH 1/2] doc: New glossary entry "Restartpoint"
---
doc/src/sgml/glossary.sgml | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 29bf1873bd..5e24b31fa0 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1342,6 +1342,20 @@ <title>Glossary</title>
</glossdef>
</glossentry>
+ <glossentry id="glossary-restartpoint">
+ <glossterm>Restartpoint</glossterm>
+ <glossdef>
+ <para>
+ A variant of a <glossterm
+ linkend="glossary-checkpoint">checkpoint</glossterm> performed on a
+ <glossterm linkend="glossary-replica">replica</glossterm>.
+ </para>
+ <para>
+ For more information, see <xref linkend="wal-configuration"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-result-set">
<glossterm>Result set</glossterm>
<glossdef>
--
2.40.0
From 48e0db4d09f09cb57c70faeddfcf46594c0f0d98 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 2 May 2023 08:55:50 +0200
Subject: [PATCH 2/2] doc: New glossary entry "Log sequence number"
"LSN" was already listed in the Acronyms appendix, but it is more
suitable as a glossary entry, so move it there and have the acronyms
entry link into the glossary.
---
doc/src/sgml/acronyms.sgml | 3 +--
doc/src/sgml/glossary.sgml | 22 ++++++++++++++++++++++
doc/src/sgml/stylesheet-common.xsl | 1 +
3 files changed, 24 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index a60ff54a6c..22e0dc5c70 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -402,8 +402,7 @@ <title>Acronyms</title>
<term><acronym>LSN</acronym></term>
<listitem>
<para>
- Log Sequence Number, see <link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>
- and <link linkend="wal-internals">WAL Internals</link>.
+ <glossterm linkend="glossary-log-sequence-number">Log Sequence Number</glossterm>
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 5e24b31fa0..4fc240b180 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1039,6 +1039,28 @@ <title>Glossary</title>
</glossdef>
</glossentry>
+ <glossentry id="glossary-log-sequence-number">
+ <glossterm>Log sequence number</glossterm>
+ <acronym>LSN</acronym>
+ <glossdef>
+ <para>
+ Byte offset into the <glossterm linkend="glossary-wal">WAL</glossterm>,
+ increasing monotonically with each new <glossterm
+ linkend="glossary-wal-record">WAL record</glossterm>.
+ </para>
+ <para>
+ For more information, see <link
+ linkend="datatype-pg-lsn"><type>pg_lsn</type></link> and <xref
+ linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lsn">
+ <glossterm>LSN</glossterm>
+ <glosssee otherterm="glossary-log-sequence-number"/>
+ </glossentry>
+
<glossentry>
<glossterm>Master (server)</glossterm>
<glosssee otherterm="glossary-primary-server" />
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index d2928f86eb..b7fb6c489a 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -28,6 +28,7 @@
</xsl:param>
<xsl:param name="callout.graphics" select="'0'"></xsl:param>
+<xsl:param name="glossentry.show.acronym">yes</xsl:param>
<xsl:param name="toc.section.depth">2</xsl:param>
<xsl:param name="linenumbering.extension" select="'0'"></xsl:param>
<xsl:param name="section.autolabel" select="1"></xsl:param>
--
2.40.0
Attachments:
[text/plain] 0001-doc-New-glossary-entry-Restartpoint.patch (1.1K, ../../60915312-62cd-9c94-0d94-556023ece45f@enterprisedb.com/2-0001-doc-New-glossary-entry-Restartpoint.patch)
download | inline diff:
From 8ef8a2f08bc4225bfb3528db78e57021d682ec93 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 2 May 2023 08:54:54 +0200
Subject: [PATCH 1/2] doc: New glossary entry "Restartpoint"
---
doc/src/sgml/glossary.sgml | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 29bf1873bd..5e24b31fa0 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1342,6 +1342,20 @@ <title>Glossary</title>
</glossdef>
</glossentry>
+ <glossentry id="glossary-restartpoint">
+ <glossterm>Restartpoint</glossterm>
+ <glossdef>
+ <para>
+ A variant of a <glossterm
+ linkend="glossary-checkpoint">checkpoint</glossterm> performed on a
+ <glossterm linkend="glossary-replica">replica</glossterm>.
+ </para>
+ <para>
+ For more information, see <xref linkend="wal-configuration"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-result-set">
<glossterm>Result set</glossterm>
<glossdef>
--
2.40.0
[text/plain] 0002-doc-New-glossary-entry-Log-sequence-number.patch (2.7K, ../../60915312-62cd-9c94-0d94-556023ece45f@enterprisedb.com/3-0002-doc-New-glossary-entry-Log-sequence-number.patch)
download | inline diff:
From 48e0db4d09f09cb57c70faeddfcf46594c0f0d98 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 2 May 2023 08:55:50 +0200
Subject: [PATCH 2/2] doc: New glossary entry "Log sequence number"
"LSN" was already listed in the Acronyms appendix, but it is more
suitable as a glossary entry, so move it there and have the acronyms
entry link into the glossary.
---
doc/src/sgml/acronyms.sgml | 3 +--
doc/src/sgml/glossary.sgml | 22 ++++++++++++++++++++++
doc/src/sgml/stylesheet-common.xsl | 1 +
3 files changed, 24 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index a60ff54a6c..22e0dc5c70 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -402,8 +402,7 @@ <title>Acronyms</title>
<term><acronym>LSN</acronym></term>
<listitem>
<para>
- Log Sequence Number, see <link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>
- and <link linkend="wal-internals">WAL Internals</link>.
+ <glossterm linkend="glossary-log-sequence-number">Log Sequence Number</glossterm>
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 5e24b31fa0..4fc240b180 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1039,6 +1039,28 @@ <title>Glossary</title>
</glossdef>
</glossentry>
+ <glossentry id="glossary-log-sequence-number">
+ <glossterm>Log sequence number</glossterm>
+ <acronym>LSN</acronym>
+ <glossdef>
+ <para>
+ Byte offset into the <glossterm linkend="glossary-wal">WAL</glossterm>,
+ increasing monotonically with each new <glossterm
+ linkend="glossary-wal-record">WAL record</glossterm>.
+ </para>
+ <para>
+ For more information, see <link
+ linkend="datatype-pg-lsn"><type>pg_lsn</type></link> and <xref
+ linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lsn">
+ <glossterm>LSN</glossterm>
+ <glosssee otherterm="glossary-log-sequence-number"/>
+ </glossentry>
+
<glossentry>
<glossterm>Master (server)</glossterm>
<glosssee otherterm="glossary-primary-server" />
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index d2928f86eb..b7fb6c489a 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -28,6 +28,7 @@
</xsl:param>
<xsl:param name="callout.graphics" select="'0'"></xsl:param>
+<xsl:param name="glossentry.show.acronym">yes</xsl:param>
<xsl:param name="toc.section.depth">2</xsl:param>
<xsl:param name="linenumbering.extension" select="'0'"></xsl:param>
<xsl:param name="section.autolabel" select="1"></xsl:param>
--
2.40.0
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: some new glossary entries
@ 2023-05-02 10:06 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2023-05-02 10:06 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-docs
> On 2 May 2023, at 09:05, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
>
> I wrote glossary entries for some terms I wanted to look up there but didn't find: "restartpoint" and "LSN". I put this together based on existing text. "LSN" was already in the acronyms list but I think it's more appropriate in the glossary, so I moved things around a bit.
+1 LGTM.
+ <glossentry id="glossary-lsn">
+ <glossterm>LSN</glossterm>
+ <glosssee otherterm="glossary-log-sequence-number"/>
+ </glossentry>
The other <glosssee otherterm="foo" /> entries doesn't have a glossentry id
attribute set, is the use here related to the glossentry.show.acronym param?
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: some new glossary entries
@ 2023-05-02 10:24 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: Alvaro Herrera @ 2023-05-02 10:24 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; pgsql-docs
On 2023-May-02, Daniel Gustafsson wrote:
> + <glossentry id="glossary-lsn">
> + <glossterm>LSN</glossterm>
> + <glosssee otherterm="glossary-log-sequence-number"/>
> + </glossentry>
>
> The other <glosssee otherterm="foo" /> entries doesn't have a glossentry id
> attribute set, is the use here related to the glossentry.show.acronym param?
I debated with myself for 347d2b07fcc2 on whether to add id attribs to
<glosssee> entries. The only saving grace for doing that is that you
can link to such entries; but if you do that, you're only causing the
user one more click in order to see the definition they want to see. So
in the end I decided not make the glosssee's directly referenceable.
And I think this new entry shouldn't have an id either.
I think that what glossentry.show.acronym allows is to show the
<acronym> text that's part of the main entry:
https://stackoverflow.com/questions/28869578/docbook-5-rendering-without-abbrev-tag/28879785#2887978...
so the fact that there's an id in the other entry doesn't change
anything.
If we do turn glossentry.show.acronym on (and I don't see any reason not
to), we can follow up later to add <acronym> and <abbrev> tags to other
entries, too.
--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
"I'm always right, but sometimes I'm more right than other times."
(Linus Torvalds)
https://lore.kernel.org/git/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: some new glossary entries
@ 2023-05-02 10:55 Daniel Gustafsson <daniel@yesql.se>
parent: Alvaro Herrera <alvherre@alvh.no-ip.org>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2023-05-02 10:55 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; pgsql-docs
> On 2 May 2023, at 12:24, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> On 2023-May-02, Daniel Gustafsson wrote:
>
>> + <glossentry id="glossary-lsn">
>> + <glossterm>LSN</glossterm>
>> + <glosssee otherterm="glossary-log-sequence-number"/>
>> + </glossentry>
>>
>> The other <glosssee otherterm="foo" /> entries doesn't have a glossentry id
>> attribute set, is the use here related to the glossentry.show.acronym param?
>
> I debated with myself for 347d2b07fcc2 on whether to add id attribs to
> <glosssee> entries. The only saving grace for doing that is that you
> can link to such entries; but if you do that, you're only causing the
> user one more click in order to see the definition they want to see. So
> in the end I decided not make the glosssee's directly referenceable.
> And I think this new entry shouldn't have an id either.
Agreed, that makes sense.
> I think that what glossentry.show.acronym allows is to show the
> <acronym> text that's part of the main entry:
> https://stackoverflow.com/questions/28869578/docbook-5-rendering-without-abbrev-tag/28879785#2887978...
> so the fact that there's an id in the other entry doesn't change
> anything.
>
> If we do turn glossentry.show.acronym on (and I don't see any reason not
> to), we can follow up later to add <acronym> and <abbrev> tags to other
> entries, too.
+1
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: some new glossary entries
@ 2023-05-04 05:37 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 5+ messages in thread
From: Peter Eisentraut @ 2023-05-04 05:37 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Alvaro Herrera <alvherre@alvh.no-ip.org>; +Cc: pgsql-docs
On 02.05.23 12:55, Daniel Gustafsson wrote:
>> On 2 May 2023, at 12:24, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>>
>> On 2023-May-02, Daniel Gustafsson wrote:
>>
>>> + <glossentry id="glossary-lsn">
>>> + <glossterm>LSN</glossterm>
>>> + <glosssee otherterm="glossary-log-sequence-number"/>
>>> + </glossentry>
>>>
>>> The other <glosssee otherterm="foo" /> entries doesn't have a glossentry id
>>> attribute set, is the use here related to the glossentry.show.acronym param?
>>
>> I debated with myself for 347d2b07fcc2 on whether to add id attribs to
>> <glosssee> entries. The only saving grace for doing that is that you
>> can link to such entries; but if you do that, you're only causing the
>> user one more click in order to see the definition they want to see. So
>> in the end I decided not make the glosssee's directly referenceable.
>> And I think this new entry shouldn't have an id either.
>
> Agreed, that makes sense.
>
>> I think that what glossentry.show.acronym allows is to show the
>> <acronym> text that's part of the main entry:
>> https://stackoverflow.com/questions/28869578/docbook-5-rendering-without-abbrev-tag/28879785#2887978...
>> so the fact that there's an id in the other entry doesn't change
>> anything.
>>
>> If we do turn glossentry.show.acronym on (and I don't see any reason not
>> to), we can follow up later to add <acronym> and <abbrev> tags to other
>> entries, too.
>
> +1
Committed with the recommended changes.
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2023-05-04 05:37 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-05-02 07:05 some new glossary entries Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-02 10:06 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-02 10:24 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-05-02 10:55 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-04 05:37 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox