Re: [PATCH v5 2/4] docs: improve formatting in git-send-email documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 30, 2025, 17:15 UTC
- Message-ID
- <xmqqbjraf29c.fsf@gitster.g>
- In-Reply-To
- <PN3PR01MB9597DEE8C41CB1599B9A97CEB861A@PN3PR01MB9597.INDPRD01.PROD.OUTLOOK.COM>
Aditya Garg <gargaditya08@live.com> writes:
Show 10 quoted lines
>> But I do not see any link in ... >> >>>>> - by 'c_rehash', or a single file containing one or more PEM format >>>>> - certificates concatenated together: see verify(1) -CAfile and >>>>> - -CApath for more information on these). Set it to an empty string >> >> ... the text that was removed. The reference to verify(1) is a >> command in the OpenSSL suite, right? > > If this is a command, its not phrased nicely imo. I'll just leave it as is.
In any case, there isn't an link in the document that is dangling, is there? It is not like I am trying to prove you wrong. I am trying to see if the change you made is still addressing a valid concern, and if so if there is a way to make the result better, possibly in some other ways.
I agree with you that this passage is not nice to expect that the readers are familiar with what appears in
https://docs.openssl.org/master/man1/openssl-verify/
where `-CAfile` and `-CApath` are two of the command line options described there and has "more information on these". The description of these options on that page redirects us to
https://docs.openssl.org/master/man1/openssl-verification-options/
and expects us to scroll down to #trusted-certificate-options anchor, which is doubly unnice, but that part is not a fault of our own documentation ;-).
Perhaps something like this would clarify the description?
Documentation/git-send-email.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
diff --git c/Documentation/git-send-email.adoc w/Documentation/git-send-email.adoc index 7f223db42d..53f30fccf9 100644 --- c/Documentation/git-send-email.adoc +++ w/Documentation/git-send-email.adoc @@ -267,8 +267,10 @@ must be used for each option. Path to a store of trusted CA certificates for SMTP SSL/TLS certificate validation (either a directory that has been processed by 'c_rehash', or a single file containing one or more PEM format - certificates concatenated together: see verify(1) -CAfile and - -CApath for more information on these). Set it to an empty string + certificates concatenated together: see the description of the + `-CAfile` _<file>_ and the `-CApath` _<dir>_ options of OpenSSL's + `verify(1)` manual page 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 backing SSL library's compiled-in default otherwise (which should