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

From: Jeff King <peff@peff.net>
Date: May 18, 2016, 18:15 UTC
Message-ID: <20160518181500.GD5796@sigill.intra.peff.net>
In-Reply-To: <1463587109-22476-1-git-send-email-tom.russello@grenoble-inp.org>

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

Show 11 quoted lines

> 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