[v3,4/9] doc: trailer: examples: avoid the word "message" by itself

Commit Message

Linus Arver June 6, 2023, 2:08 a.m. UTC

From: Linus Arver <[e-mail]>

Previously, "message" could mean the input, output, commit message, or
"internal body text inside the commit message" (in the EXAMPLES
section). Avoid overloading this term by using the appropriate meanings
explicitly.

Signed-off-by: Linus Arver <[e-mail]>
---
 Documentation/git-interpret-trailers.txt | 50 ++++++++++++------------
 1 file changed, 25 insertions(+), 25 deletions(-)

Comments

Christian Couder June 14, 2023, 3:12 p.m. UTC | #1

>  $ git config trailer.sign.key "Signed-off-by"
>  $ cat msg.txt
>  subject
>
> -message
> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.

I am not sure this change is clarifying anything. If you want
something clearer for "internal body text inside the commit message",
you could perhaps just use "body" or "body text".

I am not against using such latin words, but then why only in the body
and not in the subject too? And if it's used in the subject too, then
I am not sure it will make it easy for users to understand that the
example is using a simple commit message.

Linus Arver June 15, 2023, 3:03 a.m. UTC | #2

Christian Couder <[e-mail]> writes:

>>   $ git config trailer.sign.key "Signed-off-by"
>>   $ cat msg.txt
>>   subject

>> -message
>> +Lorem ipsum dolor sit amet, consectetur adipiscing elit.

> I am not sure this change is clarifying anything. If you want
> something clearer for "internal body text inside the commit message",
> you could perhaps just use "body" or "body text".

> I am not against using such latin words, but then why only in the body
> and not in the subject too? And if it's used in the subject too, then
> I am not sure it will make it easy for users to understand that the
> example is using a simple commit message.

I can't remember why I didn't just use "body text", which I agree is
better than the (albeit famous) Latin phrase. It's shorter, simpler, and
also search-friendly (for cases where the user is not sure of exactly
which word they want to search for). Updated in v4 to use "body
text".

Patch

diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index ffde97a6c3d..011ed0c3590 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -82,12 +82,12 @@  OPTIONS
 
 --trim-empty::
 	If the <value> part of any trailer contains only whitespace,
-	the whole trailer will be removed from the resulting message.
+	the whole trailer will be removed from the output.
 	This applies to existing trailers as well as new trailers.
 
 --trailer <token>[(=|:)<value>]::
 	Specify a (<token>, <value>) pair that should be applied as a
-	trailer to the input messages. See the description of this
+	trailer to the inputs. See the description of this
 	command.
 
 --where <placement>::
@@ -101,7 +101,7 @@  OPTIONS
 --if-exists <action>::
 --no-if-exists::
 	Specify what action will be performed when there is already at
-	least one trailer with the same <token> in the message.  A setting
+	least one trailer with the same <token> in the input.  A setting
 	provided with '--if-exists' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`,
@@ -110,7 +110,7 @@  OPTIONS
 --if-missing <action>::
 --no-if-missing::
 	Specify what action will be performed when there is no other
-	trailer with the same <token> in the message.  A setting
+	trailer with the same <token> in the input.  A setting
 	provided with '--if-missing' overrides all configuration variables
 	and applies to all '--trailer' options until the next occurrence of
 	'--if-missing' or '--no-if-missing'. Possible actions are `doNothing`
@@ -177,7 +177,7 @@  first trailer with the same <token>.
 trailer.ifexists::
 	This option makes it possible to choose what action will be
 	performed when there is already at least one trailer with the
-	same <token> in the message.
+	same <token> in the input.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
 is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
@@ -187,10 +187,10 @@  trailer with the same (<token>, <value>) pair is above or below the line
 where the new trailer will be added.
 +
 With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<token>, <value>) pair is already in the message.
+with the same (<token>, <value>) pair is already in the input.
 +
 With `add`, a new trailer will be added, even if some trailers with
-the same (<token>, <value>) pair are already in the message.
+the same (<token>, <value>) pair are already in the input.
 +
 With `replace`, an existing trailer with the same <token> will be
 deleted and the new trailer will be added. The deleted trailer will be
@@ -198,12 +198,12 @@  the closest one (with the same <token>) to the place where the new one
 will be added.
 +
 With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <token> in the message.
+added if there is already one with the same <token> in the input.
 
 trailer.ifmissing::
 	This option makes it possible to choose what action will be
 	performed when there is not yet any trailer with the same
-	<token> in the message.
+	<token> in the input.
 +
 The valid values for this option are: `add` (this is the default) and
 `doNothing`.
@@ -275,37 +275,37 @@  EXAMPLES
 --------
 
 * Configure a 'sign' trailer with a 'Signed-off-by' key, and then
-  add two of these trailers to a message:
+  add two of these trailers to a commit message file:
 +
 ------------
 $ git config trailer.sign.key "Signed-off-by"
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 $ git interpret-trailers --trailer 'sign: Alice <[e-mail]>' --trailer 'sign: Bob <[e-mail]>' <msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <[e-mail]>
 Signed-off-by: Bob <[e-mail]>
 ------------
 
-* Use the `--in-place` option to edit a message file in place:
+* Use the `--in-place` option to edit a commit message file in place:
 +
 ------------
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Bob <[e-mail]>
 $ git interpret-trailers --trailer 'Acked-by: Alice <[e-mail]>' --in-place msg.txt
 $ cat msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Bob <[e-mail]>
 Acked-by: Alice <[e-mail]>
@@ -328,7 +328,7 @@  $ git interpret-trailers --trailer 'Cc: Alice <[e-mail]>' --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
@@ -336,19 +336,19 @@  $ 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 <[e-mail]>
 $ cat msg2.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <[e-mail]>
 $ git interpret-trailers --trailer sign <msg2.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Signed-off-by: Alice <[e-mail]>
 ------------
@@ -376,14 +376,14 @@  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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Helped-by: Junio C Hamano <[e-mail]>
 Helped-by: Christian Couder <[e-mail]>
@@ -400,14 +400,14 @@  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
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
 ------------
@@ -419,7 +419,7 @@  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
@@ -432,7 +432,7 @@  $ git config trailer.see.cmd "glog-ref"
 $ git interpret-trailers --trailer=see <msg.txt
 subject
 
-message
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 See-also: fe3187489d69c4 (subject of related commit)
 ------------