Re: [PATCH v4 00/11] doc: interpret-trailers: explain key format

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 <[email protected]> wrote:
>
> From: Kristoffer Haugsbakk <[email protected]>
>
> 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

> • 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