Re: [PATCH 3/4] strbuf.h: format asciidoc code blocks as 4-space indent

From: Michael Haggerty <mhagger@alum.mit.edu>
Date: Dec 14, 2014, 17:42 UTC
Message-ID: <548DCC02.60100@alum.mit.edu>
In-Reply-To: <20141212223903.GE29365@google.com>

On 12/12/2014 11:39 PM, Jonathan Nieder wrote:

Show 15 quoted lines

> Jeff King wrote:
> 
>> This is much easier to read when the whole thing is stuffed
>> inside a comment block. And there is precedent for this
>> convention in markdown (and just in general ascii text).
>>
>> Signed-off-by: Jeff King <peff@peff.net>
>> ---
> 
> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
> 
>> As a side note, I actually find markdown much more pleasant to read and
>> write than asciidoc.
> 
> I do, too.  Quoting in asciidoc is a nightmare.

Peff, thanks for working on this. I think it is a definite improvement.

I suggest that we accept the use of asciidoc/markdown's convention of using backwards quotes to mark code snippets (especially identifier names) within comments *anywhere* in our code base. For example, this appears in refs.c:

    /*
     * Create a struct ref_entry object for the specified dirname.
     * dirname is the name of the directory with a trailing slash
     * (e.g., "refs/heads/") or "" for the top-level directory.
     */

I claim that it is more readable with a tiny bit of markup:

    /*
     * Create a `struct ref_entry` object for the specified `dirname`.
     * `dirname` is the name of the directory with a trailing slash
     * (e.g., "refs/heads/") or "" for the top-level directory.
     */

Marking up `struct ref_entry` helps make it clear that the two words belong together, and marking up `dirname` makes it clear that we are talking about a specific identifier (in this case, a function parameter).

Currently, comments use a mix of unadorned text, single-quoted text, and double-quoted text when talking about code. I think the asciidoc/markdown convention is clearer [1].

I think we shouldn't be pedantic about this. When a comment is readable with no markup, there's no need to add markup. And "incorrect" markup shouldn't by itself be reason to reject a patch. But in many examples, a little bit of markup makes the text less ambiguous and easier to read.

Michael

[1] Yes, I see the irony in trying to improve a mixture of three
    conventions by adding a fourth one.

-- 
Michael Haggerty
mhagger@alum.mit.edu