Skip to contentSkip to conversation

Doc: note minimum scissors line length for mailinfo

PATCH In review Evan Gates 4 participants 10 messages Sep 25, 2020 – Sep 28, 2020 Documentation

lore
Share & tools
lore

Evan Gates

author
#0 lore raw

PATCH 1/1 Doc: note minimum scissors line length for mailinfo

There is a comment in is_scissors_line describing the requirements for a line to be considered a scissors line. While the existing wording covers most of the requirements, there was no mention of minimum size.

---
This comes up after I tried to use --8<-- as scissors but git am didn't recognize it because it's only 6 bytes. I couldn't figure out why until I cloned git and checked the source.

I am not subscribed to the list, please cc me in any replies.

 Documentation/git-mailinfo.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/git-mailinfo.txt +5 -5
index 3bbc731f67..859829d32f 100644
@@ -74,11 +74,11 @@ conversion, even with this flag.
 --scissors::
 	Remove everything in body before a scissors line.  A line that
 	mainly consists of scissors (either ">8" or "8<") and perforation
-	(dash "-") marks is called a scissors line, and is used to request
-	the reader to cut the message at that line.  If such a line
-	appears in the body of the message before the patch, everything
-	before it (including the scissors line itself) is ignored when
-	this option is used.
+	(dash "-") marks and is at least 8 bytes long ("-- >8 --") is
+	called a scissors line, and is used to request the reader to cut
+	the message at that line.  If such a line appears in the body
+	of the message before the patch, everything before it (including
+	the scissors line itself) is ignored when this option is used.
 +
 This is useful if you want to begin your message in a discussion thread
 with comments and suggestions on the message you are responding to, and to
Signature · 1 line
2.28.0
Reviewed-by on v1 1/1
#1 lore raw

Hi,

Quoted 9 lines · Evan Gates

There is a comment in is_scissors_line describing the requirements for a line to be considered a scissors line. While the existing wording covers most of the requirements, there was no mention of minimum size.

---
This comes up after I tried to use --8<-- as scissors but git am didn't recognize it because it's only 6 bytes. I couldn't figure out why until I cloned git and checked the source.

Thanks for following through. It's probably worth mentioning this example ("--8<--") in the commit message as well.

[...]

Documentation/git-mailinfo.txt conversion, even with this flag. · line 77

Quoted 12 lines
Documentation/git-mailinfo.txt +1 -5
@@ -74,11 +74,11 @@ conversion, even with this flag.
 --scissors::
 	Remove everything in body before a scissors line.  A line that
 	mainly consists of scissors (either ">8" or "8<") and perforation
-	(dash "-") marks is called a scissors line, and is used to request
-	the reader to cut the message at that line.  If such a line
-	appears in the body of the message before the patch, everything
-	before it (including the scissors line itself) is ignored when
-	this option is used.
+	(dash "-") marks and is at least 8 bytes long ("-- >8 --") is

nit: I think "characters" instead of "bytes" would focus a bit more on the intent. It's true that characters and bytes coincide in this example, but using characters might be a bit more in the terms that the user is already thinking in.

By the way, is this the right criterion? Perhaps an alternative method would be to make "--8<--" count as a scissors like after all. What do you think?

Documentation/git-mailinfo.txt conversion, even with this flag. · line 84

Quoted 7 lines
Documentation/git-mailinfo.txt +4 -0
+	called a scissors line, and is used to request the reader to cut
+	the message at that line.  If such a line appears in the body
+	of the message before the patch, everything before it (including
+	the scissors line itself) is ignored when this option is used.
 +
 This is useful if you want to begin your message in a discussion thread
 with comments and suggestions on the message you are responding to, and to

With the commit message and wording tweaks listed above,

Thanks.

#2 lore raw
Quoted 10 lines · [email protected] writes:

Documentation/git-mailinfo.txt conversion, even with this flag. · line 77

Quoted 1 line
Documentation/git-mailinfo.txt +1 -0
+	(dash "-") marks and is at least 8 bytes long ("-- >8 --") is

