* bug#8275: 24.0.50; Intro to Emacs Lisp Issue @ 2011-03-17 17:35 Jason Earl 2011-03-19 21:58 ` Chong Yidong 0 siblings, 1 reply; 11+ messages in thread From: Jason Earl @ 2011-03-17 17:35 UTC (permalink / raw) To: 8275 (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) ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2011-03-17 17:35 bug#8275: 24.0.50; Intro to Emacs Lisp Issue Jason Earl @ 2011-03-19 21:58 ` Chong Yidong 2011-03-20 1:06 ` Robert J. Chassell 2011-03-20 3:34 ` Stefan Monnier 0 siblings, 2 replies; 11+ messages in thread From: Chong Yidong @ 2011-03-19 21:58 UTC (permalink / raw) To: Robert J. Chassell; +Cc: 8275, Jason Earl 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@notengoamigos.org> writes: > (info "(eintr) append-to-buffer overview") covers a previous version of > append-to-buffer. ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2011-03-19 21:58 ` Chong Yidong @ 2011-03-20 1:06 ` Robert J. Chassell 2011-03-20 3:34 ` Stefan Monnier 1 sibling, 0 replies; 11+ messages in thread From: Robert J. Chassell @ 2011-03-20 1:06 UTC (permalink / raw) To: Chong Yidong; +Cc: 8275, bob, jearl 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@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@gnu.org bob@rattlesnake.com http://www.rattlesnake.com http://www.teak.cc ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2011-03-19 21:58 ` Chong Yidong 2011-03-20 1:06 ` Robert J. Chassell @ 2011-03-20 3:34 ` Stefan Monnier 2011-03-20 21:20 ` Andreas Röhler 2021-10-21 19:42 ` Stefan Kangas 1 sibling, 2 replies; 11+ messages in thread From: Stefan Monnier @ 2011-03-20 3:34 UTC (permalink / raw) To: Chong Yidong; +Cc: 8275, Robert J. Chassell, Jason Earl > 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2011-03-20 3:34 ` Stefan Monnier @ 2011-03-20 21:20 ` Andreas Röhler 2021-10-21 19:42 ` Stefan Kangas 1 sibling, 0 replies; 11+ messages in thread From: Andreas Röhler @ 2011-03-20 21:20 UTC (permalink / raw) To: bug-gnu-emacs 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2011-03-20 3:34 ` Stefan Monnier 2011-03-20 21:20 ` Andreas Röhler @ 2021-10-21 19:42 ` Stefan Kangas 2021-12-12 6:50 ` bug#8275: [PATCH] " Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 1 sibling, 1 reply; 11+ messages in thread From: Stefan Kangas @ 2021-10-21 19:42 UTC (permalink / raw) To: Stefan Monnier; +Cc: 8275-done, Chong Yidong, Jason Earl Stefan Monnier <monnier@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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2021-10-21 19:42 ` Stefan Kangas @ 2021-12-12 6:50 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-12-12 8:14 ` Eli Zaretskii 0 siblings, 1 reply; 11+ messages in thread From: Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-12 6:50 UTC (permalink / raw) To: Stefan Kangas; +Cc: 8275, cyd, monnier, jearl [-- Attachment #1: Type: text/plain, Size: 2011 bytes --] >>> 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. [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: Cleanup append-to-buffer section in ELisp Intro --] [-- Type: text/x-patch, Size: 9704 bytes --] From 5c9495b5db9ecf168333d589260601948e26bfd8 Mon Sep 17 00:00:00 2001 From: YugaEgo <yet@ego.team> Date: Fri, 10 Dec 2021 23:29:51 +0200 Subject: [PATCH] Cleanup append-to-buffer section in ELisp Intro * doc/lispintro/emacs-lisp-intro.texi (append-to-buffer, Buffer Related Review, fwd-para let): Finalize shifting focus of the 'let*' introduction to the 'append-to-buffer' section. Improve wording, fix typos, remove redundant comments (Bug#8275). --- doc/lispintro/emacs-lisp-intro.texi | 147 ++++++++++------------------ 1 file changed, 49 insertions(+), 98 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 9f1f10e8d6..737749c625 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -4896,25 +4896,6 @@ Body of mark-whole-buffer is set at the end of the buffer. The whole buffer is, therefore, the region. -@c FIXME: the definition of append-to-buffer has been changed (in -@c 2010-03-30). -@c In Bug#8275, Stefan Monner <monnier@iro.umontreal.ca> writes: -@c >> Do you want to fix this, or shall I try? The problem is that -@c >> append-to-buffer now uses let* and with-current-buffer, so this might -@c >> break the flow of the text. At this point in the book, let* and -@c >> with-current-buffer are not yet introduced. -@c > -@c > Here are some thoughts: -@c > - I don't think it's of any importance that the example code be -@c > identical to the currently used code. -@c > - append-to-buffer might not be the best example since AFAICT copying -@c > text from one buffer to another is not a common operation and in most -@c > cases this is done via buffer-substring + insert (often with some -@c > processing on the string between the two) rather than with -@c > insert-buffer-substring which is a rarely used function. -@c > - yes, I think the text would benefit from some rethink to try and present -@c > with-current-buffer in preference to set-buffer, but it's not -@c > a simple fix. @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4949,7 +4930,7 @@ append-to-buffer overview to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is the complete text of the function in GNU Emacs 22: @smallexample @group @@ -5017,7 +4998,9 @@ append interactive Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5046,7 +5029,7 @@ append interactive The first argument to @code{other-buffer}, the exception, is yet another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that +returned. The second argument is the symbol for true: @code{t}, that tells @code{other-buffer} that it may show visible buffers (except in this case, it will not show the current buffer, which makes sense). @@ -5082,33 +5065,6 @@ append interactive @node append-to-buffer body @subsection The Body of @code{append-to-buffer} -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5127,7 +5083,7 @@ append-to-buffer body "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5247,19 +5203,40 @@ append save-excursion @need 1200 @noindent +@anchor{let* introduced} +@cindex @code{let*} expression +@findex let* 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}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -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. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5277,27 +5254,8 @@ append save-excursion @end smallexample @noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens 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}. The variable @code{parsep} appears twice, first, to remove instances -- 2.34.1 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2021-12-12 6:50 ` bug#8275: [PATCH] " Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-12 8:14 ` Eli Zaretskii 2021-12-14 12:52 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 0 siblings, 1 reply; 11+ messages in thread From: Eli Zaretskii @ 2021-12-12 8:14 UTC (permalink / raw) To: Y. E.; +Cc: 8275, cyd, stefan, monnier, jearl > Cc: 8275@debbugs.gnu.org, cyd@stupidchicken.com, monnier@iro.umontreal.ca, > jearl@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@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? ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2021-12-12 8:14 ` Eli Zaretskii @ 2021-12-14 12:52 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-12-16 4:38 ` Richard Stallman 2021-12-18 14:27 ` Eli Zaretskii 0 siblings, 2 replies; 11+ messages in thread From: Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-14 12:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 8275, cyd, stefan, monnier, yet, jearl [-- Attachment #1: Type: text/plain, Size: 3169 bytes --] Eli Zaretskii <eliz@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. [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: Cleanup append-to-buffer section in ELisp Intro --] [-- Type: text/x-patch, Size: 9726 bytes --] From e1c2f3d92ae7a82ba98b7849647bb3940afa0e8c Mon Sep 17 00:00:00 2001 From: YugaEgo <yet@ego.team> Date: Fri, 10 Dec 2021 23:29:51 +0200 Subject: [PATCH] Cleanup append-to-buffer section in ELisp Intro * doc/lispintro/emacs-lisp-intro.texi (append-to-buffer, Buffer Related Review, fwd-para let): Finalize shifting focus of the 'let*' introduction to the 'append-to-buffer' section. Improve wording, fix typos, remove redundant comments (Bug#8275). --- doc/lispintro/emacs-lisp-intro.texi | 147 ++++++++++------------------ 1 file changed, 49 insertions(+), 98 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 9f1f10e8d6..43f1c2ddd5 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -4896,25 +4896,6 @@ Body of mark-whole-buffer is set at the end of the buffer. The whole buffer is, therefore, the region. -@c FIXME: the definition of append-to-buffer has been changed (in -@c 2010-03-30). -@c In Bug#8275, Stefan Monner <monnier@iro.umontreal.ca> writes: -@c >> Do you want to fix this, or shall I try? The problem is that -@c >> append-to-buffer now uses let* and with-current-buffer, so this might -@c >> break the flow of the text. At this point in the book, let* and -@c >> with-current-buffer are not yet introduced. -@c > -@c > Here are some thoughts: -@c > - I don't think it's of any importance that the example code be -@c > identical to the currently used code. -@c > - append-to-buffer might not be the best example since AFAICT copying -@c > text from one buffer to another is not a common operation and in most -@c > cases this is done via buffer-substring + insert (often with some -@c > processing on the string between the two) rather than with -@c > insert-buffer-substring which is a rarely used function. -@c > - yes, I think the text would benefit from some rethink to try and present -@c > with-current-buffer in preference to set-buffer, but it's not -@c > a simple fix. @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4949,8 +4930,9 @@ append-to-buffer overview to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is a possible implementation of the function: +@c GNU Emacs 22 @smallexample @group (defun append-to-buffer (buffer start end) @@ -5017,7 +4999,9 @@ append interactive Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5046,7 +5030,7 @@ append interactive The first argument to @code{other-buffer}, the exception, is yet another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that +returned. The second argument is the symbol for true, @code{t}. That tells @code{other-buffer} that it may show visible buffers (except in this case, it will not show the current buffer, which makes sense). @@ -5082,33 +5066,6 @@ append interactive @node append-to-buffer body @subsection The Body of @code{append-to-buffer} -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5127,7 +5084,7 @@ append-to-buffer body "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5247,19 +5204,39 @@ append save-excursion @need 1200 @noindent +@anchor{let* introduced} +@findex let* 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}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -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. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5277,27 +5254,8 @@ append save-excursion @end smallexample @noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens 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}. The variable @code{parsep} appears twice, first, to remove instances -- 2.34.1 ^ permalink raw reply related [flat|nested] 11+ messages in thread
* bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2021-12-14 12:52 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2021-12-16 4:38 ` Richard Stallman 2021-12-18 14:27 ` Eli Zaretskii 1 sibling, 0 replies; 11+ messages in thread From: Richard Stallman @ 2021-12-16 4:38 UTC (permalink / raw) To: Y. E.; +Cc: 8275, cyd, stefan, monnier, yet, jearl [[[ 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) ^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#8275: [PATCH] Re: bug#8275: 24.0.50; Intro to Emacs Lisp Issue 2021-12-14 12:52 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-12-16 4:38 ` Richard Stallman @ 2021-12-18 14:27 ` Eli Zaretskii 1 sibling, 0 replies; 11+ messages in thread From: Eli Zaretskii @ 2021-12-18 14:27 UTC (permalink / raw) To: Y. E.; +Cc: 8275-done, cyd, stefan, monnier, jearl > From: Y. E. <yet@ego.team> > Cc: yet@ego.team, stefan@marxist.se, 8275@debbugs.gnu.org, > cyd@stupidchicken.com, > monnier@iro.umontreal.ca, jearl@notengoamigos.org > Date: Tue, 14 Dec 2021 14:52:51 +0200 > > Eli Zaretskii <eliz@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. ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2021-12-18 14:27 UTC | newest] Thread overview: 11+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2011-03-17 17:35 bug#8275: 24.0.50; Intro to Emacs Lisp Issue Jason Earl 2011-03-19 21:58 ` Chong Yidong 2011-03-20 1:06 ` Robert J. Chassell 2011-03-20 3:34 ` Stefan Monnier 2011-03-20 21:20 ` Andreas Röhler 2021-10-21 19:42 ` Stefan Kangas 2021-12-12 6:50 ` bug#8275: [PATCH] " Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-12-12 8:14 ` Eli Zaretskii 2021-12-14 12:52 ` Y. E. via Bug reports for GNU Emacs, the Swiss army knife of text editors 2021-12-16 4:38 ` Richard Stallman 2021-12-18 14:27 ` Eli Zaretskii
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.