[PATCH] Documentation: Fix inconsistent quotes

[PATCH] Documentation: Fix inconsistent quotes

[Stefan Tatschner]

While reading 'man git' I realized that the highlighting of the
environment variables is not consistent. This patch adds missing single
quotes and substitutes backticks with the proper quotes as well.

Signed-off-by: Stefan Tatschner <stefan@sevenbyte.org>
---
 Documentation/git.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 959c9d4..bb345a4 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -1000,7 +1000,7 @@ Unsetting the variable, or setting it to empty, "0" or
 	cloning of shallow repositories.
 	See 'GIT_TRACE' for available trace output options.
 
-GIT_LITERAL_PATHSPECS::
+'GIT_LITERAL_PATHSPECS'::
 	Setting this variable to `1` will cause Git to treat all
 	pathspecs literally, rather than as glob patterns. For example,
 	running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
@@ -1009,15 +1009,15 @@ GIT_LITERAL_PATHSPECS::
 	literal paths to Git (e.g., paths previously given to you by
 	`git ls-tree`, `--raw` diff output, etc).
 
-GIT_GLOB_PATHSPECS::
+'GIT_GLOB_PATHSPECS'::
 	Setting this variable to `1` will cause Git to treat all
 	pathspecs as glob patterns (aka "glob" magic).
 
-GIT_NOGLOB_PATHSPECS::
+'GIT_NOGLOB_PATHSPECS'::
 	Setting this variable to `1` will cause Git to treat all
 	pathspecs as literal (aka "literal" magic).
 
-GIT_ICASE_PATHSPECS::
+'GIT_ICASE_PATHSPECS'::
 	Setting this variable to `1` will cause Git to treat all
 	pathspecs as case-insensitive.
 
@@ -1031,7 +1031,7 @@ GIT_ICASE_PATHSPECS::
 	variable when it is invoked as the top level command by the
 	end user, to be recorded in the body of the reflog.
 
-`GIT_REF_PARANOIA`::
+'GIT_REF_PARANOIA'::
 	If set to `1`, include broken or badly named refs when iterating
 	over lists of refs. In a normal, non-corrupted repository, this
 	does nothing. However, enabling it may help git to detect and
-- 
2.3.7

Re: [PATCH] Documentation: Fix inconsistent quotes

[Jeff King]

On Wed, Apr 29, 2015 at 08:08:52PM +0200, Stefan Tatschner wrote:

> While reading 'man git' I realized that the highlighting of the
> environment variables is not consistent. This patch adds missing single
> quotes and substitutes backticks with the proper quotes as well.

I think this is OK in that it makes things consistent, and chooses the
style that is already in the majority.

But IMHO, using backticks looks much better. In the roff-formatted
manpages single quotes underline, but backticks use bold. The former is
hard to read when the content has underscores. For the HTML, the single
quotes produce italics, versus a typewriter font for backticks. Which
is...OK, I guess, but I think I like the backtick behavior better.

I think we're wildly inconsistent about this throughout the
documentation, though.

-Peff

Re: [PATCH] Documentation: Fix inconsistent quotes

[Jonathan Nieder]

Hi,

Jeff King wrote:

> But IMHO, using backticks looks much better. In the roff-formatted
> manpages single quotes underline, but backticks use bold.

Are you sure?  My copy of git.1.gz has backticks converted into no
formatting at all:

	Other options are available to control how the manual page is displayed\&. See
	\fBgit-help\fR(1)
	for more information, because
	git \-\-help \&.\&.\&.
	is converted internally into
	git help \&.\&.\&.\&.

Thanks,
Jonathan

Re: [PATCH] Documentation: Fix inconsistent quotes

[Jeff King]

On Wed, Apr 29, 2015 at 12:09:46PM -0700, Jonathan Nieder wrote:

> Hi,
> 
> Jeff King wrote:
> 
> > But IMHO, using backticks looks much better. In the roff-formatted
> > manpages single quotes underline, but backticks use bold.
> 
> Are you sure?  My copy of git.1.gz has backticks converted into no
> formatting at all:
> 
> 	Other options are available to control how the manual page is displayed\&. See
> 	\fBgit-help\fR(1)
> 	for more information, because
> 	git \-\-help \&.\&.\&.
> 	is converted internally into
> 	git help \&.\&.\&.\&.

It's actually optional. See 5121a6d (Documentation: option to render
literal text as bold for manpages, 2009-03-27). I don't see a good
reason that wasn't made the default early, except conservatism. I've had
it enabled for years (though I admit I don't read the manpages that much
these days :) ).

-Peff

Re: [PATCH] Documentation: Fix inconsistent quotes

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Apr 29, 2015 at 12:09:46PM -0700, Jonathan Nieder wrote:
>
>> Hi,
>> 
>> Jeff King wrote:
>> 
>> > But IMHO, using backticks looks much better. In the roff-formatted
>> > manpages single quotes underline, but backticks use bold.
>> 
>> Are you sure?  My copy of git.1.gz has backticks converted into no
>> formatting at all:
>> 
>> 	Other options are available to control how the manual page is displayed\&. See
>> 	\fBgit-help\fR(1)
>> 	for more information, because
>> 	git \-\-help \&.\&.\&.
>> 	is converted internally into
>> 	git help \&.\&.\&.\&.
>
> It's actually optional. See 5121a6d (Documentation: option to render
> literal text as bold for manpages, 2009-03-27). I don't see a good
> reason that wasn't made the default early, except conservatism. I've had
> it enabled for years (though I admit I don't read the manpages that much
> these days :) ).

Interesting.  What I happen to use when populating the git-manpages
repository would have wider impact to the users, as I hear that some
(or many) distros just package whatever I have there.  I do not mind
enabling it on my end if that gives us more readable rendition.

Re: [PATCH] Documentation: Fix inconsistent quotes

[Jeff King]

On Wed, Apr 29, 2015 at 01:13:53PM -0700, Junio C Hamano wrote:

> > It's actually optional. See 5121a6d (Documentation: option to render
> > literal text as bold for manpages, 2009-03-27). I don't see a good
> > reason that wasn't made the default early, except conservatism. I've had
> > it enabled for years (though I admit I don't read the manpages that much
> > these days :) ).
> 
> Interesting.  What I happen to use when populating the git-manpages
> repository would have wider impact to the users, as I hear that some
> (or many) distros just package whatever I have there.  I do not mind
> enabling it on my end if that gives us more readable rendition.

I think it's probably fine and a positive change, but one never knows. I
guess distros don't package what you ship until you actually tag a
release, so it would be OK to start doing so during a cycle to shake out
any problems (and in fact preferable, as anybody who follows "master"
using "make install-man-quick" would get it early and be able to make a
report).

If we are doing that, it would make sense to flip MAN_BOLD_LITERAL on by
default during that same cycle, so we could get reports from people who
build the manpages from source.

-Peff

Re: [PATCH] Documentation: Fix inconsistent quotes

[Stefan Tatschner]

On Wed, 2015-04-29 at 20:08 +0200, Stefan Tatschner wrote:
> While reading 'man git' I realized that the highlighting of the
> environment variables is not consistent. This patch adds missing 
> single
> quotes and substitutes backticks with the proper quotes as well.

Since currently there are some patches around which aim to improve the
documentation, may I ask about the status of this patch? Should I
improve/modify something, or is it actually not needed?

Thanks,
Stefan