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

From: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
Date: Jul 18, 2017, 14:29 UTC
Message-ID: <1500388168.2065.2.camel@gmail.com>
In-Reply-To: <xmqqefteg155.fsf@gitster.mtv.corp.google.com>

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