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@xxxxxxxxxx> ## 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@xxxxxxxxxx> ## 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@xxxxxxxxxx> @@ 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@xxxxxxxxxxx> +Signed-off-by: Bob <bob@xxxxxxxxxxx> @@ 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 -- gitgitgadget
