From: Tom Russello Date: Mon, 06 Jun 2016 15:38:09 GMT Subject: Re: [PATCH v3 1/3] doc: clearer rule about formatting literals Message-ID: In-Reply-To: On 06/06/16 15:42, Matthieu Moy wrote: > Matthieu Moy writes: > >> Tom Russello 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. > 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.