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

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