[PATCH v3 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.


Changes from v2 to 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.


Changes from v1 to 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 | 132 +++++++++++++----------
 1 file changed, 76 insertions(+), 56 deletions(-)


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

Range-diff vs v2:

  1:  65e6fbdec92 =  1:  7d504700b91 doc: trailer: fix grammar
  2:  82353471831 =  2:  65386432ca4 doc: trailer: swap verb order
  3:  5fabe166714 =  3:  e0a56c8e61d doc: trailer: drop "commit message part" phrasing
  4:  783a0b1e003 !  4:  52f7d29f509 doc: trailer: examples: avoid the word "message" by itself
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       
      -message
      +Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - $ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>'
     + $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
       subject
       
      -message
     @@ Documentation/git-interpret-trailers.txt: EXAMPLES
       
       Signed-off-by: Bob <bob@example.com>
       Acked-by: Alice <alice@example.com>
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/glog-find-author"
     - $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <<EOF
     - > subject
     - >
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - >
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re
     + $ cat msg1.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ 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 "$(git config user.name) <$(git config user.
     + $ git interpret-trailers --trailer sign <msg1.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Bob <bob@example.com>
     + $ cat msg2.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Alice <alice@example.com>
     + $ git interpret-trailers --trailer sign <msg2.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + Signed-off-by: Alice <alice@example.com>
     + ------------
     +@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ git config trailer.help.key "Helped-by: "
     + $ git config trailer.help.ifExists "addIfDifferentNeighbor"
     + $ git config trailer.help.cmd "~/bin/glog-find-author"
     + $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
       subject
       
      -message
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.help.cmd "~/bin/g
       
       Helped-by: Junio C Hamano <gitster@pobox.com>
       Helped-by: Christian Couder <christian.couder@gmail.com>
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/glog-grep"
     - $ git interpret-trailers --trailer="ref:Add copyright notices." <<EOF
     - > subject
     - >
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - >
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + $ git config trailer.ref.key "Reference-to: "
     + $ git config trailer.ref.ifExists "replace"
     + $ git config trailer.ref.cmd "~/bin/glog-grep"
     + $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
       subject
       
      -message
     @@ Documentation/git-interpret-trailers.txt: $ git config trailer.ref.cmd "~/bin/gl
       
       Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
       ------------
     -@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --ab
     - $ git interpret-trailers <<EOF
     - > subject
     - > 
     --> message
     -+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     - > 
     - > see: HEAD~2
     - > EOF
     +@@ Documentation/git-interpret-trailers.txt: Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
     + $ cat msg.txt
     + subject
     + 
     +-message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     + 
     + see: HEAD~2
     + $ cat ~/bin/glog-ref
     +@@ Documentation/git-interpret-trailers.txt: $ git config trailer.see.cmd "glog-ref"
     + $ git interpret-trailers --trailer=see <msg.txt
       subject
       
      -message
  5:  dd7e29fcc21 =  5:  4a2a0e41e4a doc: trailer: remove redundant phrasing
  6:  96cb4ae2965 =  6:  f99545409dc doc: trailer: use angle brackets for <token> and <value>
  7:  4e234110ffd =  7:  6aba774489a doc: trailer.<token>.command: emphasize deprecation
  8:  8aaf9e27d98 =  8:  b13bd73d248 doc: trailer: mention 'key' in DESCRIPTION
  9:  7e95198894b =  9:  ec43e192d6e doc: trailer: add more examples in DESCRIPTION

-- 
gitgitgadget