GNU bug report logs - #8275
24.0.50; Intro to Emacs Lisp Issue

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 8275 in the body.
You can then email your comments to 8275 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: Jason Earl <jearl <at> notengoamigos.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.0.50; Intro to Emacs Lisp Issue
Date: Thu, 17 Mar 2011 11:35:58 -0600

(info "(eintr) append-to-buffer overview") covers a previous version of
append-to-buffer.


In GNU Emacs 24.0.50.5 (i686-pc-linux-gnu, GTK+ Version 2.22.0)
 of 2011-03-14 on c3po
Windowing system distributor `The X.Org Foundation', version 11.0.10900000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Info

Minor modes in effect:
  diff-auto-refine-mode: t
  yas/global-mode: t
  shell-dirtrack-mode: t
  global-semantic-mru-bookmark-mode: t
  global-semanticdb-minor-mode: t
  global-semantic-idle-completions-mode: t
  global-semantic-idle-scheduler-mode: t
  global-semantic-idle-summary-mode: t
  global-semantic-decoration-mode: t
  global-semantic-highlight-func-mode: t
  global-semantic-stickyfunc-mode: t
  semantic-mode: t
  show-paren-mode: t
  delete-selection-mode: t
  tooltip-mode: t
  mouse-wheel-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:
<return> <switch-frame> C-x k <return> <up> <down> 
<switch-frame> <up> <switch-frame> <up> <up> <switch-frame> 
<switch-frame> <switch-frame> <down> C-x o <return> 
<down> <return> <switch-frame> <switch-frame> <switch-frame> 
<switch-frame> C-x o <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <left> <down> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <return> q <up> <up> <switch-frame> 
C-h i u u u u u <down> <down> <down> <return> i s a 
v e - e x c u r <tab> <return> , u <return> SPC SPC 
SPC SPC SPC SPC SPC SPC SPC SPC SPC SPC SPC SPC SPC 
SPC SPC SPC SPC SPC SPC SPC <up> <up> <up> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <switch-frame> 
<switch-frame> M-x r e b o <tab> <backspace> <backspace> 
p o <tab> r <tab> b <tab> <tab> e m <tab> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> d o <tab> <backspace> 
<backspace> e m <tab> <return>

Recent messages:
uncompressing eintr-3.gz...done
uncompressing eintr-2.gz...done
uncompressing eintr-3.gz...done
uncompressing eintr-3.gz...done
uncompressing eintr-3.gz...done
uncompressing eintr-1.gz...done
Found `save-excursion' in Index.  (Only match) [2 times]
byte-code: End of buffer [3 times]
Added 3 events for today
Making completion list... [2 times]

Load-path shadows:
~/.emacs.d/lisp/slime/slime hides /home/jearl/quicklisp/dists/quicklisp/software/slime-20110219-cvs/slime
~/.emacs.d/lisp/slime/hyperspec hides /home/jearl/quicklisp/dists/quicklisp/software/slime-20110219-cvs/hyperspec
~/.emacs.d/lisp/slime/slime-autoloads hides /home/jearl/quicklisp/dists/quicklisp/software/slime-20110219-cvs/slime-autoloads
/usr/local/share/emacs/site-lisp/emms/tq hides /usr/local/share/emacs/24.0.50/lisp/emacs-lisp/tq

