bug#74630: 31.0.50; emacs-mail-verify

bug#74630: 31.0.50; emacs-mail-verify

[Richard Stallman]

The doc string of `emacs-mail-verify' does not say how it
indicates that the signature is valid, or how it indicates
that the signature is not valid.

Would someone please add that to its doc string?


In GNU Emacs 31.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 2.24.33, cairo version 1.16.0) of 2024-08-01 built on freetop
Repository revision: a2c439db687774f7b57959c39560993579c5d1bd
Repository branch: master
System Description: Trisquel GNU/Linux Aramo (11.0)

Configured using:
 'configure 'CFLAGS=-O0 -g' --with-gnutls=ifavailable'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GPM GSETTINGS HARFBUZZ JPEG LIBOTF
LIBSELINUX LIBXML2 M17N_FLT MODULES NOTIFY INOTIFY PDUMPER PNG RSVG
SECCOMP SOUND THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM XINPUT2
XPM GTK2 ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: ELisp/l

Minor modes in effect:
  bug-reference-prog-mode: t
  gpm-mouse-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  minibuffer-regexp-mode: t
  line-number-mode: t
  transient-mark-mode: t
  auto-composition-mode: linux
  auto-encryption-mode: t
  auto-compression-mode: t
  abbrev-mode: t

Load-path shadows:
None found.

Features:
(shadow emacsbug epa-file vc-git diff-mode track-changes easy-mmode
vc-dispatcher bug-reference find-func shortdoc comp-common rx apropos
rmail-spam-filter rmailedit rmailsort undigest help-fns radix-tree
rect jka-compr display-line-numbers novice mule-util cal-move cal-menu
calendar cal-loaddefs mail-extr ffap quail epa-mail etags fileloop
generator xref project rmailkwd cl-extra help-mode shell pcomplete
thingatpt files-x grep compile comint ansi-osc ansi-color ring dabbrev
ispell rmailout mailalias misearch multi-isearch textsec uni-scripts
idna-mapping ucs-normalize uni-confusable textsec-check shr pixel-fill
kinsoku url-file svg xml dom qp rmailmm message sendmail yank-media
puny rfc822 mml mml-sec epa epg epg-config gnus-util
text-property-search time-date mm-decode mm-bodies mm-encode
mailabbrev gmm-utils mailheader mail-parse rfc2231 dired-aux dired
dired-loaddefs t-mouse term/linux view derived disp-table advice
rmailsum rmail rfc6068 rfc2047 rfc2045 ietf-drums mm-util mail-prsvr
mail-utils finder-inf info osm-autoloads package browse-url url
url-proxy url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util mailcap url-handlers url-parse
auth-source cl-seq eieio eieio-core cl-macs icons password-cache json
subr-x map byte-opt gv bytecomp byte-compile url-vars cl-loaddefs
cl-lib rmc iso-transl tooltip cconv eldoc paren electric uniquify
ediff-hook vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd touch-screen tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode
lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch
easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer nadvice seq simple
cl-generic indonesian philippine cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button
loaddefs theme-loaddefs faces cus-face macroexp files window
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget keymap hashtable-print-readable backquote threads
dbusbind inotify dynamic-setting system-font-setting
font-render-setting cairo gtk x-toolkit xinput2 x multi-tty
move-toolbar make-network-process emacs)

Memory information:
((conses 16 622712 118122) (symbols 48 15101 10)
 (strings 32 79308 9073) (string-bytes 1 1459899) (vectors 16 57657)
 (vector-slots 8 1411286 252804) (floats 8 142 345)
 (intervals 56 69856 759) (buffers 984 77))
[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#74630: 31.0.50; emacs-mail-verify

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 01 Dec 2024 00:39:00 -0500
> 
> 
> The doc string of `emacs-mail-verify' does not say how it
> indicates that the signature is valid, or how it indicates
> that the signature is not valid.

I guess you meant epa-mail-verify?

