threads / patch / 39184

patchDocumentation: Fix inconsistent quotes

Subject: [PATCH] Documentation: Fix inconsistent quotes

## tl;dr

7 messages between Apr 29, 2015 and May 14, 2015. Diffs are folded; open one to read it.

replies: 6people: 4as markdown or json

Stefan Tatschner· Apr 29, 2015, 18:08 UTC · lore

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(-)
Show changes to Documentation/git.txt +5 −5
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
Jeff King· Apr 29, 2015, 18:51 UTC · re: Stefan Tatschner · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

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
Jonathan Nieder· Apr 29, 2015, 19:09 UTC · re: Jeff King · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

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

Jeff King· Apr 29, 2015, 20:04 UTC · re: Jonathan Nieder · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

On Wed, Apr 29, 2015 at 12:09:46PM -0700, Jonathan Nieder wrote:
Show 16 quoted lines
> 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
Junio C Hamano· Apr 29, 2015, 20:13 UTC · re: Jeff King · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

Jeff King <peff@peff.net> writes:
Show 24 quoted lines
> 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.

Jeff King· Apr 29, 2015, 20:32 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

On Wed, Apr 29, 2015 at 01:13:53PM -0700, Junio C Hamano wrote:
Show 10 quoted lines
> > 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
Stefan Tatschner· May 14, 2015, 09:14 UTC · re: Stefan Tatschner · lore

Re: [PATCH] Documentation: Fix inconsistent quotes

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

← back to recent threads