Features:
(shadow emacsbug jka-compr gnus-uu yenc gnus-html url-cache mm-url
shr-color color shr gnus-dup mailalias smtpmail bbdb-gui vc-dispatcher
vc-svn tramp-cache tramp-sh tramp tramp-compat tramp-loaddefs
multi-isearch qp smiley ansi-color gnus-cite flow-fill gnus-async
gnus-bcklg gnus-ml nndraft nnmh utf-7 nnimap utf7 nnfolder bbdb-gnus
bbdb-snarf mail-extr bbdb-com rot13 disp-table netrc gnus-agent
gnus-srvr gnus-score score-mode nnvirtual gnus-msg gnus-art mm-uu
mml2015 epg-config mm-view mml-smime smime dig nntp proto-stream
starttls gnus-cache nnir gnus-sum macroexp nnoo gnus-group gnus-undo
nnmail mail-source gnus-fun gnus-start gnus-spec gnus-int gnus-range
message sendmail rfc822 mml mml-sec mm-decode mm-bodies mm-encode
mailabbrev gmm-utils mailheader gnus-win gnus gnus-ems nnheader
mail-utils wid-edit calc-menu calc-aent calc calc-loaddefs calc-macs
mule-util cal-move tabify org-table newcomment cal-china lunar solar
cal-dst holidays hol-loaddefs cal-iso paredit company-files
company-oddmuse company-keywords company-dabbrev-code company-dabbrev
company-etags company-gtags company-ropemacs company-xcode
company-semantic semantic/analyze semantic/sort semantic/scope
semantic/analyze/fcn company-eclim company-css company-nxml 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-glyph
nxml-enc xmltok company-elisp help-mode view company auctex-autoloads
tex-site info company-autoloads package slime-fancy slime-fontifying-fu
slime-package-fu slime-references slime-scratch slime-presentations
slime-fuzzy slime-fancy-inspector slime-c-p-c slime-editing-commands
slime-autodoc slime-parse slime-repl slime apropos hideshow pp hyperspec
slime-autoloads emms-playlist-limit emms-volume emms-volume-amixer
emms-i18n emms-history emms-score emms-stream-info
emms-metaplaylist-mode emms-bookmarks emms-lastfm-client
emms-lastfm-scrobbler emms-cue emms-mode-line-icon emms-browser sort
emms-playlist-sort emms-last-played emms-player-xine emms-player-mpd tq
emms-playing-time emms-lyrics emms-url hl-line emms-streams
emms-tag-editor format-spec emms-mark emms-mode-line emms-cache
emms-info-ogginfo emms-info-mp3info emms-playlist-mode emms-player-vlc
emms-player-mplayer emms-player-simple emms-source-playlist
emms-source-file dired emms-info-libtag emms-info later-do emms-setup
emms emms-compat magit diff-mode log-edit pcvs-util add-log yasnippet
dropdown-list ess-toolbar ess-mouse mouseme browse-url ess-menu speedbar
sb-image dframe ess-swv ess-noweb noweb-font-lock-mode ess-bugs-l
essd-els ess-sas-d ess-sas-l ess-sas-a executable shell ess-arc-d
ess-vst-d ess-xls-d ess-lsp-l ess-sta-d ess-sta-l cc-vars cc-defs
make-regexp ess-sp6-d ess-sp5-d ess-sp3-d ess-r-d ess-r-args ess-s-l
ess-inf ess-utils ess-mode noweb-mode ess ess-custom ess-compat ess-site
identica-mode edmacro kmacro json url-http tls url-auth mail-parse
rfc2231 rfc2047 rfc2045 ietf-drums url-gw url url-proxy url-privacy
url-expand url-methods url-history url-cookie url-util url-parse
auth-source assoc gnus-util password-cache url-vars mm-util mail-prsvr
mailcap longlines parse-time boxquote rect appt diary-lib diary-loaddefs
vc-bzr flyspell ispell org-wl org-w3m org-vm org-rmail org-mhe org-mew
org-irc org-jsinfo org-infojs org-html org-exp ob-exp org-exp-blocks
org-info org-gnus org-docview org-bibtex org-bbdb org-agenda org
warnings ob-emacs-lisp ob-tangle ob-ref ob-lob ob-table org-footnote
org-src ob-comint ob-keys ob ob-eval org-complete org-list org-faces
org-compat org-entities org-macs time-date noutline outline cal-menu
calendar cal-loaddefs htmlize cl org-install semantic/mru-bookmark
semantic/db-mode semantic/db eieio-base semantic/idle semantic/format
ezimage semantic/ctxt semantic/decorate/mode semantic/tag-ls
semantic/decorate pulse semantic/util-modes semantic/util semantic
semantic/tag semantic/lex semantic/fw eieio byte-opt bytecomp
byte-compile mode-local cedet flymake easy-mmode ropemacs pymacs
bbdb-autoloads bbdb timezone dbus xml w3m-load quack thingatpt easymenu
compile cmuscheme comint regexp-opt ring scheme ledger derived pcomplete
esh-arg esh-util jadoea tango-dark-theme sha1 hex-util uniquify advice
help-fns advice-preload paren delsel cus-start cus-load tooltip
ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar dnd
fontset image fringe lisp-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 loaddefs button minibuffer faces cus-face files
text-properties overlay md5 base64 format env code-pages mule custom
widget hashtable-print-readable backquote make-network-process dbusbind
dynamic-setting system-font-setting font-render-setting move-toolbar gtk
x-toolkit x multi-tty emacs)

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

