Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822

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

kristofferhaugsbakk@fastmail.com writes:

> Notes (series):
>     The (❦) is meant as a thematic break. There is too much of a thematic jump
>     between these two paragraphs without a section or something else breaking
>     them up.

I do not quite agree with this particular instance.  It rather looks
more like an unnecessary hostile move against folks who prefer to
see plain ASCII on their screen unless absolutely needed (like say
for displaying people's names with letters outside US-ASCII), as the
two paragraphs before and after are not all that unrelated.

One thing that I found a bit wanting after this step is that it lost
hint that the primary way to delimit between the key and value in
the trailer lines is to have a colon immediately after key and with
a single whitespace before the value, which is what is very typical
to see in the e-mail headers.  Sure, if a reader has not heard of
(2)822, hinting that these resemble e-mail headers would not help
them at all, but those of us among the audience of this document who
have seen e-mail headers and how they feel, the "look similar to"
was enough to hint how a colon is typically used in a trailer.  In
the updated text, the readers will have to way around line #65
before seeing the official "both key and value are trimmed for
whitespaces on both ends and then made into 'key: value'".

I mentioned "issues I raised on the previous step" in my review on
2/2, but did not remember that I haven't sent out this one yet ;-)

> @@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]
>  
>  DESCRIPTION
>  -----------
> -Add or parse _trailer_ lines that look similar to RFC 822 e-mail
> -headers, at the end of the otherwise free-form part of a commit
> -message. For example, in the following commit message
> +Add or parse _trailer_ key-value pairs at the end of the otherwise
> +free-form part of a commit message. For example, in the following commit
> +message
>  
>  ------------------------------------------------
>  subject