diff options
Diffstat (limited to 'doc/lispintro')
| -rw-r--r-- | doc/lispintro/.gitignore | 21 | ||||
| -rw-r--r-- | doc/lispintro/ChangeLog.1 (renamed from doc/lispintro/ChangeLog) | 157 | ||||
| -rw-r--r-- | doc/lispintro/Makefile.in | 119 | ||||
| -rw-r--r-- | doc/lispintro/README | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-1.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-2.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-2a.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-3.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-4.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/cons-5.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/drawers.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/emacs-lisp-intro.texi | 990 | ||||
| -rw-r--r-- | doc/lispintro/lambda-1.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/lambda-2.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/lambda-3.eps | 2 | ||||
| -rw-r--r-- | doc/lispintro/makefile.w32-in | 85 |
16 files changed, 711 insertions, 683 deletions
diff --git a/doc/lispintro/.gitignore b/doc/lispintro/.gitignore deleted file mode 100644 index e1af5a918b0..00000000000 --- a/doc/lispintro/.gitignore +++ /dev/null @@ -1,21 +0,0 @@ -*.aux -*.fn -*.fns -*.cps -*.cp -*.kys -*.ky -*.toc -*.pgs -*.pg -*.log -*.vrs -*.vr -*.dvi -*.ps -*.tp -*.tps -*.tmp -*.txt -Makefile -makefile diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog.1 index db02a257a3a..c54c165d22c 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog.1 @@ -1,3 +1,126 @@ +2015-03-25 Stefan Monnier <monnier@iro.umontreal.ca> + + * emacs-lisp-intro.texi: `save-excursion' doesn't save&restore the mark. + +2014-12-31 Paul Eggert <eggert@cs.ucla.edu> + + Less 'make' chatter for Emacs doc + * Makefile.in (AM_DEFAULT_VERBOSITY, AM_V_GEN, am__v_GEN_) + (am__v_GEN_0, am__v_GEN_1): New macros, from ../../src/Makefile.in. + (ENVADD, $(buildinfodir)/eintr.info, emacs-lisp-intro.html): + Use them. + +2014-11-09 Glenn Morris <rgm@gnu.org> + + * Makefile.in (version): Remove variable. + (clean): No longer delete dist tarfile. + (dist): Remove rule; replace with code in admin.el. + +2014-10-20 Glenn Morris <rgm@gnu.org> + + * Merge in all changes up to 24.4 release. + +2014-10-13 Glenn Morris <rgm@gnu.org> + + * Makefile.in (dist): Update for new output variables. + +2014-07-16 Álvar Jesús Ibeas Martín <alvar.ibeas@unican.es> (tiny change) + + * emacs-lisp-intro.texi (Variables, Buffer Names, if & or) + (Symbols as Chest, fwd-para while): Fix typos. + +2014-07-03 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Note for Novices, Finding More, Conclusion): + "Online" help doesn't mean what it used to any more. + +2014-06-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (%.texi): Disable implicit rules. + (mkinfodir): Remove. + (.dvi.ps): Replace with explicit rule. + (${buildinfodir}): New rule. + (${buildinfodir}/eintr.info): Use order-only prereq for output dir. + Use $<. + (emacs-lisp-intro.dvi, emacs-lisp-intro.pdf, emacs-lisp-intro.html): + Use $<. + (emacs-lisp-intro.ps): New rule. + +2014-06-15 Glenn Morris <rgm@gnu.org> + + * Makefile.in (bootstrap-clean): New. + +2014-06-10 Glenn Morris <rgm@gnu.org> + + * Makefile.in (INFO_EXT): Remove and replace by ".info" throughout. + (INFO_OPTS): Set directly rather than with configure. + +2014-06-02 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Autoload): Update loaddefs.el details. + +2014-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (infoclean): Be consistent about reporting failures. + +2014-02-25 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (X11 Colors): Don't use setq with hooks. + +2014-02-06 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (Recursive Patterns): + Do not use colons in index entries. + +2014-01-23 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (lengths-list-file): Fix textual parentheses. + +2013-12-30 Paul Eggert <eggert@cs.ucla.edu> + + Specify .texi encoding (Bug#16292). + * emacs-lisp-intro.texi: Add @documentencoding. + +2013-12-30 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi: Use @quotation for license notice. + +2013-12-12 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi: Tweak dircategory. + + * emacs-lisp-intro.texi: Sync direntry with info/dir version. + +2013-12-02 Paul Eggert <eggert@cs.ucla.edu> + + * emacs-lisp-intro.texi (Counting Words): Don't use ':' in xref + titles, as this isn't supported by Texinfo. + +2013-11-30 Glenn Morris <rgm@gnu.org> + + * Makefile.in (distclean): Remove Makefile. + +2013-10-23 Glenn Morris <rgm@gnu.org> + + * Makefile.in (install-dvi, install-html, install-pdf) + (install-ps, uninstall-dvi, uninstall-html, uninstall-ps) + (uninstall-pdf): Quote entities that might contain whitespace. + +2013-09-01 Glenn Morris <rgm@gnu.org> + + * emacs-lisp-intro.texi (beginning-of-buffer complete): + Put back a version of the removed paragraph about raw prefix arg. + +2013-09-01 Dani Moncayo <dmoncayo@gmail.com> + + * emacs-lisp-intro.texi (beginning-of-buffer complete): + Update function details. (Bug#15085) + +2013-08-28 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in (SHELL): Now @SHELL@, not /bin/sh, + for portability to hosts where /bin/sh has problems. + 2013-08-12 Glenn Morris <rgm@gnu.org> * emacs-lisp-intro.texi (Complete copy-region-as-kill): Fix typo. @@ -15,8 +138,8 @@ (emacs-lisp-intro.ps): Remove explicit rule. (emacs-lisp-intro.html): Use HTML_OPTS. (clean): Use DVI_TARGETS, HTML_TARGETS, PDF_TARGETS, PS_TARGETS. - (.PHONY): install-dvi, install-html, install-pdf, install-ps - ,install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, + (.PHONY): install-dvi, install-html, install-pdf, install-ps, + install-doc, uninstall-dvi, uninstall-html, uninstall-pdf, uninstall-ps, and uninstall-doc. (install-dvi, install-html, install-pdf, install-ps, install-doc) (uninstall-dvi, uninstall-html, uninstall-ps, uninstall-pdf) @@ -470,8 +593,8 @@ 2006-11-05 Robert J. Chassell <bob@rattlesnake.com> * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning + (defcustom): Said that `:options' is usually for a hook. + Remove extraneous space in parenthetical remark concerning `text-mode-hook-identify'. At end, mention other defines, too. (Beginning a .emacs File): Reverse words about comments so they parallel numbers of listed semi-colons. @@ -493,12 +616,12 @@ Center images for TeX output. (kill-new function): Remove indentation for sentence talking about momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. + (cons & search-fwd Review): Document @code{funcall}. + Document @code{re-search-forward} with existing @code{search-forward}. Reference chapter on regular expression searches. (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. + (Recursion with list, Every, recursive-graph-body-print): + Change `if ... progn' expression to `when'. (Recursive triangle function): For printing in small book, ensure section name is not last on bottom of preceding page. (Keep): Remove extraneous space in function definition example. @@ -507,11 +630,11 @@ function. (fwd-sentence while loops): Write a function as one, not as a form. (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. + (etags): Move sentences involving `find-tag' and sources. + State location of Emacs `src' directory. (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. + (Find a File): Fix grammar; add a `to' and write `to visit'. + Change `named' to `selected'. (lengths-list-file): Remove extraneous parenthesis from reference. (lengths-list-many-files): Explain `expand-file-name' better. (Files List): Rephrase sentence regarding Lisp sources directory. @@ -539,8 +662,8 @@ seen' the @code{eq} function. (kill-append function): Reformat `kill-append' function definition so it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete + (kill-new function): Indent the sentence beginning `notice'. + Replace `the same as' with `similar to'. Repair typo. Remove obsolete references to `yank' and `yank-pop. End section with a note that `we will digress into C.' @@ -564,8 +687,8 @@ is 3.00. Did not update ISBN number. * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. + Document `='. Remove mention that :eval was new in 21. + Updated instance's edition-number to 3.01. 2006-10-30 Robert J. Chassell <bob@rattlesnake.com> @@ -659,7 +782,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2001-2013 Free Software Foundation, Inc. + Copyright (C) 2001-2015 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index ad1b978f255..d1a696ce2c2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994-1999, 2001-2013 Free Software Foundation, Inc. +# Copyright (C) 1994-1999, 2001-2015 Free Software Foundation, Inc. # This file is part of GNU Emacs. @@ -17,17 +17,14 @@ # You should have received a copy of the GNU General Public License # along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. -SHELL = /bin/sh +SHELL = @SHELL@ -# NB If you add any more configure variables, -# update the sed rules in the dist target below. srcdir = @srcdir@ -version=@version@ buildinfodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. +# Directory with docstyle.texi and emacsver.texi. emacsdir = $(srcdir)/../emacs prefix = @prefix@ @@ -46,9 +43,8 @@ GZIP_PROG = @GZIP_PROG@ HTML_OPTS = --no-split --html -INFO_EXT=@INFO_EXT@ # Options used only when making info output. -INFO_OPTS=@INFO_OPTS@ +INFO_OPTS= --no-split INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ @@ -59,50 +55,58 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ - MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" +# 'make' verbosity. +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ + +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = + +ENVADD = \ + $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(emacsdir):$(TEXINPUTS)" \ + MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs-lisp-intro.dvi HTML_TARGETS = emacs-lisp-intro.html PDF_TARGETS = emacs-lisp-intro.pdf PS_TARGETS = emacs-lisp-intro.ps -mkinfodir = @${MKDIR_P} ${buildinfodir} - srcs = ${srcdir}/emacs-lisp-intro.texi ${srcdir}/doclicense.texi \ - ${emacsdir}/emacsver.texi + ${emacsdir}/docstyle.texi ${emacsdir}/emacsver.texi -.PHONY: info dvi html pdf ps - -.SUFFIXES: .ps .dvi +## Disable implicit rules. +%.texi: ; -.dvi.ps: - $(DVIPS) -o $@ $< - -info: ${buildinfodir}/eintr$(INFO_EXT) +.PHONY: info dvi html pdf ps +info: ${buildinfodir}/eintr.info dvi: $(DVI_TARGETS) html: $(HTML_TARGETS) pdf: $(PDF_TARGETS) ps: $(PS_TARGETS) +${buildinfodir}: + ${MKDIR_P} $@ + # The file name eintr must fit within 5 characters, to allow for # -NN extensions to fit into DOS 8+3 limits without clashing. -# Note: "<" is not portable in ordinary make rules. -${buildinfodir}/eintr$(INFO_EXT): ${srcs} - $(mkinfodir) - $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi +${buildinfodir}/eintr.info: ${srcs} | ${buildinfodir} + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ $< emacs-lisp-intro.dvi: ${srcs} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2DVI) $< emacs-lisp-intro.pdf: ${srcs} - $(ENVADD) $(TEXI2PDF) ${srcdir}/emacs-lisp-intro.texi + $(ENVADD) $(TEXI2PDF) $< emacs-lisp-intro.html: ${srcs} - $(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ ${srcdir}/emacs-lisp-intro.texi + $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< + +emacs-lisp-intro.ps: emacs-lisp-intro.dvi + $(DVIPS) -o $@ $< -.PHONY: mostlyclean clean distclean maintainer-clean infoclean +.PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean mostlyclean: rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ @@ -110,56 +114,35 @@ mostlyclean: clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) - rm -f emacs-lispintro-${version}.tar* distclean: clean + rm -f Makefile infoclean: - -cd $(buildinfodir) && rm -f eintr$(INFO_EXT) eintr$(INFO_EXT)-[1-9] - -maintainer-clean: distclean infoclean - -.PHONY: dist - -dist: - rm -rf emacs-lispintro-${version} - mkdir emacs-lispintro-${version} - cp ${srcdir}/*.texi ${srcdir}/*.eps ${srcdir}/*.pdf \ - ${texinfodir}/texinfo.tex ${emacsdir}/emacsver.texi \ - ${srcdir}/ChangeLog* ${srcdir}/README emacs-lispintro-${version}/ - sed -e 's/@sr[c]dir@/./' -e 's/^\(texinfodir *=\).*/\1 ./' \ - -e 's/^\(emacsdir *=\).*/\1 ./' \ - -e 's/^\(buildinfodir *=\).*/\1 ./' \ - -e 's/^\(clean:.*\)/\1 infoclean/' \ - -e "s/@ver[s]ion@/${version}/" \ - -e 's/@MAKE[I]NFO@/makeinfo/' -e 's/@MK[D]IR_P@/mkdir -p/' \ - -e 's/@IN[F]O_EXT@/.info/' -e 's/@IN[F]O_OPTS@//' \ - ${srcdir}/Makefile.in > emacs-lispintro-${version}/Makefile - @if grep '@[a-zA-Z_]*@' emacs-lispintro-${version}/Makefile; then \ - echo "Unexpanded configure variables in Makefile?" 1>&2; exit 1; \ - fi - tar -cf emacs-lispintro-${version}.tar emacs-lispintro-${version} - rm -rf emacs-lispintro-${version} + rm -f \ + $(buildinfodir)/eintr.info \ + $(buildinfodir)/eintr.info-[1-9] +bootstrap-clean maintainer-clean: distclean infoclean .PHONY: install-dvi install-html install-pdf install-ps install-doc install-dvi: dvi - umask 022; $(MKDIR_P) $(DESTDIR)$(dvidir) - $(INSTALL_DATA) $(DVI_TARGETS) $(DESTDIR)$(dvidir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(dvidir)" + $(INSTALL_DATA) $(DVI_TARGETS) "$(DESTDIR)$(dvidir)" install-html: html - umask 022; $(MKDIR_P) $(DESTDIR)$(htmldir) - $(INSTALL_DATA) $(HTML_TARGETS) $(DESTDIR)$(htmldir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(htmldir)" + $(INSTALL_DATA) $(HTML_TARGETS) "$(DESTDIR)$(htmldir)" install-pdf: pdf - umask 022;$(MKDIR_P) $(DESTDIR)$(pdfdir) - $(INSTALL_DATA) $(PDF_TARGETS) $(DESTDIR)$(pdfdir) + umask 022;$(MKDIR_P) "$(DESTDIR)$(pdfdir)" + $(INSTALL_DATA) $(PDF_TARGETS) "$(DESTDIR)$(pdfdir)" install-ps: ps - umask 022; $(MKDIR_P) $(DESTDIR)$(psdir) + umask 022; $(MKDIR_P) "$(DESTDIR)$(psdir)" for file in $(PS_TARGETS); do \ - $(INSTALL_DATA) $${file} $(DESTDIR)$(psdir); \ + $(INSTALL_DATA) $${file} "$(DESTDIR)$(psdir)"; \ [ -n "${GZIP_PROG}" ] || continue; \ - rm -f $(DESTDIR)$(psdir)/$${file}.gz; \ - ${GZIP_PROG} -9n $(DESTDIR)$(psdir)/$${file}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}.gz"; \ + ${GZIP_PROG} -9n "$(DESTDIR)$(psdir)/$${file}"; \ done ## Top-level Makefile installs the info pages. @@ -170,20 +153,20 @@ install-doc: install-dvi install-html install-pdf install-ps uninstall-dvi: for file in $(DVI_TARGETS); do \ - rm -f $(DESTDIR)$(dvidir)/$${file}; \ + rm -f "$(DESTDIR)$(dvidir)/$${file}"; \ done uninstall-html: for file in $(HTML_TARGETS); do \ - rm -f $(DESTDIR)$(htmldir)/$${file}; \ + rm -f "$(DESTDIR)$(htmldir)/$${file}"; \ done uninstall-ps: ext= ; [ -n "${GZIP_PROG}" ] && ext=.gz; \ for file in $(PS_TARGETS); do \ - rm -f $(DESTDIR)$(psdir)/$${file}$${ext}; \ + rm -f "$(DESTDIR)$(psdir)/$${file}$${ext}"; \ done uninstall-pdf: for file in $(PDF_TARGETS); do \ - rm -f $(DESTDIR)$(pdfdir)/$${file}; \ + rm -f "$(DESTDIR)$(pdfdir)/$${file}"; \ done uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps diff --git a/doc/lispintro/README b/doc/lispintro/README index d1e15bc6d89..e24f8f50726 100644 --- a/doc/lispintro/README +++ b/doc/lispintro/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2013 Free Software Foundation, Inc. +Copyright (C) 2001-2015 Free Software Foundation, Inc. See the end of the file for license conditions. diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps index 77d24cbddcc..4853d6a1d8d 100644 --- a/doc/lispintro/cons-1.eps +++ b/doc/lispintro/cons-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:58 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps index 961b00a13ec..258caa94858 100644 --- a/doc/lispintro/cons-2.eps +++ b/doc/lispintro/cons-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:39 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps index 993609638a1..710f66e4648 100644 --- a/doc/lispintro/cons-2a.eps +++ b/doc/lispintro/cons-2a.eps @@ -4,7 +4,7 @@ %%CreationDate: Tue Mar 14 15:09:30 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps index e37dad0de60..2849a314133 100644 --- a/doc/lispintro/cons-3.eps +++ b/doc/lispintro/cons-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:41 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps index 9af4c2afd75..d9331242818 100644 --- a/doc/lispintro/cons-4.eps +++ b/doc/lispintro/cons-4.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:06 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps index 8a400f320de..6ceec517f52 100644 --- a/doc/lispintro/cons-5.eps +++ b/doc/lispintro/cons-5.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:27:28 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps index abfec2a7362..dcd27a60b54 100644 --- a/doc/lispintro/drawers.eps +++ b/doc/lispintro/drawers.eps @@ -9,7 +9,7 @@ %%EndComments %%BeginProlog -% Copyright (C) 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 18ea8e87e19..245113b86d7 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,9 +1,10 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header -@setfilename ../../info/eintr +@setfilename ../../info/eintr.info @c setfilename emacs-lisp-intro.info @c sethtmlfilename emacs-lisp-intro.html @settitle Programming in Emacs Lisp +@include docstyle.texi @syncodeindex vr cp @syncodeindex fn cp @finalout @@ -29,7 +30,7 @@ @c @set largebook @c (Note: if you edit the book so as to change the length of the -@c table of contents, you may have to change the value of `pageno' below.) +@c table of contents, you may have to change the value of 'pageno' below.) @c <<<< For hard copy printing, this file is now @c set for smallbook, which works for all sizes @@ -96,10 +97,9 @@ @c ---------------------------------------------------- -@dircategory GNU Emacs Lisp +@dircategory Emacs lisp @direntry -* Emacs Lisp Intro: (eintr). - A simple introduction to Emacs Lisp programming. +* Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming. @end direntry @copying @@ -113,7 +113,7 @@ Edition @value{edition-number}, @value{update-date} Distributed with Emacs version @value{EMACSVER}. @end ifnottex @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2013 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2015 Free Software Foundation, Inc. @sp 1 @@ -142,6 +142,7 @@ Boston, MA 02110-1301 USA @sp 1 ISBN 1-882114-43-4 +@quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; there @@ -153,9 +154,10 @@ Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.'' +@end quotation @end copying -@c half title; two lines here, so do not use `shorttitlepage' +@c half title; two lines here, so do not use 'shorttitlepage' @tex {\begingroup% \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% @@ -350,7 +352,7 @@ How To Write Function Definitions * if:: What if? * else:: If--then--else expressions. * Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. +* save-excursion:: Keeping track of point and buffer. * Review:: * defun Exercises:: @@ -385,7 +387,7 @@ Truth and Falsehood in Emacs Lisp * Point and mark:: A review of various locations. * Template for save-excursion:: -A Few Buffer--Related Functions +A Few Buffer-Related Functions * Finding More:: How to find more information. * simplified-beginning-of-buffer:: Shows @code{goto-char}, @@ -806,7 +808,7 @@ In addition, I have written several programs as extended examples. Although these are examples, the programs are real. I use them. Other people use them. You may use them. Beyond the fragments of programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great +just for teaching purposes; what you see is used. This is a great advantage of Emacs Lisp: it is easy to learn to use it for work. @end ignore @@ -852,12 +854,12 @@ information so you won't be surprised later when the additional information is formally introduced.) When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have +first time. Frequently, you need make only a nodding +acquaintance with some of the items mentioned. My hope is that I have structured the text and given you enough hints that you will be alert to what is important, and concentrate on it. -You will need to ``dive into'' some paragraphs; there is no other way +You will need to dive into some paragraphs; there is no other way to read them. But I have tried to keep down the number of such paragraphs. This book is intended as an approachable hill, rather than as a daunting mountain. @@ -901,7 +903,7 @@ file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) If you don't know GNU Emacs, you can still read this document profitably. However, I recommend you learn Emacs, if only to learn to move around your computer screen. You can teach yourself how to use -Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This +Emacs with the built-in tutorial. To use it, type @kbd{C-h t}. (This means you press and release the @key{CTRL} key and the @kbd{h} at the same time, and then press and release @kbd{t}.) @@ -926,7 +928,7 @@ along with the key that is labeled @key{ALT} and, at the same time, press the @key{\} key. In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The +with @kbd{C-u}, which is called the @dfn{universal argument}. The @kbd{C-u} keychord passes an argument to the subsequent command. Thus, to indent a region of plain text by 6 spaces, mark the region, and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, @@ -998,7 +1000,7 @@ bob@@gnu.org To the untutored eye, Lisp is a strange programming language. In Lisp code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the +the name stands for ``Lots of Isolated Silly Parentheses''. But the claim is unwarranted. Lisp stands for LISt Processing, and the programming language handles @emph{lists} (and lists of lists) by putting them between parentheses. The parentheses mark the boundaries @@ -1088,7 +1090,7 @@ list is made up of the words @samp{a}, @samp{list}, @samp{inside}, In Lisp, what we have been calling words are called @dfn{atoms}. This term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been +``indivisible''. As far as Lisp is concerned, the words we have been using in the lists cannot be divided into any smaller parts and still mean the same thing as part of a program; likewise with numbers and single character symbols like @samp{+}. On the other hand, unlike an @@ -1157,7 +1159,7 @@ paragraphs---is also an atom. Here is an example: @noindent In Lisp, all of the quoted text including the punctuation mark and the blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that +@dfn{string} (for ``string of characters'') and is the sort of thing that is used for messages that a computer can print for a human to read. Strings are a different kind of atom than numbers or symbols and are used differently. @@ -1238,6 +1240,10 @@ command to do something. (Usually, of course, it is the last of these three things that you really want!) @c use code for the single apostrophe, not samp. +@findex quote +@cindex @code{'} for quoting +@cindex quoting using apostrophe +@cindex apostrophe for quoting The single apostrophe, @code{'}, that I put in front of some of the example lists in preceding sections is called a @dfn{quote}; when it precedes a list, it tells Lisp to do nothing with the list, other than @@ -1259,9 +1265,9 @@ hand parenthesis of the following list and then type @kbd{C-x C-e}: @c use code for the number four, not samp. @noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' +You will see the number @code{4} appear in the echo area. (What +you have just done is evaluate the list. The echo area +is the line at the bottom of the screen that displays or echoes text.) Now try the same thing with a quoted list: place the cursor right after the following list and type @kbd{C-x C-e}: @@ -1278,7 +1284,7 @@ In both cases, what you are doing is giving a command to the program inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the interpreter a command to evaluate the expression. The name of the Lisp interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. +up with the meaning of an expression---who interprets it. You can also evaluate an atom that is not part of a list---one that is not surrounded by parentheses; again, the Lisp interpreter translates @@ -1301,7 +1307,7 @@ signposts to a traveler in a strange country; deciphering them can be hard, but once understood, they can point the way. The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. +will enter the debugger. You get out of the debugger by typing @code{q}. What we will do is evaluate a list that is not quoted and does not have a meaningful command as its first element. Here is a list almost @@ -1363,9 +1369,9 @@ Based on what we already know, we can almost read this error message. You read the @file{*Backtrace*} buffer from the bottom up; it tells you what Emacs did. When you typed @kbd{C-x C-e}, you made an interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. +an abbreviation for ``evaluate'' and @code{sexp} is an abbreviation for +``symbolic expression''. The command means ``evaluate last symbolic +expression'', which is the expression just before your cursor. Each line above tells you what the Lisp interpreter evaluated next. The most recent action is at the top. The buffer is called the @@ -1399,7 +1405,7 @@ definition of any set of instructions for the computer to carry out. The slightly odd word, @samp{void-function}, is designed to cover the way Emacs Lisp is implemented, which is that when a symbol does not have a function definition attached to it, the place that should -contain the instructions is `void'. +contain the instructions is void. On the other hand, since we were able to add 2 plus 2 successfully, by evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must @@ -1568,9 +1574,9 @@ compilation. When the Lisp interpreter works on an expression, the term for the activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New +``evaluates the expression''. I've used this term several times before. +The word comes from its use in everyday language, ``to ascertain the +value or amount of; to appraise'', according to @cite{Webster's New Collegiate Dictionary}. @menu @@ -1590,16 +1596,15 @@ instructions it found in the function definition, or perhaps it will give up on that function and produce an error message. (The interpreter may also find itself tossed, so to speak, to a different function or it may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and +an infinite loop. These actions are less common; and we can ignore them.) Most frequently, the interpreter returns a value. @cindex @samp{side effect} defined At the same time the interpreter returns a value, it may do something else as well, such as move a cursor or copy a file; this other kind of action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. +important, such as printing results, are often side effects to the +Lisp interpreter. It is fairly easy to learn to use side effects. In summary, evaluating a symbolic expression most commonly causes the Lisp interpreter to return a value and perhaps carry out a side effect; @@ -1635,9 +1640,9 @@ evaluate, the interpreter prints that value in the echo area. Now it is easy to understand the name of the command invoked by the keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. +letters @code{sexp} are an abbreviation for ``symbolic expression'', and +@code{eval} is an abbreviation for ``evaluate''. The command +evaluates the last symbolic expression. As an experiment, you can try evaluating the expression by putting the cursor at the beginning of the next line immediately following the @@ -1698,7 +1703,7 @@ Another way to think about this is to imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the -function definition, and vice-verse. +function definition, and vice versa. @menu * fill-column Example:: @@ -1836,7 +1841,7 @@ typing @kbd{q} in the @file{*Backtrace*} buffer.) This backtrace is different from the very first error message we saw, which said, @samp{Debugger entered--Lisp error: (void-function this)}. In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not +in the other error message, the function (the word @samp{this}) did not have a definition. In this experiment with the @code{+}, what we did was cause the Lisp @@ -1885,22 +1890,22 @@ The numbers added by @code{+} are called the @dfn{arguments} of the function @code{+}. These numbers are the information that is given to or @dfn{passed} to the function. -The word `argument' comes from the way it is used in mathematics and +The word ``argument'' comes from the way it is used in mathematics and does not refer to a disputation between two people; instead it refers to the information presented to the function, in this case, to the @code{+}. In Lisp, the arguments to a function are the atoms or lists that follow the function. The values returned by the evaluation of these atoms or lists are passed to the function. Different functions require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' +all.@footnote{It is curious to track the path by which the word ``argument'' came to have two different meanings, one in mathematics and the other in everyday English. According to the @cite{Oxford English Dictionary}, the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its +came to mean, by one thread of derivation, ``the evidence offered as +proof'', which is to say, ``the information offered'', which led to its meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. +``to assert in a manner against which others may make counter +assertions'', which led to the meaning of the word as a disputation. (Note here that the English word has two different definitions attached to it at the same time. By contrast, in Emacs Lisp, a symbol cannot have two different function definitions at the same time.)} @@ -1942,13 +1947,16 @@ following: @noindent The value produced by evaluating this expression is @code{"abcdef"}. +@cindex substring A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of +arguments. The function returns a part of the string, a @dfn{substring} of the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuation) from the beginning of the string. +argument is the string of characters, the second and third arguments +are numbers that indicate the beginning (inclusive) and end +(exclusive) of the substring. The numbers are a count of the number +of characters (including spaces and punctuation) from the beginning of +the string. Note that the characters in a string are numbered from +zero, not one. @need 800 For example, if you evaluate the following: @@ -1965,7 +1973,7 @@ Note that the string passed to @code{substring} is a single atom even though it is made up of several words separated by spaces. Lisp counts everything between the two quotation marks as part of the string, including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom +a kind of atom smasher since it takes an otherwise indivisible atom and extracts a part. However, @code{substring} is only able to extract a substring from an argument that is a string, not from another type of atom such as a number or symbol. @@ -2020,7 +2028,7 @@ Some functions, such as @code{concat}, @code{+} or @code{*}, take any number of arguments. (The @code{*} is the symbol for multiplication.) This can be seen by evaluating each of the following expressions in the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. +text after @samp{@result{}}, which you may read as ``evaluates to''. @need 1250 In the first set, the functions have no arguments: @@ -2121,7 +2129,7 @@ numeric value of marker positions as numbers. The @samp{p} of @code{number-or-marker-p} is the embodiment of a practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp +stands for ``predicate''. In the jargon used by the early Lisp researchers, a predicate refers to a function to determine whether some property is true or false. So the @samp{p} tells us that @code{number-or-marker-p} is the name of a function that determines @@ -2388,14 +2396,14 @@ to the symbol @code{herbivores}: not have fit on a page; and humans find it easier to read nicely formatted lists.) -Although I have been using the term `assign', there is another way of +Although I have been using the term ``assign'', there is another way of thinking about the workings of @code{set} and @code{setq}; and that is to say that @code{set} and @code{setq} make the symbol @emph{point} to the list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as +chapters we shall come upon at least one symbol that has ``pointer'' as part of its name. The name is chosen because the symbol has a value, specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. +the symbol is set to point to the list. @node Counting @subsection Counting @@ -2500,8 +2508,8 @@ of which the function is the first element. @item A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to +an error); in addition, it may also carry out some action that is a +side effect. In many cases, a function's primary purpose is to create a side effect. @end itemize @@ -2637,9 +2645,9 @@ The former is the name of the buffer and the latter is the name of the file. In Info, the buffer name is @file{"*info*"}. Info does not point to any file, so the result of evaluating @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the +from the Latin word for ``nothing''; in this case, it means that the buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) +used to mean ``false'' and is a synonym for the empty list, @code{()}.) When I am writing, the name of my buffer is @file{"introduction.texinfo"}. The name of the file to which it @@ -2651,7 +2659,7 @@ functions; without the parentheses, the interpreter would attempt to evaluate the symbols as variables. @xref{Variables}.) In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice-verse. +find that people refer to a file when they mean a buffer and vice versa. Indeed, most people say, ``I am editing a file,'' rather than saying, ``I am editing a buffer which I will soon save to a file.'' It is almost always clear from context what people mean. When dealing with @@ -2659,7 +2667,7 @@ computer programs, however, it is important to keep the distinction in mind, since the computer is not as smart as a person. @cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a +The word ``buffer'', by the way, comes from the meaning of the word as a cushion that deadens the force of a collision. In early computers, a buffer cushioned the interaction between files and the computer's central processing unit. The drums or tapes that held a file and the @@ -2836,10 +2844,10 @@ following more complex expression: @c noindent In this case, the first argument to @code{other-buffer} tells it which buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} +@code{other-buffer} it is OK to switch to a visible buffer. In +regular use, @code{switch-to-buffer} takes you to a buffer not visible +in windows since you would most likely use @kbd{C-x o} +(@code{other-window}) to go to another visible buffer.} In the programming examples in later sections of this document, you will see the function @code{set-buffer} more often than @@ -2862,7 +2870,7 @@ there until the command finishes running). Also, we have just introduced another jargon term, the word @dfn{call}. When you evaluate a list in which the first symbol is a function, you are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' +the function as an entity that can do something for you if you call it---just as a plumber is an entity who can fix a leak if you call him or her. @@ -2905,7 +2913,7 @@ the following expression in the usual way: @end smallexample @noindent -As I write this, the value of @code{point} is 65724. The @code{point} +As I write this, the value of point is 65724. The @code{point} function is frequently used in some of the examples later in this book. @@ -2964,7 +2972,7 @@ symbol refers to it.) * if:: What if? * else:: If--then--else expressions. * Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. +* save-excursion:: Keeping track of point and buffer. * Review:: * defun Exercises:: @end menu @@ -3080,9 +3088,9 @@ function. Instead of choosing the word @code{number} for the name of the argument, I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it +the word @code{multiplicand}. I picked the word ``number'' because it tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the +well have chosen the word ``multiplicand'' to indicate the role that the value placed in this slot will play in the workings of the function. I could have called it @code{foogle}, but that would have been a bad choice because it would not tell humans what it means. The choice of @@ -3094,16 +3102,16 @@ list, even the name of a symbol used in some other function: the name you use in an argument list is private to that particular definition. In that definition, the name refers to a different entity than any use of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an +nick-name ``Shorty'' in your family; when your family members refer to +``Shorty'', they mean you. But outside your family, in a movie, for +example, the name ``Shorty'' refers to someone else. Because a name in an argument list is private to the function definition, you can change the value of such a symbol inside the body of a function without changing its value outside the function. The effect is similar to that produced by a @code{let} expression. (@xref{let, , @code{let}}.) @ignore -Note also that we discuss the word `number' in two different ways: as a +Note also that we discuss the word ``number'' in two different ways: as a symbol that appears in the code, and as the name of something that will be replaced by a something else during the evaluation of the function. In the first case, @code{number} is a symbol, not a number; it happens @@ -3148,7 +3156,7 @@ to evaluate this yet! @noindent The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of +next section, is bound to the value 3 in the actual use of the function. Note that although @code{number} was inside parentheses in the function definition, the argument passed to the @code{multiply-by-seven} function is not in parentheses. The @@ -3159,7 +3167,7 @@ definition begins. If you evaluate this example, you are likely to get an error message. (Go ahead, try it!) This is because we have written the function definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. +not yet loaded the function definition in Emacs. Installing a function is the process that tells the Lisp interpreter the definition of the function. Installation is described in the next section. @@ -3223,6 +3231,7 @@ function, @code{multiply-by-seven}. When you do this, a @smallexample @group multiply-by-seven is a Lisp function. + (multiply-by-seven NUMBER) Multiply NUMBER by seven. @@ -3248,8 +3257,8 @@ add the number to itself seven times instead of multiplying the number by seven. It produces the same answer, but by a different path. At the same time, we will add a comment to the code; a comment is text that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. +useful or enlightening. The comment is that this is the second +version. @smallexample @group @@ -3352,7 +3361,7 @@ it could not be used as an example of key binding.) (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command to a key.) -A prefix argument is passed to an interactive function by typing the +A @dfn{prefix argument} is passed to an interactive function by typing the @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you type @kbd{C-u} without a number, it defaults to 4). @@ -3445,13 +3454,16 @@ a function. (@xref{Interactive Codes, , Code Characters for Consider the function @code{zap-to-char}. Its interactive expression is +@c FIXME: the interactive expression of zap-to-char has been changed +@c (in 2012-04-10). + @smallexample (interactive "p\ncZap to char: ") @end smallexample The first part of the argument to @code{interactive} is @samp{p}, with which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You +interpret a prefix, as a number to be passed to the function. You can specify a prefix either by typing @kbd{C-u} followed by a number or by typing @key{META} followed by a number. The prefix is the number of specified characters. Thus, if your prefix is three and the @@ -3565,8 +3577,8 @@ variable of the same name that is not part of the function. To understand why the @code{let} special form is necessary, consider the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is +``the house'', as in the sentence, ``The house needs painting.'' If you +are visiting a friend and your host refers to ``the house'', he is likely to be referring to @emph{his} house, not yours, that is, to a different house. @@ -3594,7 +3606,7 @@ and the two are not intended to refer to the same value. The The @code{let} special form prevents confusion. @code{let} creates a name for a @dfn{local variable} that overshadows any use of the same name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not +that whenever your host refers to ``the house'', he means his house, not yours. (Symbols used in argument lists work the same way. @xref{defun, , The @code{defun} Macro}.) @@ -3607,21 +3619,21 @@ Another way to think about @code{let} is that it is like a @code{setq} that is temporary and local. The values set by @code{let} are automatically undone when the @code{let} is finished. The setting only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of +expression. In computer science jargon, we would say the binding of a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' +in Emacs Lisp, scoping is dynamic, not lexical. @code{let} can create more than one variable at once. Also, @code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created +value specified by you, or @code{nil}. (In the jargon, this is +binding the variable to the value.) After @code{let} has created and bound the variables, it executes the code in the body of the @code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon +as the value of the whole @code{let} expression. (``Execute'' is a jargon term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English +meaning ``to give practical effect to'' (@cite{Oxford English Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) +``execute'' has evolved as a synonym to ``evaluate''.) @node Parts of let Expression @subsection The Parts of a @code{let} Expression @@ -3682,26 +3694,26 @@ to the two variables @code{zebra} and @code{tiger}. The body of the @smallexample @group -(let ((zebra 'stripes) - (tiger 'fierce)) +(let ((zebra "stripes") + (tiger "fierce")) (message "One kind of animal has %s and another is %s." zebra tiger)) @end group @end smallexample -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. +Here, the varlist is @code{((zebra "stripes") (tiger "fierce"))}. The two variables are @code{zebra} and @code{tiger}. Each variable is the first element of a two-element list and each value is the second element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According +variable @code{zebra} to the value @code{"stripes"}@footnote{According to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras become impossibly dangerous as they grow older'' but the claim here is that they do not become fierce like a tiger. (1997, W. W. Norton and Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} +variable @code{tiger} to the value @code{"fierce"}. In this example, +both values are strings. The values could just as well have been +another list or a symbol. The body of the @code{let} follows after the list holding the variables. In this example, the body is a list that uses the @code{message} function to print a string in the echo area. @@ -3781,8 +3793,8 @@ make decisions. You can write function definitions without using included here. It is used, for example, in the code for the function @code{beginning-of-buffer}. -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the +The basic idea behind an @code{if}, is that @emph{if} a test is true, +@emph{then} an expression is evaluated. If the test is not true, the expression is not evaluated. For example, you might make a decision such as, ``if it is warm and sunny, then go to the beach!'' @@ -3798,7 +3810,7 @@ such as, ``if it is warm and sunny, then go to the beach!'' @cindex @samp{if-part} defined @cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; +An @code{if} expression written in Lisp does not use the word ``then''; the test and the action are the second and third elements of the list whose first element is @code{if}. Nonetheless, the test part of an @code{if} expression is often called the @dfn{if-part} and the second @@ -3806,7 +3818,7 @@ argument is often called the @dfn{then-part}. Also, when an @code{if} expression is written, the true-or-false-test is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written +action to carry out if the test is true, the then-part, is written on the second and subsequent lines. This makes the @code{if} expression easier to read. @@ -3846,17 +3858,17 @@ of time, we would not need to run the test!) For example, the value may be bound to an argument of a function definition. In the following function definition, the character of the animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a +@code{characteristic} is @code{"fierce"}, then the message, @samp{It is a tiger!} will be printed; otherwise, @code{nil} will be returned. @smallexample @group (defun type-of-animal (characteristic) "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', +If the CHARACTERISTIC is the string \"fierce\", then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) + (if (equal characteristic "fierce") + (message "It is a tiger!"))) @end group @end smallexample @@ -3868,18 +3880,18 @@ can evaluate the following two expressions to see the results: @smallexample @group -(type-of-animal 'fierce) +(type-of-animal "fierce") -(type-of-animal 'zebra) +(type-of-animal "striped") @end group @end smallexample @c Following sentences rewritten to prevent overfull hbox. @noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} +When you evaluate @code{(type-of-animal "fierce")}, you will see the +following message printed in the echo area: @code{"It is a tiger!"}; and +when you evaluate @code{(type-of-animal "striped")} you will see @code{nil} printed in the echo area. @node type-of-animal in detail @@ -3909,7 +3921,7 @@ The parts of the function that match this template look like this: @group (defun type-of-animal (characteristic) "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', +If the CHARACTERISTIC is the string \"fierce\", then warn of a tiger." @var{body: the} @code{if} @var{expression}) @end group @@ -3938,8 +3950,8 @@ looks like this: @smallexample @group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) +(if (equal characteristic "fierce") + (message "It is a tiger!"))) @end group @end smallexample @@ -3947,26 +3959,26 @@ looks like this: Here, the true-or-false-test is the expression: @smallexample -(equal characteristic 'fierce) +(equal characteristic "fierce") @end smallexample @noindent In Lisp, @code{equal} is a function that determines whether its first argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the +string @code{"fierce"} and the first argument is the value of the symbol @code{characteristic}---in other words, the argument passed to this function. In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} +@code{"fierce"} is passed to @code{type-of-animal}. Since @code{"fierce"} +is equal to @code{"fierce"}, the expression, @code{(equal characteristic +"fierce")}, returns a value of true. When this happens, the @code{if} evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. +@code{(message "It is a tiger!")}. On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and +argument @code{"striped"} is passed to @code{type-of-animal}. @code{"striped"} +is not equal to @code{"fierce"}, so the then-part is not evaluated and @code{nil} is returned by the @code{if} expression. @node else @@ -4025,34 +4037,33 @@ arguments to the function. @group (defun type-of-animal (characteristic) ; @r{Second version.} "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) +If the CHARACTERISTIC is the string \"fierce\", +then warn of a tiger; else say it is not fierce." + (if (equal characteristic "fierce") + (message "It is a tiger!") + (message "It is not fierce!"))) @end group @end smallexample @sp 1 @smallexample @group -(type-of-animal 'fierce) +(type-of-animal "fierce") -(type-of-animal 'zebra) +(type-of-animal "striped") @end group @end smallexample @c Following sentence rewritten to prevent overfull hbox. @noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. +When you evaluate @code{(type-of-animal "fierce")}, you will see the +following message printed in the echo area: @code{"It is a tiger!"}; but +when you evaluate @code{(type-of-animal "striped")}, you will see +@code{"It is not fierce!"}. -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be +(Of course, if the @var{characteristic} were @code{"ferocious"}, the +message @code{"It is not fierce!"} would be printed; and it would be misleading! When you write code, you need to take into account the possibility that some such argument will be tested by the @code{if} and write your program accordingly.) @@ -4064,10 +4075,10 @@ and write your program accordingly.) @findex nil There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of +expression. So far, we have spoken of ``true'' and ``false'' as values of predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. +``false'' is just our old friend @code{nil}. Anything else---anything +at all---is ``true''. The expression that tests for truth is interpreted as @dfn{true} if the result of evaluating it is a value that is not @code{nil}. In @@ -4148,8 +4159,8 @@ On the other hand, this function returns @code{nil} if the test is false. @section @code{save-excursion} @findex save-excursion @cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation +@cindex Preserving point and buffer +@cindex Point and buffer preservation @findex point @findex mark @@ -4157,11 +4168,11 @@ The @code{save-excursion} function is the third and final special form that we will discuss in this chapter. In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary +function is very common. It saves the location of point, +executes the body of the function, and then restores point to +its previous position if its location was changed. Its primary purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. +unexpected movement of point. @menu * Point and mark:: A review of various locations. @@ -4198,8 +4209,8 @@ region}. Numerous commands work on the region, including @code{center-region}, @code{count-lines-region}, @code{kill-region}, and @code{print-region}. -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the +The @code{save-excursion} special form saves the location of point and +restores this position after the code within the body of the special form is evaluated by the Lisp interpreter. Thus, if point were in the beginning of a piece of text and some code moved point to the end of the buffer, the @code{save-excursion} would put point back to where @@ -4210,16 +4221,16 @@ In Emacs, a function frequently moves point as part of its internal workings even though a user would not expect this. For example, @code{count-lines-region} moves point. To prevent the user from being bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of +view) unnecessary, @code{save-excursion} is often used to keep point in +the location expected by the user. The use of @code{save-excursion} is good housekeeping. To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside +value of point even if something goes wrong in the code inside of it (or, to be more precise and to use the proper jargon, ``in case of abnormal exit''). This feature is very helpful. -In addition to recording the values of point and mark, +In addition to recording the value of point, @code{save-excursion} keeps track of the current buffer, and restores it, too. This means you can write code that will change the buffer and have @code{save-excursion} switch you back to the original buffer. @@ -4246,7 +4257,7 @@ one expression in the body, the value of the last one will be returned as the value of the @code{save-excursion} function. The other expressions in the body are evaluated only for their side effects; and @code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). +is restoring the position of point). @need 1250 In more detail, the template for a @code{save-excursion} expression @@ -4349,7 +4360,7 @@ The name of an existing buffer. The name of an existing file. @item p -The numeric prefix argument. (Note that this `p' is lower case.) +The numeric prefix argument. (Note that this @code{p} is lower case.) @item r Point and the mark, as two numeric arguments, smallest first. This @@ -4384,9 +4395,9 @@ For example, @end smallexample @item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. +Record the values of point and the current buffer before +evaluating the body of this special form. Restore the value of point and +buffer afterward. @need 1250 For example, @@ -4441,7 +4452,7 @@ markers, are equal. @item equal @itemx eq Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns +of the word ``same'' and @code{eq} uses another: @code{equal} returns true if the two objects have a similar structure and contents, such as two copies of the same book. On the other hand, @code{eq}, returns true if both arguments are actually the same object. @@ -4470,7 +4481,7 @@ shorter, alternative name is @code{string=}. There are no string test functions that correspond to @var{>}, @code{>=}, or @code{<=}. @item message -Print a message in the echo area. The first argument is a string that +Print a message in the echo area. The first argument is a string that can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of arguments that follow the string. The argument used by @samp{%s} must be a string or a symbol; the argument used by @samp{%d} must be a @@ -4545,7 +4556,7 @@ and if so, prints an appropriate message. @end itemize @node Buffer Walk Through -@chapter A Few Buffer--Related Functions +@chapter A Few Buffer-Related Functions In this chapter we study in detail several of the functions used in GNU Emacs. This is called a ``walk-through''. These functions are used as @@ -4586,7 +4597,7 @@ function definition. Put point into the name of the file that contains the function and press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take +@code{push-button} rather than ``return'' or ``enter''. Emacs will take you directly to the function definition. @ignore @@ -4594,7 +4605,7 @@ Not In version 22 If you move point over the file name and press the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function +than ``return'' or ``enter'', Emacs will take you directly to the function definition. @end ignore @@ -4604,7 +4615,7 @@ file, you can use the @code{find-tag} function to jump to it. Lisp, and C, and it works with non-programming text as well. For example, @code{find-tag} will jump to the various nodes in the Texinfo source file of this document. -The @code{find-tag} function depends on `tags tables' that record +The @code{find-tag} function depends on @dfn{tags tables} that record the locations of the functions, variables, and other items to which @code{find-tag} jumps. @@ -4622,7 +4633,7 @@ screen. To switch back to your current buffer, type @kbd{C-x b @cindex TAGS table, specifying @findex find-tag Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', +set, you may also need to specify the location of your tags table, which is a file called @file{TAGS}. For example, if you are interested in Emacs sources, the tags table you will most likely want, if it has already been created for you, will be in a subdirectory of @@ -4648,14 +4659,14 @@ After you become more familiar with Emacs Lisp, you will find that you will frequently use @code{find-tag} to navigate your way around source code; and you will create your own @file{TAGS} tables. -@cindex Library, as term for `file' +@cindex Library, as term for ``file'' Incidentally, the files that contain Lisp code are conventionally called @dfn{libraries}. The metaphor is derived from that of a specialized library, such as a law library or an engineering library, rather than a general library. Each library, or file, contains functions that relate to a particular topic or activity, such as @file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for on-line help. (Sometimes several +shortcuts, and @file{help.el} for help. (Sometimes several libraries provide code for a single activity, as the various @file{rmail@dots{}} files provide code for reading electronic mail.) In @cite{The GNU Emacs Manual}, you will see sentences such as ``The @@ -4914,7 +4925,7 @@ The expression works nearly the same as before. It sets a mark at the highest numbered place in the buffer that it can. However, in this version, @code{push-mark} has two additional arguments. The second argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes +it @emph{should} display a message that says ``Mark set'' when it pushes the mark. The third argument is @code{t}. This tells @code{push-mark} to activate the mark when Transient Mark mode is turned on. Transient Mark mode highlights the currently active @@ -4929,6 +4940,8 @@ result of this, point is placed at the beginning of the buffer and mark 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). @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4954,8 +4967,7 @@ current buffer to a specified buffer. The @code{append-to-buffer} command uses the @code{insert-buffer-substring} function to copy the region. @code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. +substring from a buffer, and inserts it into another buffer. Most of @code{append-to-buffer} is concerned with setting up the conditions for @@ -5199,8 +5211,8 @@ of the two-element list, @code{(oldbuf (current-buffer))}. The body of the @code{let} expression in @code{append-to-buffer} consists of a @code{save-excursion} expression. -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the +The @code{save-excursion} function saves the location of point, and restores it +to that position after the expressions in the body of the @code{save-excursion} complete execution. In addition, @code{save-excursion} keeps track of the original buffer, and restores it. This is how @code{save-excursion} is used in @@ -5388,7 +5400,7 @@ Conventionally bound to @kbd{M-.} (that's a period following the @key{META} key). @item save-excursion -Save the location of point and mark and restore their values after the +Save the location of point and restore its value after the arguments to @code{save-excursion} have been evaluated. Also, remember the current buffer and return to it. @@ -5520,7 +5532,7 @@ the buffer you are in (and you have not seen the computer shift its attention, so you don't know that that buffer is now called @code{oldbuf}). -Incidentally, this is what is meant by `replacement'. To replace text, +Incidentally, this is what is meant by ``replacement''. To replace text, Emacs erases the previous text and then inserts new text. @need 1250 @@ -5702,8 +5714,8 @@ then the buffer itself must be got. You can imagine yourself at a conference where an usher is wandering around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. +usher is bound to your name, not to you; but when the usher finds +you and takes your arm, the usher becomes bound to you. @need 800 In Lisp, you might describe this situation like this: @@ -5754,8 +5766,7 @@ so the true-or-false-test looks like this: @noindent @code{not} is a function that returns true if its argument is false and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice-verse: -what is ``not true'' is false and what is ``not false'' is true. +returns true, the @code{not} expression returns false and vice versa. Using this test, the @code{if} expression works as follows: when the value of the variable @code{buffer} is actually a buffer rather than @@ -5894,7 +5905,7 @@ the value of point, which will be at the end of the inserted text, is recorded in the variable @code{newmark}. After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. +is relocated to its original place. However, it is convenient to locate a mark at the end of the newly inserted text and locate point at its beginning. The @code{newmark} @@ -6133,7 +6144,7 @@ size of the buffer. The reason for this is that the old version 18 Emacs used numbers that are no bigger than eight million or so and in the computation that followed, the programmer feared that Emacs might try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over +``overflow'', mentioned in the comment, means numbers that are over large. More recent versions of Emacs use larger numbers, but this code has not been touched, if only because people now look at buffers that are far, far larger than ever before. @@ -6153,7 +6164,7 @@ was that function called several times, it gave the size of the whole buffer, not the accessible part. The computation makes much more sense when it handles just the accessible part. (@xref{Narrowing & Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) +attention to an accessible part.) @need 800 The line looks like this: @@ -6181,8 +6192,8 @@ This expression is a multiplication, with two arguments to the function The first argument is @code{(prefix-numeric-value arg)}. When @code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform +passed to the function as its argument is passed a @dfn{raw prefix +argument}, and not a number. (It is a number in a list.) To perform the arithmetic, a conversion is necessary, and @code{prefix-numeric-value} does the job. @@ -6323,7 +6334,7 @@ and avoids clobbering the mark." (/ (+ 10 (* size (prefix-numeric-value arg))) 10))) (point-min)))) - (if arg (forward-line 1))) + (if (and arg (not (consp arg))) (forward-line 1))) @end group @end smallexample @@ -6390,7 +6401,7 @@ to move point to the beginning of the next line if the command is invoked with an argument: @smallexample -(if arg (forward-line 1))) +(if (and arg (not (consp arg))) (forward-line 1)) @end smallexample @noindent @@ -6399,14 +6410,10 @@ appropriate tenths position in the buffer. This is a flourish that means that the cursor is always located @emph{at least} the requested tenths of the way through the buffer, which is a nicety that is, perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. - -On the other hand, it also means that if you specify the command with -a @kbd{C-u}, but without a number, that is to say, if the `raw prefix -argument' is simply a cons cell, then the command puts you at the -beginning of the second line @dots{} I don't know whether this is -intended or whether no one has dealt with the code to avoid this -happening. +to draw complaints. (The @code{(not (consp arg))} portion is so that +if you specify the command with a @kbd{C-u}, but without a number, +that is to say, if the raw prefix argument is simply a cons cell, +the command does not put you at the beginning of the second line.) @node Second Buffer Related Review @section Review @@ -6434,7 +6441,7 @@ is optional; this means that the function can be evaluated without the argument, if desired. @item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive +Convert the raw prefix argument produced by @code{(interactive "P")} to a numeric value. @item forward-line @@ -6687,8 +6694,8 @@ restored just before the completion of the function by the @code{save-restriction} special form. The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} +saves the location of the cursor (i.e., of point), and +restores it after the code in the body of the @code{save-excursion} uses the @code{beginning-of-line} function to move point. (Note that the @code{(widen)} expression comes between the @@ -6759,8 +6766,8 @@ it, and @code{count-lines} counts only the lines @emph{before} the current line. After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores +printed in the echo area, the @code{save-excursion} restores point to +its original position; and @code{save-restriction} restores the original narrowing, if any. @node narrow Exercise @@ -6816,11 +6823,11 @@ namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) @end ifnottex The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for +abbreviation of the word ``construct''. The origins of the names for @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These +is an acronym from the phrase ``Contents of the Address part of the +Register''; and @code{cdr} (pronounced ``could-er'') is an acronym from +the phrase ``Contents of the Decrement part of the Register''. These phrases refer to specific pieces of hardware on the very early computer on which the original Lisp was developed. Besides being obsolete, the phrases have been completely irrelevant for more than 25 @@ -6855,7 +6862,7 @@ Clearly, a more reasonable name for the @code{car} function would be @code{car} does not remove the first item from the list; it only reports what it is. After @code{car} has been applied to a list, the list is still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. +``non-destructive''. This feature turns out to be important. The @sc{cdr} of a list is the rest of the list, that is, the @code{cdr} function returns the part of the list that follows the @@ -6940,10 +6947,10 @@ non-destructive---that is, they do not modify or change lists to which they are applied. This is very important for how they are used. Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated +in Lisp, certain kinds of atom, such as an array, can be separated into parts; but the mechanism for doing this is different from the mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The +atoms of a list are unsplittable. (@xref{Lisp Atoms}.) The @code{car} and @code{cdr} functions are used for splitting lists and are considered fundamental to Lisp. Since they cannot split or gain access to the parts of an array, an array is considered an atom. @@ -6977,8 +6984,8 @@ appear in the echo area. @code{cons} causes the creation of a new list in which the element is followed by the elements of the original list. -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this +We often say that @code{cons} puts a new element at the beginning of +a list, or that it attaches or pushes elements onto the list, but this phrasing can be misleading, since @code{cons} does not change an existing list, but creates a new one. @@ -7003,7 +7010,7 @@ need to provide at least an empty list at the beginning. Here is a series of @code{cons} expressions that build up a list of flowers. If you are reading this in Info in GNU Emacs, you can evaluate each of the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. +after @samp{@result{}}, which you may read as ``evaluates to''. @smallexample @group @@ -7116,7 +7123,7 @@ In an earlier version: This is written with a special notation, @samp{#<subr}, that indicates that the function @code{length} is one of the primitive functions written in C rather than in Emacs Lisp. (@samp{subr} is an - abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a + abbreviation for ``subroutine''.) @xref{What Is a Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more about subroutines. @end ignore @@ -7275,9 +7282,9 @@ This can be very convenient. Note that the elements are numbered from zero, not one. That is to say, the first element of a list, its @sc{car} is the zeroth element. -This is called `zero-based' counting and often bothers people who +This zero-based counting often bothers people who are accustomed to the first element in a list being number one, which -is `one-based'. +is one-based. @need 1250 For example: @@ -7416,7 +7423,7 @@ variable which has a list as its value, and the list to which the @noindent If you evaluate this expression, the list @code{(cat dog)} will appear in the echo area. This is the value returned by the function. The -result we are interested in is the ``side effect'', which we can see by +result we are interested in is the side effect, which we can see by evaluating the variable @code{domesticated-animals}: @smallexample @@ -7448,17 +7455,17 @@ fish. Replace the rest of that list with a list of other fish. @cindex Erasing text @cindex Deleting text -Whenever you cut or clip text out of a buffer with a `kill' command in +Whenever you cut or clip text out of a buffer with a @dfn{kill} command in GNU Emacs, it is stored in a list and you can bring it back with a -`yank' command. +@dfn{yank} command. -(The use of the word `kill' in Emacs for processes which specifically +(The use of the word ``kill'' in Emacs for processes which specifically @emph{do not} destroy the values of the entities is an unfortunate -historical accident. A much more appropriate word would be `clip' since +historical accident. A much more appropriate word would be ``clip'' since that is what the kill commands do; they clip text out of a buffer and put it into storage from which it can be brought back. I have often -been tempted to replace globally all occurrences of `kill' in the Emacs -sources with `clip' and all occurrences of `killed' with `clipped'.) +been tempted to replace globally all occurrences of ``kill'' in the Emacs +sources with ``clip'' and all occurrences of ``killed'' with ``clipped''.) @menu * Storing Text:: Text is stored in a list. @@ -7487,7 +7494,7 @@ look like this: @need 1200 @noindent The function @code{cons} can be used to create a new list from a piece -of text (an `atom', to use the jargon) and an existing list, like +of text (an ``atom'', to use the jargon) and an existing list, like this: @smallexample @@ -7531,7 +7538,7 @@ than nothing at all. The list that holds the pieces of text is called the @dfn{kill ring}. This chapter leads up to a description of the kill ring and how it is used by first tracing how the @code{zap-to-char} function works. This -function uses (or `calls') a function that invokes a function that +function calls a function that invokes a function that manipulates the kill ring. Thus, before reaching the mountains, we climb the foothills. @@ -7612,7 +7619,20 @@ Goes backward if ARG is negative; error if CHAR not found." @end smallexample The documentation is thorough. You do need to know the jargon meaning -of the word `kill'. +of the word ``kill''. + +@cindex curved quotes +@cindex curly quotes +The version 22 documentation string for @code{zap-to-char} uses ASCII +grave accent and apostrophe to quote a symbol, so it appears as +@t{`case-fold-search'}. This quoting style was inspired by 1970s-era +displays in which grave accent and apostrophe were often mirror images +suitable for use as quotes. On most modern displays this is no longer +true, and when these two ASCII characters appear in documentation +strings or diagnostic message formats, Emacs typically transliterates +them to curved single quotes, so that the abovequoted symbol appears +as @t{‘case-fold-search’}. Source-code strings can also simply use +curved quotes directly. @node zap-to-char interactive @subsection The @code{interactive} Expression @@ -7629,7 +7649,7 @@ The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies two different things. First, and most simply, is the @samp{p}. This part is separated from the next part by a newline, @samp{\n}. The @samp{p} means that the first argument to the function will be -passed the value of a `processed prefix'. The prefix argument is +passed the value of a @dfn{processed prefix}. The prefix argument is passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If the function is called interactively without a prefix, 1 is passed to this argument. @@ -7700,7 +7720,7 @@ function @code{char-to-string} to ensure that the computer treats that character as a string.) If the search is backwards, @code{search-forward} leaves point just before the first character in the target. Also, @code{search-forward} returns @code{t} for true. -(Moving point is therefore a `side effect'.) +(Moving point is therefore a side effect.) @need 1250 In @code{zap-to-char}, the @code{search-forward} function looks like this: @@ -7930,13 +7950,13 @@ The command \\[yank] can retrieve it from there. @dots{} " ;; @bullet{} Since order matters, pass point first. (interactive (list (point) (mark))) ;; @bullet{} And tell us if we cannot cut the text. - ;; `unless' is an `if' without a then-part. + ;; 'unless' is an 'if' without a then-part. (unless (and beg end) (error "The mark is not set now, so there is no region")) @end group @group - ;; @bullet{} `condition-case' takes three arguments. + ;; @bullet{} 'condition-case' takes three arguments. ;; If the first argument is nil, as it is here, ;; information about the error signal is not ;; stored for use by another function. @@ -7944,33 +7964,33 @@ The command \\[yank] can retrieve it from there. @dots{} " @end group @group - ;; @bullet{} The second argument to `condition-case' tells the + ;; @bullet{} The second argument to 'condition-case' tells the ;; Lisp interpreter what to do when all goes well. @end group @group - ;; It starts with a `let' function that extracts the string + ;; It starts with a 'let' function that extracts the string ;; and tests whether it exists. If so (that is what the - ;; `when' checks), it calls an `if' function that determines + ;; 'when' checks), it calls an 'if' function that determines ;; whether the previous command was another call to - ;; `kill-region'; if it was, then the new text is appended to + ;; 'kill-region'; if it was, then the new text is appended to ;; the previous text; if not, then a different function, - ;; `kill-new', is called. + ;; 'kill-new', is called. @end group @group - ;; The `kill-append' function concatenates the new string and - ;; the old. The `kill-new' function inserts text into a new + ;; The 'kill-append' function concatenates the new string and + ;; the old. The 'kill-new' function inserts text into a new ;; item in the kill ring. @end group @group - ;; `when' is an `if' without an else-part. The second `when' + ;; 'when' is an 'if' without an else-part. The second 'when' ;; again checks whether the current string exists; in ;; addition, it checks whether the previous command was - ;; another call to `kill-region'. If one or the other + ;; another call to 'kill-region'. If one or the other ;; condition is true, then it sets the current command to - ;; be `kill-region'. + ;; be 'kill-region'. @end group @group (let ((string (filter-buffer-substring beg end t))) @@ -7979,10 +7999,10 @@ The command \\[yank] can retrieve it from there. @dots{} " (if (eq last-command 'kill-region) @end group @group - ;; @minus{} `yank-handler' is an optional argument to - ;; `kill-region' that tells the `kill-append' and - ;; `kill-new' functions how deal with properties - ;; added to the text, such as `bold' or `italics'. + ;; @minus{} 'yank-handler' is an optional argument to + ;; 'kill-region' that tells the 'kill-append' and + ;; 'kill-new' functions how deal with properties + ;; added to the text, such as 'bold' or 'italics'. (kill-append string (< end beg) yank-handler) (kill-new string nil yank-handler))) (when (or string (eq last-command 'kill-region)) @@ -7991,7 +8011,7 @@ The command \\[yank] can retrieve it from there. @dots{} " @end group @group - ;; @bullet{} The third argument to `condition-case' tells the interpreter + ;; @bullet{} The third argument to 'condition-case' tells the interpreter ;; what to do with an error. @end group @group @@ -8034,7 +8054,7 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 1. `condition-case' takes three arguments. + ;; 1. 'condition-case' takes three arguments. ;; If the first argument is nil, as it is here, ;; information about the error signal is not ;; stored for use by another function. @@ -8042,25 +8062,25 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 2. The second argument to `condition-case' + ;; 2. The second argument to 'condition-case' ;; tells the Lisp interpreter what to do when all goes well. @end group @group - ;; The `delete-and-extract-region' function usually does the + ;; The 'delete-and-extract-region' function usually does the ;; work. If the beginning and ending of the region are both - ;; the same, then the variable `string' will be empty, or nil + ;; the same, then the variable 'string' will be empty, or nil (let ((string (delete-and-extract-region beg end))) @end group @group - ;; `when' is an `if' clause that cannot take an `else-part'. - ;; Emacs normally sets the value of `last-command' to the + ;; 'when' is an 'if' clause that cannot take an 'else-part'. + ;; Emacs normally sets the value of 'last-command' to the ;; previous command. @end group @group - ;; `kill-append' concatenates the new string and the old. - ;; `kill-new' inserts text into a new item in the kill ring. + ;; 'kill-append' concatenates the new string and the old. + ;; 'kill-new' inserts text into a new item in the kill ring. (when string (if (eq last-command 'kill-region) ;; if true, prepend string @@ -8070,7 +8090,7 @@ The text is deleted but saved in the kill ring." @end group @group - ;; 3. The third argument to `condition-case' tells the interpreter + ;; 3. The third argument to 'condition-case' tells the interpreter ;; what to do with an error. @end group @group @@ -8138,7 +8158,7 @@ However, if an error occurs, among its other actions, the function generating the error signal will define one or more error condition names. -An error handler is the third argument to @code{condition case}. +An error handler is the third argument to @code{condition-case}. An error handler has two parts, a @var{condition-name} and a @var{body}. If the @var{condition-name} part of an error handler matches a condition name generated by an error, then the @var{body} @@ -8200,7 +8220,7 @@ Technically speaking, @code{when} is a Lisp macro. A Lisp macro enables you to define new control constructs and other language features. It tells the interpreter how to compute another Lisp expression which will in turn compute the value. In this case, the -`other expression' is an @code{if} expression. +other expression is an @code{if} expression. The @code{kill-region} function definition also has an @code{unless} macro; it is the converse of @code{when}. The @code{unless} macro is @@ -8234,7 +8254,7 @@ The then-part is evaluated if the previous command was another call to @code{yank-handler} is an optional argument to @code{kill-region} that tells the @code{kill-append} and @code{kill-new} functions how deal -with properties added to the text, such as `bold' or `italics'. +with properties added to the text, such as bold or italics. @code{last-command} is a variable that comes with Emacs that we have not seen before. Normally, whenever a function is executed, Emacs @@ -8322,7 +8342,7 @@ document from the beginning, understanding these parts of a function is almost becoming routine. The documentation is somewhat confusing unless you remember that the -word `kill' has a meaning different from usual. The `Transient Mark' +word ``kill'' has a meaning different from usual. The Transient Mark and @code{interprogram-cut-function} comments explain certain side-effects. @@ -8474,8 +8494,8 @@ a moment. (Also, the function provides an optional argument called @code{yank-handler}; when invoked, this argument tells the function -how to deal with properties added to the text, such as `bold' or -`italics'.) +how to deal with properties added to the text, such as bold or +italics.) @c !!! bug in GNU Emacs 22 version of kill-append ? It has a @code{let*} function to set the value of the first element of @@ -8567,20 +8587,8 @@ function which in turn uses the @code{setcar} function. @unnumberedsubsubsec The @code{kill-new} function @findex kill-new -@c in GNU Emacs 22, additional documentation to kill-new: -@ignore -Optional third arguments YANK-HANDLER controls how the STRING is later -inserted into a buffer; see `insert-for-yank' for details. -When a yank handler is specified, STRING must be non-empty (the yank -handler, if non-nil, is stored as a `yank-handler' text property on STRING). - -When the yank handler has a non-nil PARAM element, the original STRING -argument is not used by `insert-for-yank'. However, since Lisp code -may access and use elements from the kill ring directly, the STRING -argument should still be a \"useful\" string for such uses." -@end ignore @need 1200 -The @code{kill-new} function looks like this: +In version 22 the @code{kill-new} function looks like this: @smallexample @group @@ -8645,7 +8653,7 @@ As usual, we can look at this function in parts. The function definition has an optional @code{yank-handler} argument, which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. +added to the text, such as bold or italics. We will skip that. @need 1200 The first line of the documentation makes sense: @@ -8889,7 +8897,7 @@ It starts with an @code{if} expression In this case, the expression tests first to see whether @code{menu-bar-update-yank-menu} exists as a function, and if so, calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the +is testing has a function definition that is not void. If the symbol's function definition were void, we would receive an error message, as we did when we created errors intentionally (@pxref{Making Errors, , Generate an Error Message}). @@ -8916,7 +8924,7 @@ The expression determines whether the second argument to @end ignore @code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu +possible to use the ``Select and Paste'' menu in the Edit item of a menu bar; using a mouse, you can look at the various pieces of text you have saved and select one piece to paste. @@ -8952,7 +8960,7 @@ an existing element or as a new element, leads us to the code for bringing back text that has been cut out of the buffer---the yank commands. However, before discussing the yank commands, it is better to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before +clear such mysteries as the use of the term ``pointer''. But before that, we will digress into C. @ignore @@ -8963,7 +8971,7 @@ expression is true, @code{kill-append} prepends the string to the just previously clipped text. For a detailed discussion, see @ref{kill-append function, , The @code{kill-append} function}.) -If you then yank back the text, i.e., `paste' it, you get both +If you then yank back the text, i.e., paste it, you get both pieces of text at once. That way, if you delete two words in a row, and then yank them back, you get both words, in their proper order, with one yank. (The @w{@code{(< end beg))}} expression makes sure the @@ -9069,7 +9077,7 @@ The sixth part is nearly like the argument that follows the @code{interactive} declaration in a function written in Lisp: a letter followed, perhaps, by a prompt. The only difference from the Lisp is when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. +(which is a null string), as in this macro. If you were to specify arguments, you would place them between quotation marks. The C macro for @code{goto-char} includes @@ -9081,13 +9089,13 @@ and provides a prompt. The seventh part is a documentation string, just like the one for a function written in Emacs Lisp. This is written as a C comment. (When you build Emacs, the program @command{lib-src/make-docfile} extracts -these comments and uses them to make the ``real'' documentation.) +these comments and uses them to make the documentation.) @end itemize @need 1200 In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' +what kind of object they are, followed by the body +of the macro. For @code{delete-and-extract-region} the body consists of the following four lines: @smallexample @@ -9113,13 +9121,13 @@ passed to @code{del_range}. These are @w{@code{XINT (start)}} and As far as the C language is concerned, @code{start} and @code{end} are two integers that mark the beginning and end of the region to be deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can +to understand, the two integers are of type @code{Lisp_Object}, which can also be a C union instead of an integer type.}. In early versions of Emacs, these two numbers were thirty-two bits long, but the code is slowly being generalized to handle other lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. +information; the remaining bits are used as content. @samp{XINT} is a C macro that extracts the relevant number from the longer collection of bits; the three other bits are discarded. @@ -9328,7 +9336,7 @@ For example: its remaining arguments to its first argument. @item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. +Return the result of taking @sc{cdr} @var{n} times on a list. @iftex The @tex @@ -9336,7 +9344,7 @@ $n^{th}$ @end tex @code{cdr}. @end iftex -The `rest of the rest', as it were. +The ``rest of the rest'', as it were. @need 1250 For example: @@ -9645,7 +9653,7 @@ address-boxes for the list.) If a symbol is set to the @sc{cdr} of a list, the list itself is not changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, +the jargon, @sc{car} and @sc{cdr} are ``non-destructive''.) Thus, evaluation of the following expression @smallexample @@ -9807,7 +9815,7 @@ In an earlier section, I suggested that you might imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice-verse. +drawer holding the function definition, and vice versa. Actually, what is put in each drawer is the address of the value or function definition. It is as if you found an old chest in the attic, @@ -9815,7 +9823,7 @@ and in one of its drawers you found a map giving you directions to where the buried treasure lies. (In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to +symbol has a drawer for a @dfn{property list} which can be used to record other information. Property lists are not discussed here; see @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp Reference Manual}.) @@ -9909,8 +9917,8 @@ What does the @code{more-flowers} list now contain? @cindex Retrieving text @cindex Pasting text -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of +Whenever you cut text out of a buffer with a kill command in GNU Emacs, +you can bring it back with a yank command. The text that is cut out of the buffer is put in the kill ring and the yank commands insert the appropriate contents of the kill ring back into a buffer (not necessarily the original buffer). @@ -9922,7 +9930,7 @@ the second element. Successive @kbd{M-y} commands replace the second element with the third, fourth, or fifth element, and so on. When the last element in the kill ring is reached, it is replaced by the first element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure +``ring'' rather than just a ``list''. However, the actual data structure that holds the text is a list. @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the list is handled as a ring.) @@ -10066,7 +10074,7 @@ These two ways of talking about the same thing sound confusing at first but make sense on reflection. The kill ring is generally thought of as the complete structure of data that holds the information of what has recently been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part +on the other hand, serves to indicate---that is, to point to---that part of the kill ring of which the first element (the @sc{car}) will be inserted. @@ -10150,7 +10158,7 @@ their kin; but you can use recursion, which provides a very powerful way to think about and then to solve problems@footnote{You can write recursive functions to be frugal or wasteful of mental or computer resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer +frugal of mental resources---sometimes use considerable computer resources. Emacs was designed to run on machines that we now consider limited and its default settings are conservative. You may want to increase the values of @code{max-specpdl-size} and @@ -10213,7 +10221,7 @@ evaluated. This process is called a loop since the Lisp interpreter repeats the same thing again and again, like an airplane doing a loop. When the result of evaluating the true-or-false-test is false, the Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. +expression and exits the loop. Clearly, if the value returned by evaluating the first argument to @code{while} is always true, the body following will be evaluated @@ -10374,7 +10382,7 @@ expression, @code{(print-elements-of-list animals)}, by typing to be printed in the @file{*scratch*} buffer instead of being printed in the echo area. (Otherwise you will see something like this in your echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) +each @samp{^J} stands for a newline.) @need 1500 In a recent instance of GNU Emacs, you can evaluate these expressions @@ -10943,8 +10951,8 @@ provide for looping. Sometimes these are quicker to write than the equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it +@code{dolist} works like a @code{while} loop that @sc{cdr}s down a +list: @code{dolist} automatically shortens the list each time it loops---takes the @sc{cdr} of the list---and binds the @sc{car} of each shorter version of the list to the first of its arguments. @@ -11045,7 +11053,7 @@ of the work you have to do when writing a @code{while} expression. Like a @code{while} loop, a @code{dolist} loops. What is different is that it automatically shortens the list each time it loops---it -`@sc{cdr}s down the list' on its own---and it automatically binds +@sc{cdr}s down the list on its own---and it automatically binds the @sc{car} of each shorter version of the list to the first of its arguments. @@ -11100,7 +11108,7 @@ up the number of pebbles in a triangle. @smallexample @group (defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." + "Using `dotimes', add up the number of pebbles in a triangle." (let ((total 0)) ; otherwise a total is a void variable (dotimes (number number-of-rows total) (setq total (+ total (1+ number)))))) @@ -11118,10 +11126,10 @@ call a program that runs exactly like itself, but with slightly different arguments. The code runs exactly the same because it has the same name. However, even though the program has the same name, it is not the same entity. It is different. In the jargon, it is a -different `instance'. +different ``instance''. -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first +Eventually, if the program is written correctly, the slightly +different arguments will become sufficiently different from the first arguments that the final instance will stop. @menu @@ -11161,10 +11169,10 @@ install a function definition, that is, when you evaluate a @code{defun} macro, you install the necessary equipment to build robots. It is as if you were in a factory, setting up an assembly line. Robots with the same name are built according to the same -blueprints. So they have, as it were, the same `model number', but a -different `serial number'. +blueprints. So they have the same model number, but a +different serial number. -We often say that a recursive function `calls itself'. What we mean +We often say that a recursive function ``calls itself''. What we mean is that the instructions in a recursive function cause the Lisp interpreter to run a different function that has the same name and does the same job as the first, but with different arguments. @@ -11275,7 +11283,7 @@ Uses recursion." The @code{print-elements-recursively} function first tests whether there is any content in the list; if there is, the function prints the first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the +function invokes itself, but gives itself as its argument, not the whole list, but the second and subsequent elements of the list, the @sc{cdr} of the list. @@ -11291,16 +11299,16 @@ a different individual from the first, but is the same model. When the second evaluation occurs, the @code{when} expression is evaluated and if true, prints the first element of the list it receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list +list). Then the function calls itself with the @sc{cdr} of the list it is invoked with, which (the second time around) is the @sc{cdr} of the @sc{cdr} of the original list. -Note that although we say that the function `calls itself', what we +Note that although we say that the function ``calls itself'', what we mean is that the Lisp interpreter assembles and instructs a new instance of the program. The new instance is a clone of the first, but is a separate individual. -Each time the function `invokes itself', it invokes itself on a +Each time the function invokes itself, it does so on a shorter version of the original list. It creates a new instance that works on a shorter list. @@ -11612,7 +11620,7 @@ and this provides a sense of its primal capabilities. @node Every @unnumberedsubsubsec Recursive Pattern: @emph{every} @cindex Every, type of recursive pattern -@cindex Recursive pattern: every +@cindex Recursive pattern - every In the @code{every} recursive pattern, an action is performed on every element of a list. @@ -11711,14 +11719,14 @@ But when the list has at least one element, @node Accumulate @unnumberedsubsubsec Recursive Pattern: @emph{accumulate} @cindex Accumulate, type of recursive pattern -@cindex Recursive pattern: accumulate +@cindex Recursive pattern - accumulate Another recursive pattern is called the @code{accumulate} pattern. In the @code{accumulate} recursive pattern, an action is performed on every element of a list and the result of that action is accumulated with the results of performing the action on the other elements. -This is very like the `every' pattern using @code{cons}, except that +This is very like the @code{every} pattern using @code{cons}, except that @code{cons} is not used, but some other combiner. @need 1500 @@ -11762,14 +11770,14 @@ accumulate pattern. @node Keep @unnumberedsubsubsec Recursive Pattern: @emph{keep} @cindex Keep, type of recursive pattern -@cindex Recursive pattern: keep +@cindex Recursive pattern - keep A third recursive pattern is called the @code{keep} pattern. In the @code{keep} recursive pattern, each element of a list is tested; the element is acted on and the results are kept only if the element meets a criterion. -Again, this is very like the `every' pattern, except the element is +Again, this is very like the @code{every} pattern, except the element is skipped unless it meets a criterion. @need 1500 @@ -11870,7 +11878,7 @@ think of it as a little robot---cannot complete its job. It must hand off the calculation for @code{(triangle-recursively 6)} to a second instance of the program, to a second robot. This second individual is completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different +``different instantiation''. Or, put another way, it is a different robot. It is the same model as the first; it calculates triangle numbers recursively; but it has a different serial number. @@ -11914,18 +11922,17 @@ more steps. @node No deferment solution @subsection No Deferment Solution @cindex No deferment solution -@cindex Defermentless solution @cindex Solution without deferment The solution to the problem of deferred operations is to write in a manner that does not defer operations@footnote{The phrase @dfn{tail recursive} is used to describe such a process, one that uses -`constant space'.}. This requires +constant space.}. This requires writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' +function definitions, an initialization function and a helper function. -The `initialization' function sets up the job; the `helper' function +The initialization function sets up the job; the helper function does the work. @need 1200 @@ -11936,7 +11943,7 @@ so simple, I find them hard to understand. @group (defun triangle-initialization (number) "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function +This is the initialization component of a two function duo that uses recursion." (triangle-recursive-helper 0 0 number)) @end group @@ -11946,7 +11953,7 @@ duo that uses recursion." @group (defun triangle-recursive-helper (sum counter number) "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo +This is the helper component of a two function duo that uses recursion." (if (> counter number) sum @@ -11967,21 +11974,21 @@ Install both function definitions by evaluating them, then call @end group @end smallexample -The `initialization' function calls the first instance of the `helper' +The initialization function calls the first instance of the helper function with three arguments: zero, zero, and a number which is the number of rows in the triangle. -The first two arguments passed to the `helper' function are +The first two arguments passed to the helper function are initialization values. These values are changed when @code{triangle-recursive-helper} invokes new instances.@footnote{The jargon is mildly confusing: @code{triangle-recursive-helper} uses a process that is iterative in a procedure that is recursive. The process is called iterative because the computer need only record the three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the +procedure is recursive because the function calls itself. On the other hand, both the process and the procedure used by @code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} +``recursive'' has different meanings in the two contexts.} Let's see what happens when we have a triangle that has one row. (This triangle will have one pebble in it!) @@ -12117,7 +12124,7 @@ Internet, see @uref{http://www.gnu.org/software/texinfo/manual/texinfo/} @end ifhtml @iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU +``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU Documentation Format}. @end iftex @end itemize @@ -12134,8 +12141,8 @@ Documentation Format}. Regular expression searches are used extensively in GNU Emacs. The two functions, @code{forward-sentence} and @code{forward-paragraph}, illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. +where to move point. The phrase ``regular expression'' is often written +as ``regexp''. Regular expression searches are described in @ref{Regexp Search, , Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in @@ -12332,7 +12339,7 @@ search is successful, it leaves point immediately after the last character in the target. If the search is backwards, it leaves point just before the first character in the target. You may tell @code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) +is therefore a side effect.) Like @code{search-forward}, the @code{re-search-forward} function takes four arguments: @@ -12422,8 +12429,8 @@ Here is the code for @code{forward-sentence}: @smallexample @group (defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. + "Move forward to next end of sentence. With argument, repeat. +With negative argument, move backward repeatedly to start of sentence. The variable `sentence-end' is a regular expression that matches ends of sentences. Also, every paragraph boundary terminates sentences as well." @@ -12634,7 +12641,7 @@ evaluates its then-part; otherwise, the Emacs Lisp interpreter evaluates the else-part. The true-or-false-test of the @code{if} expression is the regular expression search. -It may seem odd to have what looks like the `real work' of +It may seem odd to have what looks like the real work of the @code{forward-sentence} function buried here, but this is a common way this kind of operation is carried out in Lisp. @@ -12916,6 +12923,7 @@ The next line of the @code{forward-paragraph} function begins a @code{let*} expression. This is a different than @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 @@ -13238,7 +13246,7 @@ Consider what happens when there is no fill prefix. @noindent This @code{while} loop has us searching forward for @code{sp-parstart}, which is the combination of possible whitespace -with a the local value of the start of a paragraph or of a paragraph +with the local value of the start of a paragraph or of a paragraph separator. (The latter two are within an expression starting @code{\(?:} so that they are not referenced by the @code{match-beginning} function.) @@ -13365,7 +13373,7 @@ of which I load 12---you can create a @file{TAGS} file for the Emacs Lisp files in that directory. @need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For +The @code{etags} program takes all the usual shell wildcards. For example, if you have two directories for which you want a single @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where @file{../elisp/} is the second directory: @@ -13404,7 +13412,7 @@ program to attempt to find it. Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list for you the full path names of all your @file{TAGS} files. On my system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any +plain vanilla system I recently installed did not contain any @file{TAGS} files. If the tags table you want has been created, you can use the @code{M-x @@ -13420,7 +13428,7 @@ visit-tags-table}. The GNU Emacs sources come with a @file{Makefile} that contains a sophisticated @code{etags} command that creates, collects, and merges tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The +into one @file{TAGS} file in the @file{src/} directory. (The @file{src/} directory is below the top level of your Emacs directory.) @need 1250 @@ -13507,9 +13515,9 @@ For example: @smallexample @group (let* ((foo 7) - (bar (* 3 foo))) + (bar (* 3 foo))) (message "`bar' is %d." bar)) - @result{} `bar' is 21. + @result{} ‘bar’ is 21. @end group @end smallexample @@ -13538,7 +13546,7 @@ Write a function to search for a regular expression that matches two or more blank lines in sequence. @item -Write a function to search for duplicated words, such as `the the'. +Write a function to search for duplicated words, such as ``the the''. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for information on how to write a regexp (a regular expression) to match a string that is composed of two identical @@ -13548,7 +13556,7 @@ regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. @end itemize @node Counting Words -@chapter Counting: Repetition and Regexps +@chapter Counting via Repetition and Regexps @cindex Repetition for word counting @cindex Regular expressions for word counting @@ -13673,7 +13681,7 @@ forward, and false when point is at the end of the region. We could use @code{(forward-word 1)} as the expression for moving point forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. +``word'' if we use a regular expression search. A regular expression search that finds the pattern for which it is searching leaves point after the last character matched. This means @@ -13717,7 +13725,7 @@ single backslash has special meaning to the Emacs Lisp interpreter. It indicates that the following character is interpreted differently than usual. For example, the two characters, @samp{\n}, stand for @samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so +backslashes in a row stand for an ordinary, unspecial backslash, so Emacs Lisp interpreter ends of seeing a single backslash followed by a letter. So it discovers the letter is special.) @@ -13940,7 +13948,7 @@ What happens is this: the search is limited to the region, and fails as you expect because there are no word-constituent characters in the region. Since it fails, we receive an error message. But we do not want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." +message ``The region does NOT have any words.'' The solution to this problem is to provide @code{re-search-forward} with a third argument of @code{t}, which causes the function to return @@ -14109,8 +14117,8 @@ the region, as returned by the recursive call; and then the user. Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, +somehow secondary to the primary work of a function. But in this +case, what you might consider the primary job of the function, counting words, is done within the @code{let} expression. @need 1250 @@ -14151,8 +14159,8 @@ Using @code{let}, the function definition looks like this: Next, we need to write the recursive counting function. -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. +A recursive function has at least three parts: the do-again-test, the +next-step-expression, and the recursive call. The do-again-test determines whether the function will or will not be called again. Since we are counting words in a region and can use a @@ -14176,7 +14184,7 @@ the expression that moves point forward, word by word. The third part of a recursive function is the recursive call. -Somewhere, also, we also need a part that does the `work' of the +Somewhere, also, we also need a part that does the work of the function, a part that does the counting. A vital part! @need 1250 @@ -14432,7 +14440,7 @@ exclamation mark, and question mark. Do the same using recursion. Our next project is to count the number of words in a function definition. Clearly, this can be done using some variant of -@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting Words: +@code{@value{COUNT-WORDS}}. @xref{Counting Words, , Counting via Repetition and Regexps}. If we are just going to count the words in one definition, it is easy enough to mark the definition with the @kbd{C-M-h} (@code{mark-defun}) command, and then call @@ -14502,9 +14510,9 @@ be difficult. When we first start thinking about how to count the words in a function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp +we going to count? When we speak of ``words'' with respect to a Lisp function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} +symbols. For example, the following @code{multiply-by-seven} function contains the five symbols @code{defun}, @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In addition, in the documentation string, it contains the four words @@ -14546,8 +14554,8 @@ regexp is: @noindent This regular expression is a pattern defining one or more word constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section +that are not word constituents. What is meant by ``word constituent +characters'' brings us to the issue of syntax, which is worth a section of its own. @node Syntax @@ -14565,9 +14573,9 @@ character. (For more information, @pxref{Syntax Tables, , Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the +Usually, a hyphen is not specified as a word constituent character. +Instead, it is specified as being in the class of characters that are +part of symbol names but not words. This means that the @code{@value{COUNT-WORDS}} function treats it in the same way it treats an interword white space, which is why @code{@value{COUNT-WORDS}} counts @samp{multiply-by-seven} as three words. @@ -14586,8 +14594,8 @@ Alternatively, we can redefine the regexp used in the procedure has the merit of clarity, but the task is a little tricky. @need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: +The first part is simple enough: the pattern must match at least one +character that is a word or symbol constituent. Thus: @smallexample "\\(\\w\\|\\s_\\)+" @@ -14603,8 +14611,8 @@ following the group indicates that the word or symbol constituent characters must be matched at least once. However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, +What we want is to follow the first part with optionally one or more +characters that are not constituents of a word or symbol. At first, I thought I could define this with the following: @smallexample @@ -14970,7 +14978,7 @@ The task is easy: use @code{find-file-noselect} and @code{set-buffer}. @section @code{lengths-list-file} in Detail The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and +loop containing a function to move point forward defun by defun, and a function to count the number of words and symbols in each defun. This core must be surrounded by functions that do various other tasks, including finding the file, and ensuring that point starts out at the @@ -15036,14 +15044,14 @@ Next comes a call to widen the buffer if it is narrowed. This function is usually not needed---Emacs creates a fresh buffer if none already exists; but if a buffer visiting the file already exists Emacs returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would +be widened. If we wanted to be fully user-friendly, we would arrange to save the restriction and the location of point, but we won't. The @code{(goto-char (point-min))} expression moves point to the beginning of the buffer. -Then comes a @code{while} loop in which the `work' of the function is +Then comes a @code{while} loop in which the work of the function is carried out. In the loop, Emacs determines the length of each definition and constructs a lengths' list containing the information. @@ -15064,18 +15072,19 @@ C-e} (@code{eval-last-sexp}). @c !!! 22.1.1 lisp sources location here @smallexample (lengths-list-file - "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") + "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el") @end smallexample @noindent -(You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1.1. To change the expression, copy it to +You may need to change the pathname of the file; the one here is for +GNU Emacs version 22.1. To change the expression, copy it to the @file{*scratch*} buffer and edit it. @need 1200 @noindent -(Also, to see the full length of the list, rather than a truncated +Also, to see the full length of the list, rather than a truncated version, you may have to evaluate the following: +@c We do not want to insert, so do not mention the zero prefix argument. @smallexample (custom-set-variables '(eval-expression-print-length nil)) @@ -15101,7 +15110,8 @@ took seven seconds to produce and looked like this: (75 41 80 62 20 45 44 68 45 12 34 235) @end smallexample -(The newer version of @file{debug.el} contains more defuns than the +@noindent +The newer version of @file{debug.el} contains more defuns than the earlier one; and my new machine is much faster than the old one.) Note that the length of the last definition in the file is first in @@ -15262,11 +15272,11 @@ Besides a @code{while} loop, you can work on each of a list of files with recursion. A recursive version of @code{lengths-list-many-files} is short and simple. -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' +The recursive function has the usual parts: the do-again-test, the +next-step-expression, and the recursive call. The do-again-test determines whether the function should call itself again, which it will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the +the next-step-expression resets the @code{list-of-files} to the @sc{cdr} of itself, so eventually the list will be empty; and the recursive call calls itself on the shorter list. The complete function is shorter than this description! @@ -15367,7 +15377,7 @@ numbers. @end ifnottex Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the +should not be too hard to write a function that @sc{cdr}s down the lengths' list, looks at each element, determines which length range it is in, and increments a counter for that range. @@ -15387,7 +15397,7 @@ that we will need. Emacs contains a function to sort lists, called (as you might guess) @code{sort}. The @code{sort} function takes two arguments, the list to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. +two list elements is less than the second. As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong Type Object as an Argument}), a predicate is a function that @@ -15506,7 +15516,7 @@ as a list that looks like this (but with more elements): The @code{directory-files-and-attributes} function returns a list of lists. Each of the lists within the main list consists of 13 elements. The first element is a string that contains the name of the -file---which, in GNU/Linux, may be a `directory file', that is to +file---which, in GNU/Linux, may be a @dfn{directory file}, that is to say, a file with the special attributes of a directory. The second element of the list is @code{t} for a directory, a string for symbolic link (the string is the name linked to), or @code{nil}. @@ -15571,8 +15581,8 @@ the function comes upon a sub-directory, it should go into that sub-directory and repeat its actions. However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In +refers to itself, called @file{.} (``dot''), and a name that refers to +its parent directory, called @file{..} (``dot dot''). (In @file{/}, the root directory, @file{..} refers to itself, since @file{/} has no parent.) Clearly, we do not want our @code{files-in-below-directory} function to enter those directories, @@ -15605,8 +15615,8 @@ Let's write a function definition to do these tasks. We will use a @code{while} loop to move from one filename to another within a directory, checking what needs to be done; and we will use a recursive call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), +pattern is Accumulate +(@pxref{Accumulate}), using @code{append} as the combiner. @ignore @@ -15641,7 +15651,7 @@ Here is the function: @end group @group (cond - ;; check to see whether filename ends in `.el' + ;; check to see whether filename ends in '.el' ;; and if so, append its name to a list. ((equal ".el" (substring (car (car current-directory-list)) -3)) (setq el-files-list @@ -15857,7 +15867,7 @@ produces: (4 3 2 1) @end smallexample -Note that the @code{nreverse} function is ``destructive''---that is, +Note that the @code{nreverse} function is destructive---that is, it changes the list to which it is applied; this contrasts with the @code{car} and @code{cdr} functions, which are non-destructive. In this case, we do not want the original @code{defuns-per-range-list}, @@ -16063,7 +16073,7 @@ the function to label the axes automatically. Since Emacs is designed to be flexible and work with all kinds of terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as +be made from one of the typewriter symbols. An asterisk will do; as we enhance the graph-printing function, we can make the choice of symbol a user option. @@ -16093,7 +16103,7 @@ a regular expression, including functions that are not interactive. What we want to look for is some command that prints or inserts columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. +the word ``print'' or the word ``insert'' or the word ``column''. Therefore, we can simply type @kbd{M-x apropos RET print\|insert\|column RET} and look at the result. On my system, this command once too takes quite some time, and then produced a list of 79 @@ -16230,7 +16240,7 @@ Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) @findex apply We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first +This function is @code{apply}. This function applies its first argument (a function) to its remaining arguments, the last of which may be a list. @@ -16248,7 +16258,7 @@ returns 8. without a book such as this. It is possible to discover other functions, like @code{search-forward} or @code{insert-rectangle}, by guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to +though its base in metaphor is clear---apply its first argument to the rest---I doubt a novice would come up with that particular word when using @code{apropos} or other aid. Of course, I could be wrong; after all, the function was first named by someone who had to invent @@ -16336,7 +16346,7 @@ returns As written, @code{column-of-graph} contains a major flaw: the symbols used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, +hard-coded as a space and asterisk. This is fine for a prototype, but you, or another user, may wish to use other symbols. For example, in testing the graph function, you many want to use a period in place of the space, to make sure the point is being repositioned properly @@ -16415,7 +16425,7 @@ is no more than a bar graph in which the part of each bar that is below the top is blank. To construct a column for a line graph, the function first constructs a list of blanks that is one shorter than the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to +list; then it uses @code{cons} again to attach the top blanks to the list. It is easy to see how to write such a function, but since we don't @@ -16531,7 +16541,7 @@ The one unexpected expression in this function is the @w{@code{(sit-for 0)}} expression in the @code{while} loop. This expression makes the graph printing operation more interesting to watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the +@dfn{sit} or do nothing for a zero length of time and then redraw the screen. Placed here, it causes Emacs to redraw the screen column by column. Without it, Emacs would not redraw the screen until the function exits. @@ -16593,14 +16603,14 @@ Emacs will print a graph like this: @findex recursive-graph-body-print The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' +The recursive solution is divided into two parts: an outside wrapper that uses a @code{let} expression to determine the values of several variables that need only be found once, such as the maximum height of the graph, and an inside function that is called recursively to print the graph. @need 1250 -The `wrapper' is uncomplicated: +The wrapper is uncomplicated: @smallexample @group @@ -16618,13 +16628,13 @@ The numbers-list consists of the Y-axis values." @end smallexample The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} +the do-again-test, the printing code, the recursive call, and the +next-step-expression. The do-again-test is a @code{when} expression that determines whether the @code{numbers-list} contains any remaining elements; if it does, the function prints one column of the graph using the printing code and calls itself again. The function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter +next-step-expression which causes the call to act on a shorter version of the @code{numbers-list}. @smallexample @@ -16700,8 +16710,8 @@ Write a line graph version of the graph printing functions. @cindex Initialization file ``You don't have to like Emacs to like it''---this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize +paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box +Emacs is a generic tool. Most people who use it, customize it to suit themselves. GNU Emacs is mostly written in Emacs Lisp; this means that by writing @@ -16739,7 +16749,7 @@ person hopes to do with an unadorned file? Fundamental mode is the right default for such a file, just as C mode is the right default for editing C code. (Enough programming languages have syntaxes that enable them to share or nearly share features, so C mode is -now provided by CC mode, the `C Collection'.) +now provided by CC mode, the C Collection.) But when you do know who is going to use Emacs---you, yourself---then it makes sense to customize Emacs. @@ -16784,8 +16794,8 @@ have the same form as your @file{.emacs} file, but are loaded by everyone. Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped +@file{site-init.el}, are loaded into Emacs and then dumped if a +dumped version of Emacs is created, as is most common. (Dumped copies of Emacs load more quickly. However, once a file is loaded and dumped, a change to it does not lead to a change in Emacs unless you load it yourself or re-dump Emacs. @xref{Building Emacs, , Building @@ -16897,7 +16907,7 @@ M-x customize @end smallexample @noindent -and find that the group for editing files of data is called `data'. +and find that the group for editing files of data is called ``data''. Enter that group. Text Mode Hook is the first member. You can click on its various options, such as @code{turn-on-auto-fill}, to set the values. After you click on the button to @@ -17057,7 +17067,7 @@ Just remember: type @kbd{C-h} two times for help. @end smallexample @noindent -`Mode help', as I call this, is very helpful. Usually, it tells you +``Mode help'', as I call this, is very helpful. Usually, it tells you all you need to know. Of course, you don't need to include comments like these in your @@ -17068,7 +17078,7 @@ remember to look here to remind myself. @node Text and Auto-fill @section Text and Auto Fill Mode -Now we come to the part that `turns on' Text mode and +Now we come to the part that turns on Text mode and Auto Fill mode. @smallexample @@ -17100,7 +17110,7 @@ on C mode. Also, Emacs looks at first nonblank line of the file; if the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs possesses a list of extensions and specifications that it uses automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. +per-buffer, local variables list, if any. @ifinfo @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU @@ -17153,7 +17163,7 @@ In this line, the @code{add-hook} command adds @code{turn-on-auto-fill} is the name of a program, that, you guessed it!, turns on Auto Fill mode. -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' +Every time Emacs turns on Text mode, Emacs runs the commands hooked onto Text mode. So every time Emacs turns on Text mode, Emacs also turns on Auto Fill mode. @@ -17190,15 +17200,15 @@ fill commands to insert two spaces after a colon: @node Mail Aliases @section Mail Aliases -Here is a @code{setq} that `turns on' mail aliases, along with more +Here is a @code{setq} that turns on mail aliases, along with more reminders. @smallexample @group ;;; Mail mode -; To enter mail mode, type `C-x m' +; To enter mail mode, type 'C-x m' ; To enter RMAIL (for reading mail), -; type `M-x rmail' +; type 'M-x rmail' (setq mail-aliases t) @end group @end smallexample @@ -17210,7 +17220,7 @@ This @code{setq} command sets the value of the variable says, in effect, ``Yes, use mail aliases.'' Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' +for lists of email addresses. The file where you keep your aliases is @file{~/.mailrc}. You write an alias like this: @smallexample @@ -17248,7 +17258,7 @@ command sets values only in buffers that do not have their own local values for the variable. @ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. +@xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}. @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}. @@ -17285,9 +17295,9 @@ This also shows how to set a key globally, for all modes. @findex global-set-key The command is @code{global-set-key}. It is followed by the keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double +shown: @code{\C-c} stands for Control-C, which means to press the +control key and the @key{c} key at the same time. The @code{w} means +to press the @key{w} key. The keybinding is surrounded by double quotation marks. In documentation, you would write this as @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather than a @key{CTRL} key, you would write @@ -17308,19 +17318,19 @@ adapt what is there. As for the keybinding itself: @kbd{C-c w}. This combines the prefix key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since +reserved for individuals' own use. (I call these @dfn{own} keys, since these are for my own use.) You should always be able to create such a keybinding for your own use without stomping on someone else's keybinding. If you ever write an extension to Emacs, please avoid taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. +C-w} instead. Otherwise, we will run out of own keys. @need 1250 Here is another keybinding, with a comment: @smallexample @group -;;; Keybinding for `occur' +;;; Keybinding for 'occur' ; I use occur a lot, so let's bind it to a key: (global-set-key "\C-co" 'occur) @end group @@ -17341,7 +17351,7 @@ work: @smallexample @group -;;; Unbind `C-x f' +;;; Unbind 'C-x f' (global-unset-key "\C-xf") @end group @end smallexample @@ -17359,7 +17369,7 @@ The following rebinds an existing key: @smallexample @group -;;; Rebind `C-x C-b' for `buffer-menu' +;;; Rebind 'C-x C-b' for 'buffer-menu' (global-set-key "\C-x\C-b" 'buffer-menu) @end group @end smallexample @@ -17512,8 +17522,13 @@ Incidentally, @code{load-library} is an interactive interface to the @smallexample @group (defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." + "Load the Emacs Lisp library named LIBRARY. +This is an interface to the function `load'. LIBRARY is searched +for in `load-path', both with and without `load-suffixes' (as +well as `load-file-rep-suffixes'). + +See Info node `(emacs)Lisp Libraries' for more details. +See `load-file' for a different interface to `load'." (interactive (list (completing-read "Load library: " (apply-partially 'locate-file-completion-table @@ -17524,7 +17539,7 @@ This is an interface to the function `load'." @end smallexample The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the +``library'' as a conventional synonym for ``file''. The source for the @code{load-library} command is in the @file{files.el} library. Another interactive command that does a slightly different job is @@ -17549,15 +17564,15 @@ are not loaded right away; but you need to wait a moment when you first use such a function, while its containing file is evaluated. Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should +@file{loaddefs.el} library contains thousands of autoloaded functions, +from @code{5x5} to @code{zone}. Of course, you may +come to use a rare function frequently. When you do, you should load that function's file with a @code{load} expression in your @file{.emacs} file. In my @file{.emacs} file, I load 14 libraries that contain functions that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. +better to include these files in my dumped Emacs, but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more about dumping.) @@ -17684,7 +17699,7 @@ emacs -Q -D @group (when (>= emacs-major-version 21) (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) + ;; Insert newline when you press 'C-n' (next-line) ;; at the end of the buffer (setq next-line-add-newlines t) @end group @@ -17756,7 +17771,7 @@ file that set values: @group ;; Set calendar highlighting colors -(setq calendar-load-hook +(add-hook 'calendar-load-hook (lambda () (set-face-foreground 'diary-face "skyblue") (set-face-background 'holiday-face "slate blue") @@ -17805,9 +17820,9 @@ Set the shape and color of the mouse cursor: @smallexample @group ; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. +; '/usr/include/X11/cursorfont.h'; +; for example, the 'target' cursor is number 128; +; the 'top_left_arrow' cursor is number 132. @end group @group @@ -17858,10 +17873,10 @@ problem recently.) @smallexample @group -;; Translate `C-h' to <DEL>. +;; Translate 'C-h' to <DEL>. ; (keyboard-translate ?\C-h ?\C-?) -;; Translate <DEL> to `C-h'. +;; Translate <DEL> to 'C-h'. (keyboard-translate ?\C-? ?\C-h) @end group @end smallexample @@ -17879,7 +17894,7 @@ problem recently.) or start GNU Emacs with the command @code{emacs -nbc}. @need 1250 -@item When using `grep'@* +@item When using @command{grep}@* @samp{-i}@w{ } Ignore case distinctions@* @samp{-n}@w{ } Prefix each line of output with line number@* @samp{-H}@w{ } Print the filename for each match.@* @@ -17918,7 +17933,7 @@ This avoids problems with symbolic links. @end group @end smallexample -If you want to write with Chinese `GB' characters, set this instead: +If you want to write with Chinese GB characters, set this instead: @smallexample @group @@ -17961,7 +17976,7 @@ Lock} key is at the far left of the home row: @smallexample @group -# Bind the key labeled `Caps Lock' to `Control' +# Bind the key labeled 'Caps Lock' to 'Control' # (Such a broken user interface suggests that keyboard manufacturers # think that computers are typewriters from 1885.) @@ -18098,7 +18113,7 @@ beginning @code{(#("%12b" 0 4 @dots{}}. The @code{#(} begins the list. The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' +@code{buffer-name} function with which we are familiar; the @samp{12} specifies the maximum number of characters that will be displayed. When a name has fewer characters, whitespace is added to fill out to this number. (Buffer names can and often should be longer than 12 @@ -18108,7 +18123,7 @@ window.) @code{:eval} says to evaluate the following form and use the result as a string to display. In this case, the expression displays the first component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to +a @samp{.} (period), so I use the @code{string-match} function to tell me the length of the first component. The substring from the zeroth character to that length is the name of the machine. @@ -18123,18 +18138,18 @@ This is the expression: @end smallexample @samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' +to appear for each recursive editing level. @samp{%n} says ``Narrow'' when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the +the buffer that is above the bottom of the window, or ``Top'', ``Bottom'', +or ``All''. (A lower case @samp{p} tell you the percentage above the @emph{top} of the window.) @samp{%-} inserts enough dashes to fill out the line. -Remember, ``You don't have to like Emacs to like it''---your own +Remember, you don't have to like Emacs to like it---your own Emacs can have different colors, different commands, and different keys than a default Emacs. -On the other hand, if you want to bring up a plain `out of the box' +On the other hand, if you want to bring up a plain out-of-the-box Emacs, with no customization, type: @smallexample @@ -18235,9 +18250,9 @@ Debugger entered--Lisp error: (void-function 1=) long lines. As usual, you can quit the debugger by typing @kbd{q} in the @file{*Backtrace*} buffer.) -In practice, for a bug as simple as this, the `Lisp error' line will +In practice, for a bug as simple as this, the Lisp error line will tell you what you need to know to correct the definition. The -function @code{1=} is `void'. +function @code{1=} is void. @ignore @need 800 @@ -18533,7 +18548,7 @@ beginning of the @code{if} line of the function. Also, you will see an arrowhead at the left hand side of that line. The arrowhead marks the line where the function is executing. (In the following examples, we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) +see the arrowhead as a solid triangle in the window fringe.) @smallexample =>@point{}(if (= number 1) @@ -18568,7 +18583,7 @@ Result: 3 (#o3, #x3, ?\C-c) @noindent This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the +hexadecimal three, and @sc{ascii} Control-C (the third letter of the alphabet, in case you need to know this information). You can continue moving through the code until you reach the line with @@ -18615,7 +18630,7 @@ Lisp Reference Manual}. Install the @code{@value{COUNT-WORDS}} function and then cause it to enter the built-in debugger when you call it. Run the command on a region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after +remarkable number of times. On your system, is a hook called after the command finishes? (For information on hooks, see @ref{Command Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference Manual}.) @@ -18686,9 +18701,9 @@ easy-to-read description of Emacs Lisp. It is written not only for experts, but for people who know what you know. (The @cite{Reference Manual} comes with the standard GNU Emacs distribution. Like this introduction, it comes as a Texinfo source file, so you can read it -on-line and as a typeset, printed book.) +on your computer and as a typeset, printed book.) -Go to the other on-line help that is part of GNU Emacs: the on-line +Go to the other built-in help that is part of GNU Emacs: the built-in documentation for all functions and variables, and @code{find-tag}, the program that takes you to sources. @@ -18736,7 +18751,7 @@ customize the @code{interactive} expression without using the standard character codes; and it shows how to create a temporary buffer. (The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its +it is a built-in function. @code{help-follow} takes you to its source as does @code{find-tag}, when properly set up.) You can look at a function's source using @code{find-tag}, which is @@ -18804,7 +18819,7 @@ The GNU Emacs Lisp Reference Manual}.) You might try searching just for duplicated word-constituent characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. +such as the two occurrences of ``th'' in ``with the''. Another possible regexp searches for word-constituent characters followed by non-word-constituent characters, reduplicated. Here, @@ -18851,7 +18866,7 @@ Here is the @code{the-the} function, as I include it in my @end group @group -;; Bind `the-the' to C-c \ +;; Bind 'the-the' to C-c \ (global-set-key "\C-c\\" 'the-the) @end group @end smallexample @@ -18997,13 +19012,21 @@ The @code{current-kill} function is used by @code{yank} and by @group (defun current-kill (n &optional do-not-move) "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. +If N is zero and `interprogram-paste-function' is set to a +function that returns a string or a list of strings, and if that +function doesn't return nil, then that string (or list) is added +to the front of the kill ring and the string (or first string in +the list) is returned as the latest kill. @end group @group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." +If N is not zero, and if `yank-pop-change-selection' is +non-nil, use `interprogram-cut-function' to transfer the +kill at the new yank point into the window system selection. +@end group +@group +If optional arg DO-NOT-MOVE is non-nil, then don't actually +move the yanking point; just return the Nth kill forward." + (let ((interprogram-paste (and (= n 0) interprogram-paste-function (funcall interprogram-paste-function)))) @@ -19015,8 +19038,10 @@ yanking point; just return the Nth kill forward." ;; text to the kill ring, so Emacs doesn't try to own the ;; selection, with identical text. (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) + (if (listp interprogram-paste) + (mapc 'kill-new (nreverse interprogram-paste)) + (kill-new interprogram-paste))) + (car kill-ring)) @end group @group (or kill-ring (error "Kill ring is empty")) @@ -19024,8 +19049,12 @@ yanking point; just return the Nth kill forward." (nthcdr (mod (- n (length kill-ring-yank-pointer)) (length kill-ring)) kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) + (unless do-not-move + (setq kill-ring-yank-pointer ARGth-kill-element) + (when (and yank-pop-change-selection + (> n 0) + interprogram-cut-function) + (funcall interprogram-cut-function (car ARGth-kill-element)))) (car ARGth-kill-element))))) @end group @end smallexample @@ -19092,7 +19121,7 @@ The @code{if} expression has two parts, one if there exists @code{interprogram-paste} and one if not. @need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} +Let us consider the else-part of the @code{current-kill} function. (The then-part uses the @code{kill-new} function, which we have already described. @xref{kill-new function, , The @code{kill-new} function}.) @@ -19156,14 +19185,14 @@ list even if the @code{do-not-move} argument is true. @ifnottex @node Digression concerning error -@unnumberedsubsubsec Digression about the word `error' +@unnumberedsubsubsec Digression about the word ``error'' @end ifnottex In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot +the term ``error'' as the name of the @code{error} function. A better +term would be ``cancel''. Strictly speaking, of course, you cannot point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. +from the point of view of the computer, the word ``error'' is correct. But a human expects to attempt this sort of thing, if only to find out whether the kill ring is full or empty. This is an act of exploration. @@ -19173,8 +19202,8 @@ not necessarily an error, and therefore should not be labeled as one, even in the bowels of a computer. As it is, the code in Emacs implies that a human who is acting virtuously, by exploring his or her environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. +takes the same steps as it does when there is an error, a term such as +``cancel'' would have a clearer connotation. @ifnottex @node Determining the Element @@ -19336,15 +19365,15 @@ The code looks like this: "Reinsert (\"paste\") the last stretch of killed text. More precisely, reinsert the stretch of killed text most recently killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. +With just \\[universal-argument] as argument, same but put point at beginning (and mark at end). +With argument N, reinsert the Nth most recently killed stretch of killed +text. When this command inserts killed text into the buffer, it honors `yank-excluded-properties' and `yank-handler' as described in the doc string for `insert-for-yank-1', which see. -See also the command \\[yank-pop]." +See also the command `yank-pop' (\\[yank-pop])." @end group @group (interactive "*P") @@ -19360,8 +19389,7 @@ See also the command \\[yank-pop]." ((eq arg '-) -2) (t (1- arg))))) (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. + ;; This is like exchange-point-and-mark, but doesn't activate the mark. ;; It is cleaner to avoid activation, even though the command ;; loop would deactivate the mark because we inserted text. (goto-char (prog1 (mark t) @@ -19790,9 +19818,9 @@ For example, if you evaluate the following, the result is 15: (* (1+ (/ 12 5)) 5) @end smallexample -All through this discussion, we have been using `five' as the value +All through this discussion, we have been using 5 as the value for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to +value. For generality, we should replace 5 with a variable to which we can assign a value. The best name I can think of for this variable is @code{Y-axis-label-spacing}. @@ -20017,7 +20045,7 @@ the @code{print-Y-axis} function, which inserts the list as a column. Height must be the maximum height of the graph. Full width is the width of the highest label element." ;; Value of height and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by print-graph. @end group @group (let ((start (point))) @@ -20299,7 +20327,7 @@ First, we create a numbered element with blank spaces before each number: @end smallexample Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: +the number 1 under the first column: @findex print-X-axis-numbered-line @smallexample @@ -20707,9 +20735,9 @@ The graph looks like this: @end smallexample @noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) +(A question: is the @samp{2} on the bottom of the vertical axis a bug or a +feature? If you think it is a bug, and should be a @samp{1} instead, (or +even a @samp{0}), you can modify the sources.) @node Graphing words in defuns @appendixsubsec Graphing Numbers of Words and Symbols @@ -20817,8 +20845,8 @@ Thus, @end smallexample @noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. +is a function that returns the value resulting from +dividing whatever is passed to it as @code{arg} by 50. @need 1200 Earlier, for example, we had a function @code{multiply-by-seven}; it @@ -20959,7 +20987,7 @@ element of its second argument, in turn. The second argument must be a sequence. The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the +``mapping over a domain'', meaning to apply a function to each of the elements in a domain. The mathematical phrase is based on the metaphor of a surveyor walking, one step at a time, over an area he is mapping. And @samp{car}, of course, comes from the Lisp notion of the @@ -21039,7 +21067,7 @@ that none had that many words or symbols.) @cindex Bug, most insidious type @cindex Insidious type of bug -I said `almost ready to print'! Of course, there is a bug in the +I said ``almost ready to print''! Of course, there is a bug in the @code{print-graph} function @dots{} It has a @code{vertical-step} option, but not a @code{horizontal-step} option. The @code{top-of-range} scale goes from 10 to 300 by tens. But the @@ -21142,7 +21170,7 @@ each column." @end group @group ;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by print-graph. (let* ((leading-spaces (make-string full-Y-label-width ? )) ;; symbol-width @r{is provided by} graph-body-print @@ -21470,7 +21498,7 @@ Optionally, print according to VERTICAL-STEP." @end group @group ;; Value of height and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by 'print-graph'. (let ((start (point))) (insert-rectangle (Y-axis-column height full-Y-label-width vertical-step)) @@ -21635,7 +21663,7 @@ each column." @end group @group ;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. +;; are passed by 'print-graph'. (let* ((leading-spaces (make-string full-Y-label-width ? )) ;; symbol-width @r{is provided by} graph-body-print @@ -21873,7 +21901,7 @@ users think that a proprietary manual is good enough---so they don't see the need to write a free manual. They do not see that the free operating system has a gap that needs filling. -Why do users think that proprietary manuals are good enough? Some have +Why do users think that proprietary manuals are good enough? Some have not considered the issue. I hope this article will do something to change that. diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps index 11f3318037c..21b180c27cf 100644 --- a/doc/lispintro/lambda-1.eps +++ b/doc/lispintro/lambda-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:31:53 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps index 3022ce9bb6c..6eff61bbd22 100644 --- a/doc/lispintro/lambda-2.eps +++ b/doc/lispintro/lambda-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:09 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps index 0d66eb73332..6ab228262d5 100644 --- a/doc/lispintro/lambda-3.eps +++ b/doc/lispintro/lambda-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:49 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2013 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2015 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in deleted file mode 100644 index 39760ba5612..00000000000 --- a/doc/lispintro/makefile.w32-in +++ /dev/null @@ -1,85 +0,0 @@ -#### -*- Makefile -*- for the Emacs Lisp Introduction manual. - -# Copyright (C) 2003-2013 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. - - -srcdir = . - -infodir = $(srcdir)/../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc -# Directory with emacsver.texi. -emacsdir = $(srcdir)/../emacs - -INFO_EXT=.info -INFO_OPTS=--no-split -I$(emacsdir) -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi $(emacsdir)/emacsver.texi \ - $(srcdir)/doclicense.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = $(infodir)/eintr$(INFO_EXT) -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -INSTALL_INFO = install-info -TEXI2DVI = texi2dvi -TEXI2PDF = texi2pdf -DVIPS = dvips -ENVADD = $(srcdir)\..\..\nt\envadd.bat \ - "TEXINPUTS=$(srcdir);$(texinfodir);$(emacsdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir) -I$(emacsdir) -I$(texinfodir)" /C - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -$(infodir)/eintr$(INFO_EXT): $(INFO_SOURCES) - $(MAKEINFO) $(INFO_OPTS) -o $@ $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: $(INFO_SOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.pdf: $(INFO_SOURCES) - $(ENVADD) $(TEXI2PDF) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - - $(DEL) *.dvi $(infodir)/eintr$(INFO_EXT)* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: |