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

Matthieu Moy [off-list ref] writes:

Tom Russello [off-list ref] writes:

quoted

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

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.