Subject: Re: bug#62958: [PATCH] Set PAGER=cat in comint.el

From: Spencer Baugh <[email-masked]>
Date: Tue, 16 May 2023 15:49:21 -0400

Eli Zaretskii <[email-masked]> writes:

>> From: Spencer Baugh <[email-masked]>
>> Cc: [email-masked],  [email-masked]
>> Date: Tue, 09 May 2023 13:13:56 -0400
>> 
>> Eli Zaretskii <[email-masked]> writes:
>> 
>> >> From: Spencer Baugh <[email-masked]>
>> >> Date: Tue, 9 May 2023 13:01:07 -0400
>> >> Cc: [email-masked], [email-masked]
>> >> 
>> >>  I'm asking why this is not already obvious from the fact that this is
>> >>  a defcustom, by default off.  All your addition says is "don't disable
>> >>  paging in all cases, sometimes it can be useful".  But we already said
>> >>  that, in effect, by making the paging enabled by default.  So there's
>> >>  no reason to have that text, as it isn't instrumental, and doesn't add
>> >>  anything.
>> >> 
>> >> How does "this is a defcustom, by default off" communicate "you should use vc-print-log if you turn this
>> >> on"?
>> >
>> > Why are we suddenly talking about vc-print-log when discussing a much
>> > more general feature?
>> 
>> Because disabling pagination effectively breaks the shell command "git
>> log" and vc-print-log is one alternative to running "git log", and I
>> don't know how else the user would realize that.  (In my experience with
>> talking to users about this, they usually don't)
>
> A doc string of a general option is not the proper place for talking
> about some very specific case when that option is used.  If the main
> problem is vc-print-log, we should find another way of dealing with
> it.

OK, how about this doc string?

  "If non-nil, the program to use for pagination of program output.

Some programs produce large amounts of output, and have provision for
pagination of their output through a filter program, commonly known as
a \"pager\".  The pager limits the amount of output produced and
allows the user to interactively browse the output one page at a time.
Some programs paginate their output by default, by always starting a
pager.  The program they use as the pager is specified by the
environment variable PAGER; if that variable is not defined, they use
some fixed default, such as \"less\".

The interactive browsing aspects of pagination are not needed, and get
in the way, when the output of the program is directed to an Emacs
buffer, so in those cases pagination might need to be disabled.
Disabling pagination means that some programs will produce large
amounts of output, but most such programs have other ways to limit
their output, such as additional arguments or Emacs interfaces.
To disable pagination, this variable's value should be a string that
names a program, such as \"cat\", which passes through all of the
output without any filtering or delays.  Comint will then set the
PAGER variable to name that program, when it invokes external
programs."