[PATCH 1/2] doc: interpret-trailers: stop fixating on RFC 822

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This command handles the *trailers* key–value pair format. But the
command isn’t introduced as such; it is instead introduced by stating
that these trailer lines look similar to RFC 822 email headers.

This is overwrought:

• most people do not deal directly with email headers or think about
  email RFCs; and
• simply calling them “key-value pairs” should be more than suggestive
  enough considering the context here.

Se let’s call the format just that, show the example, and then briefly
explain the format of the keys (coming up); this change facilitates
the next commit where we will explain what characters are permitted in
the key.

Concretely, let’s replace the introduction with “key-value pairs” and
remove the last mention of RFC 822, but keep the innocuous comparison
with email line folding in the middle. We do not need the final
disclaimer now that the *only* mention of email headers is that Git
trailers have something similar to email line folding; there is no
invitation to speculate that trailers would follow any other email
format rules since we do not compare them directly any more.

❦

Talking about trailers as an RFC 822/2822-like format seems to go back
to the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated
this command and in turn the first trailer support in git(1) beyond
adding s-o-b lines.

† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    The (❦) is meant as a thematic break. There is too much of a thematic jump
    between these two paragraphs without a section or something else breaking
    them up.
    
    (one was not tempted to use `---` here)

 Documentation/git-interpret-trailers.adoc | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 77b4f63b05c..e7c1f821619 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]
 
 DESCRIPTION
 -----------
-Add or parse _trailer_ lines that look similar to RFC 822 e-mail
-headers, at the end of the otherwise free-form part of a commit
-message. For example, in the following commit message
+Add or parse _trailer_ key-value pairs at the end of the otherwise
+free-form part of a commit message. For example, in the following commit
+message
 
 ------------------------------------------------
 subject
@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and
   newlines in it.
 ------------------------------------------------
 
-Note that trailers do not follow (nor are they intended to follow) many of the
-rules for RFC 822 headers. For example they do not follow the encoding rule.
-
 OPTIONS
 -------
 `--in-place`::
-- 
2.53.0.32.gf6228eaf9cc