| 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 19:29:37 |
| Message-ID: | AMBP193MB2742FED5B7B05AF5694920F894722@AMBP193MB2742.EURP193.PROD.OUTLOOK.COM |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs |
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
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Xavier Fischer | 2026-11-10 20:56:17 | RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc.. |
| Previous Message | Karen Jex | 2026-11-10 16:30:11 | Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc.. |