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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 13, 2013, 21:56 UTC
Message-ID: <xmqqy54sc6ev.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1384323709-2690-2-git-send-email-jstjohn@purdue.edu>

"Jason St. John" <jstjohn@purdue.edu> writes:

Show 18 quoted lines

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