git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Jonathan Nieder" <jrnieder@gmail.com>,
	git@vger.kernel.org,
	"Felipe Contreras" <felipe.contreras@gmail.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: Re: [PATCH] doc: explain the use of color.pager
Date: Thu, 20 May 2021 04:33:56 -0400	[thread overview]
Message-ID: <YKYe9PZbTO1CyBOp@coredump.intra.peff.net> (raw)
In-Reply-To: <xmqq5yzdvrlg.fsf@gitster.g>

On Thu, May 20, 2021 at 03:36:59PM +0900, Junio C Hamano wrote:

> > More importantly, I think I'd find a
> > reference to the commit or a quotation from the affected user more
> > helpful than a reference to the mailing list archive, since that would
> > make this a bit more self-contained.
> 
> The original commit and its log message we ended up with did not
> explain the motivation behind well enough.
> 
> The motivation from the original thread:
> 
>       When I use a pager that escapes the escape character or highlights the
>       content itself the output of git diff without the pager should have
>       colors but not with the pager.  For example using git diff with a
>       pathspec is quite short most of the time.  For git diff I have to
>       enable paging manually and run git diff | $PAGER usually but git log
>       uses the pager automatically and should not use colors with it.
> 
> can be quoted as a whole, but "the point is to deal with ..." is a
> succinct summary that is good enough for the purpose of this commit,
> I would think.

Thanks, I was just preparing a near-identical response.

I do think it's an important principle in general to summarize the
content of things we link to. It's just that the summary in this case
was so short that it was easy to look past. :)

> > If I understood correctly, how about some text like the following?
> >
> > 	A boolean to specify whether `auto` color modes should colorize
> > 	output going to a pager, in addition to their behavior of
> > 	colorizing output going to a terminal. Defaults to true; [etc]
> 
> The variable has no control over what happens to output that
> directly goes to a terminal, so while the additional phrase might
> not be technically wrong per-se, I do not see why this is more clear
> than the original.

Unsurprisingly, that's my opinion, too. While writing it, I actually did
try some longer explanations to explain from the ground up, but I
worried it was distracting from the main point of this variable. E.g.,
something like:

  When color mode options (e.g., `color.ui`) are set to `auto`, Git by
  default will enable color when the output is going to a terminal or to
  a pager (since the pager itself is outputting to a terminal). This is
  a problem if your pager doesn't faithfully relay the color codes to
  the terminal. You can set this boolean to `false` to disable color
  when output is going to a terminal.

> So, in short, I think it would be sufficient to amend the proposed
> log message with s/deal with/to deal with/ and nothing else.

I'm happy with that.

-Peff

  reply	other threads:[~2021-05-20  8:33 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-19  9:17 Jeff King
2021-05-19 10:41 ` Felipe Contreras
2021-05-19 19:53 ` Jonathan Nieder
2021-05-19 20:39   ` Felipe Contreras
2021-05-19 22:47   ` Junio C Hamano
2021-05-20  6:36   ` Junio C Hamano
2021-05-20  8:33     ` Jeff King [this message]
2021-05-20 15:05       ` Jonathan Nieder

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YKYe9PZbTO1CyBOp@coredump.intra.peff.net \
    --to=peff@peff.net \
    --cc=avarab@gmail.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jrnieder@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).