On Thu, Nov 14, 2013 at 8:44 PM, Jason St. John <jstjohn@xxxxxxxxxx> wrote: > 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 I forgot to mention that if we do go with this, then I will need to resubmit this patch. Sorry for the extra email. -- 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