GNU bug report logs - #56974
29.0.50; Missing documentation for former subr-x macros

Previous Next

To reply to this bug, email your comments to 56974 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; Missing documentation for former subr-x macros
Date: Thu, 04 Aug 2022 13:06:20 +0000

As far as I see, if-let, when-let, thread-first, ... were moved from
subr-x.el to subr.el last April (b05a103e).  But there appears to be no
documentation in (I'd assume) lispref/controls.texi.  My understanding
was that these macros were not documented in the Elisp manual as they
were just part of subr-x, as the comment in the subr-x header indicates

    ;; Do not document these functions in the lispref.
    ;; https://lists.gnu.org/r/emacs-devel/2014-01/msg01006.html

So should they be documented now?


In GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.34, cairo version 1.17.6)
 of 2022-08-01 built on rhea
Repository revision: 47f1cae83c269ea43d6b208e055ce536c017856f
Repository branch: feature/package+vc
System Description: Fedora Linux 36 (Workstation Edition)

Configured using:
 'configure --with-pgtk --with-native-compilation --with-imagemagick'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ IMAGEMAGICK
JPEG JSON LIBSELINUX LIBSYSTEMD LIBXML2 MODULES NATIVE_COMP NOTIFY
INOTIFY PDUMPER PGTK PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS XIM GTK3 ZLIB

Important settings:
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Texinfo/P

Minor modes in effect:
  gtags-mode: t
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  auto-revert-mode: t
  bug-reference-prog-mode: t
  TeX-PDF-mode: t
  shell-dirtrack-mode: t
  flyspell-mode: t
  repeat-mode: t
  diff-hl-flydiff-mode: t
  winner-mode: t
  windmove-mode: t
  corfu-history-mode: t
  vertico-multiform-mode: t
  vertico-mode: t
  electric-pair-mode: t
  recentf-mode: t
  save-place-mode: t
  savehist-mode: t
  xterm-mouse-mode: t
  pixel-scroll-precision-mode: t
  pixel-scroll-mode: t
  display-time-mode: t
  display-battery-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tab-bar-mode: t
  file-name-shadow-mode: t
  context-menu-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  line-number-mode: t
  auto-fill-function: do-auto-fill
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  auto-save-visited-mode: t

Load-path shadows:
/home/philip/.config/emacs/elpa/transient-0.3.7/transient hides /home/philip/Source/emacs/lisp/transient
~/.config/emacs/site-lisp/autoload hides /home/philip/Source/emacs/lisp/emacs-lisp/autoload
/home/philip/Source/emacs/lisp/ps-def hides /home/philip/Source/emacs/lisp/obsolete/ps-def