> Would someone please add that to its doc string?

Not sure what you expected the doc string to say.  Would the below be
enough?

  Verify OpenPGP cleartext signed messages in the current buffer.
  The buffer is expected to contain a mail message.

  If the verification fails, the command signals an error.

The last sentence describes the following snippet from
epa-verify-region, which epa-mail-verify calls:

    (unless (epg-context-result-for context 'verify)
      (error "Unable to verify region"))

There are also other reasons to signal an error, e.g. if there are no
"-----BEGIN PGP SIGNED MESSAGE-----" line.  But eventually, all of the
problems cause an error.

If this is somehow not detailed enough, then I'm afraid someone else,
who knows the code, will have to improve the doc string, because I
could see no clear description in the code what values could the
context-result have and what is the meaning of each result.  Maybe I
missed something.

bug#74630: 31.0.50; emacs-mail-verify

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I guess you meant epa-mail-verify?

Oops, yes.

  > Not sure what you expected the doc string to say.  Would the below be
  > enough?

  >   Verify OpenPGP cleartext signed messages in the current buffer.
  >   The buffer is expected to contain a mail message.

  >   If the verification fails, the command signals an error.

That is better, becauee it gives enough information to deduce what
indicates success.  But the user should need to do any deduction about
that, let alone read code and guess what some other functions do.

To make the doc string truly clear, it should say explicitly what
indicates success.  That way the user can know, rather than just
supposing.

Should the function be changed to display a message, "Signature verified",
on success?

Do some people run this function from a hook for every message and
want to see output only in case of failure?

Should it a value indicating success or failure?


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#74630: 31.0.50; emacs-mail-verify

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: 74630@debbugs.gnu.org
> Date: Wed, 04 Dec 2024 01:09:05 -0500
> 
>   > Not sure what you expected the doc string to say.  Would the below be
>   > enough?
> 
>   >   Verify OpenPGP cleartext signed messages in the current buffer.
>   >   The buffer is expected to contain a mail message.
> 
>   >   If the verification fails, the command signals an error.
> 
> That is better, becauee it gives enough information to deduce what
> indicates success.  But the user should need to do any deduction about
> that, let alone read code and guess what some other functions do.

Thanks, I installed a change along those lines.

> To make the doc string truly clear, it should say explicitly what
> indicates success.  That way the user can know, rather than just
> supposing.

I don't know how to describe success in this case, except as the lack
of an error.

> Should the function be changed to display a message, "Signature verified",
> on success?

It says "Verifying...done", which I think is enough (and quite
standard in Emacs).

> Do some people run this function from a hook for every message and
> want to see output only in case of failure?

See above: it displays a message in case of success as well.

> Should it a value indicating success or failure?

I don't know.  The values of the relevant functions don't seem to be
documented.

bug#74630: 31.0.50; emacs-mail-verify

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Do some people run this function from a hook for every message and
  > > want to see output only in case of failure?

  > See above: it displays a message in case of success as well.

I agree, that should be enough.
(I didn't know it did that.)

Perhaps document that in the doc string:

  On successful verification, displays ""Verifying...done" in echo area.

Perhaps it should return t if it succeeds in verifying, and nil otherwise.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#74630: 31.0.50; emacs-mail-verify

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: 74630@debbugs.gnu.org
> Date: Fri, 20 Dec 2024 00:23:00 -0500
> 
>   > > Do some people run this function from a hook for every message and
>   > > want to see output only in case of failure?
> 
>   > See above: it displays a message in case of success as well.
> 
> I agree, that should be enough.
> (I didn't know it did that.)
> 
> Perhaps document that in the doc string:
> 
>   On successful verification, displays ""Verifying...done" in echo area.

That sounds redundant, as the message seems to speak for itself?

> Perhaps it should return t if it succeeds in verifying, and nil otherwise.

I thought about it, but the functions it calls don't have their return
value documented, so doing that seems to require a serious surgery of
the code with which I'm not familiar.