[PATCH v4 08/11] doc: interpret-trailers: join new-trailers again

From: Kristoffer Haugsbakk <[email protected]>

There are three paragraphs that talk about how a new trailer is added.
But the first one is separated from the other two by two paragraphs
about how `key-alias` can make using `--trailer` more convenient. This
short how-to does not follow thematically from the previous paragraph,
and can wait until we have fully described how a new trailer is
added. So let’s move the three paragraphs about the new-trailer topic
together and move the how-to paragraphs after that.

***

Let’s now review the history of the document. Even if the document
is not quite correct in its current state, just doing the apparently
obvious edit without considering the history does not respect the
effort that went into changing the document in the past.

These three paragraphs were originally next to each other, in the first
version of the doc.[1] But extra sentences about this how-to topic was
added to the first paragraph nine years later:[2]

    [...]
    `': '` (one colon followed by one space). For convenience, the
    <token> can be a shortened string key (e.g., "sign") instead of the
    full string which should [...]

And then it was split into it’s own paragraph a little later.[3]

This evolution shows, in my opinion, that this how-to never followed
thematically from the existing topic. Which means that there is nothing
that was potentially lost to time that we need to restore or respect.

† 1: dfd66ddf (Documentation: add documentation for 'git
     interpret-trailers', 2014-10-13)
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
     2023-09-07)

Suggested-by: D. Ben Knoble <[email protected]>
Signed-off-by: Kristoffer Haugsbakk <[email protected]>
---

Notes (series):
    v4:
    • Msg: Fix word-confusion: s/There are three trailers/There are
      three paragraphs.
    
      🔗 https://lore.kernel.org/git/CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com/
    
      I knew that I was going to fix this when I started on
      version 4. But you would not believe how many times I
      went over the commit log without seeing that I had
      neglected to do this part.
    
    ---
    
    v3: [new]
    • Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/
    • Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]
    
      🔗 1: https://lore.kernel.org/git/[email protected]/

 Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index a0f7ed6fdd9..616f479a367 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -74,19 +74,6 @@ key: value
 This means that the trimmed _<key>_ and _<value>_ will be separated by
 "`:`{nbsp}" (one colon followed by one space).
 
-For convenience, a _<key-alias>_ can be configured to make using `--trailer`
-shorter to type on the command line. This can be configured using the
-`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
-of the full _<key>_ string, although case sensitivity does not matter. For
-example, if you have
-
-------------------------------------------------
-trailer.sign.key "Signed-off-by: "
-------------------------------------------------
-
-in your configuration, you only need to specify `--trailer="sign: foo"`
-on the command line instead of `--trailer="Signed-off-by: foo"`.
-
 By default the new trailer will appear at the end of all the existing
 trailers. If there is no existing trailer, the new trailer will appear
 at the end of the input. A blank line will be added before the new
@@ -101,6 +88,19 @@ The group must either be at the end of the input or be the last
 non-whitespace lines before a line that starts with `---` (followed by a
 space or the end of the line).
 
+For convenience, a _<key-alias>_ can be configured to make using `--trailer`
+shorter to type on the command line. This can be configured using the
+`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
+of the full _<key>_ string, although case sensitivity does not matter. For
+example, if you have
+
+------------------------------------------------
+trailer.sign.key "Signed-off-by: "
+------------------------------------------------
+
+in your configuration, you only need to specify `--trailer="sign: foo"`
+on the command line instead of `--trailer="Signed-off-by: foo"`.
+
 When reading trailers, there can be no whitespace before or inside the
 _<key>_, but any number of regular space and tab characters are allowed
 between the _<key>_ and the separator. There can be whitespaces before,
-- 
2.54.0.22.g9e26862b904