On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gits...@pobox.com> wrote:
> "Jason St. John" <jstj...@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 <jstj...@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 majord...@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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to