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

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 v1 ===============

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 | 124 +++++++++++++----------
 1 file changed, 72 insertions(+), 52 deletions(-)

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

Range-diff vs v1:

  1:  12d4850a9ab !  1:  65e6fbdec92 doc: trailer: fix grammar
     @@ Documentation/git-interpret-trailers.txt: SYNOPSIS
       DESCRIPTION
       -----------
      -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail
     -+Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
     ++Parse or add 'trailer' lines that look similar to RFC 822 e-mail
       headers, at the end of the otherwise free-form part of a commit
       message.
       
     +@@ Documentation/git-interpret-trailers.txt: for the same <token>, 'trailer.<token>.cmd' is used and
     + 'trailer.<token>.command' is ignored.
     + 
     + trailer.<token>.cmd::
     +-	This option can be used to specify a shell command that will be called:
     ++	This option can be used to specify a shell command that will be called
     + 	once to automatically add a trailer with the specified <token>, and then
     +-	each time a '--trailer <token>=<value>' argument to modify the <value> of
     +-	the trailer that this option would produce.
     ++	called each time a '--trailer <token>=<value>' argument is specified to
     ++	modify the <value> of the trailer that this option would produce.
     + +
     + When the specified command is first called to add a trailer
     + with the specified <token>, the behavior is as if a special
  2:  b7717424437 !  2:  82353471831 doc: trailer: swap verb order
     @@ Documentation/git-interpret-trailers.txt: SYNOPSIS
       
       DESCRIPTION
       -----------
     --Parse or add 'trailer' lines, that look similar to RFC 822 e-mail
     -+Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
     +-Parse or add 'trailer' lines that look similar to RFC 822 e-mail
     ++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.
       
  3:  ad2d669eb0a <  -:  ----------- doc: trailer: --no-divider: more precise language
  4:  0c10e40794d <  -:  ----------- doc: trailer: explain "commit mesage part" on first usage
  -:  ----------- >  3:  5fabe166714 doc: trailer: drop "commit message part" phrasing
  -:  ----------- >  4:  783a0b1e003 doc: trailer: examples: avoid the word "message" by itself
  5:  5bad365c786 =  5:  dd7e29fcc21 doc: trailer: remove redundant phrasing
  6:  8e36d1bd1f0 <  -:  ----------- doc: trailer: trailer.<token>.cmd: add missing verb phrase
  7:  ab11527ca58 !  6:  96cb4ae2965 doc: trailer: use angle brackets for <token> and <value>
     @@ Commit message
          Signed-off-by: Linus Arver <linusa@google.com>
      
       ## Documentation/git-interpret-trailers.txt ##
     -@@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such three minus signs start the patch
     - part of the message. See also `--no-divider` below.
     +@@ Documentation/git-interpret-trailers.txt: non-whitespace lines before a line that starts with '---' (followed by a
     + space or the end of the line).
       
       When reading trailers, there can be no whitespace before or inside the
      -token, but any number of regular space and tab characters are allowed
     @@ Documentation/git-interpret-trailers.txt: space or the end of the line). Such th
       with each subsequent line starting with at least one whitespace, like
       the "folding" in RFC 822.
       
     +@@ Documentation/git-interpret-trailers.txt: trailer.<token>.command::
     + 	This option behaves in the same way as 'trailer.<token>.cmd', except
     + 	that it doesn't pass anything as argument to the specified command.
     + 	Instead the first occurrence of substring $ARG is replaced by the
     +-	value that would be passed as argument.
     ++	<value> that would be passed as argument.
     + +
     + The 'trailer.<token>.command' option has been deprecated in favor of
     + 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
  8:  59804321793 !  7:  4e234110ffd doc: trailer.<token>.command: refer to existing example
     @@ Metadata
      Author: Linus Arver <linusa@google.com>
      
       ## Commit message ##
     -    doc: trailer.<token>.command: refer to existing example
     +    doc: trailer.<token>.command: emphasize deprecation
     +
     +    This puts the deprecation notice up front, instead of leaving it to the
     +    next paragraph.
      
          Signed-off-by: Linus Arver <linusa@google.com>
      
     @@ Documentation/git-interpret-trailers.txt: trailer.<token>.ifmissing::
       	that option for trailers with the specified <token>.
       
       trailer.<token>.command::
     --	This option behaves in the same way as 'trailer.<token>.cmd', except
     --	that it doesn't pass anything as argument to the specified command.
     --	Instead the first occurrence of substring $ARG is replaced by the
     --	value that would be passed as argument.
     -+	This option behaves in the
     -+	same way as 'trailer.<token>.cmd', except that it doesn't pass anything as
     -+	argument to the specified command. Instead the first occurrence of substring
     -+	$ARG is replaced by the <value> from the trailer. See the
     -+	'trailer.see.command' trailer example in the "EXAMPLES" section below.
     ++	Deprecated in favor of 'trailer.<token>.cmd'.
     + 	This option behaves in the same way as 'trailer.<token>.cmd', except
     + 	that it doesn't pass anything as argument to the specified command.
     + 	Instead the first occurrence of substring $ARG is replaced by the
     + 	<value> that would be passed as argument.
     + +
     +-The 'trailer.<token>.command' option has been deprecated in favor of
     +-'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
     ++Note that $ARG in the user's command is
     + only replaced once and that the original way of replacing $ARG is not safe.
       +
     - The 'trailer.<token>.command' option has been deprecated in favor of
     - 'trailer.<token>.cmd' due to the fact that $ARG in the user's command is
     + When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given
  9:  1ac58b0b07c <  -:  ----------- doc: trailer.<token>.command: emphasize deprecation
 10:  2c04a5ba7f0 =  8:  8aaf9e27d98 doc: trailer: mention 'key' in DESCRIPTION
 11:  ea483b364b4 !  9:  7e95198894b doc: trailer: add more examples in DESCRIPTION
     @@ Commit message
       ## Documentation/git-interpret-trailers.txt ##
      @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
       -----------
     - Add or parse 'trailer' lines, that look similar to RFC 822 e-mail
     + 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.
      +message. For example, in the following commit message
     @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
      +------------------------------------------------
      +subject
      +
     -+message
     ++Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      +
      +Signed-off-by: Alice <alice@example.com>
      +Signed-off-by: Bob <bob@example.com>
     @@ Documentation/git-interpret-trailers.txt: DESCRIPTION
      +
      +the last two lines starting with "Signed-off-by" are trailers.
       
     - This command reads some patches or commit messages from either the
     - <file> arguments or the standard input if no <file> is specified. If
     + This command reads commit messages from either the
     + <file> arguments or the standard input if no <file> is specified.
      @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no whitespace before or inside the
       between the <token> and the separator. There can be whitespaces before,
       inside or after the <value>. The <value> may be split over multiple lines
     @@ Documentation/git-interpret-trailers.txt: When reading trailers, there can be no
      +the "folding" in RFC 822. Example:
      +
      +------------------------------------------------
     -+token: Lorem ipsum dolor sit amet, consectetur
     -+  adipiscing elit.
     ++token: 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