nit: I think "characters" instead of "bytes" would focus a bit more on the intent. It's true that characters and bytes coincide in this example, but using characters might be a bit more in the terms that the user is already thinking in.

By the way, is this the right criterion? Perhaps an alternative method would be to make "--8<--" count as a scissors like after all. What do you think?

Mildly negative.

It certainly was fun to declare that users can use anything that look like perforation drawn on paper, and to pile more and more heuristics to detect such a line. But I think, instead of describing all these details in the manual, telling the users to always write "-- >8 --" and nothing else would be a better approach.

It would save them time.

Let's not waste people's time by encouraging them to be "creative" in areas that do not make the world a better place. How flexible they can be when drawing the line to mark the part that recipent can discard does not matter in the end result of their work.

Thanks.

#3 lore raw
Quoted 7 lines · Junio C Hamano

It certainly was fun to declare that users can use anything that look like perforation drawn on paper, and to pile more and more heuristics to detect such a line. But I think, instead of describing all these details in the manual, telling the users to always write "-- >8 --" and nothing else would be a better approach.

It would save them time.

Agreed, I think this is a much better direction.

Another advantage is that it makes us easier to change the heuristics, confident that we are training users to aim for the simple and reliable case instead of the edge cases that may need to be tweaked over time.

Thanks,
Jonathan

author
#4 lore raw
Quoted 8 lines · Jonathan Nieder
Quoted 6 lines · Junio C Hamano

It certainly was fun to declare that users can use anything that look like perforation drawn on paper, and to pile more and more heuristics to detect such a line. But I think, instead of describing all these details in the manual, telling the users to always write "-- >8 --" and nothing else would be a better approach.

Quoted 8 lines
Quoted 1 line

It would save them time.

Agreed, I think this is a much better direction.

Another advantage is that it makes us easier to change the heuristics, confident that we are training users to aim for the simple and reliable case instead of the edge cases that may need to be tweaked over time.

Sounds good to me. How about:

Remove everything in body before a scissors line ("-- >8 --"). The line represents scissors and perforation marks, and is used to request the reader to cut the message at that line. If that line appears in the body of the message before the patch, everything before it (including the scissors line itself) is ignored when this option is used.

Etiquette question: Should a v2 patch be a new thread or reply to this one?

#5 lore raw
Quoted 20 lines · Evan Gates
Quoted 8 lines · Jonathan Nieder
Quoted 6 lines · Junio C Hamano

It certainly was fun to declare that users can use anything that look like perforation drawn on paper, and to pile more and more heuristics to detect such a line. But I think, instead of describing all these details in the manual, telling the users to always write "-- >8 --" and nothing else would be a better approach.

Quoted 8 lines
Quoted 1 line

It would save them time.

Agreed, I think this is a much better direction.

Another advantage is that it makes us easier to change the heuristics, confident that we are training users to aim for the simple and reliable case instead of the edge cases that may need to be tweaked over time.

Sounds good to me. How about:

Quoted 8 lines

Remove everything in body before a scissors line ("-- >8 --"). The line represents scissors and perforation marks, and is used to request the reader to cut the message at that line. If that line appears in the body of the message before the patch, everything before it (including the scissors line itself) is ignored when this option is used.

Etiquette question: Should a v2 patch be a new thread or reply to this one?

Typically you would reply to this thread, ie, to
[email protected]

Kevin

author
#6 lore raw

PATCH v2 1/1 Doc: specify exact scissors line

In reply to Evan Gates

The existing wording covers most of the requirements of a scissors line, but there is no mention of the minimum size requirement that led to a six character line ("-->8--") not counting as a scissors line. Specify the exact line to use ("-- >8 --") instead of trying to document all the details.

---
Changes in v2:
- Specify exact line instead of adding text about 8 character minimum

 Documentation/git-mailinfo.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
Documentation/git-mailinfo.txt +3 -4
index 3bbc731f67..fbb7d2813f 100644
@@ -72,10 +72,9 @@ conversion, even with this flag.
 	is useful in order to associate commits with mailing list discussions.
 
 --scissors::
