[PATCH 0/4] Misc. documentation fixes

[PATCH 0/4] Misc. documentation fixes

[astian]

Hi there,

I was looking into adding a new option to git-send-email (and I may
later send the patches implementing that) but as I looked over the code
and associated documentation I found a few places where I thought
improvement could be made.  So here are some documentation fixes and
clarifications that you might find useful.

They apply cleanly on top of commit 8b2efe2a0 (Fifteenth batch for 2.14).

Note 1: even though I'm sending them as a "series", all of these are in
fact independent of each other.

Note 2: see below for a couple of patch-specific comments.

astian (4):
  Doc/config.txt: explain repeated sections
  Doc/config.txt: fix typos
  Doc/git-send-email.txt: clarify a couple of options

    Still to fix:
      --smtp-encryption:
        The current nomenclarure is braindamaged: what's currently
        called "ssl" should be called "tls", what's currently called
        "tls" should be called "starttls".

      --smtp-server-option:
        IMO the option is wrongly named: this option only works with a
        local sendmail-like binary.  When talking to that program, SMTP
        is not used.

  Doc/config.txt: fix documentation for smtpEncryption

    I don't know what's the story behind this, but IMO having
    "smtpEncryption" configurable from "sendemail.<identity>"
    subsections is useful and should be preserved.

    For example, one can set "ssl" (meaning TLS) as global configuration
    (under "sendemail"), but set it to "none" (that is, plain text) for
    a particular identity that actually connects to an i2p or onion
    server, i.e. through an already encrypted transport.

 Documentation/config.txt         |  5 +----
 Documentation/git-send-email.txt | 15 +++++++++------
 2 files changed, 10 insertions(+), 10 deletions(-)

-- 
2.13.2

[PATCH 1/4] Doc/config.txt: explain repeated sections

[astian]

Add a paragraph explaining what happens when a section name is repeated
in the configuration file(s).

The example configuration file shown in this document already implied
Git's behaviour, this patch simply tries to make it explicit.

Signed-off-by: astian <astian@eclipso.at>
---
 Documentation/config.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..afce25705 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -31,6 +31,10 @@ characters, `-` and `.` are allowed in section names.  Each variable
 must belong to some section, which means that there must be a section
 header before the first setting of a variable.
 
+Multiple occurrences of the same section are all logically merged.  (There's
+no special treatment for variables defined multiple times across physically
+different sections, the variable is simply made multivalued.)
+
 Sections can be further divided into subsections.  To begin a subsection
 put its name in double quotes, separated by space from the section name,
 in the section header, like in the example below:
-- 
2.13.2

Re: [PATCH 1/4] Doc/config.txt: explain repeated sections

[Junio C Hamano]

astian <astian@eclipso.at> writes:

> Add a paragraph explaining what happens when a section name is repeated
> in the configuration file(s).
>
> The example configuration file shown in this document already implied
> Git's behaviour, this patch simply tries to make it explicit.
>
> Signed-off-by: astian <astian@eclipso.at>
> ---
>  Documentation/config.txt | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index d5c9c4cab..afce25705 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -31,6 +31,10 @@ characters, `-` and `.` are allowed in section names.  Each variable
>  must belong to some section, which means that there must be a section
>  header before the first setting of a variable.
>  
> +Multiple occurrences of the same section are all logically merged.  (There's
> +no special treatment for variables defined multiple times across physically
> +different sections, the variable is simply made multivalued.)
> +

Looks correct; it's a bit surprising that we didn't already mention
multiple occurrences, but I do not find it so this is a good
addition. 

I do not see a strong reason for () around the second sentence,
though.

By the way, with something that is supposed to hopefully have some
legal value down the line if somebody starts making noises, it
really would be nice to have a real person to associate things with.
It would be embarrassing later if there is no way to even look you
up somehow.  Documentation/SubmittingPatches asks you to sign-off
with a real name for a reason.

Thanks.

Re: [PATCH 1/4] Doc/config.txt: explain repeated sections

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> +Multiple occurrences of the same section are all logically merged.  (There's
>> +no special treatment for variables defined multiple times across physically
>> +different sections, the variable is simply made multivalued.)
>> +
>
> Looks correct; it's a bit surprising that we didn't already mention
> multiple occurrences, but I do not find it so this is a good
> addition. 
>
> I do not see a strong reason for () around the second sentence,
> though.

