# [PATCH] Documentation: Fix inconsistent quotes 7 messages from 2015-04-29 to 2015-05-14. Participants: Stefan Tatschner, Jeff King, Jonathan Nieder, Junio C Hamano. Thread: https://gitlist.dev/t/39184 ## Stefan Tatschner, 2015-04-29 18:08 Subject: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <1430330932-10578-1-git-send-email-stefan@sevenbyte.org> URL: https://gitlist.dev/e/1430330932-10578-1-git-send-email-stefan%40sevenbyte.org ``` 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 --- 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 ``` ## Jeff King, 2015-04-29 18:51 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <20150429185141.GA32207@peff.net> URL: https://gitlist.dev/e/20150429185141.GA32207%40peff.net In-Reply-To: <1430330932-10578-1-git-send-email-stefan@sevenbyte.org> ``` 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, 2015-04-29 19:09 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <20150429190946.GQ5467@google.com> URL: https://gitlist.dev/e/20150429190946.GQ5467%40google.com In-Reply-To: <20150429185141.GA32207@peff.net> ``` 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, 2015-04-29 20:04 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <20150429200453.GA750@peff.net> URL: https://gitlist.dev/e/20150429200453.GA750%40peff.net In-Reply-To: <20150429190946.GQ5467@google.com> ``` 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 ``` ## Junio C Hamano, 2015-04-29 20:13 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: URL: https://gitlist.dev/e/xmqqpp6m4rr2.fsf%40gitster.dls.corp.google.com In-Reply-To: <20150429200453.GA750@peff.net> ``` Jeff King 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. ``` ## Jeff King, 2015-04-29 20:32 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <20150429203247.GA1685@peff.net> URL: https://gitlist.dev/e/20150429203247.GA1685%40peff.net In-Reply-To: ``` 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 ``` ## Stefan Tatschner, 2015-05-14 09:14 Subject: Re: [PATCH] Documentation: Fix inconsistent quotes Message-ID: <1431594857.15159.4.camel@sevenbyte.org> URL: https://gitlist.dev/e/1431594857.15159.4.camel%40sevenbyte.org In-Reply-To: <1430330932-10578-1-git-send-email-stefan@sevenbyte.org> ``` 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 ```