From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Mon, 06 Jun 2016 13:36:22 GMT
Subject: Re: [PATCH v3 1/3] doc: clearer rule about formatting literals
Message-ID: <vpqmvmyo2w9.fsf@anie.imag.fr>
In-Reply-To: <20160606100905.23006-2-tom.russello@grenoble-inp.org>

Tom Russello <tom.russello@grenoble-inp.org> writes:

> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -526,12 +526,13 @@ Writing Documentation:
>   modifying paragraphs or option/command explanations that contain options
>   or commands:
>  
> - Literal examples (e.g. use of command-line options, command names, and
> - configuration variables) are typeset in monospace, and if you can use
> - `backticks around word phrases`, do so.
> + Literal examples (e.g. use of command-line options, command names,
> + configuration and environment variables) must be typeset in monospace (i.e.
> + wrapped with backticks):
>     `--pretty=oneline`
>     `git rev-list`
>     `remote.pushDefault`
> +   `GIT_DIR`

Don't you want `$GIT_DIR` here?

>   Word phrases enclosed in `backtick characters` are rendered literally
>   and will not be further expanded. The use of `backticks` to achieve the

It might make sense to mention that they will appear bold in manpages
too.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/