From: Chong Yidong <cyd <at> stupidchicken.com>
To: "Robert J. Chassell"  <bob <at> gnu.org>
Cc: 8275 <at> debbugs.gnu.org, Jason Earl <jearl <at> notengoamigos.org>
Subject: Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sat, 19 Mar 2011 17:58:55 -0400

Hi Bob,

Do you want to fix this, or shall I try?  The problem is that
append-to-buffer now uses let* and with-current-buffer, so this might
break the flow of the text.  At this point in the book, let* and
with-current-buffer are not yet introduced.


Jason Earl <jearl <at> notengoamigos.org> writes:

> (info "(eintr) append-to-buffer overview") covers a previous version of
> append-to-buffer.

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

From: bob <at> gnu.org (Robert J. Chassell)
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: 8275 <at> debbugs.gnu.org, bob <at> gnu.org, jearl <at> notengoamigos.org
Subject: Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sat, 19 Mar 2011 21:06:50 -0400

    Do you want to fix this, or shall I try?  The problem is that
    append-to-buffer now uses let* and with-current-buffer, so this might
    break the flow of the text.  At this point in the book, let* and
    with-current-buffer are not yet introduced.


    Jason Earl <jearl <at> notengoamigos.org> writes:

    > (info "(eintr) append-to-buffer overview") covers a previous version of
    > append-to-buffer.

Please try to fix it.  I am getting worse and have made many
mistakes just in composing this.  (I think I found them all.)
Please try to fix any in the future, too.

-- 
    Robert J. Chassell                          
    bob <at> gnu.org                                 bob <at> rattlesnake.com
    http://www.rattlesnake.com                  http://www.teak.cc

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: 8275 <at> debbugs.gnu.org, "Robert J. Chassell" <bob <at> gnu.org>,
	Jason Earl <jearl <at> notengoamigos.org>
Subject: Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sat, 19 Mar 2011 23:34:47 -0400

> Do you want to fix this, or shall I try?  The problem is that
> append-to-buffer now uses let* and with-current-buffer, so this might
> break the flow of the text.  At this point in the book, let* and
> with-current-buffer are not yet introduced.

Here are some thoughts:
- I don't think it's of any importance that the example code be
  identical to the currently used code.
- append-to-buffer might not be the best example since AFAICT copying
  text from one buffer to another is not a common operation and in most
  cases this is done via buffer-substring + insert (often with some
  processing on the string between the two) rather than with
  insert-buffer-substring which is a rarely used function.
- yes, I think the text would benefit from some rethink to try and present
  with-current-buffer in preference to set-buffer, but it's not
  a simple fix.


        Stefan

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

From: Andreas Röhler <andreas.roehler <at> easy-emacs.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sun, 20 Mar 2011 22:20:39 +0100

