Re: [PATCH 2/2] Fix minor grammatical and other formatting issues in the "git log" man page

> On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> "Jason St. John" <jstjohn@purdue.edu> writes:
>>
>>> Documentation/git-log.txt:
>>> -- replace single quotes around options/commands with backticks
>>> -- use single quotes around references to sections
>>> -- replaced some double quotes with proper AsciiDoc quotes (e.g.
>>>      ``foo'')
>>> -- use backticks around files and file paths
>>> -- use title case when referring to section headings
>>> -- use backticks around option arguments/defaults
>>>
>>> Signed-off-by: Jason St. John <jstjohn@purdue.edu>
>>> ---
>>> When working on this commit, I noticed a difference in how options and
>>> option descriptions are separated (e.g. with a blank line or not). At least
>>> with Vim's syntax highlighting, if there is a blank line between the option
>>> and its description, the text block is all colored the same; however, if
>>> there isn't a blank line, then the text block is not specially colored.
>>>
>>> Is there an existing convention for how this should be done?
>>
>> I do not think we have a written rule or convention (and I do not
>> know if we want one).  While reading the text in the source form
>> (and the point of choosing AsciiDoc was to be able to read the docs
>> without formatting), I personally have a slight preference to
>> immediately follow the body text to the label in the labelled list,
>> and a blank line after the item, i.e.
>>
>>         item label::
>>                 This describes the item.
>>
>>         next item label::
>>                 This describes the next item.
>>
>> as it makes it clear that the body belongs to the heading that
>> precedes it.
>>
>> But it does help to have a blank between the label and the beginning
>> of the body when reflowing the body with fill-paragraph, i.e.
>>
>>         item label::
>>
>>                 This describes the item.
>>
>> You say that it is also easier on Vim to have the blank line there,
>> so perhaps we may want to aim for updating the documentation over
>> time to consistently do so.  I dunno.
>> --
>> To unsubscribe from this list: send the line "unsubscribe git" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
> As I stated in my recent resubmit[1], I decided to remove the blank
> lines after option subheadings because the syntax highlighting in Vim
> actually looks better with the blank lines removed. As such, I would
> prefer that we go with the option of removing these blank lines going
> forward.
>
> If we are in agreement on this, should I send in a patch for
> CodingGuidelines to state this?
>
> [1] http://marc.info/?l=git&m=138447927208462&w=2