public inbox for [email protected]
help / color / mirror / Atom feedFrom: Jürgen Purtz <[email protected]>
To: Justin Pryzby <[email protected]>
To: Alvaro Herrera <[email protected]>
To: Corey Huinker <[email protected]>
To: Roger Harkavy <[email protected]>
To: [email protected]
To: Fabien COELHO <[email protected]>
To: Michael Paquier <[email protected]>
Subject: Re: Add A Glossary
Date: Sat, 21 Mar 2020 15:08:30 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <CADkLM=fwtE-TCU7sRnvaE74z12kOp_A+CdUwMr7aZt39pXbh6A@mail.gmail.com>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
On 21.03.20 00:03, Justin Pryzby wrote:
>>>> + <glossentry id="glossary-host">
>>>> + <glossterm>Host</glossterm>
>>>> + <glossdef>
>>>> + <para>
>>>> + See <glossterm>Server</glossterm>.
>>> Or client. Or proxy at some layer or other intermediate thing. Maybe just
>>> remove this.
>> Sometimes the term "host" is used in a different meaning. Therefor we shall
>> have this glossary entry for clarification that it shall be used only in the
>> sense of a "server".
> I think that suggests just removing "host" and consistently saying "server".
"server", "host", "database server": All three terms are used
intensively in the documentation. When we define glossary terms, we
should also take into account the consequences for those parts.
"database server" is the most diffuse. E.g.: In 'config.sgml' he is used
in the sense of some hardware or VM "... If you have a dedicated
database server with 1GB or more of RAM ..." as well as in the sense of
an instance "... To start the database server on the command prompt
...". Additionally the term is completely misleading. In both cases we
do not mean something which is related to a database but something which
is related to a cluster.
In the past, people accepted such blurs. My - minimal - intention is to
raise awareness of such ambiguities, or - better - to clearly define the
situation in the glossary. But this is only a first step. The second
step shall be a rework of the documentation to use the preferred terms
defined in the glossary. Because there will be a time gap between the
two steps, we may want to be a little chatty in the glossary and define
ambiguous terms as shown in the following example:
---
Server: The term "Server" denotes .... .
Host: An outdated term which will be replaced by
<xref-to-the-glossary>Server</xref> over time.
Database Server: An outdated term which sometimes denotes a
<xref-to-the-glossary>Server</xref> and sometimes an
<xref-to-the-glossary>Instance</xref>.
---
This is a pattern for all terms which we currently described with the
phrase "See ...". Later, after reviewing the documentation by
eliminating the non-preferred terms, the glossary entries with "An
outdated term ..." can be dropped.
In the last days we have seen many huge and small proposals. I think, it
will be helpful to summarize this work by waiting for a patch from
Alvaro containing everything it deems useful from his point of view.
Kind regards, Jürgen
view thread (97+ 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], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: Add A Glossary
In-Reply-To: <[email protected]>
* 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