Features:
(shadow skeleton two-column grep tramp-archive tramp-gvfs tramp-cache
zeroconf tramp tramp-loaddefs trampver tramp-integration tramp-compat
ls-lisp dcl-mode tempo consult-imenu markdown-mode etags fileloop
generator gtags-mode tar-mode arc-mode archive-mode macrostep
alect-black-alt-theme alect-light-theme alect-light-alt-theme
alect-dark-theme alect-dark-alt-theme cus-theme ert alect-themes
alect-themes-autoloads files-x gtags-mode-autoloads html2text package-x
flymake-cc edebug reposition shortdoc delsel pulse cus-edit ctrlf
hl-line ctrlf-autoloads package-vc xref ffap vertico-buffer
consult-vertico consult-icomplete consult compat-28 magit-bookmark
bookmark pp vc-hg vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs goto-addr
mailalias smtpmail autocrypt-message ecomplete view emacsbug
magit-extras face-remap magit-submodule magit-obsolete magit-blame
magit-stash magit-reflog magit-bisect magit-push magit-pull magit-fetch
magit-clone magit-remote magit-commit magit-sequence magit-notes
magit-worktree magit-tag magit-merge magit-branch magit-reset
magit-files magit-refs magit-status magit magit-repos magit-apply
magit-wip magit-log which-func magit-diff git-commit magit-core
magit-autorevert autorevert filenotify magit-margin magit-transient
magit-process with-editor server magit-mode transient edmacro kmacro
magit-git magit-section magit-utils dash log-edit avy whitespace
bug-reference cl-print debug backtrace find-func cus-start mhtml-mode
css-mode smie eww xdg url-queue mm-url color js sgml-mode facemenu
tex-info tex crm texmathp texinfo texinfo-loaddefs tabify imenu man
smerge-mode add-log vc-annotate nroff-mode cc-awk cc-mode cc-fonts
cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs
python shell pcomplete shell-command+ ietf-drums-date sort smiley
gnus-cite mail-extr qp textsec uni-scripts idna-mapping ucs-normalize
uni-confusable textsec-check gnus-async gnus-bcklg gnus-ml disp-table
char-fold misearch multi-isearch dired-aux gnus-dired mm-archive
mule-util url-cache url-http url-auth url-gw display-line-numbers
finder-inf vertico-directory orderless vertico-flat vc-git buffer-env
compat vc-backup log-view pcvs-util copyright time-stamp
modus-vivendi-theme autocrypt-gnus autocrypt nndraft nnmh utf-7 nnfolder
epa-file network-stream nsm gnus-agent gnus-srvr gnus-score score-mode
nnvirtual gnus-msg gnus-art mm-uu mml2015 mm-view mml-smime smime gnutls
dig nntp gnus-cache gnus-sum shr pixel-fill kinsoku url-file url-dired
svg dom gnus-group gnus-undo gnus-start gnus-dbus gnus-cloud nnimap
nnmail mail-source utf7 netrc nnoo parse-time iso8601 gnus-spec gnus-int
gnus-range message yank-media puny rfc822 mml mml-sec epa derived epg
rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader gnus-win noutline outline checkdoc
flymake-proc flymake project thingatpt flyspell ispell comp comp-cstr
warnings icons cl-extra auth-source-pass repeat dired-x dired
dired-loaddefs rx sendmail rfc2047 rfc2045 ietf-drums gnus nnheader
gnus-util time-date mail-utils range mm-util mail-prsvr diff-hl-flydiff
diff diff-hl vc-dir ewoc vc vc-dispatcher diff-mode easy-mmode
hippie-exp winner windmove corfu-history corfu vertico-multiform vertico
elec-pair recentf tree-widget wid-edit saveplace savehist xt-mouse
modus-operandi-theme modus-themes pcase format-spec pixel-scroll
cua-base icomplete time battery dbus xml cus-load setup site-lisp
compile text-property-search comint ansi-color autoload loaddefs-gen
lisp-mnt magit-autoloads vertico-autoloads buffer-env-autoloads
geiser-chibi-autoloads consult-autoloads compat-autoloads crdt-autoloads
corfu-autoloads slime-autoloads geiser-impl help-fns radix-tree
help-mode geiser-custom geiser-base ring transient-autoloads info
tex-site 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 password-cache json subr-x map byte-opt gv bytecomp
byte-compile cconv url-vars cl-loaddefs cl-lib rmc iso-transl tooltip
eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/pgtk-win pgtk-win term/common-win pgtk-dnd
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 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 pgtk
multi-tty make-network-process native-compile emacs)

Memory information:
((conses 16 1282480 178918)
 (symbols 48 56238 14)
 (strings 32 254489 16947)
 (string-bytes 1 7300121)
 (vectors 16 122508)
 (vector-slots 8 3196813 139019)
 (floats 8 871 930)
 (intervals 56 72624 5479)
 (buffers 992 150))

Message #8 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philip Kaludercic <philipk <at> posteo.net>
Cc: 56974 <at> debbugs.gnu.org
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Thu, 04 Aug 2022 16:22:14 +0300

