[PATCH v4 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs

From: Kristoffer Haugsbakk <[email protected]>

Two commits ago we moved new-trailers paragraph next to each other.
But there is something curious about two of them:

    By default the new trailer will appear at the end of the trailer
    block. [...]

Then a source block and a paragraph later:

    By default, a `<key>=<value>` or `<key>:<value>` argument given
    using `--trailer` will be appended after the existing trailers only
    if [...]

Why are there two paragraphs that talk about how “By default” a trailer
will be appended?

We can make these paragraphs flow better, and with a more distinct
character each, by dividing the flow like this:

1. Declare that we are about to talk about `--trailer` appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then discuss what each trailer line will look like

Signed-off-by: Kristoffer Haugsbakk <[email protected]>
---

Notes (series):
    v4:
    • Simplify “This is how the new trailer” paragraph: drop “More
      concretely,” since it is misleading (this is not a “more
      concretely continuation of the preceding paragraph(s))[1]
    
      🔗 1: https://lore.kernel.org/git/[email protected]/
    
    ---
    
    v3: [new]
    • Based on draft: https://lore.kernel.org/git/[email protected]/
    • See msg:
    
          Two commits ago we moved new-trailers paragraph next to
          each other.
    
      This commit here might fit better one step back. So that it
      becomes the commit right after. But I can deal with that commit
      movement if this change is accepted. For now I didn’t bother.

 Documentation/git-interpret-trailers.adoc | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index a1adab20fef..ac59ef51f80 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -60,10 +60,18 @@ 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
+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.
+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 will be inserted before the
+new trailer block in that case.
+
+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:
 
@@ -74,12 +82,6 @@ key: value
 This means that the trimmed _<key>_ and _<value>_ will be separated by
 "`:`{nbsp}" (one colon followed by one space).
 
-By default the new trailer will appear at the end of the trailer block.
-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 will be inserted before the
-new trailer block in that case.
-
 Existing trailers are extracted from the input by looking for the
 trailer block. A trailer block is a group of one or more lines that (i)
 is all trailers, or (ii) contains at least one Git-generated or
-- 
2.54.0.22.g9e26862b904