Re: [PATCH] State correct usage of backticks for options in man pages in the coding guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 13, 2013, 17:21 UTC
Message-ID: <xmqq61rwfc9p.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1384316501-27965-1-git-send-email-jstjohn@purdue.edu>

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

> + Backticks are used around options or commands:
> +   `--pretty=oneline`
> +   `git rev-list`

I'd prefer to see the objective stated before a particular means to achieve it. I.e. not "backticks around options and commands", but "literal examples (e.g. use of command line options, command names and configuration variables) are typeset monospaced, and if you can use `backticks around word phrase`, do so.".

Show 5 quoted lines

> + Options or commands should use unescaped AsciiDoc:
> +   Correct:
> +      `--pretty=oneline`
> +   Incorrect:
> +      `\--pretty=oneline`

I think it is wrong to single out "options or commands" here, and also it is wrong to say "unescaped". The "unescaped" is merely a consequence of combination between:

http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html#_text_formatting

    Word phrases `enclosed in backtick characters` (grave accents)
    are also rendered in a monospaced font but in this case the
    enclosed text is rendered literally and is not subject to
    further expansion.

and the use of `backticks` to achieve "literal examples are typeset monospaced" rule.

If some place in the documentation needs to typeset a command use example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with the former, we do need to quote the part we do not want to get substituted.

Thanks.