On Wed, Nov 13, 2013 at 4:56 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > "Jason St. John" <jstjohn@xxxxxxxxxx> 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@xxxxxxxxxx> >> --- >> 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@xxxxxxxxxxxxxxx > 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 majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html