Subject: Re: Add A Glossary
To: Justin Pryzby <pryzby@telsasoft.com>,
 Alvaro Herrera <alvherre@2ndquadrant.com>,
 Corey Huinker <corey.huinker@gmail.com>,
 Roger Harkavy <rogerharkavy@gmail.com>, pgsql-hackers@postgresql.org,
 Fabien COELHO <coelho@cri.ensmp.fr>, Michael Paquier <michael@paquier.xyz>
References: 
 <CADkLM=fwtE-TCU7sRnvaE74z12kOp_A+CdUwMr7aZt39pXbh6A@mail.gmail.com>
 <20200320001122.GA19602@alvherre.pgsql>
 <20200320195841.GA13662@telsasoft.com>
 <64b49f34-eaf6-6de2-e951-0eb8d4afabc2@purtz.de>
 <20200320230318.GB13662@telsasoft.com>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <265c2a2c-88ba-a36c-e5c3-6b873e7914d8@purtz.de>
Date: Sat, 21 Mar 2020 15:08:30 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.4.1
MIME-Version: 1.0
In-Reply-To: <20200320230318.GB13662@telsasoft.com>
Content-Type: multipart/alternative;
 boundary="------------BC7B6159ACA5CF65DB46CDFC"
Content-Language: en-US
Precedence: bulk

This is a multi-part message in MIME format.
--------------BC7B6159ACA5CF65DB46CDFC
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

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


--------------BC7B6159ACA5CF65DB46CDFC
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <div class="moz-cite-prefix">On 21.03.20 00:03, Justin Pryzby wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:20200320230318.GB13662@telsasoft.com">
      <blockquote type="cite" style="color: #000000;">
        <blockquote type="cite" style="color: #000000;">
          <blockquote type="cite" style="color: #000000;">
            <pre class="moz-quote-pre" wrap="">+   &lt;glossentry id="glossary-host"&gt;
+    &lt;glossterm&gt;Host&lt;/glossterm&gt;
+    &lt;glossdef&gt;
+     &lt;para&gt;
+      See &lt;glossterm&gt;Server&lt;/glossterm&gt;.
</pre>
          </blockquote>
          <pre class="moz-quote-pre" wrap="">Or client.  Or proxy at some layer or other intermediate thing.  Maybe just
remove this.
</pre>
        </blockquote>
        <pre class="moz-quote-pre" wrap="">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".
</pre>
      </blockquote>
      <pre class="moz-quote-pre" wrap="">I think that suggests just removing "host" and consistently saying "server".
</pre>
    </blockquote>
    <p>"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.</p>
    <p>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:</p>
    <p>---</p>
    <p>Server: The term "Server" denotes ....  .</p>
    <p>Host: An outdated term which will be replaced by
      &lt;xref-to-the-glossary&gt;Server&lt;/xref&gt; over time.<br>
    </p>
    <p>Database Server: An outdated term which sometimes denotes a
      &lt;xref-to-the-glossary&gt;Server&lt;/xref&gt; and sometimes an
      &lt;xref-to-the-glossary&gt;Instance&lt;/xref&gt;.</p>
    <p>---</p>
    <p>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.<br>
    </p>
    <p>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.<br>
    </p>
    <p>Kind regards, Jürgen<br>
    </p>
    <p><br>
    </p>
  </body>
</html>

--------------BC7B6159ACA5CF65DB46CDFC--