[PATCH v4 0/9] docs: interpret-trailers: reword and add examples

["Linus Arver via GitGitGadget" <gitgitgadget@gmail.com>]

This series makes some small improvements to the docs for
git-interpret-trailers. The intent is to make it easier to read for
beginners who have never used this command before.


Updates in v4
=============

 * vs Patch v3 3/9: Reworded a sentence to avoid ambiguity with the word
   "ignored".
 * vs Patch v3 4/9: Replaced "Lorem ipsum..." in favor of "body text" which
   is shorter and more obvious (and search-friendly).
 * vs Patch v3 8/9: Expanded the explanation about 'trailer..key' and its
   convenience, instead of only stating how to use this option.


Updates in v3
=============

 * Rebased on top of "master" at fe86abd751 (Git 2.41, 2023-06-01). The only
   conflict was in Patch v2 4/9
   (https://lore.kernel.org/git/783a0b1e00309e9bcf13494908d99317df72f0d6.1683839975.git.gitgitgadget@gmail.com/),
   because cbb83daeaf (doc: interpret-trailers: fix example, 2023-05-01)
   added the "subject/message" style for the examples that did not have any
   message text in them. These examples' additional message lines have been
   replaced with Lorem ipsum... like the others in Patch v2 4/9.


Updates in v2
=============

In order of significance:

 * The phrase "commit message part" has been removed.
 * The word "message" is always used as part of the bigger phrase "commit
   message".
 * Deprecation language for trailer.<token>.command has been updated to
   minimize whitespace churn, while also tweaking the 2nd paragraph to
   reduce duplication.
 * The phrase "Lorem ipsum..." is always only used to stand in for the body
   paragraph(s) of a commit message.
 * Grammar fixes have been squashed together (01+06 previously).

Linus Arver (9):
  doc: trailer: fix grammar
  doc: trailer: swap verb order
  doc: trailer: drop "commit message part" phrasing
  doc: trailer: examples: avoid the word "message" by itself
  doc: trailer: remove redundant phrasing
  doc: trailer: use angle brackets for <token> and <value>
  doc: trailer.<token>.command: emphasize deprecation
  doc: trailer: mention 'key' in DESCRIPTION
  doc: trailer: add more examples in DESCRIPTION

 Documentation/git-interpret-trailers.txt | 134 +++++++++++++----------
 1 file changed, 78 insertions(+), 56 deletions(-)


base-commit: fe86abd7511a9a6862d5706c6fa1d9b57a63ba09
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1506%2Flistx%2Fdoc-trailer-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1506/listx/doc-trailer-v4
Pull-Request: https://github.com/git/git/pull/1506

Range-diff vs v3:

  1:  7d504700b91 =  1:  7d504700b91 doc: trailer: fix grammar
  2:  65386432ca4 =  2:  65386432ca4 doc: trailer: swap verb order
  3:  e0a56c8e61d !  3:  3c85477d791 doc: trailer: drop "commit message part" phrasing
     @@ Documentation/git-interpret-trailers.txt: Add or parse 'trailer' lines that look
      +This command can also operate on the output of linkgit:git-format-patch[1],
      +which is more elaborate than a plain commit message. Namely, such output
      +includes a commit message (as above), a "---" divider line, and a patch part.
     -+For these inputs, the divider and patch parts are ignored, unless `--no-divider`
     -+is specified.
     ++For these inputs, the divider and patch parts are not modified by
     ++this command and are emitted as is on the output, unless
     ++`--no-divider` is specified.
       
       Some configuration variables control the way the `--trailer` arguments
      -are applied to each commit message and the way any existing trailer in
  4:  52f7d29f509 !  4:  6b4cb31b170 doc: trailer: examples: avoid the word "message" by itself
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       Signed-off-by: Bob <bob@example.com>
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       Acked-by: Alice <alice@example.com>
     @@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.sign.key "Signed-off-by: "
       $ git config trailer.sign.ifmissing add
       $ git config trailer.sign.ifexists doNothing
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.sign.cmd 'echo "$
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Bob <bob@example.com>
       $ cat msg2.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       $ git interpret-trailers --trailer sign <msg2.txt
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Signed-off-by: Alice <alice@example.com>
       ------------
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.help.key "Helped-by: "
       $ git config trailer.help.ifExists "addIfDifferentNeighbor"
       $ git config trailer.help.cmd "~/bin/glog-find-author"
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1"
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Helped-by: Junio C Hamano <gitster@pobox.com>
       Helped-by: Christian Couder <christian.couder@gmail.com>
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       $ git config trailer.ref.key "Reference-to: "
       $ git config trailer.ref.ifExists "replace"
       $ git config trailer.ref.cmd "~/bin/glog-grep"
     @@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
       ------------
     @@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyrigh
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       see: HEAD~2
       $ cat ~/bin/glog-ref
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref
       subject
       
      -message
     -+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     ++body text
       
       See-also: fe3187489d69c4 (subject of related commit)
       ------------
  5:  4a2a0e41e4a =  5:  a4a2ed16dcc doc: trailer: remove redundant phrasing
  6:  f99545409dc =  6:  7a96d0705b9 doc: trailer: use angle brackets for <token> and <value>
  7:  6aba774489a =  7:  f67458a3660 doc: trailer.<token>.command: emphasize deprecation
  8:  b13bd73d248 !  8:  604265c54df doc: trailer: mention 'key' in DESCRIPTION
     @@ Documentation/git-interpret-trailers.txt: token: value
       
       This means that the trimmed <token> and <value> will be separated by
      -`': '` (one colon followed by one space).
     -+`': '` (one colon followed by one space). If the <token> should have a different
     -+string representation than itself, then the 'key' can be configured with
     -+'trailer.<token>.key'.
     ++`': '` (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
     ++appear before the separator on the output (e.g., "Signed-off-by"). This can be
     ++configured using the 'trailer.<token>.key' configuration variable.
       
       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
  9:  ec43e192d6e =  9:  1a3755eacbe doc: trailer: add more examples in DESCRIPTION

-- 
gitgitgadget