Re: [PATCH v3 1/3] doc: clearer rule about formatting literals

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Jun 6, 2016, 13:42 UTC
Message-ID: <vpq8tyio2lu.fsf@anie.imag.fr>
In-Reply-To: <vpqmvmyo2w9.fsf@anie.imag.fr>

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

Show 20 quoted lines

> 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?

Actually, not really. The use (which seems rather consistant) is to say "The `GIT_...` environment variable" when referring to the variable, and to use $GIT_... when referring to its value, like in "`$GIT_DIR/hooks` directory".

It makes sense since not all systems use $ (AFAIK, Windows uses %variable% where POSIX uses $variable), so it's best to use a neutral syntax when possible. OTOH, writting `GIT_DIR/hooks` without the $ would be really confusing as one could read it as the literal string `GIT_DIR`.

I think this rule (when to use $ and when not to use it) deserves to be clarified here too.

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