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

From: Tom Russello <tom.russello@grenoble-inp.org>
Date: Jun 6, 2016, 15:38 UTC
Message-ID: <c31c7d1c-fac9-45f6-b53c-842cab16eacb@grenoble-inp.org>
In-Reply-To: <vpq8tyio2lu.fsf@anie.imag.fr>

On 06/06/16 15:42, Matthieu Moy wrote:

Show 12 quoted lines

> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> 
>> Tom Russello <tom.russello@grenoble-inp.org> writes:
>>> + 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?

No, I didn't as we can find both of them in the documentation and because there is no guideline about this.

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

I think this is the more intuitive solution as well.

Show 8 quoted lines

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

Ok, I add this to the CodingGuidelines file.