public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Junio C Hamano <gitster@pobox•com>
To: "Jason St. John" <jstjohn@purdue•edu>
Cc: git@vger•kernel.org
Subject: Re: [PATCH] State correct usage of backticks for options in man pages in the coding guidelines
Date: Wed, 13 Nov 2013 09:21:38 -0800	[thread overview]
Message-ID: <xmqq61rwfc9p.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <1384316501-27965-1-git-send-email-jstjohn@purdue.edu> (Jason St. John's message of "Tue, 12 Nov 2013 23:21:41 -0500")

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

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

     prev parent reply	other threads:[~2013-11-13 17:21 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2013-11-13  4:21 [PATCH] State correct usage of backticks for options in man pages in the coding guidelines Jason St. John
2013-11-13 10:04 ` Ramkumar Ramachandra
2013-11-13 17:21 ` Junio C Hamano [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqq61rwfc9p.fsf@gitster.dls.corp.google.com \
    --to=gitster@pobox$(echo .)com \
    --cc=git@vger$(echo .)kernel.org \
    --cc=jstjohn@purdue$(echo .)edu \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox