GNU bug report logs - #34842
26.1; Alist documentation: let-alist

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 34842 in the body.
You can then email your comments to 34842 AT debbugs.gnu.org in the normal way.

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

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

From: Sebastián Monía <seb.hoagie <at> outlook.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 14:16:15 +0000

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

The macro let-alist is too useful to work with JSON-parsed data for it to be missing from the docs.

In the page https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html we should add some documentation about it. Below a suggestion.

Thank you!

— Macro: let-alist `value`
Creates a binding for each symbol in the association list `value`, prefixed with dot. This is very useful when accessing several items in the same alist, and it's best understood through a simple example:

(setq colors '((rose red) (lily white) (buttercup yellow)))
(let-alist colors
    (print .rose)
    (print .buttercup))
    ⇒ red
    ⇒ yellow



In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30 built on CIRROCUMULUS
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor 'Microsoft Corp.', version 10.0.17134
Recent messages:
When done with a buffer, type C-c C-c
Type C-c C-c to finish, or C-c C-k to cancel
Auto-saving...done
Saving file c:/Home/github/pepita/.git/COMMIT_EDITMSG...
Wrote c:/Home/github/pepita/.git/COMMIT_EDITMSG
Git.Exe finished
Mark set
Running C:/Program Files/Git/mingw64/libexec/git-core/git.exe push -v origin master:refs/heads/master
Git.Exe finished
delete-backward-char: Text is read-only [4 times]

Configured using:
 'configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS THREADS LCMS2

Important settings:
  value of $LANG: ENU
  locale-coding-system: utf-8

Major mode: Magit

Minor modes in effect:
  semantic-minor-modes-format: ((:eval (if (or semantic-highlight-edits-mode semantic-show-unmatched-syntax-mode)  S)))
  electric-pair-mode: t
  delete-selection-mode: t
  global-hl-line-mode: t
  which-key-mode: t
  nyan-mode: t
  magit-gitflow-mode: t
  global-magit-file-mode: t
  diff-auto-refine-mode: t
  magit-auto-revert-mode: t
  global-git-commit-mode: t
  icomplete-mode: t
  ido-vertical-mode: t
  doom-modeline-mode: t
  eldoc-in-minibuffer-mode: t
  async-bytecomp-package-mode: t
  recentf-mode: t
  global-company-mode: t
  company-mode: t
  global-anzu-mode: t
  anzu-mode: t
  shell-dirtrack-mode: t
  symon-mode: t
  minions-mode: t
  ido-ubiquitous-mode: t
  ido-everywhere: t
  global-visible-mark-mode: t
  visible-mark-mode: t
  global-flycheck-mode: t
  projectile-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
c:/home/github/pepita/temp hides c:/home/github/panda/temp
~/.emacs.d/lisp/dired-git-info hides c:/Home/.emacs.d/elpa/dired-git-info-0.2/dired-git-info

Features:
(shadow sort mail-extr emacsbug sendmail pepita loadhist markdown-mode
color pcmpl-unix em-xtra em-rebind em-smart em-tramp texnfo-upd texinfo
man em-unix em-term term ehelp em-script em-prompt em-ls em-hist em-pred
em-glob em-dirs em-cmpl em-basic em-banner em-alias esh-var esh-io
esh-cmd esh-opt esh-ext esh-proc esh-arg esh-groups eshell esh-module
esh-mode esh-util profiler pulse eieio-opt help-fns warnings
subword-mode-expansions cap-words superword subword ruby-mode-expansions
ruby-mode smie ert ewoc autoload radix-tree lisp-mnt tar-mode
magit-patch magit-subtree magit-ediff timezone
python-el-fgallina-expansions python tramp-sh cl-print debug conf-mode
dired-x dabbrev vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs vc
vc-dispatcher deadgrep spinner rng-xsd xsd-regexp rng-cmpct
nxml-mode-expansions rng-nxml rng-valid rng-loc rng-uri rng-parse
nxml-parse rng-match rng-dt rng-util rng-pttrn nxml-ns nxml-mode
nxml-outln nxml-rap nxml-util nxml-enc xmltok bug-reference magit-extras
speedbar sb-image ezimage dframe org-rmail org-mhe org-irc org-info
org-gnus nnir gnus-sum gnus-group gnus-undo gnus-start gnus-cloud nnimap
nnmail mail-source utf7 netrc nnoo gnus-spec gnus-int gnus-range
gnus-win org-docview doc-view jka-compr image-mode org-bibtex bibtex
org-bbdb org-w3m org-element avl-tree generator the-org-mode-expansions
org org-macro org-footnote org-pcomplete org-list org-faces org-entities
org-version ob-emacs-lisp ob ob-tangle org-src ob-ref ob-lob ob-table
ob-keys ob-exp ob-comint ob-core ob-eval org-compat org-macs
org-loaddefs misearch multi-isearch two-column iso-transl face-remap
vc-git company-oddmuse company-keywords company-etags company-gtags
company-dabbrev-code company-dabbrev company-files company-capf
company-cmake company-xcode company-clang company-semantic company-eclim
company-template company-bbdb linum whitespace csv deploy-status panda
let-alist elec-pair delsel hl-line ws-butler which-key
web-mode-expansions web-mode sql view sly sly-completion sly-buttons
sly-messages sly-common apropos arc-mode archive-mode noutline outline
hyperspec powershell omnisharp omnisharp-unit-test-actions
omnisharp-code-structure omnisharp-server-installation
omnisharp-format-actions omnisharp-solution-actions
omnisharp-helm-integration omnisharp-navigation-actions
omnisharp-current-symbol-actions omnisharp-auto-complete-actions
omnisharp-server-actions omnisharp-http-utils omnisharp-utils
omnisharp-server-management omnisharp-settings etags xref popup
csharp-mode nyan-mode magit-gitflow magit-bookmark magit-submodule
magit-obsolete magit-blame magit-stash 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
smerge-mode diff-mode magit-core magit-autorevert autorevert filenotify
magit-margin magit-transient magit-process magit-mode transient
git-commit magit-git magit-section magit-utils crm log-edit pcvs-util
add-log with-editor server json-mode json-reformat json-snatcher
js-mode-expansions js html-mode-expansions sgml-mode cc-mode-expansions
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs imenu icomplete ido-vertical-mode ibuffer-projectile
format-all dotnet doom-modeline doom-modeline-segments doom-modeline-env
all-the-icons all-the-icons-faces data-material data-weathericons
data-octicons data-fileicons data-faicons data-alltheicons
doom-modeline-core project shrink-path f eldoc-eval docker docker-volume
docker-network docker-machine docker-image docker-container
docker-process docker-utils tablist tablist-filter semantic/wisent/comp
semantic/wisent semantic/wisent/wisent semantic/util-modes semantic/util
semantic semantic/tag semantic/lex semantic/fw mode-local cedet
docker-group magit-popup async-bytecomp async dashboard
dashboard-widgets recentf tree-widget page-break-lines cal-menu calendar
cal-loaddefs bookmark pp eww-lnum eww mm-url gnus nnheader url-queue shr
svg xml dom browse-url expand-region text-mode-expansions
er-basic-expansions expand-region-core expand-region-custom ediff-merg
ediff-wind ediff-diff ediff-mult ediff-help ediff-init ediff-util ediff
company edmacro kmacro pcase browse-kill-ring cl anzu docker-tramp
tramp-cache tramp tramp-compat tramp-loaddefs trampver ucs-normalize
shell pcomplete parse-time advice doom-challenger-deep-theme symon
battery minions ido-completing-read+ memoize s cus-edit wid-edit
minibuf-eldef ido visible-mark easy-mmode flycheck cl-extra json map
find-func help-mode subr-x dash cus-start cus-load projectile grep
compile comint ansi-color ring ibuf-ext ibuffer ibuffer-loaddefs
thingatpt doom-themes doom-themes-common mm-archive message dired
dired-loaddefs format-spec rfc822 mml mml-sec epa derived epg gnus-util
rmail rmail-loaddefs mailabbrev gmm-utils mailheader mm-decode mm-bodies
mm-encode mail-utils network-stream starttls url-http tls gnutls
mail-parse rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr url-gw
nsm rmc puny url-cache url-auth url url-proxy url-privacy url-expand
url-methods url-history url-cookie url-domsuf url-util mailcap
finder-inf gh-common marshal eieio-compat rx sly-autoloads info package
easymenu epg-config url-handlers url-parse auth-source cl-seq eieio
eieio-core cl-macs eieio-loaddefs password-cache url-vars seq byte-opt
gv bytecomp byte-compile cconv cl-loaddefs cl-lib time-date mule-util
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars
term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow isearch timer select
scroll-bar mouse jit-lock font-lock syntax facemenu font-core
term/tty-colors frame cl-generic 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 charscript charprop case-table epa-hook jka-cmpr-hook
help simple abbrev obarray minibuffer cl-preloaded 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 w32notify w32 lcms2 multi-tty make-network-process emacs)

Memory information:
((conses 16 1709736 281452)
 (symbols 56 71685 1)
 (miscs 48 3592 362)
 (strings 32 250688 79276)
 (string-bytes 1 7771630)
 (vectors 16 139525)
 (vector-slots 8 2987162 7516)
 (floats 8 1544 3542)
 (intervals 56 18844 7820)
 (buffers 992 97))

[Message part 2 (text/html, inline)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Sebastián Monía <seb.hoagie <at> outlook.com>,
 34842 <at> debbugs.gnu.org
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 08:16:28 -0700 (PDT)

> In [(elisp)`Association Lists'] we should add some
> documentation about [macro `let-alist']. Below a
> suggestion.

1. I agree that it might be good to document this
macro in node `Association Lists'.

2. But the example suggested is much less clear
than the example in the doc string.

3. The example in the doc string is itself not
correct. Instead of "essentially" it should just
show the actual macroexpansion.  And it should
use a different variable name than `alist'.  E.g.:

(let-alist my-alist
  (if (and .title .body)
      .body
    .site
    .site.contents))

expands to:

(let ((alist  my-alist))
  (let ((\.title  (cdr (assq 'title alist)))
        (\.body   (cdr (assq 'body alist)))
        (\.site   (cdr (assq 'site alist)))
        (\.site\.contents
         (cdr (assq 'contents
                    (cdr (assq 'site alist))))))
    (if (and \.title \.body)
        \.body
      \.site
      \.site\.contents)))

(And yes, the backslashes are necessary.)

4. The last paragraph of the doc string is unclear.
What does "access alists inside the original alist"
mean?  How is anything it tries to describe
"displayed in the example above", which has NO
nesting of `let-alist'?

Whatever it might be trying to say, if the point of
the last paragraph is important, then perhaps an
example of such nesting is called for, pointing out
what is meant.

Perhaps such a paragraph and example don't need to
be in both the doc string and the manual (dunno
how important this is, not knowing what it's really
trying to say).

5. The doc (manual and doc string) should explicitly
say that `assq' is used, not `assoc'.  It should not
just hand-wave about this, saying "search is done".
And it should say what it means by "this search is
done at compile time" - what the consequences of this are.

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

From: Sebastián Monía <seb.hoagie <at> outlook.com>
To: "34842 <at> debbugs.gnu.org" <34842 <at> debbugs.gnu.org>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 16:30:16 +0000

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

I thought that the example in the docstring was too long compared to the smaller/simpler examples in the rest of the page, but wouldn't be against using that instead if it's more clear.

The nested access example is in .site.contents, maybe being explicit about which line displays the concept would be a nice improvement.

And most of what you said in point 5 is above my level so I will defer to people with more knowledge.

Thank you for your feedback Drew!

---------------------------------------------------
Why Emacs?
http://david.rothlis.net/emacs/why.html



From: Drew Adams
Sent: Wednesday, March 13, 9:16 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebastián Monía, 34842 <at> debbugs.gnu.org


> In [(elisp)`Association Lists'] we should add some > documentation about [macro `let-alist']. Below a > suggestion. 1. I agree that it might be good to document this macro in node `Association Lists'. 2. But the example suggested is much less clear than the example in the doc string. 3. The example in the doc string is itself not correct. Instead of "essentially" it should just show the actual macroexpansion. And it should use a different variable name than `alist'. E.g.: (let-alist my-alist (if (and .title .body) .body .site .site.contents)) expands to: (let ((alist my-alist)) (let ((\.title (cdr (assq 'title alist))) (\.body (cdr (assq 'body alist))) (\.site (cdr (assq 'site alist))) (\.site\.contents (cdr (assq 'contents (cdr (assq 'site alist)))))) (if (and \.title \.body) \.body \.site \.site\.contents))) (And yes, the backslashes are necessary.) 4. The last paragraph of the doc string is unclear. What does "access alists inside the original alist" mean? How is anything it tries to describe "displayed in the example above", which has NO nesting of `let-alist'? Whatever it might be trying to say, if the point of the last paragraph is important, then perhaps an example of such nesting is called for, pointing out what is meant. Perhaps such a paragraph and example don't need to be in both the doc string and the manual (dunno how important this is, not knowing what it's really trying to say). 5. The doc (manual and doc string) should explicitly say that `assq' is used, not `assoc'. It should not just hand-wave about this, saying "search is done". And it should say what it means by "this search is done at compile time" - what the consequences of this are.

[Message part 2 (text/html, inline)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Sebastián Monía <seb.hoagie <at> outlook.com>,
 34842 <at> debbugs.gnu.org
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
Date: Wed, 13 Mar 2019 10:51:36 -0700 (PDT)

Thanks for filing the bug, BTW.

> I thought that the example in the docstring was
> too long compared to the smaller/simpler examples
> in the rest of the page, but wouldn't be against
> using that instead if it's more clear. 

The example could be shorter, yes.  But it needs
to be correct and show what `let-alist' does.

> The nested access example is in .site.contents,

But the doc talks about nested uses of `let-alist'.
There is only one `let-alist' in the example that the
doc claims shows the behavior of nesting `let-alist'.

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

From: Sebastián Monía <seb.hoagie <at> outlook.com>
To: "34842 <at> debbugs.gnu.org" <34842 <at> debbugs.gnu.org>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Thu, 14 Mar 2019 04:47:05 +0000

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

I think when it says nested let-alist uses, it refers to the fact that let-alist automatically went to the next level of depth to provide a binding for .title

Without that feature you would need a second let-alist: (let-alist .company # more code here)

Sorry for the lack of formatting I'm on mobile. Hope that made sense!

---------------------------------------------------
Why Emacs?
http://david.rothlis.net/emacs/why.html



From: Drew Adams
Sent: Wednesday, March 13, 11:51 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebastián Monía, 34842 <at> debbugs.gnu.org


Thanks for filing the bug, BTW. > I thought that the example in the docstring was > too long compared to the smaller/simpler examples > in the rest of the page, but wouldn't be against > using that instead if it's more clear. The example could be shorter, yes. But it needs to be correct and show what `let-alist' does. > The nested access example is in .site.contents, But the doc talks about nested uses of `let-alist'. There is only one `let-alist' in the example that the doc claims shows the behavior of nesting `let-alist'.

[Message part 2 (text/html, inline)]

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Sebastián Monía <seb.hoagie <at> outlook.com>
Cc: 34842 <at> debbugs.gnu.org
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 01:32:04 +0200

Sebastián Monía <seb.hoagie <at> outlook.com> writes:

> The macro let-alist is too useful to work with JSON-parsed data for it to be
> missing from the docs.
>
> In the page
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
> we should add some documentation about it. Below a suggestion.
>
> Thank you!
>
> — Macro: let-alist `value`
> Creates a binding for each symbol in the association list `value`, prefixed with
> dot. This is very useful when accessing several items in the same alist, and it's
> best understood through a simple example:
>
> (setq colors '((rose red) (lily white) (buttercup yellow)))
> (let-alist colors
>     (print .rose)
>     (print .buttercup))
>     ⇒ red
>     ⇒ yellow

Even though I question the usefulness of this macro (especially since it
doesn't nest well, so it seems just kinda ad-hoc), I've now documented
it along the lines you suggest.  Drew wanted the manual to describe more
fully the actual details behind the implementation, but I think that
doesn't add much clarity.

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

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 34842 <at> debbugs.gnu.org,
 Sebastián Monía <seb.hoagie <at> outlook.com>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 03:03:07 +0100

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

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

> Sebastián Monía <seb.hoagie <at> outlook.com> writes:
>
>> The macro let-alist is too useful to work with JSON-parsed data for it to be
>> missing from the docs.
>>
>> In the page
>> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
>> we should add some documentation about it. Below a suggestion.
>>
>> Thank you!
>>
>> — Macro: let-alist `value`
>> Creates a binding for each symbol in the association list `value`, prefixed with
>> dot. This is very useful when accessing several items in the same alist, and it's
>> best understood through a simple example:
>>
>> (setq colors '((rose red) (lily white) (buttercup yellow)))
>> (let-alist colors
>>     (print .rose)
>>     (print .buttercup))
>>     ⇒ red
>>     ⇒ yellow
>
> Even though I question the usefulness of this macro (especially since it
> doesn't nest well, so it seems just kinda ad-hoc), I've now documented
> it along the lines you suggest.  Drew wanted the manual to describe more
> fully the actual details behind the implementation, but I think that
> doesn't add much clarity.

Thanks.  The following constitute what I think are some opportunities
for clarifying the current doc.  WDYT?

[let-alist.diff (text/x-diff, inline)]

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c06e95640d..00c2211c36 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1781,39 +1781,51 @@ Association Lists
 @sc{car}.
 @end defun
 
-@defmac let-alist alist body
-Creates a binding for each symbol used as keys the association list
-@var{alist}, prefixed with dot.  This can be useful when accessing
-several items in the same association list, and it's best understood
-through a simple example:
+@defmac let-alist alist body <at> dots{}
+This macro sets up a local binding for each variable that is used in
+@var{body} and whose name starts with a dot, and then evaluates
+@var{body}.  In each case the dot-prefixed variable is bound to the
+value associated with its dot-less suffix in the association list
+@var{alist}.
+
+This can be convenient when accessing several items in the same
+association list, and is best understood through a simple example:
 
 @lisp
 (setq colors '((rose . red) (lily . white) (buttercup . yellow)))
 (let-alist colors
   (if (eq .rose 'red)
       .lily))
-=> white
+     @result{} white
 @end lisp
 
-The @var{body} is inspected at compilation time, and only the symbols
-that appear in @var{body} with a @samp{.} as the first character in
-the symbol name will be bound.  Finding the keys is done with
-@code{assq}, and the @code{cdr} of the return value of this
-@code{assq} is assigned as the value for the binding.
+The @var{body} is inspected at compilation time, and only those
+variables that appear in @var{body} and whose name starts with a
+@samp{.} are bound.  Each such @var{.symbol} is bound to the @sc{cdr}
+of the first association for @var{symbol} in @var{alist} using
+@code{assq}.  If no such association exists, @var{.symbol} is bound to
+@code{nil}:
 
-Nested association lists is supported:
+@lisp
+(let-alist colors
+  .tulip)
+     @result{} nil
+@end lisp
+
+Nested association lists are also supported by concatenating multiple
+dot-prefixed symbols:
 
 @lisp
 (setq colors '((rose . red) (lily (belladonna . yellow) (brindisi . pink))))
 (let-alist colors
   (if (eq .rose 'red)
       .lily.belladonna))
-=> yellow
+     @result{} yellow
 @end lisp
 
-Nesting @code{let-alist} inside each other is allowed, but the code in
-the inner @code{let-alist} can't access the variables bound by the
-outer @code{let-alist}.
+Nesting @code{let-alist} inside calls to itself is allowed, but the
+@var{body} of the inner @code{let-alist} can't access the bindings set
+up by the outer @code{let-alist}.
 @end defmac
 
 @node Property Lists

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

-- 
Basil

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 34842 <at> debbugs.gnu.org,
 Sebastián Monía <seb.hoagie <at> outlook.com>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 04:48:11 +0200

"Basil L. Contovounesios" <contovob <at> tcd.ie> writes:

> Thanks.  The following constitute what I think are some opportunities
> for clarifying the current doc.  WDYT?

Looks good to me, but:

> +@samp{.} are bound.  Each such @var{.symbol} is bound to the @sc{cdr}
> +of the first association for @var{symbol} in @var{alist} using
> +@code{assq}.  If no such association exists, @var{.symbol} is bound to
> +@code{nil}:
>
> +@lisp
> +(let-alist colors
> +  .tulip)
> +     @result{} nil
> +@end lisp

This bit seems superfluous.  (cdr (assq ...)) is nil when no such
association exists, but this makes it sound like that's a special case
somehow...

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: contovob <at> tcd.ie, 34842 <at> debbugs.gnu.org, seb.hoagie <at> outlook.com
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 10:15:44 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Sun, 13 Oct 2019 04:48:11 +0200
> Cc: 34842 <at> debbugs.gnu.org, Sebastián Monía
>  <seb.hoagie <at> outlook.com>
> 
> "Basil L. Contovounesios" <contovob <at> tcd.ie> writes:
> 
> > Thanks.  The following constitute what I think are some opportunities
> > for clarifying the current doc.  WDYT?
> 
> Looks good to me, but:

I have one more nit: why was @dots{} added after @var{body} in the
@defmac line?  There's only one body here, isn't it?

Thanks.

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 34842 <at> debbugs.gnu.org,
 Sebastián Monía <seb.hoagie <at> outlook.com>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 13:17:51 +0100

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

> "Basil L. Contovounesios" <contovob <at> tcd.ie> writes:
>
>> Thanks.  The following constitute what I think are some opportunities
>> for clarifying the current doc.  WDYT?
>
> Looks good to me, but:

Thanks.

>> +@samp{.} are bound.  Each such @var{.symbol} is bound to the @sc{cdr}
>> +of the first association for @var{symbol} in @var{alist} using
>> +@code{assq}.  If no such association exists, @var{.symbol} is bound to
>> +@code{nil}:
>>
>> +@lisp
>> +(let-alist colors
>> +  .tulip)
>> +     @result{} nil
>> +@end lisp
>
> This bit seems superfluous.  (cdr (assq ...)) is nil when no such
> association exists, but this makes it sound like that's a special case
> somehow...

It's just making it explicit without having to refer to specifics of the
implementation.  I think it's a common style in the docs, but I don't
feel strongly about it.  Would you rather remove the example, the
sentence, or both?

-- 
Basil

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 34842 <at> debbugs.gnu.org,
 seb.hoagie <at> outlook.com
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 13:38:09 +0100

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

>> From: Lars Ingebrigtsen <larsi <at> gnus.org>
>> Date: Sun, 13 Oct 2019 04:48:11 +0200
>> Cc: 34842 <at> debbugs.gnu.org, Sebastián Monía
>>  <seb.hoagie <at> outlook.com>
>> 
>> "Basil L. Contovounesios" <contovob <at> tcd.ie> writes:
>> 
>> > Thanks.  The following constitute what I think are some opportunities
>> > for clarifying the current doc.  WDYT?
>> 
>> Looks good to me, but:
>
> I have one more nit: why was @dots{} added after @var{body} in the
> @defmac line?  There's only one body here, isn't it?

There's only one body indeed, but it comprises multiple forms.
The Elisp manual currently contains over 50 occurrences of body...,
including the following:

 -- Macro: dolist (var list [result]) body...
 -- Special Form: catch tag body...
 -- Macro: ignore-errors body...
 -- Macro: defun name args [doc] [declare] [interactive] body...
 -- Macro: lambda args [doc] [interactive] body...
 -- Macro: defsubst name args [doc] [declare] [interactive] body...     
 -- Macro: defmacro name args [doc] [declare] body...
 -- Macro: with-eval-after-load library body...
 -- Special Form: eval-when-compile body...

Whereas it only contains 7 occurrences of '&rest body':

 -- Macro: pcase-defmacro name args [doc] &rest body
 -- Macro: with-connection-local-variables &rest body
 -- Macro: gv-define-setter name arglist &rest body
 -- Macro: gv-letplace (getter setter) place &rest body
 -- Macro: minibuffer-with-setup-hook function &rest body
 -- Macro: with-coding-priority coding-systems &rest body...
 -- Macro: with-temp-message message &rest body

[Note that with-coding-priority uses both &rest and body...]

And let-alist is the only occurrence of a body without either &rest or
an ellipsis:

 -- Macro: let-alist alist body

Of course there is also the forms... style, of which there are under 20
occurrences, including:

 -- Special Form: progn forms...
 -- Special Form: if condition then-form else-forms...
 -- Macro: when condition then-forms...
 -- Macro: unless condition forms...
 -- Special Form: while condition forms...
 -- Special Form: let (bindings...) forms...

I don't mind which style is preferred, but let-alist should probably
pick one of the existing ones, right?  Any preference?

Thanks,

-- 
Basil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: larsi <at> gnus.org, 34842 <at> debbugs.gnu.org, seb.hoagie <at> outlook.com
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 16:15:39 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: Lars Ingebrigtsen <larsi <at> gnus.org>,  34842 <at> debbugs.gnu.org,
>   seb.hoagie <at> outlook.com
> Date: Sun, 13 Oct 2019 13:38:09 +0100
> 
> I don't mind which style is preferred, but let-alist should probably
> pick one of the existing ones, right?  Any preference?

I prefer either "body" or "forms <at> dots{}".

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 34842 <at> debbugs.gnu.org,
 Sebastián Monía <seb.hoagie <at> outlook.com>
Subject: Re: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 19:39:25 +0200

"Basil L. Contovounesios" <contovob <at> tcd.ie> writes:

> It's just making it explicit without having to refer to specifics of the
> implementation.  I think it's a common style in the docs, but I don't
> feel strongly about it.  Would you rather remove the example, the
> sentence, or both?

I think both the sentence and the example are confusing, because they
make an issue out of things behaving normally as if that behaviour is
special to this case.

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

Previous Next

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