bug#21048: 24.4; Letrec docs

bug#21048: 24.4; Letrec docs

[Rustom Mody]

[-- Attachment #1: Type: text/plain, Size: 3469 bytes --]

I find letrec is not in the info pages though it has a brief
'describe-function' result.
Eli Zaretsii suggested a bug-report, so here it is!



In GNU Emacs 24.4.1 (x86_64-pc-linux-gnu, GTK+ Version 3.14.9)
 of 2015-03-21 on kissel, modified by Debian
Windowing system distributor `The X.Org Foundation', version 11.0.11701000
System Description:    Ubuntu 15.04

Configured using:
 `configure --build x86_64-linux-gnu --prefix=/usr
 --sharedstatedir=/var/lib --libexecdir=/usr/lib
 --localstatedir=/var/lib --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.4/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.4/site-lisp:/usr/share/emacs/site-lisp
 --build x86_64-linux-gnu --prefix=/usr --sharedstatedir=/var/lib
 --libexecdir=/usr/lib --localstatedir=/var/lib
 --infodir=/usr/share/info --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs24:/etc/emacs:/usr/local/share/emacs/24.4/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.4/site-lisp:/usr/share/emacs/site-lisp
 --with-x=yes --with-x-toolkit=gtk3 --with-toolkit-scroll-bars
 'CFLAGS=-g -O2 -fstack-protector-strong -Wformat
 -Werror=format-security -Wall' CPPFLAGS=-D_FORTIFY_SOURCE=2
 'LDFLAGS=-Wl,-Bsymbolic-functions -Wl,-z,relro''

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

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  electric-indent-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
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
M-x r e p o r t <tab> <return>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
easymenu mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util help-fns mail-prsvr mail-utils time-date tooltip electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar
dnd fontset image regexp-opt fringe tabulated-list newcomment lisp-mode
prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote make-network-process
dbusbind gfilenotify dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)

Memory information:
((conses 16 71135 7794)
 (symbols 48 17572 0)
 (miscs 40 35 113)
 (strings 32 9054 4369)
 (string-bytes 1 249011)
 (vectors 16 8912)
 (vector-slots 8 383118 18327)
 (floats 8 63 68)
 (intervals 56 216 0)
 (buffers 960 11)
 (heap 1024 21493 1000))

[-- Attachment #2: Type: text/html, Size: 3894 bytes --]

bug#21048: 24.4; Letrec docs

[Lars Ingebrigtsen]

Rustom Mody <rustompmody@gmail.com> writes:

> I find letrec is not in the info pages though it has a brief
> 'describe-function' result.
> Eli Zaretsii suggested a bug-report, so here it is!

I have now documented letrec in the Emacs 27 Emacs Lisp manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#21048: 24.4; Letrec docs

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Wed, 09 Oct 2019 06:06:51 +0200
> Cc: 21048@debbugs.gnu.org
> 
> Rustom Mody <rustompmody@gmail.com> writes:
> 
> > I find letrec is not in the info pages though it has a brief
> > 'describe-function' result.
> > Eli Zaretsii suggested a bug-report, so here it is!
> 
> I have now documented letrec in the Emacs 27 Emacs Lisp manual.

Thanks, but I have trouble understanding what the text you wrote
says.  I think it needs clarifying, or maybe a descriptive enough
example.

bug#21048: 24.4; Letrec docs

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, but I have trouble understanding what the text you wrote
> says.  I think it needs clarifying, or maybe a descriptive enough
> example.

Yeah, it's pretty subtle what the difference is -- feel free to rewrite
to make it clearer.

I went through the tree looking for a real-life example of when this
macro is useful, and the first half-dozen examples I looked at could
have been written with let* instead and worked just as well, as far as I
can tell.

But I found one in elisp-mode.el and I adapted it slightly and added
this to the manual:

----

For instance, here's a closure that removes itself from a hook after
being run once:

@lisp
(letrec ((hookfun (lambda ()
                    (message "Run once")
                    (remove-hook 'post-command-hook hookfun))))
  (add-hook 'post-command-hook hookfun))
@end lisp


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no