pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  
help / color / mirror / Atom feed
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Karen Jex <karenhjex@gmail.com>
To: David E. Wheeler <david@justatheory.com>
Cc: Karen Jex <karenjex@hotmail.com>
Cc: Daniel Gustafsson <daniel@yesql.se>
Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Date: Wed, 11 Nov 2026 08:22:42 +0100
Message-ID: <472e310fee1b497358a5c31ff25aebe11eb09d10.camel@cybertec.at> (raw)
In-Reply-To: <CAOpR_fbRg0O_rsrkoJjnPe9aR7ChFuVgABe1rhwq=5EzPxt1GA@mail.gmail.com>
References: <D7B95A7B-88B8-43E6-9DFB-2261B0849337@yesql.se>
	<DBAP195MB09396FA26617A837F43F7DF3CB762@DBAP195MB0939.EURP195.PROD.OUTLOOK.COM>
	<0979E710-8C50-4051-87BD-6DE9ABF58938@justatheory.com>
	<CAOpR_fZWjuS5aqoSvzYh5h+y7L4MoT4zX7=Rnys-gnn1omwyBA@mail.gmail.com>
	<CAOpR_fbRg0O_rsrkoJjnPe9aR7ChFuVgABe1rhwq=5EzPxt1GA@mail.gmail.com>

On Tue, 2026-11-10 at 17:30 +0100, Karen Jex wrote:
> I originally thought we should standardise on "plaintext", but after
> reviewing the ways in which the terms are used throughout the docs, I
> propose the following approach:
> 
> 1. Use "plain text" to indicate unformatted text: e.g. "...a plain
> text file with special syntax that translators edit."
> (https://www.postgresql.org/docs/devel/nls-translator.html#NLS-TRANSLATOR-CONCEPTS).
> 
> 2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
> is good practice not to send the original cleartext password..."
> (https://www.postgresql.org/docs/devel/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN).
> This is consistent with the AuthenticationCleartextPassword server
> message referenced on the same page.
> 
> This is consistent with the vocabulary that is used most often in the
> documentation, and the terms are different enough to avoid
> confusion/ambiguity.
> 
> I attach the proposed patch and, for completeness, a csv file that
> lists the proposed changes. I would be very grateful for any feedback
> before I submit it to -hackers.

Submitting the patch to pgsql-docs is good enough; you don't need to
re-send it to -hackers (but you can do that of course).  You can have a
commitfest entry point to a message in any PostgreSQL mailing list -
just reference the message ID.

I think your choice of "cleartext" and "plain text" is fine.  I personally
would feel better about "plain-text" whenever you use it as an adjective
(like in "a plain-text file") and "plain text" for a noun (like "write a
file as plain text"), but I am not a native speaker, and my feeling could
be the German-speaker's preference for compound words.  Also, the borders
between noun and adjective in English are blurry ("a fun thing").

There are three occurrences of "non-plain-text" that you changed to
"non-plain text".  This feels wrong, since to me the hyphen ties stronger
than the space.  I would read that as meaning something like "compound text".
I'd suggest that you rewrite those sentences to avoid the construct.

You could add some of the considerations that led to your choice of words
to the commit message, as well as "Author:", "Reviewed-By:" and
"Discussion:" tags (see other commit messages).  It would save the
committer some keystrokes.

Yours,
Laurenz Albe






view thread (21+ messages)  latest in thread

Message-ID: <472e310fee1b497358a5c31ff25aebe11eb09d10.camel@cybertec.at>
Permalink:  ../472e310fee1b497358a5c31ff25aebe11eb09d10.camel@cybertec.at/
Also on:    postgresql.org/message-id/472e310fee1b497358a5c31ff25aebe11eb09d10.camel@cybertec.at

 · 

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: pgsql-docs@postgresql.org
  Cc: laurenz.albe@cybertec.at, karenhjex@gmail.com, david@justatheory.com, karenjex@hotmail.com, daniel@yesql.se, pgsql-docs@lists.postgresql.org
  Subject: Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
  In-Reply-To: <472e310fee1b497358a5c31ff25aebe11eb09d10.camel@cybertec.at>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

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