Re: [PATCH v5 2/4] docs: improve formatting in git-send-email documentation

[Junio C Hamano <gitster@pobox.com>]

Aditya Garg <gargaditya08@live.com> writes:

>> 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