Am 20.03.2011 04:34, schrieb Stefan Monnier:
>> Do you want to fix this, or shall I try?  The problem is that
>> append-to-buffer now uses let* and with-current-buffer, so this might
>> break the flow of the text.  At this point in the book, let* and
>> with-current-buffer are not yet introduced.
>
> Here are some thoughts:
> - I don't think it's of any importance that the example code be
>    identical to the currently used code.
> - append-to-buffer might not be the best example since AFAICT copying
>    text from one buffer to another is not a common operation and in most
>    cases this is done via buffer-substring + insert (often with some
>    processing on the string between the two) rather than with
>    insert-buffer-substring which is a rarely used function.
> - yes, I think the text would benefit from some rethink to try and present
>    with-current-buffer in preference to set-buffer, but it's not
>    a simple fix.
>
>
>          Stefan
>
>
>
>


just add:

"as GNU Emacs version 19 used it"

Cheers

Andreas

Message #24 received at 8275-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 8275-done <at> debbugs.gnu.org, Chong Yidong <cyd <at> stupidchicken.com>,
 Jason Earl <jearl <at> notengoamigos.org>
Subject: Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Thu, 21 Oct 2021 12:42:54 -0700

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> Do you want to fix this, or shall I try?  The problem is that
>> append-to-buffer now uses let* and with-current-buffer, so this might
>> break the flow of the text.  At this point in the book, let* and
>> with-current-buffer are not yet introduced.
>
> Here are some thoughts:
> - I don't think it's of any importance that the example code be
>   identical to the currently used code.
> - append-to-buffer might not be the best example since AFAICT copying
>   text from one buffer to another is not a common operation and in most
>   cases this is done via buffer-substring + insert (often with some
>   processing on the string between the two) rather than with
>   insert-buffer-substring which is a rarely used function.
> - yes, I think the text would benefit from some rethink to try and present
>   with-current-buffer in preference to set-buffer, but it's not
>   a simple fix.

I've now added the above comments to a comment in the file itself.  If
anyone intends to review that section, they will find the comment and a
pointer to this bug report.

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

From: Y. E. <yet <at> ego.team>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 8275 <at> debbugs.gnu.org, cyd <at> stupidchicken.com, monnier <at> iro.umontreal.ca,
 jearl <at> notengoamigos.org
Subject: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sun, 12 Dec 2021 08:50:16 +0200

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

>>> Do you want to fix this, or shall I try?  The problem is that
>>> append-to-buffer now uses let* and with-current-buffer, so this might
>>> break the flow of the text.  At this point in the book, let* and
>>> with-current-buffer are not yet introduced.

The current version of the 'append-to-buffer' section:
- Provides explanations based on the 'append-to-buffer' function
  definition from GNU Emacs 22, which uses 'let*' but not
  'with-current-buffer'.
- Already introduces 'let*'.

The suggested patch improves the flow of the text by re-organizing it to
correspond better the structure of the 'append-to-buffer' function and
providing more details about the 'let*' expression in it.

>> Here are some thoughts:
>> - I don't think it's of any importance that the example code be
>>   identical to the currently used code.

I also tend to think it should be fine to stick to some Emacs' version
(22 in this case) of the code, at least at this stage.

>> - append-to-buffer might not be the best example since AFAICT copying
>>   text from one buffer to another is not a common operation and in most
>>   cases this is done via buffer-substring + insert (often with some
>>   processing on the string between the two) rather than with
>>   insert-buffer-substring which is a rarely used function.
>> - yes, I think the text would benefit from some rethink to try and present
>>   with-current-buffer in preference to set-buffer, but it's not
>>   a simple fix.

The suggested patch concentrates on cleanups rather than rewrites,
because this may be a sufficient change (at this stage, again) and an
easier one to accomplish.

> I've now added the above comments to a comment in the file itself.  If
> anyone intends to review that section, they will find the comment and a
> pointer to this bug report.

