* bug#56974: 29.0.50; Missing documentation for former subr-x macros @ 2022-08-04 13:06 Philip Kaludercic 2022-08-04 13:22 ` Eli Zaretskii 0 siblings, 1 reply; 10+ messages in thread From: Philip Kaludercic @ 2022-08-04 13:06 UTC (permalink / raw) To: 56974 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)) ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-04 13:06 bug#56974: 29.0.50; Missing documentation for former subr-x macros Philip Kaludercic @ 2022-08-04 13:22 ` Eli Zaretskii 2022-08-05 9:19 ` Philip Kaludercic 0 siblings, 1 reply; 10+ messages in thread From: Eli Zaretskii @ 2022-08-04 13:22 UTC (permalink / raw) To: Philip Kaludercic; +Cc: 56974 > From: Philip Kaludercic <philipk@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-04 13:22 ` Eli Zaretskii @ 2022-08-05 9:19 ` Philip Kaludercic 2022-08-05 12:01 ` Lars Ingebrigtsen 2022-08-05 13:50 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors 0 siblings, 2 replies; 10+ messages in thread From: Philip Kaludercic @ 2022-08-05 9:19 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 56974 [-- Attachment #1: Type: text/plain, Size: 727 bytes --] Eli Zaretskii <eliz@gnu.org> writes: >> From: Philip Kaludercic <philipk@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: [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Document-if-let-if-let-when-let-and-and-let.patch --] [-- Type: text/x-patch, Size: 2777 bytes --] From 0d4c3f418d5dcdaa2f2f9c93b7e1fd103a310c62 Mon Sep 17 00:00:00 2001 From: Philip Kaludercic <philipk@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@dots) then &rest else@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@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@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@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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-05 9:19 ` Philip Kaludercic @ 2022-08-05 12:01 ` Lars Ingebrigtsen 2022-08-06 1:45 ` Michael Heerdegen 2022-08-05 13:50 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors 1 sibling, 1 reply; 10+ messages in thread From: Lars Ingebrigtsen @ 2022-08-05 12:01 UTC (permalink / raw) To: Philip Kaludercic; +Cc: 56974, Eli Zaretskii Philip Kaludercic <philipk@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@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-05 12:01 ` Lars Ingebrigtsen @ 2022-08-06 1:45 ` Michael Heerdegen 2022-08-06 12:19 ` Lars Ingebrigtsen 0 siblings, 1 reply; 10+ messages in thread From: Michael Heerdegen @ 2022-08-06 1:45 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: 56974, Philip Kaludercic, Eli Zaretskii Lars Ingebrigtsen <larsi@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@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-06 1:45 ` Michael Heerdegen @ 2022-08-06 12:19 ` Lars Ingebrigtsen 2022-08-07 2:15 ` Michael Heerdegen 0 siblings, 1 reply; 10+ messages in thread From: Lars Ingebrigtsen @ 2022-08-06 12:19 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 56974, Philip Kaludercic, Eli Zaretskii Michael Heerdegen <michael_heerdegen@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.) ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-06 12:19 ` Lars Ingebrigtsen @ 2022-08-07 2:15 ` Michael Heerdegen 2022-08-07 12:51 ` Lars Ingebrigtsen 2022-08-09 9:10 ` Philip Kaludercic 0 siblings, 2 replies; 10+ messages in thread From: Michael Heerdegen @ 2022-08-07 2:15 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: 56974, Philip Kaludercic, Eli Zaretskii Lars Ingebrigtsen <larsi@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-07 2:15 ` Michael Heerdegen @ 2022-08-07 12:51 ` Lars Ingebrigtsen 2022-08-09 9:10 ` Philip Kaludercic 1 sibling, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2022-08-07 12:51 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 56974, Philip Kaludercic, Eli Zaretskii Michael Heerdegen <michael_heerdegen@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-07 2:15 ` Michael Heerdegen 2022-08-07 12:51 ` Lars Ingebrigtsen @ 2022-08-09 9:10 ` Philip Kaludercic 1 sibling, 0 replies; 10+ messages in thread From: Philip Kaludercic @ 2022-08-09 9:10 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 56974, Lars Ingebrigtsen, Eli Zaretskii Michael Heerdegen <michael_heerdegen@web.de> writes: > Lars Ingebrigtsen <larsi@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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#56974: 29.0.50; Missing documentation for former subr-x macros 2022-08-05 9:19 ` Philip Kaludercic 2022-08-05 12:01 ` Lars Ingebrigtsen @ 2022-08-05 13:50 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors 1 sibling, 0 replies; 10+ messages in thread From: Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-08-05 13:50 UTC (permalink / raw) To: Philip Kaludercic; +Cc: 56974, Eli Zaretskii Philip Kaludercic <philipk@posteo.net> writes: > * control.texi (Conditionals): Add if-let*, if-let, when-let* This should be: > * doc/lispref/control.texi (Conditionals): ... ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2022-08-09 9:10 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2022-08-04 13:06 bug#56974: 29.0.50; Missing documentation for former subr-x macros Philip Kaludercic 2022-08-04 13:22 ` Eli Zaretskii 2022-08-05 9:19 ` Philip Kaludercic 2022-08-05 12:01 ` Lars Ingebrigtsen 2022-08-06 1:45 ` Michael Heerdegen 2022-08-06 12:19 ` Lars Ingebrigtsen 2022-08-07 2:15 ` Michael Heerdegen 2022-08-07 12:51 ` Lars Ingebrigtsen 2022-08-09 9:10 ` Philip Kaludercic 2022-08-05 13:50 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.