threads / patch / 46407

patchdoc: reformat the paragraph containing the 'cut-line'

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

## tl;dr

4 messages between Jul 17, 2017 and Jul 18, 2017. Diffs are folded; open one to read it.

replies: 3people: 2as markdown or json

Kaartic Sivaraam· Jul 17, 2017, 15:38 UTC · lore

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(-)
Show changes to Documentation/git-commit.txt +6 −5
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
Junio C Hamano· Jul 17, 2017, 22:16 UTC · re: Kaartic Sivaraam · lore

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

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
Show 31 quoted lines
> 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`.
Kaartic Sivaraam· Jul 18, 2017, 14:29 UTC · re: Junio C Hamano · lore

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

On Mon, 2017-07-17 at 15:16 -0700, Junio C Hamano wrote:
Show 8 quoted lines
> 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.
Show 7 quoted lines
> > +
> > +        # ------------------------ >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.

Show 10 quoted lines
> 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
Kaartic Sivaraam· Jul 18, 2017, 14:34 UTC · re: Kaartic Sivaraam · lore

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(-)
Show changes to Documentation/git-commit.txt +6 −5
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

← back to recent threads