Re: [PATCH 2/2] doc: interpret-trailers: explain key format

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

On Tue, Mar 31, 2026, at 14:35, Ben Knoble wrote:
>> Le 30 mars 2026 à 18:26, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> a écrit :
>>>[snip]
>>
>> Key & value.
>>
>> Something like:
>>
>>    Just like *trailer* we emphasize these two first standalone word
>>    mentions (key and value).
>>
>> They are the only emphasized words in the diff. Although I *have* relied
>> too much on the diff context before.
>
> Perhaps “we emphasize the introduction of the terms ‘key’ and ‘value’”
> (much like a technical manual or paper may emphasize the first use of a
> new word or abbreviation, making subsequent uses link to it so readers
> can find the definition)?

I think I’ll steal that. Thanks!

> I do find it interesting that the introduction is with an example
> rather than a definition.

The example is from Linus Arver in d57fa7fc (doc: trailer: add more
examples in DESCRIPTION, 2023-06-15).[1] The version before that[2]
indirectly showed a `token: value` example (“will appear in the output
like”) after five paragraphs.

† 1: One review comment: https://lore.kernel.org/git/xmqqmt2emwlj.fsf@gitster.g/
† 2: `git show d57fa7fc73202af226b6c0^1:Documentation/git-interpret-trailers.txt`

> This suits “learning order” (concrete->abstract), but not necessarily
> “reference order” (where I just want to get to the definition). Hm.
>
> I’m not sure I have any concrete suggestions, though.

I think the only practical starting point for this format is the
simplest case first, namely:

1. One line per trailer (c.f. the value takes up multiple lines)
2. Non-empty values (see `--trim-empty`)
3. Default separator
4. No non-trailer lines
5. No configuration

Currently that starts off with two examples. But let’s try the other
way around:

***

A _trailer_ in its simplest form is a key-value pair with a colon as a
separator. The _key_ consists of ASCII alphanumeric characters and
hyphens (`-`). A _trailer block_ consists of one or more such
trailers. The trailer block needs to be preceded by a blank
line.[**1**] In other words:

    <text>

    <key>: <value>

Where <key> consists of ASCII alphanumeric characters and hyphens. For
example:

[we’re back to the original example]
------------------------------------------------
subject

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>
------------------------------------------------

***

Also optionally interject some words about commit messages and whatnot
(or even tag messages for that matter, now).

I was originally feeling skeptical of changing to something like
reference-first. But I like this now that I have gone through the
exercise of trying it out. So thanks for mentioning it. ;)

[**1**]: git-commit(1) stripspace behavior etc. doesn’t make this
         obvious but you can have just a blank line and then a trailer block. You
         don’t need any text before the blank line. `LF` indicates the blank
         line:

               LF
               Signed-off-by: Me