Re: Add A Glossary

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