The patch removes the mentioned comment since the suggested changes
cover fixing (or "wontfixing") the entries of the comment. A pointer to
this bug report was added to the suggested commit message.

[0001-Cleanup-append-to-buffer-section-in-ELisp-Intro.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Y. E." <yet <at> ego.team>
Cc: 8275 <at> debbugs.gnu.org, cyd <at> stupidchicken.com, stefan <at> marxist.se,
 monnier <at> iro.umontreal.ca, jearl <at> notengoamigos.org
Subject: Re: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sun, 12 Dec 2021 10:14:18 +0200

> Cc: 8275 <at> debbugs.gnu.org, cyd <at> stupidchicken.com, monnier <at> iro.umontreal.ca,
>  jearl <at> notengoamigos.org
> Date: Sun, 12 Dec 2021 08:50:16 +0200
> From:  Y. E. via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> The suggested patch concentrates on cleanups rather than rewrites,
> because this may be a sufficient change (at this stage, again) and an
> easier one to accomplish.
> 
> > I've now added the above comments to a comment in the file itself.  If
> > anyone intends to review that section, they will find the comment and a
> > pointer to this bug report.
> 
> The patch removes the mentioned comment since the suggested changes
> cover fixing (or "wontfixing") the entries of the comment. A pointer to
> this bug report was added to the suggested commit message.

Thanks, please see some comments below.

> -Here is the complete text of the function:
> +Here is the complete text of the function in GNU Emacs 22:

Instead of alluding to a past version of Emacs, how about saying
something more vague, like "a variant of the function", or "a possible
implementation of the function"?  The goal of this manual is not to
show actual code used by Emacs, it's to teach programming in Emacs
Lisp.  So whether this is, or was, an actual implementation is
immaterial from the didactic POV.

> -returned.  The second argument is the symbol for true, @code{t}. that
> +returned.  The second argument is the symbol for true: @code{t}, that

I think the correct fix here is to capitalize "That" (and add a
space), so that it's the next separate sentence.

> +@anchor{let* introduced}
> +@cindex @code{let*} expression
> +@findex let*

It isn't useful to have several index entries that begin with the same
text and point to the same place.  This manual has just one index,
where all the index entries are placed together.  So I suggest
removing one of these two index entries.

>  In this function, the body of the @code{save-excursion} contains only
>  one expression, the @code{let*} expression.  You know about a
> -@code{let} function.  The @code{let*} function is different.  It has a
> -@samp{*} in its name.  It enables Emacs to set each variable in its
> -varlist in sequence, one after another.
> +@code{let} function.  The @code{let*} function is different.  It
> +enables Emacs to set each variable in its varlist in sequence, one
> +after another; such that variables in the latter part of the varlist
> +can make use of the values to which Emacs set variables earlier in the
> +varlist.
>  
> -Its critical feature is that variables later in the varlist can make
> -use of the values to which Emacs set variables earlier in the varlist.
> -@xref{fwd-para let, , The @code{let*} expression}.

I don't understand the rationale for this change.  It looks like
simple rewording of the original, with different partition into
sentences.  I see nothing wrong with the original text, so why did you
need to change it?

> -We will skip functions like @code{let*} and focus on two: the
> -@code{set-buffer} function and the @code{insert-buffer-substring}
> -function.
> +@smallexample
> +@group
> +(let* ((append-to (get-buffer-create buffer))
> +       (windows (get-buffer-window-list append-to t t))
> +       point)
> +  BODY...)
> +@end group
> +@end smallexample
> +
> +@noindent
> +we see that @code{append-to} is bound to the value returned by the
> +@w{@code{(get-buffer-create buffer)}}. On the next line,
> +@code{append-to} is used as an argument to
> +@code{get-buffer-window-list}; this would not be possible with the
> +@code{let} expression.  Note that @code{point} is automatically bound
> +to @code{nil}, the same way as it would be done in the @code{let}
> +statement.
> +
> +Now let's focus on the functions @code{set-buffer} and
> +@code{insert-buffer-substring} in the body of the @code{let*}
> +expression.

So, unlike the original author, you consider it important to explain
the let* part here?  Why is that?

> @@ -5394,6 +5352,12 @@ Buffer Related Review
>  @item mark-whole-buffer
>  Mark the whole buffer as a region.  Normally bound to @kbd{C-x h}.
>  
> +@item let*
> +Declare a list of variables and give them an initial value; then
> +evaluate the rest of the expressions in the body of @code{let*}.  The
> +values of the variables can be used to bind ensuing variables in the
> +list.
> +
>  @item set-buffer
>  Switch the attention of Emacs to another buffer, but do not change the
>  window being displayed.  Used when the program rather than a human is
> @@ -12896,25 +12860,12 @@ forward-paragraph in brief
>  @node fwd-para let
>  @unnumberedsubsec The @code{let*} expression
>  
> -The next line of the @code{forward-paragraph} function begins a
> -@code{let*} expression.  This is different from @code{let}.  The
> -symbol is @code{let*} not @code{let}.
> -
>  @findex let*
> -The @code{let*} special form is like @code{let} except that Emacs sets
> -each variable in sequence, one after another, and variables in the
> -latter part of the varlist can make use of the values to which Emacs
> -set variables in the earlier part of the varlist.
> -
> -@ignore
> -( refappend save-excursion, , code save-excursion in code append-to-buffer .)
> -@end ignore
> -
> -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
> -
> -In the @code{let*} expression in this function, Emacs binds a total of
> -seven variables:  @code{opoint}, @code{fill-prefix-regexp},
> -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
> +The next line of the @code{forward-paragraph} function begins a
> +@code{let*} expression (@pxref{let* introduced,,@code{let*}
> +introduced}), in which Emacs binds a total of seven variables:
> +@code{opoint}, @code{fill-prefix-regexp}, @code{parstart},
> +@code{parsep}, @code{sp-parstart}, @code{start}, and
>  @code{found-start}.

This seems to move the description of let* to an earlier part of the
manual.  Once again, I ask: what's the rationale for the change in the
order?

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

From: Y. E. <yet <at> ego.team>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 8275 <at> debbugs.gnu.org, cyd <at> stupidchicken.com, stefan <at> marxist.se,
 monnier <at> iro.umontreal.ca, yet <at> ego.team, jearl <at> notengoamigos.org
Subject: Re: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Tue, 14 Dec 2021 14:52:51 +0200

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

Eli Zaretskii <eliz <at> gnu.org> writes:
>> -Here is the complete text of the function:
>> +Here is the complete text of the function in GNU Emacs 22:
>
> Instead of alluding to a past version of Emacs, how about saying
> something more vague, like "a variant of the function", or "a possible
> implementation of the function"?

Done.

Note that the style of the patch was based on the existing texts. Should
I create a bug report (maybe with a patch) asking to replace other 'In
GNU Emacs 22' phrases used in the same context?

________________

> The goal of this manual is not to
> show actual code used by Emacs, it's to teach programming in Emacs
> Lisp.
If this is true, then the manual has to be re-written very deeply.
Currently, the manual promises (and often does) to show actual code
usage. Citing `(eintr) On Reading this Text':

> Much of this introduction is dedicated to walkthroughs or guided
> tours of code used in GNU Emacs.  These tours are designed for two
> purposes: first, to give you familiarity with real, working code (code
> you use every day); and, second, to give you familiarity with the way
> Emacs works.

[I personally prefer what the manual promises (mostly does) now.]

________________

>> -returned.  The second argument is the symbol for true, @code{t}. that
>> +returned.  The second argument is the symbol for true: @code{t}, that
>
> I think the correct fix here is to capitalize "That" (and add a
> space), so that it's the next separate sentence.

Done.

________________


>> +@anchor{let* introduced}
>> +@cindex @code{let*} expression
>> +@findex let*
>
> It isn't useful to have several index entries that begin with the same
> text and point to the same place.  This manual has just one index,
> where all the index entries are placed together.  So I suggest
> removing one of these two index entries.

Thanks, removed.

________________

> This seems to move the description of let* to an earlier part of the
> manual.
The description of 'let*' is *already* in the earlier part of the
manual. (The patch is based on the current version.)

> Once again, I ask: what's the rationale for the change in the
> order?

The following is the order of the occurrences of 'let*' in the manual:

1. 'let*' is defined in `(eintr) append-to-buffer overview',

2. Then it's mentioned in the code and text of the `(eintr) kill-append
function',

3. Then it's mentioned in the intro text of `(eintr) forward-paragraph',

4. Then it's defined for the second time in `(eintr) fwd-para let',
using the same words and phrases as in the 1st occurrence.

Therefore, it seems to be more comprehensible for a reader to be
introduced to 'let*' (in a more clear manner than it is now) on the 1st
of the listed occurrences, rather than on the 4th.


Anyway, if there's a strong opinion 'let*' has to be introduced in
`(eintr) fwd-para let' and not earlier, then I'd suggest scratching out
the mentions of 'let*' from all the earlier parts altogether (or limit
them to a bare minimum and reference to the definition).

I'm fine with either (or any other) as long as the text of the manual
reads smoothly and doesn't contain unnecessary duplications.

[0001-Cleanup-append-to-buffer-section-in-ELisp-Intro.patch (text/x-patch, attachment)]

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

From: Richard Stallman <rms <at> gnu.org>
To: "Y. E." <yet <at> ego.team>
Cc: 8275 <at> debbugs.gnu.org, cyd <at> stupidchicken.com, stefan <at> marxist.se,
 jearl <at> notengoamigos.org, monnier <at> iro.umontreal.ca, eliz <at> gnu.org, yet <at> ego.team
Subject: Re: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Wed, 15 Dec 2021 23:38:42 -0500

[[[ 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. ]]]

  > > The goal of this manual is not to
  > > show actual code used by Emacs, it's to teach programming in Emacs
  > > Lisp.

That is basically true, but perhaps a little too strongly put.
Teaching programming in Emacs Lisp is the primary goal.

  > Currently, the manual promises (and often does) to show actual code
  > usage. Citing `(eintr) On Reading this Text':

That is also true.  That is another nice thing that the manual does
"along the way."

It is fine to say "this is the code of function foo in Emacs 22", in
case years later someone reads that text when Emacs 32 is current, so
perse will understand why this example does not show the current Emacs
code.

Would it be better to update the manual to use the Emacs 32 code as an
example?  Maybe.

The advantage is, that it will show the code of the current Emacs.
The disadvantages are,

(1) updating the explanation is work, and needs a good writer,

(2) the newer code may be longer and more complex, so that it will be
more work to understand, and thus not as good for the manual's primary
goal,

(3) the newer code might be changed so much that it is no longer an
example of the feature to be illustrated.

When that last happens, it is possible to find and use a different
piece of code in Emacs.  But that's even more work.  Maybe the best
choice is to keep the Emacs 22 code as the example.

This partly depends on whether a good writer is available.  We don't
have anyone now who writes as well as Bob Chassell.

If you want to aim to develop your skills, by all means do -- but that
calls for getting lots of careful feedback from thoughtful readers
willing to spend time critiquing your writing.  Almost nobody gets to
be that good without doihg lots of writing and getting lots if
critiques.  On manuals I've written, I have generally got dozens of
people to read them carefully to report small points that were not
entirely clear.

Sometimes I would ask what makes a certain piece of text unclear, and
discuss possible improvements.

From each critique I addressed, I learned.  If you take this path,
you'll keep getting gradually better at writing.  But the path is long.

-- 
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)

