Re: [RFC/PATCH] Formatting variables in the documentation

[Jeff King <peff@peff.net>]

On Wed, May 18, 2016 at 05:58:29PM +0200, Tom Russello wrote:

> There is no agreement on this topic (the CodingGuidelines does not
> mention it), it would be better if everyone follows the same rule: put
> each environment variable in monospace style and write this rule in
> the guide.
> 
> It is a good thing to have a consistent documentation however it
> will be painful to change with a simple regex all occurences
> (especially environment variables without any format) because some of
> them are in paths or code section.
> 
> What do you think ?

Personally, I like the "literal" backticks versus the "emphasis"
single-quotes. But you should keep in mind how they are rendered in the
manpages, which is as "nothing" and "underline", respectively (by
default, anyway). So I think some people are negative on using backticks
for that reason.

I also turn on the MAN_BOLD_LITERAL knob, which turns that "nothing"
into "bold", and the result looks quite nice. But there is some
compatibility question of whether that can be used everywhere.

Here's the most recent discussion I could find:

  http://thread.gmane.org/gmane.comp.version-control.git/281170

which talks about the issue and references an earlier discussion (which
I didn't re-read). But you probably need to address the concerns there
before moving forward with a patch like this.

-Peff