Re: [PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822
- From
- Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
- Date
- Mar 30, 2026, 22:56 UTC
- Message-ID
- <2ed992d8-7314-423d-828a-5801f4de2471@app.fastmail.com>
- In-Reply-To
- <xmqqbjg56jhb.fsf@gitster.g>
On Tue, Mar 31, 2026, at 00:27, Junio C Hamano wrote:
Show 11 quoted lines
> 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.
Show 15 quoted lines
> 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]