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

From: Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>
To: Karen Jex <karenhjex(at)gmail(dot)com>, "David E(dot) Wheeler" <david(at)justatheory(dot)com>
Cc: Karen Jex <karenjex(at)hotmail(dot)com>, Daniel Gustafsson <daniel(at)yesql(dot)se>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Date: 2026-11-10 20:56:17
Message-ID: AMBP193MB2742BB51F43CA6EA04BC00A294722@AMBP193MB2742.EURP193.PROD.OUTLOOK.COM
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

I ran a grep on the docs and found the same occurences. I agree with your changes Karen.
________________________________
De : Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>
Envoyé : mardi 10 novembre 2026 20:29
À : Karen Jex <karenhjex(at)gmail(dot)com>; David E. Wheeler <david(at)justatheory(dot)com>
Cc : Karen Jex <karenjex(at)hotmail(dot)com>; Daniel Gustafsson <daniel(at)yesql(dot)se>; pgsql-docs(at)lists(dot)postgresql(dot)org <pgsql-docs(at)lists(dot)postgresql(dot)org>
Objet : RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..

Hi! I was one of the attendees of the PGConfEU talk too (asked about whether images in the were encouraged, and heard Daniel's call for action regarding docs patches review).
I'd like to help and will start to review your changes Karen.

________________________________
De : Karen Jex <karenhjex(at)gmail(dot)com>
Envoyé : mardi 10 novembre 2026 17:30
À : David E. Wheeler <david(at)justatheory(dot)com>
Cc : Karen Jex <karenjex(at)hotmail(dot)com>; Daniel Gustafsson <daniel(at)yesql(dot)se>; pgsql-docs(at)lists(dot)postgresql(dot)org <pgsql-docs(at)lists(dot)postgresql(dot)org>
Objet : Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..

Le ven. 6 nov. 2026 à 20:16, Karen Jex <karenhjex(at)gmail(dot)com> a écrit :

> I see that the cleartext Wikipedia entry redirects to plaintext:
> https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPlaintext&data=05%7C02%7C%7C4daa536337784c47fbec08df3f47f3df%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C639299250828581654%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=YzO1VAtG4cHgIm1bCNCAUxksDl3PmIqNp1G8pEV5T44%3D&reserved=0<https://en.wikipedia.org/wiki/Plaintext>, which implies that plaintext
> may be the preferred term.

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://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel%2Fnls-translator.html%23NLS-TRANSLATOR-CONCEPTS&data=05%7C02%7C%7C4daa536337784c47fbec08df3f47f3df%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C639299250828603988%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=vG%2BEP5KIg8zTm0mPycLEUzMxLdHP8zZ8LSlet%2BiUOY4%3D&reserved=0<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://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel%2Flibpq-misc.html%23LIBPQ-PQENCRYPTPASSWORDCONN&data=05%7C02%7C%7C4daa536337784c47fbec08df3f47f3df%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C639299250828615269%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=g5Iptkeu%2BhWkxi5T1Ssv5QpiQRhlzG4EdjmOyY07NqY%3D&reserved=0<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.

--
Karen

In response to

Browse pgsql-docs by date

  From Date Subject
Next Message Laurenz Albe 2026-11-11 07:22:42 Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Previous Message Xavier Fischer 2026-11-10 19:29:37 RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..