Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format
- From
D. Ben Knoble <ben.knoble@gmail.com>
- Date
- Aug 6, 2026, 11:55 UTC
- Message-ID
- <CALnO6CAmM4r2uiuBFJcciR_94KPRSJoCOsuNKeqTQ0Bt=Puvyw@mail.gmail.com>
- In-Reply-To
- <V4_CV_doc_int-tr_key_format.ae2@msgid.xyz>
Hi Kristoffer,
Apologies for not returning to this for a while! I haven't read the whole v4 in detail, but I reviewed the final diff and output.
On Thu, Jul 30, 2026 at 5:18 AM <kristofferhaugsbakk@fastmail.com> wrote:
Show 15 quoted lines
> > From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > Topic name (applied): kh/doc-trailers > > Topic summary: Explain the format of trailer keys (alphanum and > hyphens). This is important to keep in mind so that metadata is not > lost to simple syntax errors. Also replace some terms and define the > important ones upfront. > > Here one change lead to another in order to make sure that everything > stayed coherent. So here’s a linear overview of the changes (as of v4): > > • Patches 1–3: remove RFC 822 mentions, “metadata” term > • Patch 4: This command is not just for commit messages
One small comment on patch 4
Show 8 quoted lines
> • Patches 5–7: Explain the format in the simplest case, explain > the “key” format, and add a new example > • Patch 8: join some existing paragraphs that are about the same theme > since that makes the text flow better > • Patch 9: Also use the “trailer block” term introduced to the doc in > patch 5 later in the doc > • Patch 10: Rewrite new-trailer paragraphs (relates to patch 8) > • Patch 11: document line comment behavior
A few places we use an inline list syntax ("… (i) stuff … (ii) more stuff …"). In the added example about ASCII trailers it is useful because we make reference to (ii); in the initial part of the manual, I don't see any references to the delimited items, so I'm not sure if it's worth numbering them.
Not a strong statement, though, so I'm happy either way. Everything else (that I looked at, see above) looks good to me.
Thanks!
-- D. Ben Knoble