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

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

Matthieu Moy [off-list ref] writes:

quoted

Tom Russello [off-list ref] writes:

quoted

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

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.