[PATCH] doc: reformat the paragraph containing the 'cut-line'

[PATCH] doc: reformat the paragraph containing the 'cut-line'

[Kaartic Sivaraam]

The paragraph that describes the 'scissors' cleanup mode of
'commit' had the 'cut-line' in the middle of a sentence. This
made it possible for the line to get wrapped on smaler windows.
This shouldn't be the case as it makes it hard for the user to
understand the structure of the cut-line.

Reformat the pragraph to make the 'cut-line' stand on a line of
it's own thus distinguishing it from the rest of the paragraph.
This further prevents it from getting wrapped to some extent.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/git-commit.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index afb06adba..2c0d48bab 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -196,11 +196,12 @@ whitespace::
 verbatim::
 	Do not change the message at all.
 scissors::
-	Same as `whitespace`, except that everything from (and
-	including) the line
-	"`# ------------------------ >8 ------------------------`"
-	is truncated if the message is to be edited. "`#`" can be
-	customized with core.commentChar.
+	Same as `whitespace` except that everything from (and including)
+    the line found below is truncated, if the message is to be edited.
+    "`#`" can be customized with core.commentChar.
+
+        # ------------------------ >8 ------------------------
+
 default::
 	Same as `strip` if the message is to be edited.
 	Otherwise `whitespace`.
-- 
2.13.3.973.gaaf39e6bd.dirty

Re: [PATCH] doc: reformat the paragraph containing the 'cut-line'

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> The paragraph that describes the 'scissors' cleanup mode of
> 'commit' had the 'cut-line' in the middle of a sentence. This
> made it possible for the line to get wrapped on smaler windows.
> This shouldn't be the case as it makes it hard for the user to
> understand the structure of the cut-line.
>
> Reformat the pragraph to make the 'cut-line' stand on a line of
> it's own thus distinguishing it from the rest of the paragraph.
> This further prevents it from getting wrapped to some extent.
>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Documentation/git-commit.txt | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index afb06adba..2c0d48bab 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -196,11 +196,12 @@ whitespace::
>  verbatim::
>  	Do not change the message at all.
>  scissors::
> -	Same as `whitespace`, except that everything from (and
> -	including) the line
> -	"`# ------------------------ >8 ------------------------`"
> -	is truncated if the message is to be edited. "`#`" can be
> -	customized with core.commentChar.
> +	Same as `whitespace` except that everything from (and including)
> +    the line found below is truncated, if the message is to be edited.
> +    "`#`" can be customized with core.commentChar.

Is there some funny indentation setting involved?  Why aren't these
lines aligning?

> +
> +        # ------------------------ >8 ------------------------
> +

Does an empty line before this one screw up the asciidoc formatting?

If the long line is problematic, I think it is safer to perhaps
spell it out, perhaps something like

	... except that everything is ignored down from the
	"scissors" line that begins with a core.commentChar (`#` by
	default) followed by many dashes `-`, followed by the
	scissors mark ` >8 `, followed by many dashes `-`.

???

>  default::
>  	Same as `strip` if the message is to be edited.
>  	Otherwise `whitespace`.

Re: [PATCH] doc: reformat the paragraph containing the 'cut-line'

[Kaartic Sivaraam]

On Mon, 2017-07-17 at 15:16 -0700, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
> > +	Same as `whitespace` except that everything from (and including)
> > +    the line found below is truncated, if the message is to be edited.
> > +    "`#`" can be customized with core.commentChar.
> 
> Is there some funny indentation setting involved?  Why aren't these
> lines aligning? 
> 
Yep, there was an indentation issue that I have fixed now.

> > +
> > +        # ------------------------ >8 ------------------------
> > +
> 
> 
> Does an empty line before this one screw up the asciidoc formatting?
> 
I think *no*. I build the docs with the change and didn't find anything
odd. 

> If the long line is problematic, I think it is safer to perhaps
> spell it out, perhaps something like
> 
> 	... except that everything is ignored down from the
> 	"scissors" line that begins with a core.commentChar (`#` by
> 	default) followed by many dashes `-`, followed by the
> 	scissors mark ` >8 `, followed by many dashes `-`.
> 
> ???
> 
I think it's better to keep the line as it is, considering the famous
cliché, "a picture is worth a thousand words" and combining it with the
fact that "humans looks for patterns in everything".

Spelling the line out would make it hard to get a *picture* of what's
trying to be described.

-- 
Kaartic

[PATCH] doc: reformat the paragraph containing the 'cut-line'

[Kaartic Sivaraam]

The paragraph that describes the 'scissors' cleanup mode of
'commit' had the 'cut-line' in the middle of a sentence. This
made it possible for the line to get wrapped on smaler windows.
This shouldn't be the case as it makes it hard for the user to
understand the structure of the cut-line.

Reformat the pragraph to make the 'cut-line' stand on a line of
it's own thus distinguishing it from the rest of the paragraph.
This further prevents it from getting wrapped to some extent.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/git-commit.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index afb06adba..8c74a2ca0 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -196,11 +196,12 @@ whitespace::
 verbatim::
 	Do not change the message at all.
 scissors::
-	Same as `whitespace`, except that everything from (and
-	including) the line
-	"`# ------------------------ >8 ------------------------`"
-	is truncated if the message is to be edited. "`#`" can be
-	customized with core.commentChar.
+	Same as `whitespace` except that everything from (and including)
+	the line found below is truncated, if the message is to be edited.
+	"`#`" can be customized with core.commentChar.
+
+		# ------------------------ >8 ------------------------
+
 default::
 	Same as `strip` if the message is to be edited.
 	Otherwise `whitespace`.
-- 
2.13.3.973.gaaf39e6bd.dirty