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

> "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