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

[Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>]

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

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