Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..

From: Daniel Gustafsson <daniel(at)yesql(dot)se>
To: Karen Jex <karenhjex(at)gmail(dot)com>
Cc: Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>, Peter Eisentraut <peter(at)eisentraut(dot)org>, "David E(dot) Wheeler" <david(at)justatheory(dot)com>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>, xavier_fischer(at)hotmail(dot)fr
Subject: Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Date: 2026-11-16 09:22:13
Message-ID: 03FEF8E5-0214-4ED9-93A8-BB0D77A31D50@yesql.se
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

> On 13 Nov 2026, at 10:14, Karen Jex <karenhjex(at)gmail(dot)com> wrote:

> Commitfest entry: https://commitfest.postgresql.org/patch/7630/

Thanks for the new version, I think this is pretty much done, just a few small
comments from reviewing it again:

user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ cleartext user passwords in PostgreSQL system catalogs.

..and:

- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing cleartext user passwords in PostgreSQL system

I think there is potential for additional cleanup here since it is the storage
system we are referring to and not an inherent quality of a specific password.
Something like the below (though I don't particularly like the double "in", but
I fail at english today) would be an improvement I think.

"This avoids storing user passwords in cleartext in PostgreSQL system
catalogs."

+ <glossentry>
+ <glossterm>Cleartext</glossterm>
+ <glossdef>
+ <para>
+ Unencrypted data; data that exists in an unprotected, readable format
+ during storage or transmission. Sometimes used as a synonym for
+ plaintext; the input to an encryption algorithm.
+ </para>
+ </glossdef>
+ </glossentry>

All data is readable, shouldn't this be specified as "human-readable" to make
it clear?

+ <glossentry>
+ <glossterm>Plain text</glossterm>
+ <glossdef>
+ <para>
+ Unformatted, human-readable text that consists of a sequence of printable
+ characters in a character encoding such as UTF-8.
+ </para>
+ </glossdef>
+ </glossentry>

The UTF-8 part seems distracting and potentially confusing, I think ending the
sentence on "printable characters." would be better.

Attachec v4 have the above changes plus a needed rebase since the pg_dump hunk
didn't apply anymore.

--
Daniel Gustafsson

Attachment Content-Type Size
v4-0001-doc-Standardise-cleartext-and-plain-text-terms.patch application/octet-stream 22.2 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Alexey Shishkin 2026-11-16 12:00:13 Re: OS system version upgrade (glibc / libicu version change)
Previous Message Fujii Masao 2026-11-16 04:27:27 Re: Clarification on SET SESSION AUTHORIZATION Syntax