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

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Tue, Mar 31, 2026, at 00:27, Junio C Hamano wrote:
> 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)

We can use `***` instead.

>, as the two paragraphs before and after are not all that unrelated.

Or nothing.

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

Okay. See my previous email about adding the “separated by” part.

I only mentioned the colon there (prev. email). Not the space. The
reason is the same as what I wrote in the commit message. We say that
these are key–value pairs and only use `:`SP in all the examples. I
think just pointing out the colon at the start is enough detail at that
point before all the details reveal themselves near the end of the
Description section.

IMO it’s best to stick to the normalized `:`SP when writing as well,
even though you can write `:` without any whitespace. But I can’t
imagine readers being motivated to try to deviate from the normalized
separator form; the doc just uses `:`SP... so why not just use that as
well? Compare with the key format: people *will* (or have) tried with
dots/periods, maybe also Unicode like

    Skapad-på: feature-branch-something

... because that has some data content (not just syntactic variation as
is the case for the separator format).

>[snip]