Re: [PATCH 2/2] doc: interpret-trailers: explain key format

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

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> A trailer key must consist of ASCII alphanumeric characters and
> hyphens *only*. Let’s document it explicitly instead of relying on
> readers being conservative and painting their trailers by numbers
> (by the documentation examples).

"paint"?  I am not sure what the latter half of the above paragraph
wants to say, even though I do agree that being explicit about the
allowed characters is a good idea.

> The previous commit for “key–value pairs” allows us to segue right into
> describing these lines as consisting of a key and a value, which is our
> opening to describing the key format.

And it is a good place to remedy the issue I raised for the previous
step as well ;-)

> Just like *trailer* we emphasize these two first standalone word
> mentions.

Again, I have no idea what "these two first standalone word" wants
to refer to.  It is not even clear to me if it refers to a single
thing, or two things---the verb "mentions" hints that the subject of
the sentence must be plural, but I cannot tell what two things you
are referring to.

> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index e7c1f821619..92d9c95f9d2 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -27,7 +27,10 @@ Signed-off-by: Alice <alice@example.com>
>  Signed-off-by: Bob <bob@example.com>
>  ------------------------------------------------
>  
> -the last two lines starting with `Signed-off-by` are trailers.
> +the last two lines starting with `Signed-off-by` are trailers. These two
> +trailers have the _key_ `Signed-off-by` and a _value_ (Alice and Bob).

Remedy the loss of "e-mail like" by ending the above sentence more like:

    ... and Bob), with a colon appended at the end of the key.

> +The key must consist of only ASCII alphanumeric characters and hyphens
> +(`-`). The hyphens serve as interword separators.

The first sentence is a very much welcome addition.  I however doubt
that the last sentence is necessary or beneficial, as "SignedOffBy"
is a perfectly fine key to be used for a trailer if a project
prefers (not this project, though).  I would not object to

    The hyphens can be used as inter-word separators.

or

    The hyphens can be used as inter-word separators, if you want.

but any expression that can be misinterpreted that the document
strongly suggests projects and communities to adopt the "hyphen as
inter-word separator" convention is not very welcome.

Thanks.