After re-reading this, I am wondering if the "made multivalued"
above need to be made less confusing.  For a variable that is single
valued, the usual "the last one wins" rule is applied---it's not
like

    [user] 
	name = astian
	name = gitster

makes user.name "gitster" while

    [user] 
	name = astian
    [user]
	name = gitster

makes user.name "multivalued".  In either case, the last one wins,
and it comes not from the syntax but from the semantics assigned to
the variable in question.  What we want to say is not "multi-valued",
but the above two forms both mean the same thing.

But perhaps I am needlessly worried about possible confusion too
much.  I dunno.

Thanks.

Re: [PATCH 1/4] Doc/config.txt: explain repeated sections

[Jeff King]

On Sun, Jul 09, 2017 at 12:57:07AM -0700, Junio C Hamano wrote:

> Junio C Hamano <gitster@pobox.com> writes:
> 
> >> +Multiple occurrences of the same section are all logically merged.  (There's
> >> +no special treatment for variables defined multiple times across physically
> >> +different sections, the variable is simply made multivalued.)
> >> +
> >
> > Looks correct; it's a bit surprising that we didn't already mention
> > multiple occurrences, but I do not find it so this is a good
> > addition. 
> >
> > I do not see a strong reason for () around the second sentence,
> > though.
> 
> After re-reading this, I am wondering if the "made multivalued"
> above need to be made less confusing.  For a variable that is single
> valued, the usual "the last one wins" rule is applied---it's not
> like
> 
>     [user] 
> 	name = astian
> 	name = gitster
> 
> makes user.name "gitster" while
> 
>     [user] 
> 	name = astian
>     [user]
> 	name = gitster
> 
> makes user.name "multivalued".  In either case, the last one wins,
> and it comes not from the syntax but from the semantics assigned to
> the variable in question.  What we want to say is not "multi-valued",
> but the above two forms both mean the same thing.
> 
> But perhaps I am needlessly worried about possible confusion too
> much.  I dunno.

FWIW, the use of "multivalued" here tickled my spider sense, too. I
think when talking on the list we generally reserve "multivalued" for
true "we expect this to be a list" variables. But the only mention of
"multivalued" in the config documentation seems to be:

  Some variables may appear multiple times; we say then that the
  variable is multivalued.

I think the proposed use is consistent with that (and that line is only
2 paragraphs above the proposed paragraph).

-Peff

Re: [PATCH 1/4] Doc/config.txt: explain repeated sections

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> FWIW, the use of "multivalued" here tickled my spider sense, too. I
> think when talking on the list we generally reserve "multivalued" for
> true "we expect this to be a list" variables. But the only mention of
> "multivalued" in the config documentation seems to be:
>
>   Some variables may appear multiple times; we say then that the
>   variable is multivalued.
>
> I think the proposed use is consistent with that (and that line is only
> 2 paragraphs above the proposed paragraph).

Thanks for careful reading.

[PATCH 2/4] Doc/config.txt: fix typos

[astian]

Signed-off-by: astian <astian@eclipso.at>
---
 Documentation/config.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..72e85b002 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -60,7 +60,7 @@ The variable names are case-insensitive, allow only alphanumeric characters
 and `-`, and must start with an alphabetic character.
 
 A line that defines a value can be continued to the next line by