-	Remove everything in body before a scissors line.  A line that
-	mainly consists of scissors (either ">8" or "8<") and perforation
-	(dash "-") marks is called a scissors line, and is used to request
-	the reader to cut the message at that line.  If such a line
+	Remove everything in body before a scissors line ("-- >8 --").
+	The line represents scissors and perforation marks, and is used to
+	request the reader to cut the message at that line.  If that line
 	appears in the body of the message before the patch, everything
 	before it (including the scissors line itself) is ignored when
 	this option is used.
Signature · 1 line
2.28.0
author
#7 lore raw

PATCH v3 1/1 Doc: show example scissors line

The text tries to say the code accepts many variations that look remotely like scissors and perforation marks, but gives too little detail for users to decide what is and what is not taken as a scissors line for themselves. Instead of describing the heuristics more, just spell out what will always be accepted, namely "-- >8 --", as it would not help users to give them more choices and flexibility and be "creative" in their scissors line.

---
Changes in v3:
- Reword commit message to better explain intent
- Add "e.g." to hint at other forms

Changes in v2:
- Specify exact line instead of adding text about 8 character minimum

 Documentation/git-mailinfo.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
Documentation/git-mailinfo.txt +3 -4
index 3bbc731f67..7a6aed0e30 100644
@@ -72,10 +72,9 @@ conversion, even with this flag.
 	is useful in order to associate commits with mailing list discussions.
 
 --scissors::
-	Remove everything in body before a scissors line.  A line that
-	mainly consists of scissors (either ">8" or "8<") and perforation
-	(dash "-") marks is called a scissors line, and is used to request
-	the reader to cut the message at that line.  If such a line
+	Remove everything in body before a scissors line (e.g. "-- >8 --").
+	The line represents scissors and perforation marks, and is used to
+	request the reader to cut the message at that line.  If that line
 	appears in the body of the message before the patch, everything
 	before it (including the scissors line itself) is ignored when
 	this option is used.
Signature · 1 line
2.28.0
#9 lore raw

Re: [PATCH v2] Doc: specify exact scissors line

In reply to Evan Gates
Quoted 5 lines · Evan Gates

The existing wording covers most of the requirements of a scissors line, but there is no mention of ...
...
Specify the exact line to use ("-- >8 --") instead of trying to document all the details.

s/most/some/;

For example, the code has fun heuristics to understand that things like "-- >8 ---- >8 -- cut here -- >8 ---- >8 --" is a scissors line, but we do not document it.

But what we agreed is that it is a bad idea to even attempt to describe the heuristics down to the details and sell the feature as "we accept anything that resembles a perforation drawn or printed on paper". Instead we are giving less choices to make it easier for users to follow, and the updated text is a move in that direction.

So selling this change based on "the existing description does not give enough" is not good.

The text tries to say the code accepts many variations that looks remotely like scissors and perforation line, but gives too little detail for users to decide what is and what is not taken as a scissors line for themselves. Instead of describing the heuristics more, just spell out what will always be accepted, namely "-- >8 --", as it would not help users to give them more choices and flexibility and be "creative" in their scissors line.

perhaps?

Quoted 13 lines

---
Changes in v2:
- Specify exact line instead of adding text about 8 character minimum

 Documentation/git-mailinfo.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
Documentation/git-mailinfo.txt +0 -0
index 3bbc731f67..fbb7d2813f 100644

Documentation/git-mailinfo.txt conversion, even with this flag. · line 77

Quoted 6 lines
Documentation/git-mailinfo.txt +3 -0
@@ -72,10 +72,9 @@ conversion, even with this flag.
 	is useful in order to associate commits with mailing list discussions.
 
 --scissors::
+	Remove everything in body before a scissors line ("-- >8 --").
+	The line represents scissors and perforation marks, and is used to
+	request the reader to cut the message at that line.  If that line

We want to say "e.g.", i.e. 'a scissors line (e.g. "-- >8 --")', in order to hint that we may accept other forms [*1*], and also to hint that we do not want to go int details.

Other than that, I like the conciseness of the updated text.

[Footnote]
*1* This is primarily to be friendly to left-handers to let them write "-- 8< --".