Re: [PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption

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

sndanailov@wired4ever.net writes:

> From: Sotir Danailov <sndanailov@wired4ever.net>
>
> New explanation for the difference between these values.
> It's hard to understand what they do based only on the names.
> New description of used default ports.
>
> Signed-off-by: Sotir Danailov <sndanailov@wired4ever.net>
> ---
> Changes since v1: Expanded explanation, covering more terms.
> Link to v1: https://public-inbox.org/git/20221010172859.13832-1-sndanailov@wired4ever.net/
>
>  Documentation/git-send-email.txt | 15 ++++++++++++---
>  1 file changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
> index 3290043053..d64a46fa87 100644
> --- a/Documentation/git-send-email.txt
> +++ b/Documentation/git-send-email.txt
> @@ -178,9 +178,18 @@ Sending
>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
>  
>  --smtp-encryption=<encryption>::
> -	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
> -	value reverts to plain SMTP.  Default is the value of
> -	`sendemail.smtpEncryption`.
> +	Valid values are 'ssl' and 'tls'. Any other value reverts to plain
> +	(unencrypted) SMTP, which defaults to port 25.

Please always start the description of a thing by explaining what
the thing is.  After reading two lines, we learned what values to
plug <encryption> are valid, but we still do not know what good
giving --smtp-encryption=<encryption> is supposed to give us.

> +	Despite the names, both values will use the same newer version of TLS,
> +	but for historic reasons have these names. The difference between the
> +	two values for Git is the following. 'ssl' refers to "implicit"
> +	encryption (sometimes called SMTPS), that uses port 465 by default.

And we still haven't said what the option is about at this point,
even though the reader may be able to guess that this is about a
mechanism to specify something about encryption after reading this
much text.

None of what we see in the updated text may be wrong per-se, but the
readers need "what it is about" upfront to be motivated to read it
through.

Perhaps start the description like this?

	Specify how SMTP connection should be entered into encrypted
	mode. The valid values are 'ssl' and 'tls'. Any other value ...

> +	'tls' refers to "explicit" encryption (often known as STARTTLS),
> +	that uses port 25 by default. Other ports might be used by the SMTP
> +	server, which are not the default. Commonly found alternative port for
> +	'tls' and unencrypted is 587. You need to check your provider's
> +	documentation or your server configuration to make sure
> +	for your own case. Default is the value of `sendemail.smtpEncryption`.

I think the updated text is otherwise good, but it would be better
to remove "The difference between ... is the following."  The text
is easier to read without that sentence.

Thanks.