> From: Philip Kaludercic <philipk <at> posteo.net>
> Date: Thu, 04 Aug 2022 13:06:20 +0000
> 
> 
> As far as I see, if-let, when-let, thread-first, ... were moved from
> subr-x.el to subr.el last April (b05a103e).  But there appears to be no
> documentation in (I'd assume) lispref/controls.texi.  My understanding
> was that these macros were not documented in the Elisp manual as they
> were just part of subr-x, as the comment in the subr-x header indicates
> 
>     ;; Do not document these functions in the lispref.
>     ;; https://lists.gnu.org/r/emacs-devel/2014-01/msg01006.html
> 
> So should they be documented now?

Yes, they should be.

Message #11 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 56974 <at> debbugs.gnu.org
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Fri, 05 Aug 2022 09:19:32 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Philip Kaludercic <philipk <at> posteo.net>
>> Date: Thu, 04 Aug 2022 13:06:20 +0000
>> 
>> 
>> As far as I see, if-let, when-let, thread-first, ... were moved from
>> subr-x.el to subr.el last April (b05a103e).  But there appears to be no
>> documentation in (I'd assume) lispref/controls.texi.  My understanding
>> was that these macros were not documented in the Elisp manual as they
>> were just part of subr-x, as the comment in the subr-x header indicates
>> 
>>     ;; Do not document these functions in the lispref.
>>     ;; https://lists.gnu.org/r/emacs-devel/2014-01/msg01006.html
>> 
>> So should they be documented now?
>
> Yes, they should be.

How is this for a start:

[0001-Document-if-let-if-let-when-let-and-and-let.patch (text/x-patch, inline)]

From 0d4c3f418d5dcdaa2f2f9c93b7e1fd103a310c62 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk <at> posteo.net>
Date: Fri, 5 Aug 2022 11:18:29 +0200
Subject: [PATCH] Document if-let*, if-let, when-let* and and-let*

* control.texi (Conditionals): Add if-let*, if-let, when-let*
(Combining Conditions): Add and-let*
---
 doc/lispref/control.texi | 47 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index d4520ebdee..e7fd1bb41a 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -294,6 +294,46 @@ Conditionals
 @end group
 @end example
 
+During complex computations that might at any step, one can combine a
+@code{let}-block and some of the previous conditional control
+structures:
+
+@defmac if-let (bindings <at> dots) then &rest else <at> dots
+As with @code{let*}, @var{bindings} will consist of
+@code{(@var{symbol} @var{value-form})} entries that are evaluated and
+bound sequentially.  If all @var{value-form} evaluate to
+non-@code{nil} values, then @var{then} is evaluated as were the case
+with a regular @code{let*} expression, with all the variables bound.
+If any @var{value-form} evaluates to @code{nil}, @var{else} is
+evaluated, without any bound variables.
+
+A binding may also optionally drop the @var{symbol}, and simplify to
+@code{(@var{value-form})} if only the test is of interest.
+
+For the sake of backwards compatibility, it is possible to write a
+single binding without a binding list:
+
+@example
+@group
+(if-let* (@var{symbol} (test)) foo bar)
+@equiv{}
+(if-let* ((@var{symbol} (test))) foo bar)
+@end group
+@end example
+@end defmac
+
+@defmac if-let* (bindings <at> dots) then &rest else
+@code{if-let*} is mostly equivalent to @code{if-let}, with the
+exception that the legacy @code{(if (@var{var} (test)) foo bar)}
+syntax is not permitted.
+@end defmac
+
+@defmac when-let (bindings <at> dots) &rest body
+As with @code{when}, if one is only interested in the case where all
+@var{bindings} are non-nil.  Otherwise @var{bindings} are interpreted
+just as they are by @code{if-let*}.
+@end defmac
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions
@@ -428,6 +468,13 @@ Combining Conditions
 Note that in contrast to @code{or}, both arguments are always evaluated.
 @end defun
 
+@defmac and-let* (bindings <at> dots) &rest body
+A combination of @var{let*} and @var{and}, analogous to
+@code{when-let*}.  If all @var{bindings} are non-@code{nil} and
+@var{body} is @code{nil}, then the result of the @code{and-let*} form
+will be the last value bound in @var{bindings}.
+@end defmac
+
 @node Pattern-Matching Conditional
 @section Pattern-Matching Conditional
 @cindex pcase
-- 
2.37.1

Message #14 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Philip Kaludercic <philipk <at> posteo.net>
Cc: 56974 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Fri, 05 Aug 2022 14:01:53 +0200

Philip Kaludercic <philipk <at> posteo.net> writes:

> +During complex computations that might at any step, one can combine a

Missing a word or two here?

> +For the sake of backwards compatibility, it is possible to write a
> +single binding without a binding list:

I'm not sure we need to document this bit.

> +@defmac if-let* (bindings <at> dots) then &rest else
> +@code{if-let*} is mostly equivalent to @code{if-let}, with the
> +exception that the legacy @code{(if (@var{var} (test)) foo bar)}
> +syntax is not permitted.
> +@end defmac

So I think it's sufficient to document only the *-less variant.

Message #17 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Po Lu <luangruo <at> yahoo.com>
To: Philip Kaludercic <philipk <at> posteo.net>
Cc: 56974 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Fri, 05 Aug 2022 21:50:47 +0800

Philip Kaludercic <philipk <at> posteo.net> writes:

> * control.texi (Conditionals): Add if-let*, if-let, when-let*

This should be:

> * doc/lispref/control.texi (Conditionals): ...

Message #20 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 56974 <at> debbugs.gnu.org, Philip Kaludercic <philipk <at> posteo.net>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Sat, 06 Aug 2022 03:45:05 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> > +For the sake of backwards compatibility, it is possible to write a
> > +single binding without a binding list:
>
> I'm not sure we need to document this bit.

I don't think we should.

> > +@defmac if-let* (bindings <at> dots) then &rest else
> > +@code{if-let*} is mostly equivalent to @code{if-let}, with the
> > +exception that the legacy @code{(if (@var{var} (test)) foo bar)}
> > +syntax is not permitted.
> > +@end defmac
>
> So I think it's sufficient to document only the *-less variant.

Ehm - isn't the *-less form the old one we intended to obsolete (because
of it's backwards-compatibility hack), and the *-variant the one we
actually want to advertise?

Michael.

Message #23 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 56974 <at> debbugs.gnu.org, Philip Kaludercic <philipk <at> posteo.net>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Sat, 06 Aug 2022 14:19:43 +0200

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Ehm - isn't the *-less form the old one we intended to obsolete (because
> of it's backwards-compatibility hack), and the *-variant the one we
> actually want to advertise?

when-let is a 3:1 winner over when-let* in the Emacs tree, so I think
the public has spokeneth, and we should document when-let and not
when-let*.  (And just pretend that when-let doesn't have the compat
forms in the manual.)

Message #26 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 56974 <at> debbugs.gnu.org, Philip Kaludercic <philipk <at> posteo.net>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Sun, 07 Aug 2022 04:15:42 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> when-let is a 3:1 winner over when-let* in the Emacs tree, so I think
> the public has spokeneth, and we should document when-let and not
> when-let*.  (And just pretend that when-let doesn't have the compat
> forms in the manual.)

Could be that most uses date from before the new names had been added.
AFAIR using the * names was an agreement in some thread in the past -
when this had been discussed the last time.

Personally I don't care that much, both names are equally good (or bad).
I would make them synonymous.  Although when-let and and-let are already
synonymous names...

Michael.

Message #29 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 56974 <at> debbugs.gnu.org, Philip Kaludercic <philipk <at> posteo.net>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Sun, 07 Aug 2022 14:51:26 +0200

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Personally I don't care that much, both names are equally good (or bad).
> I would make them synonymous.  Although when-let and and-let are already
> synonymous names...

There may be code problems in making when-let* and when-let synonymous
(for those that are using the outdated forms), so that's not easy to do.
But since we shouldn't document the differences, they're identical in
that way.

Message #32 received at 56974 <at> debbugs.gnu.org (full text, mbox):

From: Philip Kaludercic <philipk <at> posteo.net>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 56974 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>,
 Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#56974: 29.0.50; Missing documentation for former subr-x macros
Date: Tue, 09 Aug 2022 09:10:22 +0000

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
>
>> when-let is a 3:1 winner over when-let* in the Emacs tree, so I think
>> the public has spokeneth, and we should document when-let and not
>> when-let*.  (And just pretend that when-let doesn't have the compat
>> forms in the manual.)
>
> Could be that most uses date from before the new names had been added.
> AFAIR using the * names was an agreement in some thread in the past -
> when this had been discussed the last time.

I could imagine this being the case, and from grepping through lisp/.  I
also get the impression that people decide to use when-let vs. when-let*
the same way they would when choosing between let and let*, even though
both function more like let* than let.  Making one "more official" by
documenting the less confusingly named alternatives seems like an
argument for the *'ed ones to me.

> Personally I don't care that much, both names are equally good (or bad).
> I would make them synonymous.  Although when-let and and-let are already
> synonymous names...

What and-let are you referring to?  All I can find is and-let*.  Unless
I am missing something, I'd also argue that for the sake of consistency
documenting if-let* and when-let* would be preferable.

> Michael.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.