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

[Junio C Hamano <gitster@pobox.com>]

kristofferhaugsbakk@fastmail.com writes:

> Interdiff against v2:
> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index b42f957d666..d5e856f5d68 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in
>  the input is changed. They also make it possible to
>  automatically add some trailers.
>  
> -By default, a `<key>=<value>` or `<key>:<value>` argument given
> -using `--trailer` will be appended after the existing trailers only if
> -the last trailer has a different (_<key>_, _<value>_) pair (or if there
> -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
> -to remove starting and trailing whitespace, and the resulting trimmed
> -_<key>_ and _<value>_ will appear in the output like this:
> +Let's consider new trailers added with `--trailer`.
> +By default, the new trailer will appear at the end of the trailer block.
> +Also by default, this new trailer will only be added
> +if the last trailer is different to it.

The new text is more succinct here.

> +A trailer block will be created with only that trailer if a trailer
> +block does not already exist. Recall that a trailer block needs to be
> +preceded by a blank line, so a blank line (specifically an empty line)
> +will be inserted before the new trailer block in that case.

If you want to stress that a line with only whitespaces on it does
not count as a blank line for the purpose of this paragraph, you can
consistently say "an empty line" withotu saying "a blank line", and
you do not need to have "(specifically an empty lline)" there.

> +More concretely, this is how the new trailer is added: a `<key>=<value>`
> +or `<key>:<value>` argument given using `--trailer` will be appended
> +after the existing trailers. The _<key>_ and _<value>_ parts will be
> +trimmed to remove starting and trailing whitespace, and the resulting
> +trimmed _<key>_ and _<value>_ will appear in the output like this:

"More concretely" here feels a bit out of place, as the three paragraphs
we saw so far aren't really progression of the same thing.  First we
saw when a new trailer line is added, second we learned that an
extra empty line may be added in addition to the new trailer line.
What we are about to mention is orthogonal: how each trailer line
would look like.  There is no more or less concrete about it.

>  ------------------------------------------------
>  key: value
> @@ -74,6 +82,16 @@ key: value
>  This means that the trimmed _<key>_ and _<value>_ will be separated by
>  "`:`{nbsp}" (one colon followed by one space).
>  
> +Existing trailers are extracted from the input by looking for the
> +trailer block. Concretely, that is a group of one or more lines that (i)

"Concretely, that is a" -> "A trailer block is a".

> +is all trailers, or (ii) contains at least one Git-generated or
> +user-configured trailer and consists of at
> +least 25% trailers.

Hmph, isn't (i) a narrow subset of (ii)?

> +The trailer block is by definition at the end the the message. The end
> +of the message in turn is either (i) at the end of the input, or (ii)

"at the end the the message" -> "at the end of the commit log
message", and "the input" -> "the message", probably.

The latter is because not everybody is "parsing" the message to futz
with trailers, using the message as "input", and some are "writing
out" the message, using it as "output".

> +the last non-whitespace lines before a line that starts with `---`
> +(followed by a space or the end of the line).

OK.