| Message ID | b0577267402f6177d8ba5646e12d7691437e6e8f.1708060779.git.dsimic@manjaro.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | documentation: send-email: use camel case consistently | expand |
Dragan Simic <dsimic@manjaro.org> writes: > Correct a few random "sendemail.*" configuration parameter names in the > documentation that, for some reason, didn't use camel case format. Thanks. > There's only one "Fixes" tag, while there should actually be a whole bunch > of them to cover all the patches that introduced the configuration parameter > names fixed by this patch. I think we're fine with just one. I suspect that we are even better off without any. The only reason to have them is if we plan to cherry-pick this patch down to a separate maintenance track that the "culprit" was cherry-picked or merged to, but we typically do not do so, and if we want to do so, we'd need a much better coverage. Anyway, checking the output of $ git grep -n -e '^[a-z]*\.[a-z]*[A-Z][A-Z][a-zA-Z]*::' Documentation/config/ and comparing it with the output of $ git grep -n -e '^[a-z]*\.[a-z]*[A-Z][a-zA-Z]*::' Documentation/config/ I think we should spell "SSL" (which is an acronym) full in capital, and possibly do the same for "CC", too. All the other updates in this patch looked sensible, but I wasn't being particularly careful, so an extra set or two of eyes are certainly appreciated in case I missed any. Thanks.
Hello Junio, On 2024-02-20 01:52, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: >> There's only one "Fixes" tag, while there should actually be a whole >> bunch >> of them to cover all the patches that introduced the configuration >> parameter >> names fixed by this patch. I think we're fine with just one. > > I suspect that we are even better off without any. The only reason > to have them is if we plan to cherry-pick this patch down to a > separate maintenance track that the "culprit" was cherry-picked or > merged to, but we typically do not do so, and if we want to do so, > we'd need a much better coverage. Agreed, will drop the single "Fixes" tag in v2. > Anyway, checking the output of > > $ git grep -n -e '^[a-z]*\.[a-z]*[A-Z][A-Z][a-zA-Z]*::' > Documentation/config/ > > and comparing it with the output of > > $ git grep -n -e '^[a-z]*\.[a-z]*[A-Z][a-zA-Z]*::' > Documentation/config/ > > I think we should spell "SSL" (which is an acronym) full in capital, > and possibly do the same for "CC", too. Agreed about "SSL", which I also though about doing that way initially; will change in v2. There are already instances of "SSL" being used, such as in various http.proxySSL* configuration parameter names. Though, "CC" should remain written as "Cc", because it's the way email headers are capitalized, which "Cc" refers to.
Dragan Simic <dsimic@manjaro.org> writes: > Though, "CC" should remain written as "Cc", because it's the way email > headers are capitalized, which "Cc" refers to. E-mail headers are case insensitive, though. See above ;-).
On 2024-02-20 17:22, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >> Though, "CC" should remain written as "Cc", because it's the way email >> headers are capitalized, which "Cc" refers to. > > E-mail headers are case insensitive, though. See above ;-). I've never ever seen anyone referring to email headers as "TO", "CC" or "BCC". It's always referred to as "To", "Cc" and "Bcc". Moreover, RFC2076 [1] refers to them as "To", "cc" and "bcc". This makes it debatable whether "Cc" and "Bcc" are formally the right forms to use in regular conversations, but also makes it clear they aren't to be treated as abbreviations. [1] https://datatracker.ietf.org/doc/html/rfc2076
On 2024-02-20 17:29, Dragan Simic wrote: > On 2024-02-20 17:22, Junio C Hamano wrote: >> Dragan Simic <dsimic@manjaro.org> writes: >> >>> Though, "CC" should remain written as "Cc", because it's the way >>> email >>> headers are capitalized, which "Cc" refers to. >> >> E-mail headers are case insensitive, though. See above ;-). > > I've never ever seen anyone referring to email headers as "TO", "CC" or > "BCC". It's always referred to as "To", "Cc" and "Bcc". > > Moreover, RFC2076 [1] refers to them as "To", "cc" and "bcc". This > makes it debatable whether "Cc" and "Bcc" are formally the right forms > to use in regular conversations, but also makes it clear they aren't > to be treated as abbreviations. > > [1] https://datatracker.ietf.org/doc/html/rfc2076 Here are a few more interesting links: - https://en.wikipedia.org/wiki/Carbon_copy - https://bugzilla.mozilla.org/show_bug.cgi?id=212059 - https://bugzilla.mozilla.org/show_bug.cgi?id=50826 Thus, "cc" stems from the old age of literal carbon copies, and "bcc" was seemingly coined when email took over. Technically, "CC" and "BCC" (or "cc" and "bcc") _are_ abbreviations, but the slightly incorrect "Cc" and "Bcc" forms simply became widespread and took over. If you insist on using "CC", I'd be fine with that, but frankly, I think that would actually be confusing to the users.
Dragan Simic <dsimic@manjaro.org> writes: > If you insist on using "CC", I'd be fine with that, but frankly, I think > that would actually be confusing to the users. I do not insist; my job is to just reject what is not correct. In this particular case, I do not think Cc is outright wrong; it is near the borderline, but I do not know which side of that line it sits. I gave you one possible rule to decide what to capitalize (namely, acronyms are spelled in all caps and that is how we capitalize http.proxySSLCert and imap.preformattedHTML) and if we adopt that rule, then sendemail.supressCc would be incorrect, simply because carbon-copy should be spelled CC. You need to give an alternative criteria that is easy to understand for future developers and follow, and explain your choice in the proposed commit log message: "We spell acronyms in all caps like HTML and SSL, but in the case of carbon-copy, we spell it as Cc because ...". You need to fill that "..." is in your proposed log message to explain the choice you made in your patch text. More importantly, it is to help future developers so that they can easily follow the same rule to spell the variable names they invented in a way consistent with the rule you followed in this patch. Thanks.
On 2024-02-20 19:29, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >> If you insist on using "CC", I'd be fine with that, but frankly, I >> think >> that would actually be confusing to the users. > > I do not insist; my job is to just reject what is not correct. > > In this particular case, I do not think Cc is outright wrong; it > is near the borderline, but I do not know which side of that line it > sits. > > I gave you one possible rule to decide what to capitalize (namely, > acronyms are spelled in all caps and that is how we capitalize > http.proxySSLCert and imap.preformattedHTML) and if we adopt that > rule, then sendemail.supressCc would be incorrect, simply because > carbon-copy should be spelled CC. Please, let me remind you that I already fully agreed with using "SSL". The same applies to "HTML", for example, but "Cc" should be an exception to that rule, IMHO. > You need to give an alternative criteria that is easy to understand > for future developers and follow, and explain your choice in the > proposed commit log message: "We spell acronyms in all caps like > HTML and SSL, but in the case of carbon-copy, we spell it as Cc > because ...". > > You need to fill that "..." is in your proposed log message to > explain the choice you made in your patch text. More importantly, > it is to help future developers so that they can easily follow the > same rule to spell the variable names they invented in a way > consistent with the rule you followed in this patch. Agreed, I'll provide a detailed rationale for using "Cc" vs. "SSL" in the commit description for v3, with a few references.
On Tue, Feb 20, 2024 at 8:42 AM Dragan Simic <dsimic@manjaro.org> wrote: > I've never ever seen anyone referring to email headers as "TO", "CC" or > "BCC". It's always referred to as "To", "Cc" and "Bcc". I used some email system (back in the early 1980s) that did that. It felt weird even then. I can't remember if it was some CSMail (CSNet) or MH(Rand Mail Handler) version that did it. > Thus, "cc" stems from the old age of literal carbon copies ... That's correct. However: > and "bcc" was seemingly coined when email took over. "Blind Carbon Copies" predated email, but required adding the notation separately, if it was to be added at all. (I'm just old enough to remember using carbon copies myself, but not old enough to know what Standard Office Practice was at that time.) Whether adding a "bcc" notation was common I don't know; it seems it would be easier to leave it off if you made, say, one original and a total of 2 copies, one "blinded". (As your Wikipedia link notes, there was a practical limit to how many carbon copies one could make in the first place.) Chris
On 2024-02-21 01:43, Chris Torek wrote: > On Tue, Feb 20, 2024 at 8:42 AM Dragan Simic <dsimic@manjaro.org> > wrote: >> I've never ever seen anyone referring to email headers as "TO", "CC" >> or >> "BCC". It's always referred to as "To", "Cc" and "Bcc". > > I used some email system (back in the early 1980s) that did that. It > felt weird even then. I can't remember if it was some CSMail (CSNet) > or MH(Rand Mail Handler) version that did it. That's interesting, it shows that different variants were used in the very early days of email. Maybe even the all-lowercase "cc" and "bcc" variants were used somewhere, at least because RFC2076 (better said, the RFCs that predate it) specifies them. >> Thus, "cc" stems from the old age of literal carbon copies ... > > That's correct. However: > >> and "bcc" was seemingly coined when email took over. > > "Blind Carbon Copies" predated email, but required adding the > notation separately, if it was to be added at all. (I'm just old enough > to remember using carbon copies myself, but not old enough to > know what Standard Office Practice was at that time.) Thanks for the correction. You're right, I was lazy enough not to check that blind carbon copies predate the age of email. [1] I'm also old enough to remember the literal carbon copies, I even made a few dozens of them myself on a mechanical typewriter. They usually left me with dirty fingertips. :) Though, I'm also not old enough to know what the common office practice was like back then. > Whether adding a "bcc" notation was common I don't know; > it seems it would be easier to leave it off if you made, say, one > original and a total of 2 copies, one "blinded". > > (As your Wikipedia link notes, there was a practical limit to how > many carbon copies one could make in the first place.) Exactly, it was the limitation of mechanical typewriters. Perhaps the limit was around four or five carbon copies. [1] https://en.wikipedia.org/wiki/Blind_carbon_copy
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 7fc770ee9e69..bfdf1a633cae 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -8,7 +8,7 @@ sendemail.smtpEncryption:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the 'identity' mechanism. -sendemail.smtpsslcertpath:: +sendemail.smtpSslCertPath:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. @@ -62,27 +62,27 @@ sendemail.chainReplyTo:: sendemail.envelopeSender:: sendemail.from:: sendemail.headerCmd:: -sendemail.signedoffbycc:: +sendemail.signedOffByCc:: sendemail.smtpPass:: -sendemail.suppresscc:: +sendemail.suppressCc:: sendemail.suppressFrom:: sendemail.to:: -sendemail.tocmd:: +sendemail.toCmd:: sendemail.smtpDomain:: sendemail.smtpServer:: sendemail.smtpServerPort:: sendemail.smtpServerOption:: sendemail.smtpUser:: sendemail.thread:: sendemail.transferEncoding:: sendemail.validate:: sendemail.xmailer:: These configuration variables all provide a default for linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.signedoffcc (deprecated):: - Deprecated alias for `sendemail.signedoffbycc`. +sendemail.signedOffCc (deprecated):: + Deprecated alias for `sendemail.signedOffByCc`. sendemail.smtpBatchSize:: Number of messages to be sent per connection, after that a relogin diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index d1ef6a204e68..31acfa186457 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -138,7 +138,7 @@ Note that no attempts whatsoever are made to validate the encoding. --compose-encoding=<encoding>:: Specify encoding of compose message. Default is the value of the - 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. + 'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed. --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: Specify the transfer encoding to be used to send the message over SMTP. @@ -174,7 +174,7 @@ Sending Specify a command to run to send the email. The command should be sendmail-like; specifically, it must support the `-i` option. The command will be executed in the shell if necessary. Default - is the value of `sendemail.sendmailcmd`. If unspecified, and if + is the value of `sendemail.sendmailCmd`. If unspecified, and if --smtp-server is also unspecified, git-send-email will search for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. @@ -269,7 +269,7 @@ must be used for each option. certificates concatenated together: see verify(1) -CAfile and -CApath for more information on these). Set it to an empty string to disable certificate verification. Defaults to the value of the - `sendemail.smtpsslcertpath` configuration variable, if set, or the + `sendemail.smtpSslCertPath` configuration variable, if set, or the backing SSL library's compiled-in default otherwise (which should be the best choice on most platforms). @@ -313,7 +313,7 @@ Automating Specify a command to execute once per patch file which should generate patch file specific "To:" entries. Output of this command must be single email address per line. - Default is the value of 'sendemail.tocmd' configuration value. + Default is the value of 'sendemail.toCmd' configuration value. --cc-cmd=<command>:: Specify a command to execute once per patch file which @@ -348,19 +348,19 @@ Automating --[no-]signed-off-by-cc:: If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the - cc list. Default is the value of `sendemail.signedoffbycc` configuration + cc list. Default is the value of `sendemail.signedOffByCc` configuration value; if that is unspecified, default to --signed-off-by-cc. --[no-]cc-cover:: If this is set, emails found in Cc: headers in the first patch of the series (typically the cover letter) are added to the cc list - for each email set. Default is the value of 'sendemail.cccover' + for each email set. Default is the value of 'sendemail.ccCover' configuration value; if that is unspecified, default to --no-cc-cover. --[no-]to-cover:: If this is set, emails found in To: headers in the first patch of the series (typically the cover letter) are added to the to list - for each email set. Default is the value of 'sendemail.tocover' + for each email set. Default is the value of 'sendemail.toCover' configuration value; if that is unspecified, default to --no-to-cover. --suppress-cc=<category>:: @@ -384,7 +384,7 @@ Automating - 'all' will suppress all auto cc values. -- + -Default is the value of `sendemail.suppresscc` configuration value; if +Default is the value of `sendemail.suppressCc` configuration value; if that is unspecified, default to 'self' if --suppress-from is specified, as well as 'body' if --no-signed-off-cc is specified. @@ -471,7 +471,7 @@ Information Instead of the normal operation, dump the shorthand alias names from the configured alias file(s), one per line in alphabetical order. Note that this only includes the alias name and not its expanded email addresses. - See 'sendemail.aliasesfile' for more information about aliases. + See 'sendemail.aliasesFile' for more information about aliases. CONFIGURATION
Correct a few random "sendemail.*" configuration parameter names in the documentation that, for some reason, didn't use camel case format. There's only one "Fixes" tag, while there should actually be a whole bunch of them to cover all the patches that introduced the configuration parameter names fixed by this patch. I think we're fine with just one. Fixes: 0ee42c86cf71 ("config.txt: move sendemail-config.txt to config/") Signed-off-by: Dragan Simic <dsimic@manjaro.org> --- Documentation/config/sendemail.txt | 12 ++++++------ Documentation/git-send-email.txt | 18 +++++++++--------- 2 files changed, 15 insertions(+), 15 deletions(-)