Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
While working on a docs patch I realized that we use a wide variety of
terminology for secrets that will not be encrypted, which is very different
from secrets which will be encrypted; the former is IMO cleartext and the
latter plaintext.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
If someone does take a stab at it, I will of course spend the time to review
it.
--
Daniel Gustafsson
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
Just to confirm my understanding:
1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext".
Regards,
--
Karen Jex
________________________________
From: Daniel Gustafsson <daniel@yesql.se>
Sent: 06 November 2026 14:41
To: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
While working on a docs patch I realized that we use a wide variety of
terminology for secrets that will not be encrypted, which is very different
from secrets which will be encrypted; the former is IMO cleartext and the
latter plaintext.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
If someone does take a stab at it, I will of course spend the time to review
it.
--
Daniel Gustafsson
On Nov 6, 2026, at 09:44, Karen Jex <karenjex@hotmail.com> wrote:
I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
Yay!
Just to confirm my understanding:
1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.
I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
Best,
David
Le ven. 6 nov. 2026 à 15:49, David E. Wheeler <david@justatheory.com> a écrit :
Just to confirm my understanding:
1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
I think you're right, and that makes the task much simpler (that was
my initial understanding, before I found various articles suggesting
that cleartext and plaintext were not the same). I see that the
cleartext Wikipedia entry redirects to plaintext:
https://en.wikipedia.org/wiki/Plaintext, which implies that plaintext
may be the preferred term.
Le ven. 6 nov. 2026 à 20:16, Karen Jex <karenhjex@gmail.com> a écrit :
I see that the cleartext Wikipedia entry redirects to plaintext:
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://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.
--
Karen
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@gmail.com>
Envoyé : mardi 10 novembre 2026 17:30
À : David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.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@gmail.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
I ran a grep on the docs and found the same occurences. I agree with your changes Karen.
________________________________
De : Xavier Fischer <xavier_fischer@hotmail.fr>
Envoyé : mardi 10 novembre 2026 20:29
À : Karen Jex <karenhjex@gmail.com>; David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.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@gmail.com>
Envoyé : mardi 10 novembre 2026 17:30
À : David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.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@gmail.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
Import Notes
Reply to msg id not found: AMBP193MB2742FED5B7B05AF5694920F894722@AMBP193MB2742.EURP193.PROD.OUTLOOK.COMReference msg id not found: AMBP193MB2742FED5B7B05AF5694920F894722@AMBP193MB2742.EURP193.PROD.OUTLOOK.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
On 06.11.26 15:49, David E. Wheeler wrote:
On Nov 6, 2026, at 09:44, Karen Jex <karenjex@hotmail.com> wrote:
I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
Yay!
Just to confirm my understanding:
1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
My understanding is/was that plaintext is data meant for encryption,
after which it becomes ciphertext. Cleartext is data not meant for
encryption.
So you would use plaintext and ciphertext when describing the steps of
an encryption method. And you would use cleartext when describing what
goes over the wire when you do do LDAP authentication in PostgreSQL.
But it seems like these terms are not actually universally used that
way. If we tidy this up, consider adding glossary entries.
On 11 Nov 2026, at 11:58, Peter Eisentraut <peter@eisentraut.org> wrote:
Thanks for working on this Karen!
My understanding is/was that plaintext is data meant for encryption, after which it becomes ciphertext. Cleartext is data not meant for encryption.
That's my understanding as well, but it's not standardized anywhere and
scanning relevant RFC's didn't provide any real guidance.
If we tidy this up, consider adding glossary entries.
+1
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.
non-plain-text was never good for non-native speakers, and this didn't improve
it. I agree with trying to rewrite the sentences to avoid this construct.
--
Daniel Gustafsson
Le mer. 11 nov. 2026 à 08:22, Laurenz Albe <laurenz.albe@cybertec.at> a écrit :
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.
ack
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").
In strict grammatical terms, you are entirely correct! It "should" be
"a plain-text file". Unfortunately, computer folks appear to have
standardised on "plain text" without a hyphen in this case. I've
followed this convention rather than the more grammatically correct
version to be consistent with the way in which it is most commonly
used.
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.
Agreed - rewriting makes sense. None of the alternatives that I found
for the construct appeared any better.
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.
Will do. Thank you for the suggestions.
Regards,
--
Karen
My understanding is/was that plaintext is data meant for encryption, after which it becomes ciphertext. Cleartext is data not meant for encryption.
That's my understanding as well, but it's not standardized anywhere and
scanning relevant RFC's didn't provide any real guidance.If we tidy this up, consider adding glossary entries.
+1
I can attempt to split out cleartext and plaintext entries if there's
appetite for that, but I suspect that may actually confuse things
rather than clarifying them. Instead, I propose the following glossary
entries to define the way in which we're using the terms:
plain text
Unformatted, human-readable text that consists of a sequence of
printable characters in a character encoding such as UTF-8.
cleartext
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.
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.non-plain-text was never good for non-native speakers, and this didn't improve
it. I agree with trying to rewrite the sentences to avoid this construct.
Agreed - I'll find alternative wording.
Regards,
--
Karen
On 11 Nov 2026, at 16:16, Karen Jex <karenhjex@gmail.com> wrote:
I can attempt to split out cleartext and plaintext entries if there's
appetite for that, but I suspect that may actually confuse things
rather than clarifying them.
Agreed; we should write the docs for postgres users, knowledge of terminology
in cryptography should not be a prerequisite.
Instead, I propose the following glossary
entries to define the way in which we're using the terms:plain text
Unformatted, human-readable text that consists of a sequence of
printable characters in a character encoding such as UTF-8.cleartext
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.
Sounds good. I was trying to make the cleartext entry specify that it is
generally data which is intended as input to processing, but I wasn't
particularly successful in creating anything which reads better than what you
have above.
--
Daniel Gustafsson
Instead, I propose the following glossary
entries to define the way in which we're using the terms:plain text
Unformatted, human-readable text that consists of a sequence of
printable characters in a character encoding such as UTF-8.cleartext
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.Sounds good. I was trying to make the cleartext entry specify that it is
generally data which is intended as input to processing, but I wasn't
particularly successful in creating anything which reads better than what you
have above.
I've created a V2 patch (attached) including the glossary terms, and
with a verbose commit message as suggested by Laurenz.
I ran a grep on the docs and found the same occurences. I agree with your changes Karen.
Thank you for the review, Xavier.
And thank you, all, for the helpful discussion and suggestions.
Regards,
--
Karen
Attachments:
t254588_13v2-0001-Doc-standardise-cleartext-and-plain-text-terms.patchapplication/octet-stream; name=v2-0001-Doc-standardise-cleartext-and-plain-text-terms.patchDownload+61-39
I've created a V2 patch (attached) including the glossary terms, and
with a verbose commit message as suggested by Laurenz.
Apologies, I managed to introduce a couple of typos into my commit
message. V3 patch attached with a correction.
Attachments:
t254588_14v3-0001-Doc-standardise-cleartext-and-plain-text-terms.patchapplication/octet-stream; name=v3-0001-Doc-standardise-cleartext-and-plain-text-terms.patchDownload+61-39
On Thu, 2026-11-12 at 17:37 +0100, Karen Jex wrote:
I've created a V2 patch (attached) including the glossary terms, and
with a verbose commit message as suggested by Laurenz.Apologies, I managed to introduce a couple of typos into my commit
message. V3 patch attached with a correction.
The patch looks good to me.
One sentence in the commit message struck me as weird:
Use cleartext instead of plaintext because; it is consistent [...]
I guess that you intend the semicolon as starting an enumeration,
but this is a usage I have never seen before.
However, the committer will adapt the commit message anyway, so
(from my point of view) there is no need for another version.
Yours,
Laurenz Albe
Le ven. 13 nov. 2026 à 09:44, Laurenz Albe <laurenz.albe@cybertec.at> a écrit :
On Thu, 2026-11-12 at 17:37 +0100, Karen Jex wrote:
I've created a V2 patch (attached) including the glossary terms, and
with a verbose commit message as suggested by Laurenz.Apologies, I managed to introduce a couple of typos into my commit
message. V3 patch attached with a correction.The patch looks good to me.
Thank you for the review.
One sentence in the commit message struck me as weird:
Use cleartext instead of plaintext because; it is consistent [...]
I guess that you intend the semicolon as starting an enumeration,
but this is a usage I have never seen before.
However, the committer will adapt the commit message anyway, so
(from my point of view) there is no need for another version.
Good catch - the semicolon is an error. As suggested, I won't create a
new version just to change that.
Commitfest entry: https://commitfest.postgresql.org/patch/7630/
Best regards
--
Karen
On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.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
Attachments:
t254588_18v4-0001-doc-Standardise-cleartext-and-plain-text-terms.patchapplication/octet-stream; name=v4-0001-doc-Standardise-cleartext-and-plain-text-terms.patch; x-unix-mode=0644Download+60-38
Le lun. 16 nov. 2026 à 10:22, Daniel Gustafsson <daniel@yesql.se> a écrit :
On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.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 systemI 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."
+1 This makes it clearer. I don't mind the double "in" - I can't think
of a better alternative.
Attachec v4 have the above changes plus a needed rebase since the pg_dump hunk
didn't apply anymore.
Thank you for doing this. I agree with all of your changes.
--
Karen
On Tue, Nov 17, 2026 at 7:52 PM Karen Jex <karenhjex@gmail.com> wrote:
Le lun. 16 nov. 2026 à 10:22, Daniel Gustafsson <daniel@yesql.se> a écrit :
On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.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 systemI 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."+1 This makes it clearer. I don't mind the double "in" - I can't think
of a better alternative.
How about.
"This avoids storing user passwords as cleartext in PostgreSQL system catalogs."
======
Kind Regards,
Peter Smith.
Fujitsu Australia