-ending it with a `\`; the backquote and the end-of-line are
+ending it with a `\`; the backslash and the end-of-line are
 stripped.  Leading whitespaces after 'name =', the remainder of the
 line after the first comment character '#' or ';', and trailing
 whitespaces of the line are discarded unless they are enclosed in
@@ -2912,7 +2912,7 @@ sendemail.smtpsslcertpath::
 
 sendemail.<identity>.*::
 	Identity-specific versions of the 'sendemail.*' parameters
-	found below, taking precedence over those when the this
+	found below, taking precedence over those when this
 	identity is selected, through command-line or
 	`sendemail.identity`.
 
-- 
2.13.2

[PATCH 3/4] Doc/git-send-email.txt: clarify a couple of options

[astian]

Clarify the meaning of --smtp-encryption and --smtp-server-option.

Signed-off-by: astian <astian@eclipso.at>
---
 Documentation/git-send-email.txt | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index bac9014ac..158b51045 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -161,7 +161,8 @@ Sending
 	unspecified, choosing the envelope sender is left to your MTA.
 
 --smtp-encryption=<encryption>::
-	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
+	Specify the encryption to use, either 'ssl' (direct TLS) or
+	'tls' (plain text upgraded to TLS via STARTTLS).  Any other
 	value reverts to plain SMTP.  Default is the value of
 	`sendemail.smtpEncryption`.
 
@@ -216,13 +217,15 @@ a password is obtained using 'git-credential'.
 	`sendemail.smtpServerPort` configuration variable.
 
 --smtp-server-option=<option>::
-	If set, specifies the outgoing SMTP server option to use.
+	Specifies a command line option to pass to the local sendmail-like
+	binary.  Only useful when `--smtp-server` (or `sendemail.smtpServer`)
+	points to a local absolute path corresponding to the program binary.
 	Default value can be specified by the `sendemail.smtpServerOption`
-	configuration option.
+	configuration variable.
 +
-The --smtp-server-option option must be repeated for each option you want
-to pass to the server. Likewise, different lines in the configuration files
-must be used for each option.
+This option must be used once for each command line argument you want to pass
+to the program.  Correspondingly, the configuration variable is multivalued:
+set it, in order, once per command line argument.
 
 --smtp-ssl::
 	Legacy alias for '--smtp-encryption ssl'.
-- 
2.13.2

[PATCH 4/4] Doc/config.txt: fix documentation for smtpEncryption

[astian]

Stop saying that smtpEncryption (a configuration variable used by
git-send-email) is not usable in "sendemail.<identity>" subsections,
because that's false.

Signed-off-by: astian <astian@eclipso.at>
---
 Documentation/config.txt | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d5c9c4cab..f40758c31 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2899,10 +2899,6 @@ sendemail.identity::
 	values in the 'sendemail' section. The default identity is
 	the value of `sendemail.identity`.
 
-sendemail.smtpEncryption::
-	See linkgit:git-send-email[1] for description.  Note that this
-	setting is not subject to the 'identity' mechanism.
-
 sendemail.smtpssl (deprecated)::
 	Deprecated alias for 'sendemail.smtpEncryption = ssl'.
 
@@ -2933,6 +2929,7 @@ sendemail.suppresscc::
 sendemail.suppressFrom::
 sendemail.to::
 sendemail.smtpDomain::
+sendemail.smtpEncryption::
 sendemail.smtpServer::
 sendemail.smtpServerPort::
 sendemail.smtpServerOption::
-- 
2.13.2

Re: [PATCH 4/4] Doc/config.txt: fix documentation for smtpEncryption

[Junio C Hamano]

astian <astian@eclipso.at> writes:

> Stop saying that smtpEncryption (a configuration variable used by
> git-send-email) is not usable in "sendemail.<identity>" subsections,
> because that's false.

Hmph, does anybody know when this stopped being true, or was it
incorrect from the very beginning?

>
> Signed-off-by: astian <astian@eclipso.at>
> ---
>  Documentation/config.txt | 5 +----
>  1 file changed, 1 insertion(+), 4 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index d5c9c4cab..f40758c31 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -2899,10 +2899,6 @@ sendemail.identity::
>  	values in the 'sendemail' section. The default identity is
>  	the value of `sendemail.identity`.
>  
> -sendemail.smtpEncryption::
> -	See linkgit:git-send-email[1] for description.  Note that this
> -	setting is not subject to the 'identity' mechanism.
> -
>  sendemail.smtpssl (deprecated)::
>  	Deprecated alias for 'sendemail.smtpEncryption = ssl'.
>  
> @@ -2933,6 +2929,7 @@ sendemail.suppresscc::
>  sendemail.suppressFrom::
>  sendemail.to::
>  sendemail.smtpDomain::
> +sendemail.smtpEncryption::
>  sendemail.smtpServer::
>  sendemail.smtpServerPort::
>  sendemail.smtpServerOption::