patch, 4 partsMisc. documentation fixes

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

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(+)

astian <astian@eclipso.at> writes:

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.

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

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.

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

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

Jeff King <peff@peff.net> writes:

Thanks for careful reading.

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

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

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

astian <astian@eclipso.at> writes:

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