Subject: bug#32064: closed (Re: bug#32064: 26; doc string of `eval-last-sexp')

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 06 Jul 2018 09:38:02 +0000

Your bug report

#32064: 26; doc string of `eval-last-sexp'

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
32064: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=32064
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#32064: 26; doc string of `eval-last-sexp'
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>
Cc: [email-masked]
Date: Fri, 06 Jul 2018 12:37:33 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Thu, 5 Jul 2018 14:56:48 -0700 (PDT)
> From: Drew Adams <[email-masked]>
> 
> Looking at `eval-expression-get-print-arguments' and the doc string for `eval-expression', things are a bit clearer.  At least please incorporate something like what is said for `eval-expression' in the doc of `eval-last-sexp'. 

I preferred to fix eval-last-sexp in a somewhat different way.

> But even the `eval-expression' doc is not very good for the description of CHAR-PRINT-LIMIT.  It's not true that "unless given a positive prefix argument" a number value is printed in several... Try a prefix arg of -9, for instance.

Right, fixed.

> The doc of `eval-expression-get-print-arguments' says that it determines the prefix-arg behavior for `eval-last-sexp'.  Is that true?

Yes, AFAICT.

> The doc of `eval-expression-get-print-arguments' needs to specify the logic of what it does, and that info needs to be included in the doc of `eval-expression' and (if appropriate) the doc of `eval-last-sexp'.  Or at least their doc needs to point to such info.

I see no reason to point to eval-expression-get-print-arguments in the
doc string of eval-last-sexp.  If someone reads the code of
eval-last-sexp, they will see the call, and will look up the function.

> The doc string for `eval-expression-print-format' is not great either.  It says only what the result will "typically" look like.  It needs to specify what formats it outputs, under what conditions.

I don't see the need, as the code is quite self-describing.

> And the various doc strings seem to suggest that the handling of the last arg, CHAR-PRINT-LIMIT by `eval-exprresion' is different from its handling by `eval-last-sexp'.  But is that true?

No, it is not true.  Fixed.

I'm closing the bug, thanks for pointing out these blunders.

Subject: 26; doc string of `eval-last-sexp'
From: Drew Adams <[email-masked]>
To: [email-masked]
Date: Thu, 5 Jul 2018 13:15:16 -0700 (PDT)
List-Id: <debbugs-submit.debbugs.gnu.org>

The doc string was messed up a bit in Emacs 26, apparently for the fix
of bug #4118.

>From this, which makes sense:

 Normally, this function truncates long output according to the value
 of the variables `eval-expression-print-length' and
 `eval-expression-print-level'.  With a prefix argument of zero,
 however, there is no such truncation.  Such a prefix argument
 also causes integers to be printed in several additional formats
 (octal, hexadecimal, and character).

The text was changed to this, which does not make sense at all:

 Normally, this function truncates long output according to the
 value of the variables 'eval-expression-print-length' and
 'eval-expression-print-level'.  With a prefix argument of zero,
 however, there is no such truncation.  Such a prefix argument
 also causes integers to be printed in several additional formats
 (octal, hexadecimal, and character when the prefix argument is
 -1 or the integer is 'eval-expression-print-maximum-character' or
 less).

Both old and new say that with a prefix arg of ZERO ("such a prefix
argument") the behavior is to do both of these things:

1. Do not truncate.
2. Print in additional formats.

That's fine. But the Emacs 26+ version also says that with a ZERO prefix
arg ("such a prefix argument"), if the prefix arg is ALSO -1
(impossible) or if "the integer" (what integer?) is less than or equal
to the value of `eval-expression-print-maximum-character', the
additional formats include "character".

A character is not a format, so it's unclear what printing in format
"character" means.

But the main problem with this is that it makes us try to understand a
prefix arg that is BOTH zero and -1, and it leaves us wondering what
"the integer" is that is tested against
`eval-expression-print-maximum-character' when the prefix arg is zero.

If "the integer" is just the numeric prefix arg then the <=
`eval-expression-print-maximum-character' could be clear - but there
should be no connection with the value being zero ("such a prefix arg").
Just say: If zero then no truncation.  If <= `eval...' then ___
(whatever is meant by "character format" printing).

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''