Message #43 received at 8275-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Y. E. <yet <at> ego.team>
Cc: 8275-done <at> debbugs.gnu.org, cyd <at> stupidchicken.com, stefan <at> marxist.se,
 monnier <at> iro.umontreal.ca, jearl <at> notengoamigos.org
Subject: Re: bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue
Date: Sat, 18 Dec 2021 16:27:40 +0200

> From: Y. E. <yet <at> ego.team>
> Cc: yet <at> ego.team, stefan <at> marxist.se, 8275 <at> debbugs.gnu.org,
>  cyd <at> stupidchicken.com,
> 	monnier <at> iro.umontreal.ca, jearl <at> notengoamigos.org
> Date: Tue, 14 Dec 2021 14:52:51 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> >> -Here is the complete text of the function:
> >> +Here is the complete text of the function in GNU Emacs 22:
> >
> > Instead of alluding to a past version of Emacs, how about saying
> > something more vague, like "a variant of the function", or "a possible
> > implementation of the function"?
> 
> Done.
> 
> Note that the style of the patch was based on the existing texts. Should
> I create a bug report (maybe with a patch) asking to replace other 'In
> GNU Emacs 22' phrases used in the same context?
> 
> ________________
> 
> > The goal of this manual is not to
> > show actual code used by Emacs, it's to teach programming in Emacs
> > Lisp.
> If this is true, then the manual has to be re-written very deeply.
> Currently, the manual promises (and often does) to show actual code
> usage. Citing `(eintr) On Reading this Text':
> 
> > Much of this introduction is dedicated to walkthroughs or guided
> > tours of code used in GNU Emacs.  These tours are designed for two
> > purposes: first, to give you familiarity with real, working code (code
> > you use every day); and, second, to give you familiarity with the way
> > Emacs works.
> 
> [I personally prefer what the manual promises (mostly does) now.]
> 
> ________________
> 
> >> -returned.  The second argument is the symbol for true, @code{t}. that
> >> +returned.  The second argument is the symbol for true: @code{t}, that
> >
> > I think the correct fix here is to capitalize "That" (and add a
> > space), so that it's the next separate sentence.
> 
> Done.
> 
> ________________
> 
> 
> >> +@anchor{let* introduced}
> >> +@cindex @code{let*} expression
> >> +@findex let*
> >
> > It isn't useful to have several index entries that begin with the same
> > text and point to the same place.  This manual has just one index,
> > where all the index entries are placed together.  So I suggest
> > removing one of these two index entries.
> 
> Thanks, removed.
> 
> ________________
> 
> > This seems to move the description of let* to an earlier part of the
> > manual.
> The description of 'let*' is *already* in the earlier part of the
> manual. (The patch is based on the current version.)
> 
> > Once again, I ask: what's the rationale for the change in the
> > order?
> 
> The following is the order of the occurrences of 'let*' in the manual:
> 
> 1. 'let*' is defined in `(eintr) append-to-buffer overview',
> 
> 2. Then it's mentioned in the code and text of the `(eintr) kill-append
> function',
> 
> 3. Then it's mentioned in the intro text of `(eintr) forward-paragraph',
> 
> 4. Then it's defined for the second time in `(eintr) fwd-para let',
> using the same words and phrases as in the 1st occurrence.
> 
> Therefore, it seems to be more comprehensible for a reader to be
> introduced to 'let*' (in a more clear manner than it is now) on the 1st
> of the listed occurrences, rather than on the 4th.
> 
> 
> Anyway, if there's a strong opinion 'let*' has to be introduced in
> `(eintr) fwd-para let' and not earlier, then I'd suggest scratching out
> the mentions of 'let*' from all the earlier parts altogether (or limit
> them to a bare minimum and reference to the definition).
> 
> I'm fine with either (or any other) as long as the text of the manual
> reads smoothly and doesn't contain unnecessary duplications.

Thanks, I installed this on the master branch, and I'm closing this
bug.

Previous Next

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