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

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