Mercurial > emacs
changeset 91042:0efcd228da1f
Merge from emacs--devo--0
Patches applied:
* emacs--devo--0 (patch 866-879)
- Merge multi-tty branch
- Update from CVS
- Merge from emacs--rel--22
Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-257
| author | Miles Bader <miles@gnu.org> |
|---|---|
| date | Thu, 11 Oct 2007 16:24:58 +0000 |
| parents | bdb3fe0ba9fa (current diff) 0e7ca459b337 (diff) |
| children | 3807f7a342ae |
| files | lispref/mkinstalldirs |
| diffstat | 28 files changed, 33869 insertions(+), 38 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/ChangeLog Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,287 @@ +2007-09-12 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Add email address to Thank You correctly + +2007-09-06 Romain Francoise <romain@orebokech.com> + + * Makefile.in (maintainer-clean): Delete info files. + +2007-09-06 Glenn Morris <rgm@gnu.org> + + * Move from lispintro/ to doc/lispintro/. + * Makefile.in (infodir): Go up one more level. + (usermanualdir): Change from ../man to ../emacs. + * makefile.w32-in (infodir, ENVADD): Go up one more level. + * emacs-lisp-intro.texi (setfilename): Go up one more level. + +2007-07-30 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Fix typo on line 5173, change `thee' to + `these'. + +2007-07-25 Glenn Morris <rgm@gnu.org> + + * Relicense all FSF files to GPLv3 or later. + +2007-06-02 Chong Yidong <cyd@stupidchicken.com> + + * Version 22.1 released. + +2007-01-30 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi (else): Rephrase message of first + if-then-else example so it is right both in itself and in the + "true" case of the expression, which asks whether 4 is greater + than 5. + +2006-11-27 Andreas Schwab <schwab@suse.de> + + * Makefile.in (usermanualdir): Define. + (emacs-lisp-intro.dvi): Pass -I options to texi2dvi instead of + using TEXINPUTS. + + * emacs-lisp-intro.texi: Input texinfo instead of ../man/texinfo + to fix building outside source directory. + +2006-11-09 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Copy descriptions from detailed master + menu to menus within body. + + * emacs-lisp-intro.texi (at the beginning): Add `other shell + commands' to produce additional output formats; total is now ten. + (A Loop with an Incrementing Counter, and others): Ensure Info + menus will appear in short windows. + (Disentangle beginning-of-buffer): Replace `version 21' with `more + recent versions'. + (Simple Extension): Show how to handle multiple versions by adding + an alternative with a test of `>= 21' + + +2006-11-06 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Finish minor changes seen from DVI output. + Replace 22.1.100 with 22.1.1. + (current-kill): Mention functions that directly or indirectly call + `kill-new', which sets `kill-ring-yank-pointer'. + (Understanding current-kill): Change `lasted' to `last'. Remove + extraneous parenthesis. Reword item about returning `car' of list. + (yank): Remove mention of `rotate-yank-pointer'. + (Y Axis Element): Add comment regarding replacement of blank space. + (print-Y-axis Penultimate): Explain that `print-graph' will pass + `height-of-top-line' so `print-Y-axis' does not have a bug. + +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 + `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. + (Text and Auto-fill): Remove extraneous blank line in example. + (Mail Aliases): Remove extraneous blank line in example. + (Keybindings): Reformat as needed with `key' rather than `kbd'. + (Keybindings, Miscellaneous, Mode Line): For small book format, start + section name on top of new page. + (Simple Extension): Replace longer expression with + `emacs-major-version'. Remove comment about `number-to-string' + function. + (Miscellaneous): Add filename option, `-H', to `grep' example + (debug, debug-on-entry): Replace `GNU Emacs 22' with `a recent + GNU Emacs'. + (edebug): More properly state where to place point for 'M-x + edebug-defun'. + + * emacs-lisp-intro.texi: More minor changes. + 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}. + 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'. + (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. + (sentence-end): Specify `in English' for glyphs that end a sentence. + Note that in GNU Emacs 22, the name refers to both a variable and a + 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. + (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'. + (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 + +2006-11-04 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100. + (defcustom): Note that the value set by defconst is a variable. + (Buffer Size & Locations): Parenthetical remark about evaluation. + (Finding More): Change text to include C sources by inference. + + * emacs-lisp-intro.texi: Minor fixes. + Replace all tabs with eight spaces each so printed text looks correct. + Remove extraneous comma in a printed node name produced by `ref'. + (insert-buffer): Add a missing beginning parenthesis. + (beginning-of-buffer): Add `beginning of' to note about accessible + portion. + (narrow Exercise): Write closing parenthesis at end of correct + paragraph. + (zap-to-char): Remove extraneous `a' from first sentence. + (Complete zap-to-char): Remove two extraneous sentences. + (zap-to-char body): Move sentences on documentation two nodes earlier. + (Lisp macro): Add definition of `unless' macro. + (last-command & this-command): Remove comment that `we have not yet + 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 + references to `yank' and `yank-pop. End section with a note that `we + will digress into C.' + +2006-11-02 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition + of extraneous quotation mark to rotate-yank-pointer. + +2006-11-01 Juri Linkov <juri@jurta.org> + + * emacs-lisp-intro.texi: Fix unbalanced quotes. + +2006-10-31 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Revised text for kill-region, + copy-region-as-kill, kill-append, kill-new, forward-sentence, + forward-paragraph, find-file, current-kill, yank, and yank-pop. + Removed INSTALL MANIFEST from the directory since those files are + now irrelevant. Updated Info file in ../info. Changed numbering + so is now Revised Third Edition and this instance's edition-number + 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. + +2006-10-30 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Many changes since it turned out that + many `simple' functions were rewritten. Changes to the text + regarding zap-to-char, mark-whole-buffer, append-to-buffer, + copy-to-buffer, beginning-of-buffer, what-line, and possibly + others. (I have not reviewed all yet.) This instance does build + for Info and TeX. + +2006-10-29 Chong Yidong <cyd@stupidchicken.com> + + * Makefile.in: Use relative paths to avoid advertising filesystem + contents during compilation. + +2006-08-21 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: deleted in directory copy of texinfo.tex + and pointed towards ../man/texinfo.tex so only one file + needs updating. Added comment of what to do when building on own. + + * texinfo.tex: changed to version 2006-02-13.16 + to enable a DVI build using the more recent versions of TeX. + +2006-05-25 David Kastrup <dak@gnu.org> + + * emacs-lisp-intro.texi (setcar): replace an antelope rather than + a giraffe with a hippopotamus. + +2006-05-19 Thien-Thi Nguyen <ttn@gnu.org> + + * emacs-lisp-intro.texi (Digression concerning error): Fix typo. + +2005-09-16 Romain Francoise <romain@orebokech.com> + + * emacs-lisp-intro.texi (GNU Free Documentation License): + Specify GFDL version 1.2. + +2005-07-30 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (info): Don't run install-info. + ($(infodir)/dir): New target, produced by running install-info. + +2005-07-04 Lute Kamstra <lute@gnu.org> + + Update FSF's address in GPL notices. + + * emacs-lisp-intro.texi: Update FSF's address. + +2004-04-23 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in: Add "-*- makefile -*-" mode tag. + +2004-02-29 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in (mostlyclean, clean, maintainer-clean): Use + $(DEL) instead of rm, and ignore exit code. + +2003-11-16 Kevin Ryde <user42@zip.com.au> + + * emacs-lisp-intro.texi: [CVS commitment by <bob@rattlesnake.com>] + Corrections to cross references, + (Interactive Options): elisp "interactive" -> "Using Interactive". + (defvar and asterisk): Remove emacs "Edit Options" reference, + edit-options is no longer described in the emacs manual. + (Lists diagrammed): elisp "List Type" -> "Cons Cell Type". + +2003-09-03 Peter Runestig <peter@runestig.com> + + * makefile.w32-in: New file. + +2001-11-29 Eli Zaretskii <eliz@is.elta.co.il> + + * emacs-lisp-intro.texi (Index): @ignore extraneous text. + Use @dircategory and @direntry to define the DIR entry. + +2001-11-25 Robert J. Chassell <bob@rattlesnake.com> + + * emacs-lisp-intro.texi: Move @contents to the beginning of the + file. Set the size to @smallbook. + +2001-11-24 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in: New file. + + * README: Update. + + * *.eps: Rename to avoid clashes in DOS 8+3 namespace. + +;; Local Variables: +;; coding: iso-2022-7bit +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 2001, 2002, 2003, 2004, 2005, + 2006, 2007 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, 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; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +;;; arch-tag: ee4f8e1f-e14c-4d2e-86de-4dd697e6f1c3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/Makefile.am Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,7 @@ +AUTOMAKE_OPTIONS = foreign 1.2 +info_TEXINFOS = emacs-lisp-intro.texi +EXTRA_DIST = INSTALL MANIFEST README drawers.eps \ + cons-1.eps cons-2.eps cons-2a.eps cons-3.eps \ + cons-4.eps cons-5.eps lambda-1.eps lambda-2.eps lambda-3.eps + +# arch-tag: 6a3e6d99-7aa2-479f-939c-5531165c5747
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/Makefile.in Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,73 @@ +#### Makefile for the Emacs Lisp Introduction manual + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007 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, 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; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +SHELL = @SHELL@ + +srcdir = @srcdir@ +VPATH = @srcdir@ + +infodir = ../../info +usermanualdir = $(srcdir)/../emacs + +INFO_SOURCES = ${srcdir}/emacs-lisp-intro.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 +DVI_TARGETS = emacs-lisp-intro.dvi + +MAKEINFO = makeinfo +TEXI2DVI = texi2dvi +DVIPS = dvips + +.SUFFIXES: .dvi .ps .texi + +info: $(INFO_TARGETS) + +dvi: $(DVI_TARGETS) + +${infodir}/eintr: ${INFO_SOURCES} + cd $(srcdir); $(MAKEINFO) emacs-lisp-intro.texi -o $(infodir)/eintr + +emacs-lisp-intro.dvi: ${INFO_SOURCES} + $(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/emacs-lisp-intro.texi + +emacs-lisp-intro.html: $(INFO_SOURCES) + $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi + +.dvi.ps: + $(DVIPS) $< -o $@ + +mostlyclean: + rm -f *.log *.cp *.fn *.ky *.pg *.vr *.tp + +clean: mostlyclean + rm -f *.dvi + +distclean: clean + +maintainer-clean: distclean + rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc + cd $(infodir); rm -f eintr eintr-[1-9] + +# 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:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/Makefile.old Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,344 @@ +# Makefile.in generated automatically by automake 1.4-p4 from Makefile.am + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, +# 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + + +SHELL = @SHELL@ + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +bindir = @bindir@ +sbindir = @sbindir@ +libexecdir = @libexecdir@ +datadir = @datadir@ +sysconfdir = @sysconfdir@ +sharedstatedir = @sharedstatedir@ +localstatedir = @localstatedir@ +libdir = @libdir@ +infodir = @infodir@ +mandir = @mandir@ +includedir = @includedir@ +oldincludedir = /usr/include + +DESTDIR = + +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ + +top_builddir = . + +ACLOCAL = @ACLOCAL@ +AUTOCONF = @AUTOCONF@ +AUTOMAKE = @AUTOMAKE@ +AUTOHEADER = @AUTOHEADER@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS) +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +transform = @program_transform_name@ + +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +MAKEINFO = @MAKEINFO@ +PACKAGE = @PACKAGE@ +VERSION = @VERSION@ + +AUTOMAKE_OPTIONS = foreign 1.2 +info_TEXINFOS = emacs-lisp-intro.texi +EXTRA_DIST = INSTALL MANIFEST README chest-of-drawers-diagram.eps cons-cell-diagram1.eps cons-cell-diagram2.eps cons-cell-diagram2a.eps cons-cell-diagram3.eps cons-cell-diagram4.eps cons-cell-diagram5.eps lambda-diagram1.eps lambda-diagram2.eps lambda-diagram3.eps + +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_CLEAN_FILES = +TEXI2DVI = texi2dvi +INFO_DEPS = emacs-lisp-intro.info +DVIS = emacs-lisp-intro.dvi +TEXINFOS = emacs-lisp-intro.texi +DIST_COMMON = README INSTALL Makefile.am Makefile.in aclocal.m4 \ +configure configure.in install-sh missing mkinstalldirs texinfo.tex + + +DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) + +TAR = tar +GZIP_ENV = --best +all: all-redirect +.SUFFIXES: +.SUFFIXES: .dvi .info .ps .texi .texinfo .txi +$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) + cd $(top_srcdir) && $(AUTOMAKE) --foreign --include-deps Makefile + +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) \ + && CONFIG_FILES=$@ CONFIG_HEADERS= $(SHELL) ./config.status + +$(ACLOCAL_M4): configure.in + cd $(srcdir) && $(ACLOCAL) + +config.status: $(srcdir)/configure.in $(CONFIG_STATUS_DEPENDENCIES) + $(SHELL) ./config.status --recheck +$(srcdir)/configure: $(srcdir)/configure.in $(ACLOCAL_M4) $(CONFIGURE_DEPENDENCIES) + cd $(srcdir) && $(AUTOCONF) + +emacs-lisp-intro.info: emacs-lisp-intro.texi +emacs-lisp-intro.dvi: emacs-lisp-intro.texi + + +DVIPS = dvips + +.texi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texi.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.texi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.txi.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` +.dvi.ps: + $(DVIPS) $< -o $@ + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + $(mkinstalldirs) $(DESTDIR)$(infodir) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + d=$(srcdir); \ + for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \ + $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ + install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ + done; \ + else : ; fi + +uninstall-info: + $(PRE_UNINSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + ii=yes; \ + else ii=; fi; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + test -z "$$ii" \ + || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \ + done + @$(NORMAL_UNINSTALL) + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \ + done + +dist-info: $(INFO_DEPS) + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + d=$(srcdir); \ + for file in `cd $$d && eval echo $$base*`; do \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file; \ + done; \ + done + +mostlyclean-aminfo: + -rm -f emacs-lisp-intro.aux emacs-lisp-intro.cp emacs-lisp-intro.cps \ + emacs-lisp-intro.dvi emacs-lisp-intro.fn emacs-lisp-intro.fns \ + emacs-lisp-intro.ky emacs-lisp-intro.kys emacs-lisp-intro.ps \ + emacs-lisp-intro.log emacs-lisp-intro.pg emacs-lisp-intro.toc \ + emacs-lisp-intro.tp emacs-lisp-intro.tps emacs-lisp-intro.vr \ + emacs-lisp-intro.vrs emacs-lisp-intro.op emacs-lisp-intro.tr \ + emacs-lisp-intro.cv emacs-lisp-intro.cn + +clean-aminfo: + +distclean-aminfo: + +maintainer-clean-aminfo: + cd $(srcdir) && for i in $(INFO_DEPS); do \ + rm -f $$i; \ + if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ + rm -f $$i-[0-9]*; \ + fi; \ + done +tags: TAGS +TAGS: + + +distdir = $(PACKAGE)-$(VERSION) +top_distdir = $(distdir) + +# This target untars the dist file and tries a VPATH configuration. Then +# it guarantees that the distribution is self-contained by making another +# tarfile. +distcheck: dist + -rm -rf $(distdir) + GZIP=$(GZIP_ENV) $(TAR) zxf $(distdir).tar.gz + mkdir $(distdir)/=build + mkdir $(distdir)/=inst + dc_install_base=`cd $(distdir)/=inst && pwd`; \ + cd $(distdir)/=build \ + && ../configure --srcdir=.. --prefix=$$dc_install_base \ + && $(MAKE) $(AM_MAKEFLAGS) \ + && $(MAKE) $(AM_MAKEFLAGS) dvi \ + && $(MAKE) $(AM_MAKEFLAGS) check \ + && $(MAKE) $(AM_MAKEFLAGS) install \ + && $(MAKE) $(AM_MAKEFLAGS) installcheck \ + && $(MAKE) $(AM_MAKEFLAGS) dist + -rm -rf $(distdir) + @banner="$(distdir).tar.gz is ready for distribution"; \ + dashes=`echo "$$banner" | sed s/./=/g`; \ + echo "$$dashes"; \ + echo "$$banner"; \ + echo "$$dashes" +dist: distdir + -chmod -R a+r $(distdir) + GZIP=$(GZIP_ENV) $(TAR) chozf $(distdir).tar.gz $(distdir) + -rm -rf $(distdir) +dist-all: distdir + -chmod -R a+r $(distdir) + GZIP=$(GZIP_ENV) $(TAR) chozf $(distdir).tar.gz $(distdir) + -rm -rf $(distdir) +distdir: $(DISTFILES) + -rm -rf $(distdir) + mkdir $(distdir) + -chmod 777 $(distdir) + @for file in $(DISTFILES); do \ + d=$(srcdir); \ + if test -d $$d/$$file; then \ + cp -pr $$d/$$file $(distdir)/$$file; \ + else \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file || :; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info +info-am: $(INFO_DEPS) +info: info-am +dvi-am: $(DVIS) +dvi: dvi-am +check-am: all-am +check: check-am +installcheck-am: +installcheck: installcheck-am +install-exec-am: +install-exec: install-exec-am + +install-data-am: install-info-am +install-data: install-data-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am +install: install-am +uninstall-am: uninstall-info +uninstall: uninstall-am +all-am: Makefile $(INFO_DEPS) +all-redirect: all-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install +installdirs: + $(mkinstalldirs) $(DESTDIR)$(infodir) + + +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -rm -f Makefile $(CONFIG_CLEAN_FILES) + -rm -f config.cache config.log stamp-h stamp-h[0-9]* + +maintainer-clean-generic: +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic + +mostlyclean: mostlyclean-am + +clean-am: clean-aminfo clean-generic mostlyclean-am + +clean: clean-am + +distclean-am: distclean-aminfo distclean-generic clean-am + +distclean: distclean-am + -rm -f config.status + +maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \ + distclean-am + @echo "This command is intended for maintainers to use;" + @echo "it deletes files that may require special tools to rebuild." + +maintainer-clean: maintainer-clean-am + -rm -f config.status + +.PHONY: install-info-am uninstall-info mostlyclean-aminfo \ +distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \ +info-am info dvi-am dvi check check-am installcheck-am installcheck \ +install-exec-am install-exec install-data-am install-data install-am \ +install uninstall-am uninstall all-redirect all-am all installdirs \ +mostlyclean-generic distclean-generic clean-generic \ +maintainer-clean-generic clean mostlyclean distclean maintainer-clean + + +# 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: + +# arch-tag: f1a44ea0-b792-4ac7-be28-9626b972c216
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/README Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,84 @@ +Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 + Free Software Foundation, Inc. +See the end of the file for license conditions. + + +This directory contains the source of the "Introduction to Programming +in Emacs Lisp" written by Robert J. Chassell, bob@gnu.org. This +manual is an elementary introduction to programming in Emacs Lisp for +people who are not programmers, and who are not necessarily interested +in programming, but who do want to customize or extend their computing +environment. + +This third edition of 2006 Oct 31 updates the previous editions to GNU +Emacs 22. + +The Texinfo source file `emacs-lisp-intro.texi', formats without +reported error using `pdfeTeXk', Version 3.141592-1.21a-2.2 (Web2C +7.5.4) and texinfo.tex version 2006-08-26.17 started by `texi2dvi' +version 4.8, and with `makeinfo' version 4.8. + +Also, this tar file contains the following optional Encapsulated Post +Script figures. + + drawers.eps 7129 bytes + cons-1.eps 12136 + cons-2.eps 12523 + cons-2a.eps 12420 + cons-3.eps 12984 + cons-4.eps 13866 + cons-5.eps 12986 + lambda-1.eps 10252 + lambda-2.eps 10278 + lambda-3.eps 10275 + +See the beginning of the `emacs-lisp-intro.texi' file for appropriate +settings. These figures are not necessary; they are merely nice to +look at --- without them you get the same figures printed with ASCII +characters. + +Whether and how you print PostScript depends on your site. You not +only need to set 'print-postscript-figures' before creating the .dvi +file, but then must convert the .dvi file to .ps with a 'dvips' or +equivalent command. + +On some systems you will see an error message when `psfig.tex' is +loaded for the last two .eps files: + + ! No room for a new \write . + +If this happens, try `epsf.tex' instead of `psfig.tex', or try typing +RET at the error; the formatting may continue successfully. + +Or else find the section that says: + + @c !!! Clear print-postscript-figures if the computer formatting this + @c document is too small and cannot handle all the diagrams and figures. + @c clear print-postscript-figures + +and change the file so it reads: @clear print-postscript-figures +This will prevent TeX from attempting to load the last few .eps files. + +You will find additional instructions on formatting in the beginning +of the Texinfo file 'emacs-lisp-intro.texi'. Best Wishes! + +2006 Oct 31 +Robert J. Chassell, bob@gnu.org + + +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, 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; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, USA.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/aclocal.m4 Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,105 @@ +dnl aclocal.m4 generated automatically by aclocal 1.4-p4 + +dnl Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, +dnl 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +dnl This file is free software; the Free Software Foundation +dnl gives unlimited permission to copy and/or distribute it, +dnl with or without modifications, as long as this notice is preserved. + +dnl This program is distributed in the hope that it will be useful, +dnl but WITHOUT ANY WARRANTY, to the extent permitted by law; without +dnl even the implied warranty of MERCHANTABILITY or FITNESS FOR A +dnl PARTICULAR PURPOSE. + +# Do all the work for Automake. This macro actually does too much -- +# some checks are only needed if your package does certain things. +# But this isn't really a big deal. + +# serial 1 + +dnl Usage: +dnl AM_INIT_AUTOMAKE(package,version, [no-define]) + +AC_DEFUN(AM_INIT_AUTOMAKE, +[AC_REQUIRE([AC_PROG_INSTALL]) +PACKAGE=[$1] +AC_SUBST(PACKAGE) +VERSION=[$2] +AC_SUBST(VERSION) +dnl test to see if srcdir already configured +if test "`cd $srcdir && pwd`" != "`pwd`" && test -f $srcdir/config.status; then + AC_MSG_ERROR([source directory already configured; run "make distclean" there first]) +fi +ifelse([$3],, +AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE", [Name of package]) +AC_DEFINE_UNQUOTED(VERSION, "$VERSION", [Version number of package])) +AC_REQUIRE([AM_SANITY_CHECK]) +AC_REQUIRE([AC_ARG_PROGRAM]) +dnl FIXME This is truly gross. +missing_dir=`cd $ac_aux_dir && pwd` +AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir) +AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir) +AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir) +AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir) +AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir) +AC_REQUIRE([AC_PROG_MAKE_SET])]) + +# +# Check to make sure that the build environment is sane. +# + +AC_DEFUN(AM_SANITY_CHECK, +[AC_MSG_CHECKING([whether build environment is sane]) +# Just in case +sleep 1 +echo timestamp > conftestfile +# Do `set' in a subshell so we don't clobber the current shell's +# arguments. Must try -L first in case configure is actually a +# symlink; some systems play weird games with the mod time of symlinks +# (eg FreeBSD returns the mod time of the symlink's containing +# directory). +if ( + set X `ls -Lt $srcdir/configure conftestfile 2> /dev/null` + if test "[$]*" = "X"; then + # -L didn't work. + set X `ls -t $srcdir/configure conftestfile` + fi + if test "[$]*" != "X $srcdir/configure conftestfile" \ + && test "[$]*" != "X conftestfile $srcdir/configure"; then + + # If neither matched, then we have a broken ls. This can happen + # if, for instance, CONFIG_SHELL is bash and it inherits a + # broken ls alias from the environment. This has actually + # happened. Such a system could not be considered "sane". + AC_MSG_ERROR([ls -t appears to fail. Make sure there is not a broken +alias in your environment]) + fi + + test "[$]2" = conftestfile + ) +then + # Ok. + : +else + AC_MSG_ERROR([newly created file is older than distributed files! +Check your system clock]) +fi +rm -f conftest* +AC_MSG_RESULT(yes)]) + +dnl AM_MISSING_PROG(NAME, PROGRAM, DIRECTORY) +dnl The program must properly implement --version. +AC_DEFUN(AM_MISSING_PROG, +[AC_MSG_CHECKING(for working $2) +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if ($2 --version) < /dev/null > /dev/null 2>&1; then + $1=$2 + AC_MSG_RESULT(found) +else + $1="$3/missing $2" + AC_MSG_RESULT(missing) +fi +AC_SUBST($1)]) +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/configure Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,1044 @@ +#! /bin/sh + +# Guess values for system-dependent variables and create Makefiles. +# Generated automatically using autoconf version 2.13 +# Copyright (C) 1992, 1993, 1994, 1995, 1996, 2001, 2002, 2003, 2004, +# 2005, 2006, 2007 Free Software Foundation, Inc. +# +# This configure script is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. + +# Defaults: +ac_help= +ac_default_prefix=/usr/local +# Any additions from configure.in: + +# Initialize some variables set by options. +# The variables have the same names as the options, with +# dashes changed to underlines. +build=NONE +cache_file=./config.cache +exec_prefix=NONE +host=NONE +no_create= +nonopt=NONE +no_recursion= +prefix=NONE +program_prefix=NONE +program_suffix=NONE +program_transform_name=s,x,x, +silent= +site= +srcdir= +target=NONE +verbose= +x_includes=NONE +x_libraries=NONE +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datadir='${prefix}/share' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +libdir='${exec_prefix}/lib' +includedir='${prefix}/include' +oldincludedir='/usr/include' +infodir='${prefix}/info' +mandir='${prefix}/man' + +# Initialize some other variables. +subdirs= +MFLAGS= MAKEFLAGS= +SHELL=${CONFIG_SHELL-/bin/sh} +# Maximum number of lines to put in a shell here document. +ac_max_here_lines=12 + +ac_prev= +for ac_option +do + + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval "$ac_prev=\$ac_option" + ac_prev= + continue + fi + + case "$ac_option" in + -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; + *) ac_optarg= ;; + esac + + # Accept the important Cygnus configure options, so we can diagnose typos. + + case "$ac_option" in + + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir="$ac_optarg" ;; + + -build | --build | --buil | --bui | --bu) + ac_prev=build ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=*) + build="$ac_optarg" ;; + + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + cache_file="$ac_optarg" ;; + + -datadir | --datadir | --datadi | --datad | --data | --dat | --da) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ + | --da=*) + datadir="$ac_optarg" ;; + + -disable-* | --disable-*) + ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + eval "enable_${ac_feature}=no" ;; + + -enable-* | --enable-*) + ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } + fi + ac_feature=`echo $ac_feature| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "enable_${ac_feature}='$ac_optarg'" ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix="$ac_optarg" ;; + + -gas | --gas | --ga | --g) + # Obsolete; use --with-gas. + with_gas=yes ;; + + -help | --help | --hel | --he) + # Omit some internal or obsolete options to make the list less imposing. + # This message is too long to be a string in the A/UX 3.1 sh. + cat << EOF +Usage: configure [options] [host] +Options: [defaults in brackets after descriptions] +Configuration: + --cache-file=FILE cache test results in FILE + --help print this message + --no-create do not create output files + --quiet, --silent do not print \`checking...' messages + --version print the version of autoconf that created configure +Directory and file names: + --prefix=PREFIX install architecture-independent files in PREFIX + [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [same as prefix] + --bindir=DIR user executables in DIR [EPREFIX/bin] + --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] + --libexecdir=DIR program executables in DIR [EPREFIX/libexec] + --datadir=DIR read-only architecture-independent data in DIR + [PREFIX/share] + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data in DIR + [PREFIX/com] + --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] + --srcdir=DIR find the sources in DIR [configure dir or ..] + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM + run sed PROGRAM on installed program names +EOF + cat << EOF +Host type: + --build=BUILD configure for building on BUILD [BUILD=HOST] + --host=HOST configure for HOST [guessed] + --target=TARGET configure for TARGET [TARGET=HOST] +Features and packages: + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) + --x-includes=DIR X include files are in DIR + --x-libraries=DIR X library files are in DIR +EOF + if test -n "$ac_help"; then + echo "--enable and --with options recognized:$ac_help" + fi + exit 0 ;; + + -host | --host | --hos | --ho) + ac_prev=host ;; + -host=* | --host=* | --hos=* | --ho=*) + host="$ac_optarg" ;; + + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir="$ac_optarg" ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir="$ac_optarg" ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir="$ac_optarg" ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir="$ac_optarg" ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst \ + | --locals | --local | --loca | --loc | --lo) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* \ + | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) + localstatedir="$ac_optarg" ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir="$ac_optarg" ;; + + -nfp | --nfp | --nf) + # Obsolete; use --without-fp. + with_fp=no ;; + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) + no_create=yes ;; + + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) + no_recursion=yes ;; + + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir="$ac_optarg" ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix="$ac_optarg" ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix="$ac_optarg" ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix="$ac_optarg" ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name="$ac_optarg" ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir="$ac_optarg" ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir="$ac_optarg" ;; + + -site | --site | --sit) + ac_prev=site ;; + -site=* | --site=* | --sit=*) + site="$ac_optarg" ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir="$ac_optarg" ;; + + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir="$ac_optarg" ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target="$ac_optarg" ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers) + echo "configure generated by autoconf version 2.13" + exit 0 ;; + + -with-* | --with-*) + ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + case "$ac_option" in + *=*) ;; + *) ac_optarg=yes ;; + esac + eval "with_${ac_package}='$ac_optarg'" ;; + + -without-* | --without-*) + ac_package=`echo $ac_option|sed -e 's/-*without-//'` + # Reject names that are not valid shell variable names. + if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then + { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } + fi + ac_package=`echo $ac_package| sed 's/-/_/g'` + eval "with_${ac_package}=no" ;; + + --x) + # Obsolete; use --with-x. + with_x=yes ;; + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes="$ac_optarg" ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries="$ac_optarg" ;; + + -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } + ;; + + *) + if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then + echo "configure: warning: $ac_option: invalid host type" 1>&2 + fi + if test "x$nonopt" != xNONE; then + { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } + fi + nonopt="$ac_option" + ;; + + esac +done + +if test -n "$ac_prev"; then + { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } +fi + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +# File descriptor usage: +# 0 standard input +# 1 file creation +# 2 errors and warnings +# 3 some systems may open it to /dev/tty +# 4 used on the Kubota Titan +# 6 checking for... messages and results +# 5 compiler messages saved in config.log +if test "$silent" = yes; then + exec 6>/dev/null +else + exec 6>&1 +fi +exec 5>./config.log + +echo "\ +This file contains any messages produced by compilers while +running configure, to aid debugging if configure makes a mistake. +" 1>&5 + +# Strip out --no-create and --no-recursion so they do not pile up. +# Also quote any args containing shell metacharacters. +ac_configure_args= +for ac_arg +do + case "$ac_arg" in + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c) ;; + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; + *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) + ac_configure_args="$ac_configure_args '$ac_arg'" ;; + *) ac_configure_args="$ac_configure_args $ac_arg" ;; + esac +done + +# NLS nuisances. +# Only set these to C if already set. These must not be set unconditionally +# because not all systems understand e.g. LANG=C (notably SCO). +# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! +# Non-C LC_CTYPE values break the ctype check. +if test "${LANG+set}" = set; then LANG=C; export LANG; fi +if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi +if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi +if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -rf conftest* confdefs.h +# AIX cpp loses on an empty file, so make sure it contains at least a newline. +echo > confdefs.h + +# A filename unique to this package, relative to the directory that +# configure is in, which we can look for to find out if srcdir is correct. +ac_unique_file=emacs-lisp-intro.texi + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then its parent. + ac_prog=$0 + ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` + test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. + srcdir=$ac_confdir + if test ! -r $srcdir/$ac_unique_file; then + srcdir=.. + fi +else + ac_srcdir_defaulted=no +fi +if test ! -r $srcdir/$ac_unique_file; then + if test "$ac_srcdir_defaulted" = yes; then + { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } + else + { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } + fi +fi +srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` + +# Prefer explicitly selected file to automatically selected ones. +if test -z "$CONFIG_SITE"; then + if test "x$prefix" != xNONE; then + CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" + else + CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" + fi +fi +for ac_site_file in $CONFIG_SITE; do + if test -r "$ac_site_file"; then + echo "loading site script $ac_site_file" + . "$ac_site_file" + fi +done + +if test -r "$cache_file"; then + echo "loading cache $cache_file" + . $cache_file +else + echo "creating cache $cache_file" + > $cache_file +fi + +ac_ext=c +# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. +ac_cpp='$CPP $CPPFLAGS' +ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' +ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' +cross_compiling=$ac_cv_prog_cc_cross + +ac_exeext= +ac_objext=o +if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then + # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. + if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then + ac_n= ac_c=' +' ac_t=' ' + else + ac_n=-n ac_c= ac_t= + fi +else + ac_n= ac_c='\c' ac_t= +fi + + +ac_aux_dir= +for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do + if test -f $ac_dir/install-sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install-sh -c" + break + elif test -f $ac_dir/install.sh; then + ac_aux_dir=$ac_dir + ac_install_sh="$ac_aux_dir/install.sh -c" + break + fi +done +if test -z "$ac_aux_dir"; then + { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } +fi +ac_config_guess=$ac_aux_dir/config.guess +ac_config_sub=$ac_aux_dir/config.sub +ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. + +# Find a good install program. We prefer a C program (faster), +# so one script is as good as another. But avoid the broken or +# incompatible versions: +# SysV /etc/install, /usr/sbin/install +# SunOS /usr/etc/install +# IRIX /sbin/install +# AIX /bin/install +# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag +# AFS /usr/afsws/bin/install, which mishandles nonexistent args +# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" +# ./install, which can be erroneously created by make from ./install.sh. +echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6 +echo "configure:556: checking for a BSD compatible install" >&5 +if test -z "$INSTALL"; then +if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + IFS="${IFS= }"; ac_save_IFS="$IFS"; IFS=":" + for ac_dir in $PATH; do + # Account for people who put trailing slashes in PATH elements. + case "$ac_dir/" in + /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + # Don't use installbsd from OSF since it installs stuff as root + # by default. + for ac_prog in ginstall scoinst install; do + if test -f $ac_dir/$ac_prog; then + if test $ac_prog = install && + grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + : + else + ac_cv_path_install="$ac_dir/$ac_prog -c" + break 2 + fi + fi + done + ;; + esac + done + IFS="$ac_save_IFS" + +fi + if test "${ac_cv_path_install+set}" = set; then + INSTALL="$ac_cv_path_install" + else + # As a last resort, use the slow shell script. We don't cache a + # path for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the path is relative. + INSTALL="$ac_install_sh" + fi +fi +echo "$ac_t""$INSTALL" 1>&6 + +# Use test -z because SunOS4 sh mishandles braces in ${var-val}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' + +test -z "$INSTALL_SCRIPT" && INSTALL_SCRIPT='${INSTALL_PROGRAM}' + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' + +echo $ac_n "checking whether build environment is sane""... $ac_c" 1>&6 +echo "configure:609: checking whether build environment is sane" >&5 +# Just in case +sleep 1 +echo timestamp > conftestfile +# Do `set' in a subshell so we don't clobber the current shell's +# arguments. Must try -L first in case configure is actually a +# symlink; some systems play weird games with the mod time of symlinks +# (eg FreeBSD returns the mod time of the symlink's containing +# directory). +if ( + set X `ls -Lt $srcdir/configure conftestfile 2> /dev/null` + if test "$*" = "X"; then + # -L didn't work. + set X `ls -t $srcdir/configure conftestfile` + fi + if test "$*" != "X $srcdir/configure conftestfile" \ + && test "$*" != "X conftestfile $srcdir/configure"; then + + # If neither matched, then we have a broken ls. This can happen + # if, for instance, CONFIG_SHELL is bash and it inherits a + # broken ls alias from the environment. This has actually + # happened. Such a system could not be considered "sane". + { echo "configure: error: ls -t appears to fail. Make sure there is not a broken +alias in your environment" 1>&2; exit 1; } + fi + + test "$2" = conftestfile + ) +then + # Ok. + : +else + { echo "configure: error: newly created file is older than distributed files! +Check your system clock" 1>&2; exit 1; } +fi +rm -f conftest* +echo "$ac_t""yes" 1>&6 +if test "$program_transform_name" = s,x,x,; then + program_transform_name= +else + # Double any \ or $. echo might interpret backslashes. + cat <<\EOF_SED > conftestsed +s,\\,\\\\,g; s,\$,$$,g +EOF_SED + program_transform_name="`echo $program_transform_name|sed -f conftestsed`" + rm -f conftestsed +fi +test "$program_prefix" != NONE && + program_transform_name="s,^,${program_prefix},; $program_transform_name" +# Use a double $ so make ignores it. +test "$program_suffix" != NONE && + program_transform_name="s,\$\$,${program_suffix},; $program_transform_name" + +# sed with no file args requires a program. +test "$program_transform_name" = "" && program_transform_name="s,x,x," + +echo $ac_n "checking whether ${MAKE-make} sets \${MAKE}""... $ac_c" 1>&6 +echo "configure:666: checking whether ${MAKE-make} sets \${MAKE}" >&5 +set dummy ${MAKE-make}; ac_make=`echo "$2" | sed 'y%./+-%__p_%'` +if eval "test \"`echo '$''{'ac_cv_prog_make_${ac_make}_set'+set}'`\" = set"; then + echo $ac_n "(cached) $ac_c" 1>&6 +else + cat > conftestmake <<\EOF +all: + @echo 'ac_maketemp="${MAKE}"' +EOF +# GNU make sometimes prints "make[1]: Entering...", which would confuse us. +eval `${MAKE-make} -f conftestmake 2>/dev/null | grep temp=` +if test -n "$ac_maketemp"; then + eval ac_cv_prog_make_${ac_make}_set=yes +else + eval ac_cv_prog_make_${ac_make}_set=no +fi +rm -f conftestmake +fi +if eval "test \"`echo '$ac_cv_prog_make_'${ac_make}_set`\" = yes"; then + echo "$ac_t""yes" 1>&6 + SET_MAKE= +else + echo "$ac_t""no" 1>&6 + SET_MAKE="MAKE=${MAKE-make}" +fi + + +PACKAGE=emacs-lisp-intro + +VERSION=2.00 + +if test "`cd $srcdir && pwd`" != "`pwd`" && test -f $srcdir/config.status; then + { echo "configure: error: source directory already configured; run "make distclean" there first" 1>&2; exit 1; } +fi +cat >> confdefs.h <<EOF +#define PACKAGE "$PACKAGE" +EOF + +cat >> confdefs.h <<EOF +#define VERSION "$VERSION" +EOF + + + +missing_dir=`cd $ac_aux_dir && pwd` +echo $ac_n "checking for working aclocal""... $ac_c" 1>&6 +echo "configure:712: checking for working aclocal" >&5 +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if (aclocal --version) < /dev/null > /dev/null 2>&1; then + ACLOCAL=aclocal + echo "$ac_t""found" 1>&6 +else + ACLOCAL="$missing_dir/missing aclocal" + echo "$ac_t""missing" 1>&6 +fi + +echo $ac_n "checking for working autoconf""... $ac_c" 1>&6 +echo "configure:725: checking for working autoconf" >&5 +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if (autoconf --version) < /dev/null > /dev/null 2>&1; then + AUTOCONF=autoconf + echo "$ac_t""found" 1>&6 +else + AUTOCONF="$missing_dir/missing autoconf" + echo "$ac_t""missing" 1>&6 +fi + +echo $ac_n "checking for working automake""... $ac_c" 1>&6 +echo "configure:738: checking for working automake" >&5 +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if (automake --version) < /dev/null > /dev/null 2>&1; then + AUTOMAKE=automake + echo "$ac_t""found" 1>&6 +else + AUTOMAKE="$missing_dir/missing automake" + echo "$ac_t""missing" 1>&6 +fi + +echo $ac_n "checking for working autoheader""... $ac_c" 1>&6 +echo "configure:751: checking for working autoheader" >&5 +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if (autoheader --version) < /dev/null > /dev/null 2>&1; then + AUTOHEADER=autoheader + echo "$ac_t""found" 1>&6 +else + AUTOHEADER="$missing_dir/missing autoheader" + echo "$ac_t""missing" 1>&6 +fi + +echo $ac_n "checking for working makeinfo""... $ac_c" 1>&6 +echo "configure:764: checking for working makeinfo" >&5 +# Run test in a subshell; some versions of sh will print an error if +# an executable is not found, even if stderr is redirected. +# Redirect stdin to placate older versions of autoconf. Sigh. +if (makeinfo --version) < /dev/null > /dev/null 2>&1; then + MAKEINFO=makeinfo + echo "$ac_t""found" 1>&6 +else + MAKEINFO="$missing_dir/missing makeinfo" + echo "$ac_t""missing" 1>&6 +fi + + +trap '' 1 2 15 +cat > confcache <<\EOF +# This file is a shell script that caches the results of configure +# tests run on this system so they can be shared between configure +# scripts and configure runs. It is not useful on other systems. +# If it contains results you don't want to keep, you may remove or edit it. +# +# By default, configure uses ./config.cache as the cache file, +# creating it if it does not exist already. You can give configure +# the --cache-file=FILE option to use a different cache file; that is +# what configure does when it calls configure scripts in +# subdirectories, so they share the cache. +# Giving --cache-file=/dev/null disables caching, for debugging configure. +# config.status only pays attention to the cache file if you give it the +# --recheck option to rerun configure. +# +EOF +# The following way of writing the cache mishandles newlines in values, +# but we know of no workaround that is simple, portable, and efficient. +# So, don't put newlines in cache variables' values. +# Ultrix sh set writes to stderr and can't be redirected directly, +# and sets the high bit in the cache file unless we assign to the vars. +(set) 2>&1 | + case `(ac_space=' '; set | grep ac_space) 2>&1` in + *ac_space=\ *) + # `set' does not quote correctly, so add quotes (double-quote substitution + # turns \\\\ into \\, and sed turns \\ into \). + sed -n \ + -e "s/'/'\\\\''/g" \ + -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" + ;; + *) + # `set' quotes correctly as required by POSIX, so do not add quotes. + sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' + ;; + esac >> confcache +if cmp -s $cache_file confcache; then + : +else + if test -w $cache_file; then + echo "updating cache $cache_file" + cat confcache > $cache_file + else + echo "not updating unwritable cache $cache_file" + fi +fi +rm -f confcache + +trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 + +test "x$prefix" = xNONE && prefix=$ac_default_prefix +# Let make expand exec_prefix. +test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' + +# Any assignment to VPATH causes Sun make to only execute +# the first set of double-colon rules, so remove it if not needed. +# If there is a colon in the path, we need to keep it. +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' +fi + +trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 + +# Transform confdefs.h into DEFS. +# Protect against shell expansion while executing Makefile rules. +# Protect against Makefile macro expansion. +cat > conftest.defs <<\EOF +s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g +s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g +s%\[%\\&%g +s%\]%\\&%g +s%\$%$$%g +EOF +DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` +rm -f conftest.defs + + +# Without the "./", some shells look in PATH for config.status. +: ${CONFIG_STATUS=./config.status} + +echo creating $CONFIG_STATUS +rm -f $CONFIG_STATUS +cat > $CONFIG_STATUS <<EOF +#! /bin/sh +# Generated automatically by configure. +# Run this file to recreate the current configuration. +# This directory was configured as follows, +# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: +# +# $0 $ac_configure_args +# +# Compiler output produced by configure, useful for debugging +# configure, is in ./config.log if it exists. + +ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" +for ac_option +do + case "\$ac_option" in + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" + exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; + -version | --version | --versio | --versi | --vers | --ver | --ve | --v) + echo "$CONFIG_STATUS generated by autoconf version 2.13" + exit 0 ;; + -help | --help | --hel | --he | --h) + echo "\$ac_cs_usage"; exit 0 ;; + *) echo "\$ac_cs_usage"; exit 1 ;; + esac +done + +ac_given_srcdir=$srcdir +ac_given_INSTALL="$INSTALL" + +trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 +EOF +cat >> $CONFIG_STATUS <<EOF + +# Protect against being on the right side of a sed subst in config.status. +sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; + s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF +$ac_vpsub +$extrasub +s%@SHELL@%$SHELL%g +s%@CFLAGS@%$CFLAGS%g +s%@CPPFLAGS@%$CPPFLAGS%g +s%@CXXFLAGS@%$CXXFLAGS%g +s%@FFLAGS@%$FFLAGS%g +s%@DEFS@%$DEFS%g +s%@LDFLAGS@%$LDFLAGS%g +s%@LIBS@%$LIBS%g +s%@exec_prefix@%$exec_prefix%g +s%@prefix@%$prefix%g +s%@program_transform_name@%$program_transform_name%g +s%@bindir@%$bindir%g +s%@sbindir@%$sbindir%g +s%@libexecdir@%$libexecdir%g +s%@datadir@%$datadir%g +s%@sysconfdir@%$sysconfdir%g +s%@sharedstatedir@%$sharedstatedir%g +s%@localstatedir@%$localstatedir%g +s%@libdir@%$libdir%g +s%@includedir@%$includedir%g +s%@oldincludedir@%$oldincludedir%g +s%@infodir@%$infodir%g +s%@mandir@%$mandir%g +s%@INSTALL_PROGRAM@%$INSTALL_PROGRAM%g +s%@INSTALL_SCRIPT@%$INSTALL_SCRIPT%g +s%@INSTALL_DATA@%$INSTALL_DATA%g +s%@PACKAGE@%$PACKAGE%g +s%@VERSION@%$VERSION%g +s%@ACLOCAL@%$ACLOCAL%g +s%@AUTOCONF@%$AUTOCONF%g +s%@AUTOMAKE@%$AUTOMAKE%g +s%@AUTOHEADER@%$AUTOHEADER%g +s%@MAKEINFO@%$MAKEINFO%g +s%@SET_MAKE@%$SET_MAKE%g + +CEOF +EOF + +cat >> $CONFIG_STATUS <<\EOF + +# Split the substitutions into bite-sized pieces for seds with +# small command number limits, like on Digital OSF/1 and HP-UX. +ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. +ac_file=1 # Number of current file. +ac_beg=1 # First line for current file. +ac_end=$ac_max_sed_cmds # Line after last line for current file. +ac_more_lines=: +ac_sed_cmds="" +while $ac_more_lines; do + if test $ac_beg -gt 1; then + sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file + else + sed "${ac_end}q" conftest.subs > conftest.s$ac_file + fi + if test ! -s conftest.s$ac_file; then + ac_more_lines=false + rm -f conftest.s$ac_file + else + if test -z "$ac_sed_cmds"; then + ac_sed_cmds="sed -f conftest.s$ac_file" + else + ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" + fi + ac_file=`expr $ac_file + 1` + ac_beg=$ac_end + ac_end=`expr $ac_end + $ac_max_sed_cmds` + fi +done +if test -z "$ac_sed_cmds"; then + ac_sed_cmds=cat +fi +EOF + +cat >> $CONFIG_STATUS <<EOF + +CONFIG_FILES=\${CONFIG_FILES-"Makefile"} +EOF +cat >> $CONFIG_STATUS <<\EOF +for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then + # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". + case "$ac_file" in + *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` + ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; + *) ac_file_in="${ac_file}.in" ;; + esac + + # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. + + # Remove last slash and all that follows it. Not all systems have dirname. + ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` + if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then + # The file is in a subdirectory. + test ! -d "$ac_dir" && mkdir "$ac_dir" + ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" + # A "../" for each directory in $ac_dir_suffix. + ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` + else + ac_dir_suffix= ac_dots= + fi + + case "$ac_given_srcdir" in + .) srcdir=. + if test -z "$ac_dots"; then top_srcdir=. + else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; + /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; + *) # Relative path. + srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" + top_srcdir="$ac_dots$ac_given_srcdir" ;; + esac + + case "$ac_given_INSTALL" in + [/$]*) INSTALL="$ac_given_INSTALL" ;; + *) INSTALL="$ac_dots$ac_given_INSTALL" ;; + esac + + echo creating "$ac_file" + rm -f "$ac_file" + configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." + case "$ac_file" in + *Makefile*) ac_comsub="1i\\ +# $configure_input" ;; + *) ac_comsub= ;; + esac + + ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` + sed -e "$ac_comsub +s%@configure_input@%$configure_input%g +s%@srcdir@%$srcdir%g +s%@top_srcdir@%$top_srcdir%g +s%@INSTALL@%$INSTALL%g +" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file +fi; done +rm -f conftest.s* + +EOF +cat >> $CONFIG_STATUS <<EOF + +EOF +cat >> $CONFIG_STATUS <<\EOF + +exit 0 +EOF +chmod +x $CONFIG_STATUS +rm -fr confdefs* $ac_clean_files +test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/configure.in Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,9 @@ +dnl autoconf input file for the emacs lisp intro + +AC_INIT(emacs-lisp-intro.texi) +AM_INIT_AUTOMAKE(emacs-lisp-intro, 2.00) +AC_OUTPUT(Makefile) + +m4_if(dnl Do not change this comment + arch-tag: 8d676bd8-8677-4ae0-8aa0-99bfd595b373 +)dnl
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-1.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,584 @@ +%! +%%BoundingBox: 35 711 289 757 +%%Title: cons-cell-diagram1 +%%CreationDate: Wed Mar 8 14:26:58 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 35 711 289 757 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% BOX +gsave + 1.415 setmiterlimit + newpath + 66 66 moveto 130 66 lineto 130 98 lineto 66 98 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 98 66 moveto + 98 98 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 114 82 moveto + 0 80 atan dup cos 8 mul 194 exch sub + exch sin 8 mul 82 exch sub lineto + stroke +grestore +gsave + newpath + 194 82 8 3 80 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 146 136 moveto (rose) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 82 82 moveto + 82 131 lineto + 0 48 atan dup cos 8 mul 130 exch sub + exch sin 8 mul 131 exch sub lineto + stroke +grestore +gsave + newpath + 130 131 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 199 66 moveto 263 66 lineto 263 98 lineto 199 98 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 231 66 moveto + 231 98 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 247 82 moveto + 0 93 atan dup cos 8 mul 340 exch sub + exch sin 8 mul 82 exch sub lineto + stroke +grestore +gsave + newpath + 340 82 8 3 93 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 279 136 moveto (violet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 215 82 moveto + 215 131 lineto + 0 48 atan dup cos 8 mul 263 exch sub + exch sin 8 mul 131 exch sub lineto + stroke +grestore +gsave + newpath + 263 131 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 342 64 moveto 406 64 lineto 406 96 lineto 342 96 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 373 64 moveto + 373 96 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 389 81 moveto + 0 48 atan dup cos 8 mul 437 exch sub + exch sin 8 mul 81 exch sub lineto + stroke +grestore +gsave + newpath + 437 81 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 421 135 moveto (buttercup) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 357 81 moveto + 357 130 lineto + 0 48 atan dup cos 8 mul 405 exch sub + exch sin 8 mul 130 exch sub lineto + stroke +grestore +gsave + newpath + 405 130 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 449 87 moveto (nil) show + grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:26:58 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-2.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,606 @@ +%! +%%BoundingBox: 15 712 321 775 +%%Title: cons-cell-diagram2 +%%CreationDate: Wed Mar 8 14:26:39 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 15 712 321 775 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 32 47 moveto (bouquet) show + grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 122 65 moveto 186 65 lineto 186 97 lineto 122 97 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 154 65 moveto + 154 97 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 170 81 moveto + 0 80 atan dup cos 8 mul 250 exch sub + exch sin 8 mul 81 exch sub lineto + stroke +grestore +gsave + newpath + 250 81 8 3 80 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 202 135 moveto (rose) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 138 81 moveto + 138 130 lineto + 0 48 atan dup cos 8 mul 186 exch sub + exch sin 8 mul 130 exch sub lineto + stroke +grestore +gsave + newpath + 186 130 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 255 65 moveto 319 65 lineto 319 97 lineto 255 97 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 287 65 moveto + 287 97 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 303 81 moveto + 0 93 atan dup cos 8 mul 396 exch sub + exch sin 8 mul 81 exch sub lineto + stroke +grestore +gsave + newpath + 396 81 8 3 93 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 335 135 moveto (violet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 271 81 moveto + 271 130 lineto + 0 48 atan dup cos 8 mul 319 exch sub + exch sin 8 mul 130 exch sub lineto + stroke +grestore +gsave + newpath + 319 130 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 398 63 moveto 462 63 lineto 462 95 lineto 398 95 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 429 63 moveto + 429 95 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 445 80 moveto + 0 48 atan dup cos 8 mul 493 exch sub + exch sin 8 mul 80 exch sub lineto + stroke +grestore +gsave + newpath + 493 80 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 477 134 moveto (buttercup) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 413 80 moveto + 413 129 lineto + 0 48 atan dup cos 8 mul 461 exch sub + exch sin 8 mul 129 exch sub lineto + stroke +grestore +gsave + newpath + 461 129 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 505 86 moveto (nil) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 66 53 moveto + 66 81 lineto + 0 46 atan dup cos 8 mul 112 exch sub + exch sin 8 mul 81 exch sub lineto + stroke +grestore +gsave + newpath + 112 81 8 3 46 0 tgifarrowtip + closepath fill +grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:26:39 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-2a.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,600 @@ +%! +%%BoundingBox: 15 702 300 767 +%%Title: cons-cell-diagram2a +%%CreationDate: Tue Mar 14 15:09:30 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 15 702 300 767 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 32 62 moveto (bouquet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 64 80 moveto + 64 120 lineto + 0 49 atan dup cos 8 mul 113 exch sub + exch sin 8 mul 120 exch sub lineto + stroke +grestore +gsave + newpath + 113 120 8 3 49 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 128 110 moveto (car) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 128 142 moveto (rose) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 192 110 moveto (cdr) show + grestore + +% OVAL +gsave + newpath 207 124 4 4 tgifellipse stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 217 123 moveto + 0 38 atan dup cos 8 mul 255 exch sub + exch sin 8 mul 123 exch sub lineto + stroke +grestore +gsave + newpath + 255 123 8 3 38 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 268 111 moveto (car) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 264 143 moveto (violet) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 332 111 moveto (cdr) show + grestore + +% OVAL +gsave + newpath 347 125 4 4 tgifellipse stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 357 124 moveto + 0 38 atan dup cos 8 mul 395 exch sub + exch sin 8 mul 124 exch sub lineto + stroke +grestore +gsave + newpath + 395 124 8 3 38 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 408 112 moveto (car) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 408 136 moveto (butter-) show + 408 153 moveto (cup) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 496 113 moveto (cdr) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 495 137 moveto (nil) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 178 86 moveto + 178 157 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 485 84 moveto + 485 157 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 327 85 moveto + 327 157 lineto + stroke +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 120 86 moveto 234 86 lineto 234 157 lineto 120 157 lineto + closepath stroke + 1 setmiterlimit +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 257 85 moveto 371 85 lineto 371 157 lineto 257 157 lineto + closepath stroke + 1 setmiterlimit +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 397 84 moveto 531 84 lineto 531 157 lineto 397 157 lineto + closepath stroke + 1 setmiterlimit +grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Tue Mar 14 15:09:30 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-3.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,630 @@ +%! +%%BoundingBox: -1 691 324 757 +%%Title: cons-cell-diagram3 +%%CreationDate: Wed Mar 8 14:25:41 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: -1 691 324 757 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% BOX +gsave + 1.415 setmiterlimit + newpath + 128 102 moveto 192 102 lineto 192 134 lineto 128 134 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 160 102 moveto + 160 134 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 176 124 moveto + 0 80 atan dup cos 8 mul 256 exch sub + exch sin 8 mul 124 exch sub lineto + stroke +grestore +gsave + newpath + 256 124 8 3 80 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 208 172 moveto (rose) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 144 118 moveto + 144 167 lineto + 0 48 atan dup cos 8 mul 192 exch sub + exch sin 8 mul 167 exch sub lineto + stroke +grestore +gsave + newpath + 192 167 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 261 102 moveto 325 102 lineto 325 134 lineto 261 134 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 293 102 moveto + 293 134 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 309 118 moveto + 0 93 atan dup cos 8 mul 402 exch sub + exch sin 8 mul 118 exch sub lineto + stroke +grestore +gsave + newpath + 402 118 8 3 93 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 341 172 moveto (violet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 277 118 moveto + 277 167 lineto + 0 48 atan dup cos 8 mul 325 exch sub + exch sin 8 mul 167 exch sub lineto + stroke +grestore +gsave + newpath + 325 167 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 404 100 moveto 468 100 lineto 468 132 lineto 404 132 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 435 100 moveto + 435 132 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 451 117 moveto + 0 48 atan dup cos 8 mul 499 exch sub + exch sin 8 mul 117 exch sub lineto + stroke +grestore +gsave + newpath + 499 117 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 483 171 moveto (buttercup) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 419 117 moveto + 419 166 lineto + 0 48 atan dup cos 8 mul 467 exch sub + exch sin 8 mul 166 exch sub lineto + stroke +grestore +gsave + newpath + 467 166 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 511 123 moveto (nil) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 131 80 moveto (flowers) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 210 75 moveto + 237 75 lineto + 237 113 lineto + 0 18 atan dup cos 8 mul 255 exch sub + exch sin 8 mul 113 exch sub lineto + stroke +grestore +gsave + newpath + 255 113 8 3 18 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 2 80 moveto (bouquet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 81 77 moveto + 108 77 lineto + 108 115 lineto + 0 18 atan dup cos 8 mul 126 exch sub + exch sin 8 mul 115 exch sub lineto + stroke +grestore +gsave + newpath + 126 115 8 3 18 0 tgifarrowtip + closepath fill +grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:25:41 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-4.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,683 @@ +%! +%%BoundingBox: 6 681 355 758 +%%Title: cons-cell-diagram4 +%%CreationDate: Wed Mar 8 14:25:06 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 6 681 355 758 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% POLY/OPEN-SPLINE +gsave + newpath + 274 102 moveto + 274 134 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 289 122 moveto + 0 56 atan dup cos 8 mul 345 exch sub + exch sin 8 mul 122 exch sub lineto + stroke +grestore +gsave + newpath + 345 122 8 3 56 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 350 100 moveto 414 100 lineto 414 132 lineto 350 132 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 382 100 moveto + 382 132 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 397 114 moveto + 0 59 atan dup cos 8 mul 456 exch sub + exch sin 8 mul 114 exch sub lineto + stroke +grestore +gsave + newpath + 456 114 8 3 59 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 430 170 moveto (violet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 366 116 moveto + 366 165 lineto + 0 48 atan dup cos 8 mul 414 exch sub + exch sin 8 mul 165 exch sub lineto + stroke +grestore +gsave + newpath + 414 165 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 219 78 moveto (flowers) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 298 73 moveto + 325 73 lineto + 325 111 lineto + 0 18 atan dup cos 8 mul 343 exch sub + exch sin 8 mul 111 exch sub lineto + stroke +grestore +gsave + newpath + 343 111 8 3 18 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 459 95 moveto 523 95 lineto 523 127 lineto 459 127 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 490 95 moveto + 490 127 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 506 112 moveto + 0 48 atan dup cos 8 mul 554 exch sub + exch sin 8 mul 112 exch sub lineto + stroke +grestore +gsave + newpath + 554 112 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 566 118 moveto (nil) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 538 151 moveto (buttercup) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 474 109 moveto + 474 146 lineto + 0 48 atan dup cos 8 mul 522 exch sub + exch sin 8 mul 146 exch sub lineto + stroke +grestore +gsave + newpath + 522 146 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 244 102 moveto 308 102 lineto 308 134 lineto 244 134 lineto + closepath stroke + 1 setmiterlimit +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 324 189 moveto (rose) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 260 117 moveto + 260 184 lineto + 0 48 atan dup cos 8 mul 308 exch sub + exch sin 8 mul 184 exch sub lineto + stroke +grestore +gsave + newpath + 308 184 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 146 101 moveto 210 101 lineto 210 133 lineto 146 133 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 177 101 moveto + 177 133 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 193 118 moveto + 0 48 atan dup cos 8 mul 241 exch sub + exch sin 8 mul 118 exch sub lineto + stroke +grestore +gsave + newpath + 241 118 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 187 178 moveto (lily) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 163 118 moveto + 163 171 lineto + 0 18 atan dup cos 8 mul 181 exch sub + exch sin 8 mul 171 exch sub lineto + stroke +grestore +gsave + newpath + 181 171 8 3 18 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 16 78 moveto (bouquet) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 95 73 moveto + 122 73 lineto + 122 111 lineto + 0 18 atan dup cos 8 mul 140 exch sub + exch sin 8 mul 111 exch sub lineto + stroke +grestore +gsave + newpath + 140 111 8 3 18 0 tgifarrowtip + closepath fill +grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:25:06 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/cons-5.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,628 @@ +%! +%%BoundingBox: 15 680 305 764 +%%Title: cons-cell-diagram5 +%%CreationDate: Wed Mar 8 14:27:28 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 15 680 305 764 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% POLY/OPEN-SPLINE +gsave + newpath + 156 105 moveto + 156 137 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 171 125 moveto + 0 56 atan dup cos 8 mul 227 exch sub + exch sin 8 mul 125 exch sub lineto + stroke +grestore +gsave + newpath + 227 125 8 3 56 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 232 103 moveto 296 103 lineto 296 135 lineto 232 135 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 264 103 moveto + 264 135 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 279 117 moveto + 0 59 atan dup cos 8 mul 338 exch sub + exch sin 8 mul 117 exch sub lineto + stroke +grestore +gsave + newpath + 338 117 8 3 59 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 289 172 moveto (a different piece of text) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 248 119 moveto + 248 168 lineto + 0 29 atan dup cos 8 mul 277 exch sub + exch sin 8 mul 168 exch sub lineto + stroke +grestore +gsave + newpath + 277 168 8 3 29 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 147 66 moveto (kill-ring-yank-pointer) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 207 76 moveto + 207 114 lineto + 0 18 atan dup cos 8 mul 225 exch sub + exch sin 8 mul 114 exch sub lineto + stroke +grestore +gsave + newpath + 225 114 8 3 18 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 341 98 moveto 405 98 lineto 405 130 lineto 341 130 lineto + closepath stroke + 1 setmiterlimit +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 372 98 moveto + 372 130 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 388 115 moveto + 0 48 atan dup cos 8 mul 436 exch sub + exch sin 8 mul 115 exch sub lineto + stroke +grestore +gsave + newpath + 436 115 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 448 121 moveto (nil) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 397 154 moveto (yet more text) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 356 112 moveto + 356 149 lineto + 0 35 atan dup cos 8 mul 391 exch sub + exch sin 8 mul 149 exch sub lineto + stroke +grestore +gsave + newpath + 391 149 8 3 35 0 tgifarrowtip + closepath fill +grestore + +% BOX +gsave + 1.415 setmiterlimit + newpath + 126 105 moveto 190 105 lineto 190 137 lineto 126 137 lineto + closepath stroke + 1 setmiterlimit +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 206 192 moveto (some text) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 142 120 moveto + 142 187 lineto + 0 48 atan dup cos 8 mul 190 exch sub + exch sin 8 mul 187 exch sub lineto + stroke +grestore +gsave + newpath + 190 187 8 3 48 0 tgifarrowtip + closepath fill +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 32 66 moveto (kill-ring) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 65 81 moveto + 65 121 lineto + 0 51 atan dup cos 8 mul 116 exch sub + exch sin 8 mul 121 exch sub lineto + stroke +grestore +gsave + newpath + 116 121 8 3 51 0 tgifarrowtip + closepath fill +grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:27:28 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/drawers.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,513 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: 34 577 324 778 +%%Title: chest-of-drawers-diagram-new +%%CreationDate: Fri Sep 14 17:40:57 2001 +%%Creator: Tgif-4.1.35 by William Chia-Wei Cheng (william@cs.UCLA.edu) +%%ProducedBy: (unknown) +%%Pages: 1 +%%DocumentFonts: (atend) +%%EndComments +%%BeginProlog + +% Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 53 dict def +tgifdict begin + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/TGEL % tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/TGMAX + { exch dup 3 1 roll exch dup 3 1 roll gt { pop } { exch pop } ifelse + } def +/TGMIN + { exch dup 3 1 roll exch dup 3 1 roll lt { pop } { exch pop } ifelse + } def +/TGSW { stringwidth pop } def + +/bd { bind def } bind def + +/GS { gsave } bd +/GR { grestore } bd +/NP { newpath } bd +/CP { closepath } bd +/CHP { charpath } bd +/CT { curveto } bd +/L { lineto } bd +/RL { rlineto } bd +/M { moveto } bd +/RM { rmoveto } bd +/S { stroke } bd +/F { fill } bd +/TR { translate } bd +/RO { rotate } bd +/SC { scale } bd +/MU { mul } bd +/DI { div } bd +/DU { dup } bd +/NE { neg } bd +/AD { add } bd +/SU { sub } bd +/PO { pop } bd +/EX { exch } bd +/CO { concat } bd +/CL { clip } bd +/EC { eoclip } bd +/EF { eofill } bd +/IM { image } bd +/IMM { imagemask } bd +/ARY { array } bd +/SG { setgray } bd +/RG { setrgbcolor } bd +/SD { setdash } bd +/W { setlinewidth } bd +/SM { setmiterlimit } bd +/SLC { setlinecap } bd +/SLJ { setlinejoin } bd +/SH { show } bd +/FF { findfont } bd +/MS { makefont setfont } bd +/AR { arcto 4 {pop} repeat } bd +/CURP { currentpoint } bd +/FLAT { flattenpath strokepath clip newpath } bd +/TGSM { tgiforigctm setmatrix } def +/TGRM { savematrix setmatrix } def + +end + +%%EndProlog +%%Page: 1 1 + +%%PageBoundingBox: 34 577 324 778 +tgifdict begin +/tgifsavedpage save def + +1 SM +1 W + +0 SG + +72 0 MU 72 11 MU TR +72 128 DI 100.000 MU 100 DI DU NE SC + +GS + +/tgiforigctm matrix currentmatrix def + +% BOX +0 SG +GS + 10 SM + GS + NP 64 104 M 255 104 L 255 360 L 64 360 L CP + S + GR +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 65 296 M + 254 296 L + TGSM + 1 W + S +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 63 233 M + 255 233 L + TGSM + 1 W + S +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 63 169 M + 255 169 L + TGSM + 1 W + S +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 251 362 M + 251 361 L + 251 379 L + 244 379 L + 229 361 L + TGSM + 1 W + S +GR + +% OVAL +0 SG +GS + GS + NP 160 72 10 6 TGEL + S + GR +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 63 104 M + 128 64 L + 138 69 L + TGSM + 1 W + S +GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 255 103 M + 190 63 L + 180 68 L + TGSM + 1 W + S +GR + +% TEXT +NP +0 SG + GS + 1 W + 160 152 M + GS + GS + 0 + /Courier FF [17 0 0 -17 0 0] MS + (symbol name) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (symbol name) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 160 41 M + GS + GS + 0 + /Courier FF [17 0 0 -17 0 0] MS + (Chest of Drawers) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (Chest of Drawers) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 344 41 M + GS + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (Contents of Drawers) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 344 160 M + GS + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (bouquet) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 344 220 M + GS + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + ([none]) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 344 279 M + GS + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (\(rose violet buttercup\)) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 344 337 M + GS + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + ([not described here]) SH + GR + GR + +% POLY/OPEN-SPLINE +0 SG +GS + NP + 68 362 M + 68 361 L + 68 379 L + 75 379 L + 90 361 L + TGSM + 1 W + S +GR + +% TEXT +NP +0 SG + GS + 1 W + 158 132 M + GS + GS + 0 + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 345 139 M + GS + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (map to) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 350 259 M + GS + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (map to) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 159 213 M + GS + GS + 0 + /Courier FF [17 0 0 -17 0 0] MS + (symbol definition) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (symbol definition) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 159 195 M + GS + GS + 0 + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 160 276 M + GS + GS + 0 + /Courier FF [17 0 0 -17 0 0] MS + (variable name) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (variable name) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 158 260 M + GS + GS + 0 + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 160 339 M + GS + GS + 0 + /Courier FF [17 0 0 -17 0 0] MS + (property list) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /Courier FF [17 0 0 -17 0 0] MS + (property list) SH + GR + GR + +% TEXT +NP +0 SG + GS + 1 W + 158 323 M + GS + GS + 0 + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) TGSW + AD + GR + 2 DI NE 0 RM + 0 SG + /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS + (directions to) SH + GR + GR + +GR +tgifsavedpage restore +end +showpage + +%%Trailer +%MatchingCreationDate: Fri Sep 14 17:40:57 2001 +%%DocumentFonts: NewCenturySchlbk-Roman +%%+ Courier +%%EOF
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/emacs-lisp-intro.texi Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,22721 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename ../../info/eintr +@c setfilename emacs-lisp-intro.info +@c sethtmlfilename emacs-lisp-intro.html +@settitle Programming in Emacs Lisp +@syncodeindex vr cp +@syncodeindex fn cp +@setchapternewpage odd +@finalout + +@c --------- +@c <<<< For hard copy printing, this file is now +@c set for smallbook, which works for all sizes +@c of paper, and with Postscript figures >>>> +@smallbook +@clear largebook +@set print-postscript-figures +@c set largebook +@c clear print-postscript-figures +@c --------- + +@comment %**end of header + +@set edition-number 3.08 +@set update-date 12 September 2007 +@ignore + ## Summary of shell commands to create various output formats: + + pushd /usr/local/src/emacs/lispintro/ + ## pushd /u/intro/ + + ## Info output + makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi + + ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) + + ## DVI output + texi2dvi emacs-lisp-intro.texi + + ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & + + ## HTML output + makeinfo --html --no-split --verbose emacs-lisp-intro.texi + + ## galeon emacs-lisp-intro.html + + ## Plain text output + makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ + --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi + + popd + +# as user `root' +# insert thumbdrive + mtusb # mount -v -t ext3 /dev/sda /mnt + cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi + umtusb # umount -v /mnt +# remove thumbdrive + + ## Other shell commands + + pushd /usr/local/src/emacs/lispintro/ + ## pushd /u/intro/ + + ## PDF + texi2dvi --pdf emacs-lisp-intro.texi + # xpdf emacs-lisp-intro.pdf & + + ## DocBook -- note file extension + makeinfo --docbook --no-split --paragraph-indent=0 \ + --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi + + ## XML with a Texinfo DTD -- note file extension + makeinfo --xml --no-split --paragraph-indent=0 \ + --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi + + ## PostScript (needs DVI) + # gv emacs-lisp-intro.ps & + # Create DVI if we lack it + # texi2dvi emacs-lisp-intro.texi + dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps + + ## RTF (needs HTML) + # Use OpenOffice to view RTF + # Create HTML if we lack it + # makeinfo --no-split --html emacs-lisp-intro.texi + /usr/local/src/html2rtf.pl emacs-lisp-intro.html + + ## LaTeX (needs RTF) + /usr/bin/rtf2latex emacs-lisp-intro.rtf + + popd + +@end ignore + +@c ================ Included Figures ================ + +@c Set print-postscript-figures if you print PostScript figures. +@c If you clear this, the ten figures will be printed as ASCII diagrams. +@c (This is not relevant to Info, since Info only handles ASCII.) +@c Your site may require editing changes to print PostScript; in this +@c case, search for `print-postscript-figures' and make appropriate changes. + +@c ================ How to Create an Info file ================ + +@c If you have `makeinfo' installed, run the following command + +@c makeinfo emacs-lisp-intro.texi + +@c or, if you want a single, large Info file, and no paragraph indents: +@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi + +@c After creating the Info file, edit your Info `dir' file, if the +@c `dircategory' section below does not enable your system to +@c install the manual automatically. +@c (The `dir' file is often in the `/usr/local/share/info/' directory.) + +@c ================ How to Create an HTML file ================ + +@c To convert to HTML format +@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi + +@c ================ How to Print a Book in Various Sizes ================ + +@c This book can be printed in any of three different sizes. +@c In the above header, set @-commands appropriately. + +@c 7 by 9.25 inches: +@c @smallbook +@c @clear largebook + +@c 8.5 by 11 inches: +@c @c smallbook +@c @set largebook + +@c European A4 size paper: +@c @c smallbook +@c @afourpaper +@c @set largebook + +@c ================ How to Typeset and Print ================ + +@c If you do not include PostScript figures, run either of the +@c following command sequences, or similar commands suited to your +@c system: + +@c texi2dvi emacs-lisp-intro.texi +@c lpr -d emacs-lisp-intro.dvi + +@c or else: + +@c tex emacs-lisp-intro.texi +@c texindex emacs-lisp-intro.?? +@c tex emacs-lisp-intro.texi +@c lpr -d emacs-lisp-intro.dvi + +@c If you include the PostScript figures, and you have old software, +@c you may need to convert the .dvi file to a .ps file before +@c printing. Run either of the following command sequences, or one +@c similar: +@c +@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps +@c +@c or else: +@c +@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps +@c + +@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 ================ End of Formatting Sections ================ + +@c For next or subsequent edition: +@c create function using with-output-to-temp-buffer +@c create a major mode, with keymaps +@c run an asynchronous process, like grep or diff + +@c For 8.5 by 11 inch format: do not use such a small amount of +@c whitespace between paragraphs as smallbook format +@ifset largebook +@tex +\global\parskip 6pt plus 1pt +@end tex +@end ifset + +@c For all sized formats: print within-book cross +@c reference with ``...'' rather than [...] + +@c This works with the texinfo.tex file, version 2003-05-04.08, +@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. + +@tex +\if \xrefprintnodename + \global\def\xrefprintnodename#1{\unskip, ``#1''} + \else + \global\def\xrefprintnodename#1{ ``#1''} +\fi +% \global\def\xrefprintnodename#1{, ``#1''} +@end tex + +@c ---------------------------------------------------- + +@dircategory Emacs +@direntry +* Emacs Lisp Intro: (eintr). + A simple introduction to Emacs Lisp programming. +@end direntry + +@copying +This is an @cite{Introduction to Programming in Emacs Lisp}, for +people who are not programmers. +@sp 1 +Edition @value{edition-number}, @value{update-date} +@sp 1 +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, + 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@sp 1 + +@iftex +Published by the:@* + +GNU Press, @hfill @uref{http://www.gnupress.org}@* +a division of the @hfill General: @email{press@@gnu.org}@* +Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* +51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@* +Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@* +@end iftex + +@ifnottex +Published by the: + +@example +GNU Press, Website: http://www.gnupress.org +a division of the General: press@@gnu.org +Free Software Foundation, Inc. Orders: sales@@gnu.org +51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942 +Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652 +@end example +@end ifnottex + +@sp 1 +@c Printed copies are available for $30 each.@* +ISBN 1-882114-43-4 + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; there +being no Invariant Section, with the Front-Cover Texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of +the license is included in the section entitled ``GNU Free +Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and +modify this GNU Manual, like GNU software. Copies published by the +Free Software Foundation raise funds for GNU development.'' +@end copying + +@c half title; two lines here, so do not use `shorttitlepage' +@tex +{\begingroup% + \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% + \endgroup}% +{\begingroup\hbox{}\vskip 0.25in \chaprm% + \centerline{Programming in Emacs Lisp}% + \endgroup\page\hbox{}\page} +@end tex + +@titlepage +@sp 6 +@center @titlefont{An Introduction to} +@sp 2 +@center @titlefont{Programming in Emacs Lisp} +@sp 2 +@center Revised Third Edition +@sp 4 +@center by Robert J. Chassell + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@iftex +@headings off +@evenheading @thispage @| @| @thischapter +@oddheading @thissection @| @| @thispage +@end iftex + +@ifnothtml +@c Keep T.O.C. short by tightening up for largebook +@ifset largebook +@tex +\global\parskip 2pt plus 1pt +\global\advance\baselineskip by -1pt +@end tex +@end ifset +@end ifnothtml + +@shortcontents +@contents + +@ifnottex +@node Top, Preface, (dir), (dir) +@top An Introduction to Programming in Emacs Lisp + +@insertcopying + +This master menu first lists each chapter and index; then it lists +every node in every chapter. +@end ifnottex + +@c >>>> Set pageno appropriately <<<< + +@c The first page of the Preface is a roman numeral; it is the first +@c right handed page after the Table of Contents; hence the following +@c setting must be for an odd negative number. + +@iftex +@global@pageno = -11 +@end iftex + +@menu +* Preface:: What to look for. +* List Processing:: What is Lisp? +* Practicing Evaluation:: Running several programs. +* Writing Defuns:: How to write function definitions. +* Buffer Walk Through:: Exploring a few buffer-related functions. +* More Complex:: A few, even more complex functions. +* Narrowing & Widening:: Restricting your and Emacs attention to + a region. +* car cdr & cons:: Fundamental functions in Lisp. +* Cutting & Storing Text:: Removing text and saving it. +* List Implementation:: How lists are implemented in the computer. +* Yanking:: Pasting stored text. +* Loops & Recursion:: How to repeat a process. +* Regexp Search:: Regular expression searches. +* Counting Words:: A review of repetition and regexps. +* Words in a defun:: Counting words in a @code{defun}. +* Readying a Graph:: A prototype graph printing function. +* Emacs Initialization:: How to write a @file{.emacs} file. +* Debugging:: How to run the Emacs Lisp debuggers. +* Conclusion:: Now you have the basics. +* the-the:: An appendix: how to find reduplicated words. +* Kill Ring:: An appendix: how the kill ring works. +* Full Graph:: How to create a graph with labelled axes. +* Free Software and Free Manuals:: +* GNU Free Documentation License:: +* Index:: +* About the Author:: + +@detailmenu + --- The Detailed Node Listing --- + +Preface + +* Why:: Why learn Emacs Lisp? +* On Reading this Text:: Read, gain familiarity, pick up habits.... +* Who You Are:: For whom this is written. +* Lisp History:: +* Note for Novices:: You can read this as a novice. +* Thank You:: + +List Processing + +* Lisp Lists:: What are lists? +* Run a Program:: Any list in Lisp is a program ready to run. +* Making Errors:: Generating an error message. +* Names & Definitions:: Names of symbols and function definitions. +* Lisp Interpreter:: What the Lisp interpreter does. +* Evaluation:: Running a program. +* Variables:: Returning a value from a variable. +* Arguments:: Passing information to a function. +* set & setq:: Setting the value of a variable. +* Summary:: The major points. +* Error Message Exercises:: + +Lisp Lists + +* Numbers Lists:: List have numbers, other lists, in them. +* Lisp Atoms:: Elemental entities. +* Whitespace in Lists:: Formatting lists to be readable. +* Typing Lists:: How GNU Emacs helps you type lists. + +The Lisp Interpreter + +* Complications:: Variables, Special forms, Lists within. +* Byte Compiling:: Specially processing code for speed. + +Evaluation + +* How the Interpreter Acts:: Returns and Side Effects... +* Evaluating Inner Lists:: Lists within lists... + +Variables + +* fill-column Example:: +* Void Function:: The error message for a symbol + without a function. +* Void Variable:: The error message for a symbol without a value. + +Arguments + +* Data types:: Types of data passed to a function. +* Args as Variable or List:: An argument can be the value + of a variable or list. +* Variable Number of Arguments:: Some functions may take a + variable number of arguments. +* Wrong Type of Argument:: Passing an argument of the wrong type + to a function. +* message:: A useful function for sending messages. + +Setting the Value of a Variable + +* Using set:: Setting values. +* Using setq:: Setting a quoted value. +* Counting:: Using @code{setq} to count. + +Practicing Evaluation + +* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} + causes evaluation. +* Buffer Names:: Buffers and files are different. +* Getting Buffers:: Getting a buffer itself, not merely its name. +* Switching Buffers:: How to change to another buffer. +* Buffer Size & Locations:: Where point is located and the size of + the buffer. +* Evaluation Exercise:: + +How To Write Function Definitions + +* Primitive Functions:: +* defun:: The @code{defun} special form. +* Install:: Install a function definition. +* Interactive:: Making a function interactive. +* Interactive Options:: Different options for @code{interactive}. +* Permanent Installation:: Installing code permanently. +* let:: Creating and initializing local variables. +* 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. +* Review:: +* defun Exercises:: + +Install a Function Definition + +* Effect of installation:: +* Change a defun:: How to change a function definition. + +Make a Function Interactive + +* Interactive multiply-by-seven:: An overview. +* multiply-by-seven in detail:: The interactive version. + +@code{let} + +* Prevent confusion:: +* Parts of let Expression:: +* Sample let Expression:: +* Uninitialized let Variables:: + +The @code{if} Special Form + +* if in more detail:: +* type-of-animal in detail:: An example of an @code{if} expression. + +Truth and Falsehood in Emacs Lisp + +* nil explained:: @code{nil} has two meanings. + +@code{save-excursion} + +* Point and mark:: A review of various locations. +* Template for save-excursion:: + +A Few Buffer--Related Functions + +* Finding More:: How to find more information. +* simplified-beginning-of-buffer:: Shows @code{goto-char}, + @code{point-min}, and @code{push-mark}. +* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. +* append-to-buffer:: Uses @code{save-excursion} and + @code{insert-buffer-substring}. +* Buffer Related Review:: Review. +* Buffer Exercises:: + +The Definition of @code{mark-whole-buffer} + +* mark-whole-buffer overview:: +* Body of mark-whole-buffer:: Only three lines of code. + +The Definition of @code{append-to-buffer} + +* append-to-buffer overview:: +* append interactive:: A two part interactive expression. +* append-to-buffer body:: Incorporates a @code{let} expression. +* append save-excursion:: How the @code{save-excursion} works. + +A Few More Complex Functions + +* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. +* insert-buffer:: Read-only, and with @code{or}. +* beginning-of-buffer:: Shows @code{goto-char}, + @code{point-min}, and @code{push-mark}. +* Second Buffer Related Review:: +* optional Exercise:: + +The Definition of @code{insert-buffer} + +* insert-buffer code:: +* insert-buffer interactive:: When you can read, but not write. +* insert-buffer body:: The body has an @code{or} and a @code{let}. +* if & or:: Using an @code{if} instead of an @code{or}. +* Insert or:: How the @code{or} expression works. +* Insert let:: Two @code{save-excursion} expressions. +* New insert-buffer:: + +The Interactive Expression in @code{insert-buffer} + +* Read-only buffer:: When a buffer cannot be modified. +* b for interactive:: An existing buffer or else its name. + +Complete Definition of @code{beginning-of-buffer} + +* Optional Arguments:: +* beginning-of-buffer opt arg:: Example with optional argument. +* beginning-of-buffer complete:: + +@code{beginning-of-buffer} with an Argument + +* Disentangle beginning-of-buffer:: +* Large buffer case:: +* Small buffer case:: + +Narrowing and Widening + +* Narrowing advantages:: The advantages of narrowing +* save-restriction:: The @code{save-restriction} special form. +* what-line:: The number of the line that point is on. +* narrow Exercise:: + +@code{car}, @code{cdr}, @code{cons}: Fundamental Functions + +* Strange Names:: An historical aside: why the strange names? +* car & cdr:: Functions for extracting part of a list. +* cons:: Constructing a list. +* nthcdr:: Calling @code{cdr} repeatedly. +* nth:: +* setcar:: Changing the first element of a list. +* setcdr:: Changing the rest of a list. +* cons Exercise:: + +@code{cons} + +* Build a list:: +* length:: How to find the length of a list. + +Cutting and Storing Text + +* Storing Text:: Text is stored in a list. +* zap-to-char:: Cutting out text up to a character. +* kill-region:: Cutting text out of a region. +* copy-region-as-kill:: A definition for copying text. +* Digression into C:: Minor note on C programming language macros. +* defvar:: How to give a variable an initial value. +* cons & search-fwd Review:: +* search Exercises:: + +@code{zap-to-char} + +* Complete zap-to-char:: The complete implementation. +* zap-to-char interactive:: A three part interactive expression. +* zap-to-char body:: A short overview. +* search-forward:: How to search for a string. +* progn:: The @code{progn} special form. +* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. + +@code{kill-region} + +* Complete kill-region:: The function definition. +* condition-case:: Dealing with a problem. +* Lisp macro:: + +@code{copy-region-as-kill} + +* Complete copy-region-as-kill:: The complete function definition. +* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. + +The Body of @code{copy-region-as-kill} + +* last-command & this-command:: +* kill-append function:: +* kill-new function:: + +Initializing a Variable with @code{defvar} + +* See variable current value:: +* defvar and asterisk:: + +How Lists are Implemented + +* Lists diagrammed:: +* Symbols as Chest:: Exploring a powerful metaphor. +* List Exercise:: + +Yanking Text Back + +* Kill Ring Overview:: +* kill-ring-yank-pointer:: The kill ring is a list. +* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. + +Loops and Recursion + +* while:: Causing a stretch of code to repeat. +* dolist dotimes:: +* Recursion:: Causing a function to call itself. +* Looping exercise:: + +@code{while} + +* Looping with while:: Repeat so long as test returns true. +* Loop Example:: A @code{while} loop that uses a list. +* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. +* Incrementing Loop:: A loop with an incrementing counter. +* Incrementing Loop Details:: +* Decrementing Loop:: A loop with a decrementing counter. + +Details of an Incrementing Loop + +* Incrementing Example:: Counting pebbles in a triangle. +* Inc Example parts:: The parts of the function definition. +* Inc Example altogether:: Putting the function definition together. + +Loop with a Decrementing Counter + +* Decrementing Example:: More pebbles on the beach. +* Dec Example parts:: The parts of the function definition. +* Dec Example altogether:: Putting the function definition together. + +Save your time: @code{dolist} and @code{dotimes} + +* dolist:: +* dotimes:: + +Recursion + +* Building Robots:: Same model, different serial number ... +* Recursive Definition Parts:: Walk until you stop ... +* Recursion with list:: Using a list as the test whether to recurse. +* Recursive triangle function:: +* Recursion with cond:: +* Recursive Patterns:: Often used templates. +* No Deferment:: Don't store up work ... +* No deferment solution:: + +Recursion in Place of a Counter + +* Recursive Example arg of 1 or 2:: +* Recursive Example arg of 3 or 4:: + +Recursive Patterns + +* Every:: +* Accumulate:: +* Keep:: + +Regular Expression Searches + +* sentence-end:: The regular expression for @code{sentence-end}. +* re-search-forward:: Very similar to @code{search-forward}. +* forward-sentence:: A straightforward example of regexp search. +* forward-paragraph:: A somewhat complex example. +* etags:: How to create your own @file{TAGS} table. +* Regexp Review:: +* re-search Exercises:: + +@code{forward-sentence} + +* Complete forward-sentence:: +* fwd-sentence while loops:: Two @code{while} loops. +* fwd-sentence re-search:: A regular expression search. + +@code{forward-paragraph}: a Goldmine of Functions + +* forward-paragraph in brief:: Key parts of the function definition. +* fwd-para let:: The @code{let*} expression. +* fwd-para while:: The forward motion @code{while} loop. + +Counting: Repetition and Regexps + +* Why Count Words:: +* count-words-region:: Use a regexp, but find a problem. +* recursive-count-words:: Start with case of no words in region. +* Counting Exercise:: + +The @code{count-words-region} Function + +* Design count-words-region:: The definition using a @code{while} loop. +* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. + +Counting Words in a @code{defun} + +* Divide and Conquer:: +* Words and Symbols:: What to count? +* Syntax:: What constitutes a word or symbol? +* count-words-in-defun:: Very like @code{count-words}. +* Several defuns:: Counting several defuns in a file. +* Find a File:: Do you want to look at a file? +* lengths-list-file:: A list of the lengths of many definitions. +* Several files:: Counting in definitions in different files. +* Several files recursively:: Recursively counting in different files. +* Prepare the data:: Prepare the data for display in a graph. + +Count Words in @code{defuns} in Different Files + +* lengths-list-many-files:: Return a list of the lengths of defuns. +* append:: Attach one list to another. + +Prepare the Data for Display in a Graph + +* Data for Display in Detail:: +* Sorting:: Sorting lists. +* Files List:: Making a list of files. +* Counting function definitions:: + +Readying a Graph + +* Columns of a graph:: +* graph-body-print:: How to print the body of a graph. +* recursive-graph-body-print:: +* Printed Axes:: +* Line Graph Exercise:: + +Your @file{.emacs} File + +* Default Configuration:: +* Site-wide Init:: You can write site-wide init files. +* defcustom:: Emacs will write code for you. +* Beginning a .emacs File:: How to write a @code{.emacs file}. +* Text and Auto-fill:: Automatically wrap lines. +* Mail Aliases:: Use abbreviations for email addresses. +* Indent Tabs Mode:: Don't use tabs with @TeX{} +* Keybindings:: Create some personal keybindings. +* Keymaps:: More about key binding. +* Loading Files:: Load (i.e., evaluate) files automatically. +* Autoload:: Make functions available. +* Simple Extension:: Define a function; bind it to a key. +* X11 Colors:: Colors in X. +* Miscellaneous:: +* Mode Line:: How to customize your mode line. + +Debugging + +* debug:: How to use the built-in debugger. +* debug-on-entry:: Start debugging when you call a function. +* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. +* edebug:: How to use Edebug, a source level debugger. +* Debugging Exercises:: + +Handling the Kill Ring + +* What the Kill Ring Does:: +* current-kill:: +* yank:: Paste a copy of a clipped element. +* yank-pop:: Insert element pointed to. +* ring file:: + +The @code{current-kill} Function + +* Understanding current-kill:: + +@code{current-kill} in Outline + +* Body of current-kill:: +* Digression concerning error:: How to mislead humans, but not computers. +* Determining the Element:: + +A Graph with Labelled Axes + +* Labelled Example:: +* print-graph Varlist:: @code{let} expression in @code{print-graph}. +* print-Y-axis:: Print a label for the vertical axis. +* print-X-axis:: Print a horizontal label. +* Print Whole Graph:: The function to print a complete graph. + +The @code{print-Y-axis} Function + +* print-Y-axis in Detail:: +* Height of label:: What height for the Y axis? +* Compute a Remainder:: How to compute the remainder of a division. +* Y Axis Element:: Construct a line for the Y axis. +* Y-axis-column:: Generate a list of Y axis labels. +* print-Y-axis Penultimate:: A not quite final version. + +The @code{print-X-axis} Function + +* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. +* X Axis Tic Marks:: Create tic marks for the horizontal axis. + +Printing the Whole Graph + +* The final version:: A few changes. +* Test print-graph:: Run a short test. +* Graphing words in defuns:: Executing the final code. +* lambda:: How to write an anonymous function. +* mapcar:: Apply a function to elements of a list. +* Another Bug:: Yet another bug @dots{} most insidious. +* Final printed graph:: The graph itself! + +@end detailmenu +@end menu + +@node Preface, List Processing, Top, Top +@comment node-name, next, previous, up +@unnumbered Preface + +Most of the GNU Emacs integrated environment is written in the programming +language called Emacs Lisp. The code written in this programming +language is the software---the sets of instructions---that tell the +computer what to do when you give it commands. Emacs is designed so +that you can write new code in Emacs Lisp and easily install it as an +extension to the editor. + +(GNU Emacs is sometimes called an ``extensible editor'', but it does +much more than provide editing capabilities. It is better to refer to +Emacs as an ``extensible computing environment''. However, that +phrase is quite a mouthful. It is easier to refer to Emacs simply as +an editor. Moreover, everything you do in Emacs---find the Mayan date +and phases of the moon, simplify polynomials, debug code, manage +files, read letters, write books---all these activities are kinds of +editing in the most general sense of the word.) + +@menu +* Why:: Why learn Emacs Lisp? +* On Reading this Text:: Read, gain familiarity, pick up habits.... +* Who You Are:: For whom this is written. +* Lisp History:: +* Note for Novices:: You can read this as a novice. +* Thank You:: +@end menu + +@node Why, On Reading this Text, Preface, Preface +@ifnottex +@unnumberedsec Why Study Emacs Lisp? +@end ifnottex + +Although Emacs Lisp is usually thought of in association only with Emacs, +it is a full computer programming language. You can use Emacs Lisp as +you would any other programming language. + +Perhaps you want to understand programming; perhaps you want to extend +Emacs; or perhaps you want to become a programmer. This introduction to +Emacs Lisp is designed to get you started: to guide you in learning the +fundamentals of programming, and more importantly, to show you how you +can teach yourself to go further. + +@node On Reading this Text, Who You Are, Why, Preface +@comment node-name, next, previous, up +@unnumberedsec On Reading this Text + +All through this document, you will see little sample programs you can +run inside of Emacs. If you read this document in Info inside of GNU +Emacs, you can run the programs as they appear. (This is easy to do and +is explained when the examples are presented.) Alternatively, you can +read this introduction as a printed book while sitting beside a computer +running Emacs. (This is what I like to do; I like printed books.) If +you don't have a running Emacs beside you, you can still read this book, +but in this case, it is best to treat it as a novel or as a travel guide +to a country not yet visited: interesting, but not the same as being +there. + +Much of this introduction is dedicated to walk-throughs or guided tours +of code used in GNU Emacs. These tours are designed for two purposes: +first, to give you familiarity with real, working code (code you use +every day); and, second, to give you familiarity with the way Emacs +works. It is interesting to see how a working environment is +implemented. +Also, I +hope that you will pick up the habit of browsing through source code. +You can learn from it and mine it for ideas. Having GNU Emacs is like +having a dragon's cave of treasures. + +In addition to learning about Emacs as an editor and Emacs Lisp as a +programming language, the examples and guided tours will give you an +opportunity to get acquainted with Emacs as a Lisp programming +environment. GNU Emacs supports programming and provides tools that +you will want to become comfortable using, such as @kbd{M-.} (the key +which invokes the @code{find-tag} command). You will also learn about +buffers and other objects that are part of the environment. +Learning about these features of Emacs is like learning new routes +around your home town. + +@ignore +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 +advantage of Emacs Lisp: it is easy to learn to use it for work. +@end ignore + +Finally, I hope to convey some of the skills for using Emacs to +learn aspects of programming that you don't know. You can often use +Emacs to help you understand what puzzles you or to find out how to do +something new. This self-reliance is not only a pleasure, but an +advantage. + +@node Who You Are, Lisp History, On Reading this Text, Preface +@comment node-name, next, previous, up +@unnumberedsec For Whom This is Written + +This text is written as an elementary introduction for people who are +not programmers. If you are a programmer, you may not be satisfied with +this primer. The reason is that you may have become expert at reading +reference manuals and be put off by the way this text is organized. + +An expert programmer who reviewed this text said to me: + +@quotation +@i{I prefer to learn from reference manuals. I ``dive into'' each +paragraph, and ``come up for air'' between paragraphs.} + +@i{When I get to the end of a paragraph, I assume that that subject is +done, finished, that I know everything I need (with the +possible exception of the case when the next paragraph starts talking +about it in more detail). I expect that a well written reference manual +will not have a lot of redundancy, and that it will have excellent +pointers to the (one) place where the information I want is.} +@end quotation + +This introduction is not written for this person! + +Firstly, I try to say everything at least three times: first, to +introduce it; second, to show it in context; and third, to show it in a +different context, or to review it. + +Secondly, I hardly ever put all the information about a subject in one +place, much less in one paragraph. To my way of thinking, that imposes +too heavy a burden on the reader. Instead I try to explain only what +you need to know at the time. (Sometimes I include a little extra +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 +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 +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. + +This introduction to @cite{Programming in Emacs Lisp} has a companion +document, +@iftex +@cite{The GNU Emacs Lisp Reference Manual}. +@end iftex +@ifnottex +@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU +Emacs Lisp Reference Manual}. +@end ifnottex +The reference manual has more detail than this introduction. In the +reference manual, all the information about one topic is concentrated +in one place. You should turn to it if you are like the programmer +quoted above. And, of course, after you have read this +@cite{Introduction}, you will find the @cite{Reference Manual} useful +when you are writing your own programs. + +@node Lisp History, Note for Novices, Who You Are, Preface +@unnumberedsec Lisp History +@cindex Lisp history + +Lisp was first developed in the late 1950s at the Massachusetts +Institute of Technology for research in artificial intelligence. The +great power of the Lisp language makes it superior for other purposes as +well, such as writing editor commands and integrated environments. + +@cindex Maclisp +@cindex Common Lisp +GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT +in the 1960s. It is somewhat inspired by Common Lisp, which became a +standard in the 1980s. However, Emacs Lisp is much simpler than Common +Lisp. (The standard Emacs distribution contains an optional extensions +file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) + +@node Note for Novices, Thank You, Lisp History, Preface +@comment node-name, next, previous, up +@unnumberedsec A Note for Novices + +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 +means you press and release the @key{CTRL} key and the @kbd{h} at the +same time, and then press and release @kbd{t}.) + +Also, I often refer to one of Emacs' standard commands by listing the +keys which you press to invoke the command and then giving the name of +the command in parentheses, like this: @kbd{M-C-\} +(@code{indent-region}). What this means is that the +@code{indent-region} command is customarily invoked by typing +@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to +invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , +Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your +@key{META} key, @key{CTRL} key and @key{\} key all at the same time. +(On many modern keyboards the @key{META} key is labelled +@key{ALT}.) +Sometimes a combination like this is called a keychord, since it is +similar to the way you play a chord on a piano. If your keyboard does +not have a @key{META} key, the @key{ESC} key prefix is used in place +of it. In this case, @kbd{M-C-\} means that you press and release your +@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at +the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key +along with the key that is labelled @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 +@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, +Emacs either passes the number 4 to the command or otherwise runs the +command differently than it would otherwise.) @xref{Arguments, , +Numeric Arguments, emacs, The GNU Emacs Manual}. + +If you are reading this in Info using GNU Emacs, you can read through +this whole document just by pressing the space bar, @key{SPC}. +(To learn about Info, type @kbd{C-h i} and then select Info.) + +A note on terminology: when I use the word Lisp alone, I often am +referring to the various dialects of Lisp in general, but when I speak +of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. + +@node Thank You, , Note for Novices, Preface +@comment node-name, next, previous, up +@unnumberedsec Thank You + +My thanks to all who helped me with this book. My especial thanks to +@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland +McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: +Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both +@w{Philip Johnson} and @w{David Stampe} for their patient +encouragement. My mistakes are my own. + +@flushright +Robert J. Chassell +@email{bob@@gnu.org} +@end flushright + +@c ================ Beginning of main text ================ + +@c Start main text on right-hand (verso) page + +@tex +\par\vfill\supereject +\headings off +\ifodd\pageno + \par\vfill\supereject +\else + \par\vfill\supereject + \page\hbox{}\page + \par\vfill\supereject +\fi +@end tex + +@iftex +@headings off +@evenheading @thispage @| @| @thischapter +@oddheading @thissection @| @| @thispage +@global@pageno = 1 +@end iftex + +@node List Processing, Practicing Evaluation, Preface, Top +@comment node-name, next, previous, up +@chapter List Processing + +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 +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 +of the list. Sometimes a list is preceded by a single apostrophe or +quotation mark, @samp{'}@footnote{The single apostrophe or quotation +mark is an abbreviation for the function @code{quote}; you need not +think about functions now; functions are defined in @ref{Making +Errors, , Generate an Error Message}.} Lists are the basis of Lisp. + +@menu +* Lisp Lists:: What are lists? +* Run a Program:: Any list in Lisp is a program ready to run. +* Making Errors:: Generating an error message. +* Names & Definitions:: Names of symbols and function definitions. +* Lisp Interpreter:: What the Lisp interpreter does. +* Evaluation:: Running a program. +* Variables:: Returning a value from a variable. +* Arguments:: Passing information to a function. +* set & setq:: Setting the value of a variable. +* Summary:: The major points. +* Error Message Exercises:: +@end menu + +@node Lisp Lists, Run a Program, List Processing, List Processing +@comment node-name, next, previous, up +@section Lisp Lists +@cindex Lisp Lists + +In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. +This list is preceded by a single apostrophe. It could just as well be +written as follows, which looks more like the kind of list you are likely +to be familiar with: + +@smallexample +@group +'(rose + violet + daisy + buttercup) +@end group +@end smallexample + +@noindent +The elements of this list are the names of the four different flowers, +separated from each other by whitespace and surrounded by parentheses, +like flowers in a field with a stone wall around them. +@cindex Flowers in a field + +@menu +* Numbers Lists:: List have numbers, other lists, in them. +* Lisp Atoms:: Elemental entities. +* Whitespace in Lists:: Formatting lists to be readable. +* Typing Lists:: How GNU Emacs helps you type lists. +@end menu + +@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists +@ifnottex +@unnumberedsubsec Numbers, Lists inside of Lists +@end ifnottex + +Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. +This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each +separated by whitespace. + +In Lisp, both data and programs are represented the same way; that is, +they are both lists of words, numbers, or other lists, separated by +whitespace and surrounded by parentheses. (Since a program looks like +data, one program may easily serve as data for another; this is a very +powerful feature of Lisp.) (Incidentally, these two parenthetical +remarks are @emph{not} Lisp lists, because they contain @samp{;} and +@samp{.} as punctuation marks.) + +@need 1200 +Here is another list, this time with a list inside of it: + +@smallexample +'(this list has (a list inside of it)) +@end smallexample + +The components of this list are the words @samp{this}, @samp{list}, +@samp{has}, and the list @samp{(a list inside of it)}. The interior +list is made up of the words @samp{a}, @samp{list}, @samp{inside}, +@samp{of}, @samp{it}. + +@node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists +@comment node-name, next, previous, up +@subsection Lisp Atoms +@cindex Lisp Atoms + +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 +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 +ancient atom, a list can be split into parts. (@xref{car cdr & cons, +, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) + +In a list, atoms are separated from each other by whitespace. They can be +right next to a parenthesis. + +@cindex @samp{empty list} defined +Technically speaking, a list in Lisp consists of parentheses surrounding +atoms separated by whitespace or surrounding other lists or surrounding +both atoms and other lists. A list can have just one atom in it or +have nothing in it at all. A list with nothing in it looks like this: +@code{()}, and is called the @dfn{empty list}. Unlike anything else, an +empty list is considered both an atom and a list at the same time. + +@cindex Symbolic expressions, introduced +@cindex @samp{expression} defined +@cindex @samp{form} defined +The printed representation of both atoms and lists are called +@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. +The word @dfn{expression} by itself can refer to either the printed +representation, or to the atom or list as it is held internally in the +computer. Often, people use the term @dfn{expression} +indiscriminately. (Also, in many texts, the word @dfn{form} is used +as a synonym for expression.) + +Incidentally, the atoms that make up our universe were named such when +they were thought to be indivisible; but it has been found that physical +atoms are not indivisible. Parts can split off an atom or it can +fission into two parts of roughly equal size. Physical atoms were named +prematurely, before their truer nature was found. 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 list operations are concerned, the atoms of a list are +unsplittable. + +As in English, the meanings of the component letters of a Lisp atom +are different from the meaning the letters make as a word. For +example, the word for the South American sloth, the @samp{ai}, is +completely different from the two words, @samp{a}, and @samp{i}. + +There are many kinds of atom in nature but only a few in Lisp: for +example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such +as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have +listed in the examples above are all symbols. In everyday Lisp +conversation, the word ``atom'' is not often used, because programmers +usually try to be more specific about what kind of atom they are dealing +with. Lisp programming is mostly about symbols (and sometimes numbers) +within lists. (Incidentally, the preceding three word parenthetical +remark is a proper list in Lisp, since it consists of atoms, which in +this case are symbols, separated by whitespace and enclosed by +parentheses, without any non-Lisp punctuation.) + +@need 1250 +In addition, text between double quotation marks---even sentences or +paragraphs---is an atom. Here is an example: +@cindex Text between double quotation marks + +@smallexample +'(this list includes "text between quotation marks.") +@end smallexample + +@cindex @samp{string} defined +@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 +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. + +@node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists +@comment node-name, next, previous, up +@subsection Whitespace in Lists +@cindex Whitespace in lists + +@need 1200 +The amount of whitespace in a list does not matter. From the point of view +of the Lisp language, + +@smallexample +@group +'(this list + looks like this) +@end group +@end smallexample + +@need 800 +@noindent +is exactly the same as this: + +@smallexample +'(this list looks like this) +@end smallexample + +Both examples show what to Lisp is the same list, the list made up of +the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and +@samp{this} in that order. + +Extra whitespace and newlines are designed to make a list more readable +by humans. When Lisp reads the expression, it gets rid of all the extra +whitespace (but it needs to have at least one space between atoms in +order to tell them apart.) + +Odd as it seems, the examples we have seen cover almost all of what Lisp +lists look like! Every other list in Lisp looks more or less like one +of these examples, except that the list may be longer and more complex. +In brief, a list is between parentheses, a string is between quotation +marks, a symbol looks like a word, and a number looks like a number. +(For certain situations, square brackets, dots and a few other special +characters may be used; however, we will go quite far without them.) + +@node Typing Lists, , Whitespace in Lists, Lisp Lists +@comment node-name, next, previous, up +@subsection GNU Emacs Helps You Type Lists +@cindex Help typing lists +@cindex Formatting help + +When you type a Lisp expression in GNU Emacs using either Lisp +Interaction mode or Emacs Lisp mode, you have available to you several +commands to format the Lisp expression so it is easy to read. For +example, pressing the @key{TAB} key automatically indents the line the +cursor is on by the right amount. A command to properly indent the +code in a region is customarily bound to @kbd{M-C-\}. Indentation is +designed so that you can see which elements of a list belong to which +list---elements of a sub-list are indented more than the elements of +the enclosing list. + +In addition, when you type a closing parenthesis, Emacs momentarily +jumps the cursor back to the matching opening parenthesis, so you can +see which one it is. This is very useful, since every list you type +in Lisp must have its closing parenthesis match its opening +parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs +Manual}, for more information about Emacs' modes.) + +@node Run a Program, Making Errors, Lisp Lists, List Processing +@comment node-name, next, previous, up +@section Run a Program +@cindex Run a program +@cindex Program, running one + +@cindex @samp{evaluate} defined +A list in Lisp---any list---is a program ready to run. If you run it +(for which the Lisp jargon is @dfn{evaluate}), the computer will do one +of three things: do nothing except return to you the list itself; send +you an error message; or, treat the first symbol in the list as a +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. +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 +take it as it is written. But if there is no quote preceding a list, +the first item of the list is special: it is a command for the computer +to obey. (In Lisp, these commands are called @emph{functions}.) The list +@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp +understands that the @code{+} is an instruction to do something with the +rest of the list: add the numbers that follow. + +@need 1250 +If you are reading this inside of GNU Emacs in Info, here is how you can +evaluate such a list: place your cursor immediately after the right +hand parenthesis of the following list and then type @kbd{C-x C-e}: + +@smallexample +(+ 2 2) +@end smallexample + +@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'' +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}: + +@smallexample +'(this is a quoted list) +@end smallexample + +@noindent +You will see @code{(this is a quoted list)} appear in the echo area. + +@cindex Lisp interpreter, explained +@cindex Interpreter, Lisp, explained +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. + +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 +from the humanly readable expression to the language of the computer. +But before discussing this (@pxref{Variables}), we will discuss what the +Lisp interpreter does when you make an error. + +@node Making Errors, Names & Definitions, Run a Program, List Processing +@comment node-name, next, previous, up +@section Generate an Error Message +@cindex Generate an error message +@cindex Error message generation + +Partly so you won't worry if you do it accidentally, we will now give +a command to the Lisp interpreter that generates an error message. +This is a harmless activity; and indeed, we will often try to generate +error messages intentionally. Once you understand the jargon, error +messages can be informative. Instead of being called ``error'' +messages, they should be called ``help'' messages. They are like +signposts to a traveller 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}. + +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 +exactly the same as the one we just used, but without the single-quote +in front of it. Position the cursor right after it and type @kbd{C-x +C-e}: + +@smallexample +(this is an unquoted list) +@end smallexample + +@noindent +What you see depends on which version of Emacs you are running. GNU +Emacs version 22 provides more information than version 20 and before. +First, the more recent result of generating an error; then the +earlier, version 20 result. + +@need 1250 +@noindent +In GNU Emacs version 22, a @file{*Backtrace*} window will open up and +you will see the following in it: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: (void-function this) + (this is an unquoted list) + eval((this is an unquoted list)) + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@need 1200 +@noindent +Your cursor will be in this window (you may have to wait a few seconds +before it becomes visible). To quit the debugger and make the +debugger window go away, type: + +@smallexample +q +@end smallexample + +@noindent +Please type @kbd{q} right now, so you become confident that you can +get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter +it. + +@cindex @samp{function} defined +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. + +Each line above tells you what the Lisp interpreter evaluated next. +The most recent action is at the top. The buffer is called the +@file{*Backtrace*} buffer because it enables you to track Emacs +backwards. + +@need 800 +At the top of the @file{*Backtrace*} buffer, you see the line: + +@smallexample +Debugger entered--Lisp error: (void-function this) +@end smallexample + +@noindent +The Lisp interpreter tried to evaluate the first atom of the list, the +word @samp{this}. It is this action that generated the error message +@samp{void-function this}. + +The message contains the words @samp{void-function} and @samp{this}. + +@cindex @samp{function} defined +The word @samp{function} was mentioned once before. It is a very +important word. For our purposes, we can define it by saying that a +@dfn{function} is a set of instructions to the computer that tell the +computer to do something. + +Now we can begin to understand the error message: @samp{void-function +this}. The function (that is, the word @samp{this}) does not have a +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'. + +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 +have a set of instructions for the computer to obey and those +instructions must be to add the numbers that follow the @code{+}. + +@need 1250 +In GNU Emacs version 20, and in earlier versions, you will see only +one line of error message; it will appear in the echo area and look +like this: + +@smallexample +Symbol's function definition is void:@: this +@end smallexample + +@noindent +(Also, your terminal may beep at you---some do, some don't; and others +blink. This is just a device to get your attention.) The message goes +away as soon as you type another key, even just to move the cursor. + +We know the meaning of the word @samp{Symbol}. It refers to the first +atom of the list, the word @samp{this}. The word @samp{function} +refers to the instructions that tell the computer what to do. +(Technically, the symbol tells the computer where to find the +instructions, but this is a complication we can ignore for the +moment.) + +The error message can be understood: @samp{Symbol's function +definition is void:@: this}. The symbol (that is, the word +@samp{this}) lacks instructions for the computer to carry out. + +@node Names & Definitions, Lisp Interpreter, Making Errors, List Processing +@comment node-name, next, previous, up +@section Symbol Names and Function Definitions +@cindex Symbol names + +We can articulate another characteristic of Lisp based on what we have +discussed so far---an important characteristic: a symbol, like +@code{+}, is not itself the set of instructions for the computer to +carry out. Instead, the symbol is used, perhaps temporarily, as a way +of locating the definition or set of instructions. What we see is the +name through which the instructions can be found. Names of people +work the same way. I can be referred to as @samp{Bob}; however, I am +not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the +consciousness consistently associated with a particular life-form. +The name is not me, but it can be used to refer to me. + +In Lisp, one set of instructions can be attached to several names. +For example, the computer instructions for adding numbers can be +linked to the symbol @code{plus} as well as to the symbol @code{+} +(and are in some dialects of Lisp). Among humans, I can be referred +to as @samp{Robert} as well as @samp{Bob} and by other words as well. + +On the other hand, a symbol can have only one function definition +attached to it at a time. Otherwise, the computer would be confused as +to which definition to use. If this were the case among people, only +one person in the world could be named @samp{Bob}. However, the function +definition to which the name refers can be changed readily. +(@xref{Install, , Install a Function Definition}.) + +Since Emacs Lisp is large, it is customary to name symbols in a way +that identifies the part of Emacs to which the function belongs. +Thus, all the names for functions that deal with Texinfo start with +@samp{texinfo-} and those for functions that deal with reading mail +start with @samp{rmail-}. + +@node Lisp Interpreter, Evaluation, Names & Definitions, List Processing +@comment node-name, next, previous, up +@section The Lisp Interpreter +@cindex Lisp interpreter, what it does +@cindex Interpreter, what it does + +Based on what we have seen, we can now start to figure out what the +Lisp interpreter does when we command it to evaluate a list. +First, it looks to see whether there is a quote before the list; if +there is, the interpreter just gives us the list. On the other +hand, if there is no quote, the interpreter looks at the first element +in the list and sees whether it has a function definition. If it does, +the interpreter carries out the instructions in the function definition. +Otherwise, the interpreter prints an error message. + +This is how Lisp works. Simple. There are added complications which we +will get to in a minute, but these are the fundamentals. Of course, to +write Lisp programs, you need to know how to write function definitions +and attach them to names, and how to do this without confusing either +yourself or the computer. + +@menu +* Complications:: Variables, Special forms, Lists within. +* Byte Compiling:: Specially processing code for speed. +@end menu + +@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter +@ifnottex +@unnumberedsubsec Complications +@end ifnottex + +Now, for the first complication. In addition to lists, the Lisp +interpreter can evaluate a symbol that is not quoted and does not have +parentheses around it. The Lisp interpreter will attempt to determine +the symbol's value as a @dfn{variable}. This situation is described +in the section on variables. (@xref{Variables}.) + +@cindex Special form +The second complication occurs because some functions are unusual and do +not work in the usual manner. Those that don't are called @dfn{special +forms}. They are used for special jobs, like defining a function, and +there are not many of them. In the next few chapters, you will be +introduced to several of the more important special forms. + +The third and final complication is this: if the function that the +Lisp interpreter is looking at is not a special form, and if it is part +of a list, the Lisp interpreter looks to see whether the list has a list +inside of it. If there is an inner list, the Lisp interpreter first +figures out what it should do with the inside list, and then it works on +the outside list. If there is yet another list embedded inside the +inner list, it works on that one first, and so on. It always works on +the innermost list first. The interpreter works on the innermost list +first, to evaluate the result of that list. The result may be +used by the enclosing expression. + +Otherwise, the interpreter works left to right, from one expression to +the next. + +@node Byte Compiling, , Complications, Lisp Interpreter +@subsection Byte Compiling +@cindex Byte compiling + +One other aspect of interpreting: the Lisp interpreter is able to +interpret two kinds of entity: humanly readable code, on which we will +focus exclusively, and specially processed code, called @dfn{byte +compiled} code, which is not humanly readable. Byte compiled code +runs faster than humanly readable code. + +You can transform humanly readable code into byte compiled code by +running one of the compile commands such as @code{byte-compile-file}. +Byte compiled code is usually stored in a file that ends with a +@file{.elc} extension rather than a @file{.el} extension. You will +see both kinds of file in the @file{emacs/lisp} directory; the files +to read are those with @file{.el} extensions. + +As a practical matter, for most things you might do to customize or +extend Emacs, you do not need to byte compile; and I will not discuss +the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, +The GNU Emacs Lisp Reference Manual}, for a full description of byte +compilation. + +@node Evaluation, Variables, Lisp Interpreter, List Processing +@comment node-name, next, previous, up +@section Evaluation +@cindex Evaluation + +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 +Collegiate Dictionary}. + +@menu +* How the Interpreter Acts:: Returns and Side Effects... +* Evaluating Inner Lists:: Lists within lists... +@end menu + +@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation +@ifnottex +@unnumberedsubsec How the Lisp Interpreter Acts +@end ifnottex + +@cindex @samp{returned value} explained +After evaluating an expression, the Lisp interpreter will most likely +@dfn{return} the value that the computer produces by carrying out the +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 +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. + +In summary, evaluating a symbolic expression most commonly causes the +Lisp interpreter to return a value and perhaps carry out a side effect; +or else produce an error. + +@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation +@comment node-name, next, previous, up +@subsection Evaluating Inner Lists +@cindex Inner list evaluation +@cindex Evaluating inner lists + +If evaluation applies to a list that is inside another list, the outer +list may use the value returned by the first evaluation as information +when the outer list is evaluated. This explains why inner expressions +are evaluated first: the values they return are used by the outer +expressions. + +@need 1250 +We can investigate this process by evaluating another addition example. +Place your cursor after the following expression and type @kbd{C-x C-e}: + +@smallexample +(+ 2 (+ 3 3)) +@end smallexample + +@noindent +The number 8 will appear in the echo area. + +What happens is that the Lisp interpreter first evaluates the inner +expression, @code{(+ 3 3)}, for which the value 6 is returned; then it +evaluates the outer expression as if it were written @code{(+ 2 6)}, which +returns the value 8. Since there are no more enclosing expressions to +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'. + +As an experiment, you can try evaluating the expression by putting the +cursor at the beginning of the next line immediately following the +expression, or inside the expression. + +@need 800 +Here is another copy of the expression: + +@smallexample +(+ 2 (+ 3 3)) +@end smallexample + +@noindent +If you place the cursor at the beginning of the blank line that +immediately follows the expression and type @kbd{C-x C-e}, you will +still get the value 8 printed in the echo area. Now try putting the +cursor inside the expression. If you put it right after the next to +last parenthesis (so it appears to sit on top of the last parenthesis), +you will get a 6 printed in the echo area! This is because the command +evaluates the expression @code{(+ 3 3)}. + +Now put the cursor immediately after a number. Type @kbd{C-x C-e} and +you will get the number itself. In Lisp, if you evaluate a number, you +get the number itself---this is how numbers differ from symbols. If you +evaluate a list starting with a symbol like @code{+}, you will get a +value returned that is the result of the computer carrying out the +instructions in the function definition attached to that name. If a +symbol by itself is evaluated, something different happens, as we will +see in the next section. + +@node Variables, Arguments, Evaluation, List Processing +@comment node-name, next, previous, up +@section Variables +@cindex Variables + +In Emacs Lisp, a symbol can have a value attached to it just as it can +have a function definition attached to it. The two are different. +The function definition is a set of instructions that a computer will +obey. A value, on the other hand, is something, such as number or a +name, that can vary (which is why such a symbol is called a variable). +The value of a symbol can be any expression in Lisp, such as a symbol, +number, list, or string. A symbol that has a value is often called a +@dfn{variable}. + +A symbol can have both a function definition and a value attached to +it at the same time. Or it can have just one or the other. +The two are separate. This is somewhat similar +to the way the name Cambridge can refer to the city in Massachusetts +and have some information attached to the name as well, such as +``great programming center''. + +@ignore +(Incidentally, in Emacs Lisp, a symbol can have two +other things attached to it, too: a property list and a documentation +string; these are discussed later.) +@end ignore + +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. + +@menu +* fill-column Example:: +* Void Function:: The error message for a symbol + without a function. +* Void Variable:: The error message for a symbol without a value. +@end menu + +@node fill-column Example, Void Function, Variables, Variables +@ifnottex +@unnumberedsubsec @code{fill-column}, an Example Variable +@end ifnottex + +@findex fill-column, @r{an example variable} +@cindex Example variable, @code{fill-column} +@cindex Variable, example of, @code{fill-column} +The variable @code{fill-column} illustrates a symbol with a value +attached to it: in every GNU Emacs buffer, this symbol is set to some +value, usually 72 or 70, but sometimes to some other value. To find the +value of this symbol, evaluate it by itself. If you are reading this in +Info inside of GNU Emacs, you can do this by putting the cursor after +the symbol and typing @kbd{C-x C-e}: + +@smallexample +fill-column +@end smallexample + +@noindent +After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo +area. This is the value for which @code{fill-column} is set for me as I +write this. It may be different for you in your Info buffer. Notice +that the value returned as a variable is printed in exactly the same way +as the value returned by a function carrying out its instructions. From +the point of view of the Lisp interpreter, a value returned is a value +returned. What kind of expression it came from ceases to matter once +the value is known. + +A symbol can have any value attached to it or, to use the jargon, we can +@dfn{bind} the variable to a value: to a number, such as 72; to a +string, @code{"such as this"}; to a list, such as @code{(spruce pine +oak)}; we can even bind a variable to a function definition. + +A symbol can be bound to a value in several ways. @xref{set & setq, , +Setting the Value of a Variable}, for information about one way to do +this. + +@node Void Function, Void Variable, fill-column Example, Variables +@comment node-name, next, previous, up +@subsection Error Message for a Symbol Without a Function +@cindex Symbol without function error +@cindex Error for symbol without function + +When we evaluated @code{fill-column} to find its value as a variable, +we did not place parentheses around the word. This is because we did +not intend to use it as a function name. + +If @code{fill-column} were the first or only element of a list, the +Lisp interpreter would attempt to find the function definition +attached to it. But @code{fill-column} has no function definition. +Try evaluating this: + +@smallexample +(fill-column) +@end smallexample + +@need 1250 +@noindent +In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer +that says: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: (void-function fill-column) + (fill-column) + eval((fill-column)) + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@noindent +(Remember, to quit the debugger and make the debugger window go away, +type @kbd{q} in the @file{*Backtrace*} buffer.) + +@ignore +@need 800 +In GNU Emacs 20 and before, you will produce an error message that says: + +@smallexample +Symbol's function definition is void:@: fill-column +@end smallexample + +@noindent +(The message will go away as soon as you move the cursor or type +another key.) +@end ignore + +@node Void Variable, , Void Function, Variables +@comment node-name, next, previous, up +@subsection Error Message for a Symbol Without a Value +@cindex Symbol without value error +@cindex Error for symbol without value + +If you attempt to evaluate a symbol that does not have a value bound to +it, you will receive an error message. You can see this by +experimenting with our 2 plus 2 addition. In the following expression, +put your cursor right after the @code{+}, before the first number 2, +type @kbd{C-x C-e}: + +@smallexample +(+ 2 2) +@end smallexample + +@need 1500 +@noindent +In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that +says: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: (void-variable +) + eval(+) + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@noindent +(As with the other times we entered the debugger, you can quit by +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 +have a definition. + +In this experiment with the @code{+}, what we did was cause the Lisp +interpreter to evaluate the @code{+} and look for the value of the +variable instead of the function definition. We did this by placing the +cursor right after the symbol rather than after the parenthesis of the +enclosing list as we did before. As a consequence, the Lisp interpreter +evaluated the preceding s-expression, which in this case was the +@code{+} by itself. + +Since @code{+} does not have a value bound to it, just the function +definition, the error message reported that the symbol's value as a +variable was void. + +@ignore +@need 800 +In GNU Emacs version 20 and before, your error message will say: + +@example +Symbol's value as variable is void:@: + +@end example + +@noindent +The meaning is the same as in GNU Emacs 22. +@end ignore + +@node Arguments, set & setq, Variables, List Processing +@comment node-name, next, previous, up +@section Arguments +@cindex Arguments +@cindex Passing information to functions + +To see how information is passed to functions, let's look again at +our old standby, the addition of two plus two. In Lisp, this is written +as follows: + +@smallexample +(+ 2 2) +@end smallexample + +If you evaluate this expression, the number 4 will appear in your echo +area. What the Lisp interpreter does is add the numbers that follow +the @code{+}. + +@cindex @samp{argument} defined +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 +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' +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 +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. +(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.)} + +@menu +* Data types:: Types of data passed to a function. +* Args as Variable or List:: An argument can be the value + of a variable or list. +* Variable Number of Arguments:: Some functions may take a + variable number of arguments. +* Wrong Type of Argument:: Passing an argument of the wrong type + to a function. +* message:: A useful function for sending messages. +@end menu + +@node Data types, Args as Variable or List, Arguments, Arguments +@comment node-name, next, previous, up +@subsection Arguments' Data Types +@cindex Data types +@cindex Types of data +@cindex Arguments' data types + +The type of data that should be passed to a function depends on what +kind of information it uses. The arguments to a function such as +@code{+} must have values that are numbers, since @code{+} adds numbers. +Other functions use different kinds of data for their arguments. + +@need 1250 +@findex concat +For example, the @code{concat} function links together or unites two or +more strings of text to produce a string. The arguments are strings. +Concatenating the two character strings @code{abc}, @code{def} produces +the single string @code{abcdef}. This can be seen by evaluating the +following: + +@smallexample +(concat "abc" "def") +@end smallexample + +@noindent +The value produced by evaluating this expression is @code{"abcdef"}. + +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 +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 +punctuations) from the beginning of the string. + +@need 800 +For example, if you evaluate the following: + +@smallexample +(substring "The quick brown fox jumped." 16 19) +@end smallexample + +@noindent +you will see @code{"fox"} appear in the echo area. The arguments are the +string and the two numbers. + +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 +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. + +@node Args as Variable or List, Variable Number of Arguments, Data types, Arguments +@comment node-name, next, previous, up +@subsection An Argument as the Value of a Variable or List + +An argument can be a symbol that returns a value when it is evaluated. +For example, when the symbol @code{fill-column} by itself is evaluated, +it returns a number. This number can be used in an addition. + +@need 1250 +Position the cursor after the following expression and type @kbd{C-x +C-e}: + +@smallexample +(+ 2 fill-column) +@end smallexample + +@noindent +The value will be a number two more than what you get by evaluating +@code{fill-column} alone. For me, this is 74, because my value of +@code{fill-column} is 72. + +As we have just seen, an argument can be a symbol that returns a value +when evaluated. In addition, an argument can be a list that returns a +value when it is evaluated. For example, in the following expression, +the arguments to the function @code{concat} are the strings +@w{@code{"The "}} and @w{@code{" red foxes."}} and the list +@code{(number-to-string (+ 2 fill-column))}. + +@c For GNU Emacs 22, need number-to-string +@smallexample +(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") +@end smallexample + +@noindent +If you evaluate this expression---and if, as with my Emacs, +@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will +appear in the echo area. (Note that you must put spaces after the +word @samp{The} and before the word @samp{red} so they will appear in +the final string. The function @code{number-to-string} converts the +integer that the addition function returns to a string. +@code{number-to-string} is also known as @code{int-to-string}.) + +@node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments +@comment node-name, next, previous, up +@subsection Variable Number of Arguments +@cindex Variable number of arguments +@cindex Arguments, variable number of + +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'. + +@need 1250 +In the first set, the functions have no arguments: + +@smallexample +@group +(+) @result{} 0 + +(*) @result{} 1 +@end group +@end smallexample + +@need 1250 +In this set, the functions have one argument each: + +@smallexample +@group +(+ 3) @result{} 3 + +(* 3) @result{} 3 +@end group +@end smallexample + +@need 1250 +In this set, the functions have three arguments each: + +@smallexample +@group +(+ 3 4 5) @result{} 12 + +(* 3 4 5) @result{} 60 +@end group +@end smallexample + +@node Wrong Type of Argument, message, Variable Number of Arguments, Arguments +@comment node-name, next, previous, up +@subsection Using the Wrong Type Object as an Argument +@cindex Wrong type of argument +@cindex Argument, wrong type of + +When a function is passed an argument of the wrong type, the Lisp +interpreter produces an error message. For example, the @code{+} +function expects the values of its arguments to be numbers. As an +experiment we can pass it the quoted symbol @code{hello} instead of a +number. Position the cursor after the following expression and type +@kbd{C-x C-e}: + +@smallexample +(+ 2 'hello) +@end smallexample + +@noindent +When you do this you will generate an error message. What has happened +is that @code{+} has tried to add the 2 to the value returned by +@code{'hello}, but the value returned by @code{'hello} is the symbol +@code{hello}, not a number. Only numbers can be added. So @code{+} +could not carry out its addition. + +@need 1250 +In GNU Emacs version 22, you will create and enter a +@file{*Backtrace*} buffer that says: + +@noindent +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: + (wrong-type-argument number-or-marker-p hello) + +(2 hello) + eval((+ 2 (quote hello))) + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@need 1250 +As usual, the error message tries to be helpful and makes sense after you +learn how to read it.@footnote{@code{(quote hello)} is an expansion of +the abbreviation @code{'hello}.} + +The first part of the error message is straightforward; it says +@samp{wrong type argument}. Next comes the mysterious jargon word +@w{@samp{number-or-marker-p}}. This word is trying to tell you what +kind of argument the @code{+} expected. + +The symbol @code{number-or-marker-p} says that the Lisp interpreter is +trying to determine whether the information presented it (the value of +the argument) is a number or a marker (a special object representing a +buffer position). What it does is test to see whether the @code{+} is +being given numbers to add. It also tests to see whether the +argument is something called a marker, which is a specific feature of +Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. +When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, +its position is kept as a marker. The mark can be considered a +number---the number of characters the location is from the beginning +of the buffer.) In Emacs Lisp, @code{+} can be used to add the +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 +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 +whether it is true or false that the argument supplied is a number or +a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, +a function that tests whether its argument has the value of zero, and +@code{listp}, a function that tests whether its argument is a list. + +Finally, the last part of the error message is the symbol @code{hello}. +This is the value of the argument that was passed to @code{+}. If the +addition had been passed the correct type of object, the value passed +would have been a number, such as 37, rather than a symbol like +@code{hello}. But then you would not have got the error message. + +@ignore +@need 1250 +In GNU Emacs version 20 and before, the echo area displays an error +message that says: + +@smallexample +Wrong type argument:@: number-or-marker-p, hello +@end smallexample + +This says, in different words, the same as the top line of the +@file{*Backtrace*} buffer. +@end ignore + +@node message, , Wrong Type of Argument, Arguments +@comment node-name, next, previous, up +@subsection The @code{message} Function +@findex message + +Like @code{+}, the @code{message} function takes a variable number of +arguments. It is used to send messages to the user and is so useful +that we will describe it here. + +@need 1250 +A message is printed in the echo area. For example, you can print a +message in your echo area by evaluating the following list: + +@smallexample +(message "This message appears in the echo area!") +@end smallexample + +The whole string between double quotation marks is a single argument +and is printed @i{in toto}. (Note that in this example, the message +itself will appear in the echo area within double quotes; that is +because you see the value returned by the @code{message} function. In +most uses of @code{message} in programs that you write, the text will +be printed in the echo area as a side-effect, without the quotes. +@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in +detail}, for an example of this.) + +However, if there is a @samp{%s} in the quoted string of characters, the +@code{message} function does not print the @samp{%s} as such, but looks +to the argument that follows the string. It evaluates the second +argument and prints the value at the location in the string where the +@samp{%s} is. + +@need 1250 +You can see this by positioning the cursor after the following +expression and typing @kbd{C-x C-e}: + +@smallexample +(message "The name of this buffer is: %s." (buffer-name)) +@end smallexample + +@noindent +In Info, @code{"The name of this buffer is: *info*."} will appear in the +echo area. The function @code{buffer-name} returns the name of the +buffer as a string, which the @code{message} function inserts in place +of @code{%s}. + +To print a value as an integer, use @samp{%d} in the same way as +@samp{%s}. For example, to print a message in the echo area that +states the value of the @code{fill-column}, evaluate the following: + +@smallexample +(message "The value of fill-column is %d." fill-column) +@end smallexample + +@noindent +On my system, when I evaluate this list, @code{"The value of +fill-column is 72."} appears in my echo area@footnote{Actually, you +can use @code{%s} to print a number. It is non-specific. @code{%d} +prints only the part of a number left of a decimal point, and not +anything that is not a number.}. + +If there is more than one @samp{%s} in the quoted string, the value of +the first argument following the quoted string is printed at the +location of the first @samp{%s} and the value of the second argument is +printed at the location of the second @samp{%s}, and so on. + +@need 1250 +For example, if you evaluate the following, + +@smallexample +@group +(message "There are %d %s in the office!" + (- fill-column 14) "pink elephants") +@end group +@end smallexample + +@noindent +a rather whimsical message will appear in your echo area. On my system +it says, @code{"There are 58 pink elephants in the office!"}. + +The expression @code{(- fill-column 14)} is evaluated and the resulting +number is inserted in place of the @samp{%d}; and the string in double +quotes, @code{"pink elephants"}, is treated as a single argument and +inserted in place of the @samp{%s}. (That is to say, a string between +double quotes evaluates to itself, like a number.) + +Finally, here is a somewhat complex example that not only illustrates +the computation of a number, but also shows how you can use an +expression within an expression to generate the text that is substituted +for @samp{%s}: + +@smallexample +@group +(message "He saw %d %s" + (- fill-column 32) + (concat "red " + (substring + "The quick brown foxes jumped." 16 21) + " leaping.")) +@end group +@end smallexample + +In this example, @code{message} has three arguments: the string, +@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and +the expression beginning with the function @code{concat}. The value +resulting from the evaluation of @code{(- fill-column 32)} is inserted +in place of the @samp{%d}; and the value returned by the expression +beginning with @code{concat} is inserted in place of the @samp{%s}. + +When your fill column is 70 and you evaluate the expression, the +message @code{"He saw 38 red foxes leaping."} appears in your echo +area. + +@node set & setq, Summary, Arguments, List Processing +@comment node-name, next, previous, up +@section Setting the Value of a Variable +@cindex Variable, setting value +@cindex Setting value of variable + +@cindex @samp{bind} defined +There are several ways by which a variable can be given a value. One of +the ways is to use either the function @code{set} or the function +@code{setq}. Another way is to use @code{let} (@pxref{let}). (The +jargon for this process is to @dfn{bind} a variable to a value.) + +The following sections not only describe how @code{set} and @code{setq} +work but also illustrate how arguments are passed. + +@menu +* Using set:: Setting values. +* Using setq:: Setting a quoted value. +* Counting:: Using @code{setq} to count. +@end menu + +@node Using set, Using setq, set & setq, set & setq +@comment node-name, next, previous, up +@subsection Using @code{set} +@findex set + +To set the value of the symbol @code{flowers} to the list @code{'(rose +violet daisy buttercup)}, evaluate the following expression by +positioning the cursor after the expression and typing @kbd{C-x C-e}. + +@smallexample +(set 'flowers '(rose violet daisy buttercup)) +@end smallexample + +@noindent +The list @code{(rose violet daisy buttercup)} will appear in the echo +area. This is what is @emph{returned} by the @code{set} function. As a +side effect, the symbol @code{flowers} is bound to the list; that is, +the symbol @code{flowers}, which can be viewed as a variable, is given +the list as its value. (This process, by the way, illustrates how a +side effect to the Lisp interpreter, setting the value, can be the +primary effect that we humans are interested in. This is because every +Lisp function must return a value if it does not get an error, but it +will only have a side effect if it is designed to have one.) + +After evaluating the @code{set} expression, you can evaluate the symbol +@code{flowers} and it will return the value you just set. Here is the +symbol. Place your cursor after it and type @kbd{C-x C-e}. + +@smallexample +flowers +@end smallexample + +@noindent +When you evaluate @code{flowers}, the list +@code{(rose violet daisy buttercup)} appears in the echo area. + +Incidentally, if you evaluate @code{'flowers}, the variable with a quote +in front of it, what you will see in the echo area is the symbol itself, +@code{flowers}. Here is the quoted symbol, so you can try this: + +@smallexample +'flowers +@end smallexample + +Note also, that when you use @code{set}, you need to quote both +arguments to @code{set}, unless you want them evaluated. Since we do +not want either argument evaluated, neither the variable +@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both +are quoted. (When you use @code{set} without quoting its first +argument, the first argument is evaluated before anything else is +done. If you did this and @code{flowers} did not have a value +already, you would get an error message that the @samp{Symbol's value +as variable is void}; on the other hand, if @code{flowers} did return +a value after it was evaluated, the @code{set} would attempt to set +the value that was returned. There are situations where this is the +right thing for the function to do; but such situations are rare.) + +@node Using setq, Counting, Using set, set & setq +@comment node-name, next, previous, up +@subsection Using @code{setq} +@findex setq + +As a practical matter, you almost always quote the first argument to +@code{set}. The combination of @code{set} and a quoted first argument +is so common that it has its own name: the special form @code{setq}. +This special form is just like @code{set} except that the first argument +is quoted automatically, so you don't need to type the quote mark +yourself. Also, as an added convenience, @code{setq} permits you to set +several different variables to different values, all in one expression. + +To set the value of the variable @code{carnivores} to the list +@code{'(lion tiger leopard)} using @code{setq}, the following expression +is used: + +@smallexample +(setq carnivores '(lion tiger leopard)) +@end smallexample + +@noindent +This is exactly the same as using @code{set} except the first argument +is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} +means @code{quote}.) + +@need 1250 +With @code{set}, the expression would look like this: + +@smallexample +(set 'carnivores '(lion tiger leopard)) +@end smallexample + +Also, @code{setq} can be used to assign different values to +different variables. The first argument is bound to the value +of the second argument, the third argument is bound to the value of the +fourth argument, and so on. For example, you could use the following to +assign a list of trees to the symbol @code{trees} and a list of herbivores +to the symbol @code{herbivores}: + +@smallexample +@group +(setq trees '(pine fir oak maple) + herbivores '(gazelle antelope zebra)) +@end group +@end smallexample + +@noindent +(The expression could just as well have been on one line, but it might +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 +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 +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. + +@node Counting, , Using setq, set & setq +@comment node-name, next, previous, up +@subsection Counting +@cindex Counting + +Here is an example that shows how to use @code{setq} in a counter. You +might use this to count how many times a part of your program repeats +itself. First set a variable to zero; then add one to the number each +time the program repeats itself. To do this, you need a variable that +serves as a counter, and two expressions: an initial @code{setq} +expression that sets the counter variable to zero; and a second +@code{setq} expression that increments the counter each time it is +evaluated. + +@smallexample +@group +(setq counter 0) ; @r{Let's call this the initializer.} + +(setq counter (+ counter 1)) ; @r{This is the incrementer.} + +counter ; @r{This is the counter.} +@end group +@end smallexample + +@noindent +(The text following the @samp{;} are comments. @xref{Change a +defun, , Change a Function Definition}.) + +If you evaluate the first of these expressions, the initializer, +@code{(setq counter 0)}, and then evaluate the third expression, +@code{counter}, the number @code{0} will appear in the echo area. If +you then evaluate the second expression, the incrementer, @code{(setq +counter (+ counter 1))}, the counter will get the value 1. So if you +again evaluate @code{counter}, the number @code{1} will appear in the +echo area. Each time you evaluate the second expression, the value of +the counter will be incremented. + +When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, +the Lisp interpreter first evaluates the innermost list; this is the +addition. In order to evaluate this list, it must evaluate the variable +@code{counter} and the number @code{1}. When it evaluates the variable +@code{counter}, it receives its current value. It passes this value and +the number @code{1} to the @code{+} which adds them together. The sum +is then returned as the value of the inner list and passed to the +@code{setq} which sets the variable @code{counter} to this new value. +Thus, the value of the variable, @code{counter}, is changed. + +@node Summary, Error Message Exercises, set & setq, List Processing +@comment node-name, next, previous, up +@section Summary + +Learning Lisp is like climbing a hill in which the first part is the +steepest. You have now climbed the most difficult part; what remains +becomes easier as you progress onwards. + +@need 1000 +In summary, + +@itemize @bullet + +@item +Lisp programs are made up of expressions, which are lists or single atoms. + +@item +Lists are made up of zero or more atoms or inner lists, separated by whitespace and +surrounded by parentheses. A list can be empty. + +@item +Atoms are multi-character symbols, like @code{forward-paragraph}, single +character symbols like @code{+}, strings of characters between double +quotation marks, or numbers. + +@item +A number evaluates to itself. + +@item +A string between double quotes also evaluates to itself. + +@item +When you evaluate a symbol by itself, its value is returned. + +@item +When you evaluate a list, the Lisp interpreter looks at the first symbol +in the list and then at the function definition bound to that symbol. +Then the instructions in the function definition are carried out. + +@item +A single quotation mark, +@ifinfo +' +@end ifinfo +@ifnotinfo +@code{'} +@end ifnotinfo +, tells the Lisp interpreter that it should +return the following expression as written, and not evaluate it as it +would if the quote were not there. + +@item +Arguments are the information passed to a function. The arguments to a +function are computed by evaluating the rest of the elements of the list +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 +create a side effect. +@end itemize + +@node Error Message Exercises, , Summary, List Processing +@comment node-name, next, previous, up +@section Exercises + +A few simple exercises: + +@itemize @bullet +@item +Generate an error message by evaluating an appropriate symbol that is +not within parentheses. + +@item +Generate an error message by evaluating an appropriate symbol that is +between parentheses. + +@item +Create a counter that increments by two rather than one. + +@item +Write an expression that prints a message in the echo area when +evaluated. +@end itemize + +@node Practicing Evaluation, Writing Defuns, List Processing, Top +@comment node-name, next, previous, up +@chapter Practicing Evaluation +@cindex Practicing evaluation +@cindex Evaluation practice + +Before learning how to write a function definition in Emacs Lisp, it is +useful to spend a little time evaluating various expressions that have +already been written. These expressions will be lists with the +functions as their first (and often only) element. Since some of the +functions associated with buffers are both simple and interesting, we +will start with those. In this section, we will evaluate a few of +these. In another section, we will study the code of several other +buffer-related functions, to see how they were written. + +@menu +* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} + causes evaluation. +* Buffer Names:: Buffers and files are different. +* Getting Buffers:: Getting a buffer itself, not merely its name. +* Switching Buffers:: How to change to another buffer. +* Buffer Size & Locations:: Where point is located and the size of + the buffer. +* Evaluation Exercise:: +@end menu + +@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation +@ifnottex +@unnumberedsec How to Evaluate +@end ifnottex + +@i{Whenever you give an editing command} to Emacs Lisp, such as the +command to move the cursor or to scroll the screen, @i{you are evaluating +an expression,} the first element of which is a function. @i{This is +how Emacs works.} + +@cindex @samp{interactive function} defined +@cindex @samp{command} defined +When you type keys, you cause the Lisp interpreter to evaluate an +expression and that is how you get your results. Even typing plain text +involves evaluating an Emacs Lisp function, in this case, one that uses +@code{self-insert-command}, which simply inserts the character you +typed. The functions you evaluate by typing keystrokes are called +@dfn{interactive} functions, or @dfn{commands}; how you make a function +interactive will be illustrated in the chapter on how to write function +definitions. @xref{Interactive, , Making a Function Interactive}. + +In addition to typing keyboard commands, we have seen a second way to +evaluate an expression: by positioning the cursor after a list and +typing @kbd{C-x C-e}. This is what we will do in the rest of this +section. There are other ways to evaluate an expression as well; these +will be described as we come to them. + +Besides being used for practicing evaluation, the functions shown in the +next few sections are important in their own right. A study of these +functions makes clear the distinction between buffers and files, how to +switch to a buffer, and how to determine a location within it. + +@node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation +@comment node-name, next, previous, up +@section Buffer Names +@findex buffer-name +@findex buffer-file-name + +The two functions, @code{buffer-name} and @code{buffer-file-name}, show +the difference between a file and a buffer. When you evaluate the +following expression, @code{(buffer-name)}, the name of the buffer +appears in the echo area. When you evaluate @code{(buffer-file-name)}, +the name of the file to which the buffer refers appears in the echo +area. Usually, the name returned by @code{(buffer-name)} is the same as +the name of the file to which it refers, and the name returned by +@code{(buffer-file-name)} is the full path-name of the file. + +A file and a buffer are two different entities. A file is information +recorded permanently in the computer (unless you delete it). A buffer, +on the other hand, is information inside of Emacs that will vanish at +the end of the editing session (or when you kill the buffer). Usually, +a buffer contains information that you have copied from a file; we say +the buffer is @dfn{visiting} that file. This copy is what you work on +and modify. Changes to the buffer do not change the file, until you +save the buffer. When you save the buffer, the buffer is copied to the file +and is thus saved permanently. + +@need 1250 +If you are reading this in Info inside of GNU Emacs, you can evaluate +each of the following expressions by positioning the cursor after it and +typing @kbd{C-x C-e}. + +@example +@group +(buffer-name) + +(buffer-file-name) +@end group +@end example + +@noindent +When I do this in Info, the value returned by evaluating +@code{(buffer-name)} is @file{"*info*"}, and the value returned by +evaluating @code{(buffer-file-name)} is @file{nil}. + +On the other hand, while I am writing this Introduction, the value +returned by evaluating @code{(buffer-name)} is +@file{"introduction.texinfo"}, and the value returned by evaluating +@code{(buffer-file-name)} is +@file{"/gnu/work/intro/introduction.texinfo"}. + +@cindex @code{nil}, history of word +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 +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{()}.) + +When I am writing, the name of my buffer is +@file{"introduction.texinfo"}. The name of the file to which it +points is @file{"/gnu/work/intro/introduction.texinfo"}. + +(In the expressions, the parentheses tell the Lisp interpreter to +treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as +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. +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 +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 +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 +central processing unit were pieces of equipment that were very +different from each other, working at their own speeds, in spurts. The +buffer made it possible for them to work together effectively. +Eventually, the buffer grew from being an intermediary, a temporary +holding place, to being the place where work is done. This +transformation is rather like that of a small seaport that grew into a +great city: once it was merely the place where cargo was warehoused +temporarily before being loaded onto ships; then it became a business +and cultural center in its own right. + +Not all buffers are associated with files. For example, a +@file{*scratch*} buffer does not visit any file. Similarly, a +@file{*Help*} buffer is not associated with any file. + +In the old days, when you lacked a @file{~/.emacs} file and started an +Emacs session by typing the command @code{emacs} alone, without naming +any files, Emacs started with the @file{*scratch*} buffer visible. +Nowadays, you will see a splash screen. You can follow one of the +commands suggested on the splash screen, visit a file, or press the +spacebar to reach the @file{*scratch*} buffer. + +If you switch to the @file{*scratch*} buffer, type +@code{(buffer-name)}, position the cursor after it, and then type +@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} +will be returned and will appear in the echo area. @code{"*scratch*"} +is the name of the buffer. When you type @code{(buffer-file-name)} in +the @file{*scratch*} buffer and evaluate that, @code{nil} will appear +in the echo area, just as it does when you evaluate +@code{(buffer-file-name)} in Info. + +Incidentally, if you are in the @file{*scratch*} buffer and want the +value returned by an expression to appear in the @file{*scratch*} +buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} +instead of @kbd{C-x C-e}. This causes the value returned to appear +after the expression. The buffer will look like this: + +@smallexample +(buffer-name)"*scratch*" +@end smallexample + +@noindent +You cannot do this in Info since Info is read-only and it will not allow +you to change the contents of the buffer. But you can do this in any +buffer you can edit; and when you write code or documentation (such as +this book), this feature is very useful. + +@node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation +@comment node-name, next, previous, up +@section Getting Buffers +@findex current-buffer +@findex other-buffer +@cindex Getting a buffer + +The @code{buffer-name} function returns the @emph{name} of the buffer; +to get the buffer @emph{itself}, a different function is needed: the +@code{current-buffer} function. If you use this function in code, what +you get is the buffer itself. + +A name and the object or entity to which the name refers are different +from each other. You are not your name. You are a person to whom +others refer by name. If you ask to speak to George and someone hands you +a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, +@samp{g}, and @samp{e} written on it, you might be amused, but you would +not be satisfied. You do not want to speak to the name, but to the +person to whom the name refers. A buffer is similar: the name of the +scratch buffer is @file{*scratch*}, but the name is not the buffer. To +get a buffer itself, you need to use a function such as +@code{current-buffer}. + +However, there is a slight complication: if you evaluate +@code{current-buffer} in an expression on its own, as we will do here, +what you see is a printed representation of the name of the buffer +without the contents of the buffer. Emacs works this way for two +reasons: the buffer may be thousands of lines long---too long to be +conveniently displayed; and, another buffer may have the same contents +but a different name, and it is important to distinguish between them. + +@need 800 +Here is an expression containing the function: + +@smallexample +(current-buffer) +@end smallexample + +@noindent +If you evaluate this expression in Info in Emacs in the usual way, +@file{#<buffer *info*>} will appear in the echo area. The special +format indicates that the buffer itself is being returned, rather than +just its name. + +Incidentally, while you can type a number or symbol into a program, you +cannot do that with the printed representation of a buffer: the only way +to get a buffer itself is with a function such as @code{current-buffer}. + +A related function is @code{other-buffer}. This returns the most +recently selected buffer other than the one you are in currently, not +a printed representation of its name. If you have recently switched +back and forth from the @file{*scratch*} buffer, @code{other-buffer} +will return that buffer. + +@need 800 +You can see this by evaluating the expression: + +@smallexample +(other-buffer) +@end smallexample + +@noindent +You should see @file{#<buffer *scratch*>} appear in the echo area, or +the name of whatever other buffer you switched back from most +recently@footnote{Actually, by default, if the buffer from which you +just switched is visible to you in another window, @code{other-buffer} +will choose the most recent buffer that you cannot see; this is a +subtlety that I often forget.}. + +@node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation +@comment node-name, next, previous, up +@section Switching Buffers +@findex switch-to-buffer +@findex set-buffer +@cindex Switching to a buffer + +The @code{other-buffer} function actually provides a buffer when it is +used as an argument to a function that requires one. We can see this +by using @code{other-buffer} and @code{switch-to-buffer} to switch to a +different buffer. + +But first, a brief introduction to the @code{switch-to-buffer} +function. When you switched back and forth from Info to the +@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most +likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or +rather, to save typing, you probably only typed @kbd{RET} if the +default buffer was @file{*scratch*}, or if it was different, then you +typed just part of the name, such as @code{*sc}, pressed your +@kbd{TAB} key to cause it to expand to the full name, and then typed +your @kbd{RET} key.} when prompted in the minibuffer for the name of +the buffer to which you wanted to switch. The keystrokes, @kbd{C-x +b}, cause the Lisp interpreter to evaluate the interactive function +@code{switch-to-buffer}. As we said before, this is how Emacs works: +different keystrokes call or run different functions. For example, +@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls +@code{forward-sentence}, and so on. + +By writing @code{switch-to-buffer} in an expression, and giving it a +buffer to switch to, we can switch buffers just the way @kbd{C-x b} +does. + +@need 1000 +Here is the Lisp expression: + +@smallexample +(switch-to-buffer (other-buffer)) +@end smallexample + +@noindent +The symbol @code{switch-to-buffer} is the first element of the list, +so the Lisp interpreter will treat it as a function and carry out the +instructions that are attached to it. But before doing that, the +interpreter will note that @code{other-buffer} is inside parentheses +and work on that symbol first. @code{other-buffer} is the first (and +in this case, the only) element of this list, so the Lisp interpreter +calls or runs the function. It returns another buffer. Next, the +interpreter runs @code{switch-to-buffer}, passing to it, as an +argument, the other buffer, which is what Emacs will switch to. If +you are reading this in Info, try this now. Evaluate the expression. +(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this +expression will move you to your most recent other buffer that you +cannot see. If you really want to go to your most recently selected +buffer, even if you can still see it, you need to evaluate the +following more complex expression: + +@smallexample +(switch-to-buffer (other-buffer (current-buffer) t)) +@end smallexample + +@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.} + +In the programming examples in later sections of this document, you will +see the function @code{set-buffer} more often than +@code{switch-to-buffer}. This is because of a difference between +computer programs and humans: humans have eyes and expect to see the +buffer on which they are working on their computer terminals. This is +so obvious, it almost goes without saying. However, programs do not +have eyes. When a computer program works on a buffer, that buffer does +not need to be visible on the screen. + +@code{switch-to-buffer} is designed for humans and does two different +things: it switches the buffer to which Emacs' attention is directed; and +it switches the buffer displayed in the window to the new buffer. +@code{set-buffer}, on the other hand, does only one thing: it switches +the attention of the computer program to a different buffer. The buffer +on the screen remains unchanged (of course, normally nothing happens +there until the command finishes running). + +@cindex @samp{call} defined +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' +it---just as a plumber is an entity who can fix a leak if you call him +or her. + +@node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation +@comment node-name, next, previous, up +@section Buffer Size and the Location of Point +@cindex Size of buffer +@cindex Buffer size +@cindex Point location +@cindex Location of point + +Finally, let's look at several rather simple functions, +@code{buffer-size}, @code{point}, @code{point-min}, and +@code{point-max}. These give information about the size of a buffer and +the location of point within it. + +The function @code{buffer-size} tells you the size of the current +buffer; that is, the function returns a count of the number of +characters in the buffer. + +@smallexample +(buffer-size) +@end smallexample + +@noindent +You can evaluate this in the usual way, by positioning the +cursor after the expression and typing @kbd{C-x C-e}. + +@cindex @samp{point} defined +In Emacs, the current position of the cursor is called @dfn{point}. +The expression @code{(point)} returns a number that tells you where the +cursor is located as a count of the number of characters from the +beginning of the buffer up to point. + +@need 1250 +You can see the character count for point in this buffer by evaluating +the following expression in the usual way: + +@smallexample +(point) +@end smallexample + +@noindent +As I write this, the value of @code{point} is 65724. The @code{point} +function is frequently used in some of the examples later in this +book. + +@need 1250 +The value of point depends, of course, on its location within the +buffer. If you evaluate point in this spot, the number will be larger: + +@smallexample +(point) +@end smallexample + +@noindent +For me, the value of point in this location is 66043, which means that +there are 319 characters (including spaces) between the two +expressions. (Doubtless, you will see different numbers, since I will +have edited this since I first evaluated point.) + +@cindex @samp{narrowing} defined +The function @code{point-min} is somewhat similar to @code{point}, but +it returns the value of the minimum permissible value of point in the +current buffer. This is the number 1 unless @dfn{narrowing} is in +effect. (Narrowing is a mechanism whereby you can restrict yourself, +or a program, to operations on just a part of a buffer. +@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the +function @code{point-max} returns the value of the maximum permissible +value of point in the current buffer. + +@node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation +@section Exercise + +Find a file with which you are working and move towards its middle. +Find its buffer name, file name, length, and your position in the file. + +@node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top +@comment node-name, next, previous, up +@chapter How To Write Function Definitions +@cindex Definition writing +@cindex Function definition writing +@cindex Writing a function definition + +When the Lisp interpreter evaluates a list, it looks to see whether the +first symbol on the list has a function definition attached to it; or, +put another way, whether the symbol points to a function definition. If +it does, the computer carries out the instructions in the definition. A +symbol that has a function definition is called, simply, a function +(although, properly speaking, the definition is the function and the +symbol refers to it.) + +@menu +* Primitive Functions:: +* defun:: The @code{defun} special form. +* Install:: Install a function definition. +* Interactive:: Making a function interactive. +* Interactive Options:: Different options for @code{interactive}. +* Permanent Installation:: Installing code permanently. +* let:: Creating and initializing local variables. +* 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. +* Review:: +* defun Exercises:: +@end menu + +@node Primitive Functions, defun, Writing Defuns, Writing Defuns +@ifnottex +@unnumberedsec An Aside about Primitive Functions +@end ifnottex +@cindex Primitive functions +@cindex Functions, primitive + +@cindex C language primitives +@cindex Primitives written in C +All functions are defined in terms of other functions, except for a few +@dfn{primitive} functions that are written in the C programming +language. When you write functions' definitions, you will write them in +Emacs Lisp and use other functions as your building blocks. Some of the +functions you will use will themselves be written in Emacs Lisp (perhaps +by you) and some will be primitives written in C. The primitive +functions are used exactly like those written in Emacs Lisp and behave +like them. They are written in C so we can easily run GNU Emacs on any +computer that has sufficient power and can run C. + +Let me re-emphasize this: when you write code in Emacs Lisp, you do not +distinguish between the use of functions written in C and the use of +functions written in Emacs Lisp. The difference is irrelevant. I +mention the distinction only because it is interesting to know. Indeed, +unless you investigate, you won't know whether an already-written +function is written in Emacs Lisp or C. + +@node defun, Install, Primitive Functions, Writing Defuns +@comment node-name, next, previous, up +@section The @code{defun} Special Form +@findex defun +@cindex Special form of @code{defun} + +@cindex @samp{function definition} defined +In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to +it that tells the computer what to do when the function is called. +This code is called the @dfn{function definition} and is created by +evaluating a Lisp expression that starts with the symbol @code{defun} +(which is an abbreviation for @emph{define function}). Because +@code{defun} does not evaluate its arguments in the usual way, it is +called a @dfn{special form}. + +In subsequent sections, we will look at function definitions from the +Emacs source code, such as @code{mark-whole-buffer}. In this section, +we will describe a simple function definition so you can see how it +looks. This function definition uses arithmetic because it makes for a +simple example. Some people dislike examples using arithmetic; however, +if you are such a person, do not despair. Hardly any of the code we +will study in the remainder of this introduction involves arithmetic or +mathematics. The examples mostly involve text in one way or another. + +A function definition has up to five parts following the word +@code{defun}: + +@enumerate +@item +The name of the symbol to which the function definition should be +attached. + +@item +A list of the arguments that will be passed to the function. If no +arguments will be passed to the function, this is an empty list, +@code{()}. + +@item +Documentation describing the function. (Technically optional, but +strongly recommended.) + +@item +Optionally, an expression to make the function interactive so you can +use it by typing @kbd{M-x} and then the name of the function; or by +typing an appropriate key or keychord. + +@cindex @samp{body} defined +@item +The code that instructs the computer what to do: the @dfn{body} of the +function definition. +@end enumerate + +It is helpful to think of the five parts of a function definition as +being organized in a template, with slots for each part: + +@smallexample +@group +(defun @var{function-name} (@var{arguments}@dots{}) + "@var{optional-documentation}@dots{}" + (interactive @var{argument-passing-info}) ; @r{optional} + @var{body}@dots{}) +@end group +@end smallexample + +As an example, here is the code for a function that multiplies its +argument by 7. (This example is not interactive. @xref{Interactive, +, Making a Function Interactive}, for that information.) + +@smallexample +@group +(defun multiply-by-seven (number) + "Multiply NUMBER by seven." + (* 7 number)) +@end group +@end smallexample + +This definition begins with a parenthesis and the symbol @code{defun}, +followed by the name of the function. + +@cindex @samp{argument list} defined +The name of the function is followed by a list that contains the +arguments that will be passed to the function. This list is called +the @dfn{argument list}. In this example, the list has only one +element, the symbol, @code{number}. When the function is used, the +symbol will be bound to the value that is used as the argument to the +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 +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 +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 +name is up to the programmer and should be chosen to make the meaning of +the function clear. + +Indeed, you can choose any name you wish for a symbol in an argument +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 +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 +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 +that within the function, it is a variable who value is the number in +question, but our primary interest in it is as a symbol. On the other +hand, when we are talking about the function, our interest is that we +will substitute a number for the word @var{number}. To keep this +distinction clear, we use different typography for the two +circumstances. When we talk about this function, or about how it works, +we refer to this number by writing @var{number}. In the function +itself, we refer to it by writing @code{number}. +@end ignore + +The argument list is followed by the documentation string that +describes the function. This is what you see when you type +@w{@kbd{C-h f}} and the name of a function. Incidentally, when you +write a documentation string like this, you should make the first line +a complete sentence since some commands, such as @code{apropos}, print +only the first line of a multi-line documentation string. Also, you +should not indent the second line of a documentation string, if you +have one, because that looks odd when you use @kbd{C-h f} +(@code{describe-function}). The documentation string is optional, but +it is so useful, it should be included in almost every function you +write. + +@findex * @r{(multiplication)} +The third line of the example consists of the body of the function +definition. (Most functions' definitions, of course, are longer than +this.) In this function, the body is the list, @code{(* 7 number)}, which +says to multiply the value of @var{number} by 7. (In Emacs Lisp, +@code{*} is the function for multiplication, just as @code{+} is the +function for addition.) + +When you use the @code{multiply-by-seven} function, the argument +@code{number} evaluates to the actual number you want used. Here is an +example that shows how @code{multiply-by-seven} is used; but don't try +to evaluate this yet! + +@smallexample +(multiply-by-seven 3) +@end smallexample + +@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 +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 +parentheses are written in the function definition so the computer can +figure out where the argument list ends and the rest of the function +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. +Installing a function is the process that tells the Lisp interpreter the +definition of the function. Installation is described in the next +section. + +@node Install, Interactive, defun, Writing Defuns +@comment node-name, next, previous, up +@section Install a Function Definition +@cindex Install a Function Definition +@cindex Definition installation +@cindex Function definition installation + +If you are reading this inside of Info in Emacs, you can try out the +@code{multiply-by-seven} function by first evaluating the function +definition and then evaluating @code{(multiply-by-seven 3)}. A copy of +the function definition follows. Place the cursor after the last +parenthesis of the function definition and type @kbd{C-x C-e}. When you +do this, @code{multiply-by-seven} will appear in the echo area. (What +this means is that when a function definition is evaluated, the value it +returns is the name of the defined function.) At the same time, this +action installs the function definition. + +@smallexample +@group +(defun multiply-by-seven (number) + "Multiply NUMBER by seven." + (* 7 number)) +@end group +@end smallexample + +@noindent +By evaluating this @code{defun}, you have just installed +@code{multiply-by-seven} in Emacs. The function is now just as much a +part of Emacs as @code{forward-word} or any other editing function you +use. (@code{multiply-by-seven} will stay installed until you quit +Emacs. To reload code automatically whenever you start Emacs, see +@ref{Permanent Installation, , Installing Code Permanently}.) + +@menu +* Effect of installation:: +* Change a defun:: How to change a function definition. +@end menu + +@node Effect of installation, Change a defun, Install, Install +@ifnottex +@unnumberedsubsec The effect of installation +@end ifnottex + +You can see the effect of installing @code{multiply-by-seven} by +evaluating the following sample. Place the cursor after the following +expression and type @kbd{C-x C-e}. The number 21 will appear in the +echo area. + +@smallexample +(multiply-by-seven 3) +@end smallexample + +If you wish, you can read the documentation for the function by typing +@kbd{C-h f} (@code{describe-function}) and then the name of the +function, @code{multiply-by-seven}. When you do this, a +@file{*Help*} window will appear on your screen that says: + +@smallexample +@group +multiply-by-seven is a Lisp function. +(multiply-by-seven NUMBER) + +Multiply NUMBER by seven. +@end group +@end smallexample + +@noindent +(To return to a single window on your screen, type @kbd{C-x 1}.) + +@node Change a defun, , Effect of installation, Install +@comment node-name, next, previous, up +@subsection Change a Function Definition +@cindex Changing a function definition +@cindex Function definition, how to change +@cindex Definition, how to change + +If you want to change the code in @code{multiply-by-seven}, just rewrite +it. To install the new version in place of the old one, evaluate the +function definition again. This is how you modify code in Emacs. It is +very simple. + +As an example, you can change the @code{multiply-by-seven} function to +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''. + +@smallexample +@group +(defun multiply-by-seven (number) ; @r{Second version.} + "Multiply NUMBER by seven." + (+ number number number number number number number)) +@end group +@end smallexample + +@cindex Comments in Lisp code +The comment follows a semicolon, @samp{;}. In Lisp, everything on a +line that follows a semicolon is a comment. The end of the line is the +end of the comment. To stretch a comment over two or more lines, begin +each line with a semicolon. + +@xref{Beginning a .emacs File, , Beginning a @file{.emacs} +File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp +Reference Manual}, for more about comments. + +You can install this version of the @code{multiply-by-seven} function by +evaluating it in the same way you evaluated the first function: place +the cursor after the last parenthesis and type @kbd{C-x C-e}. + +In summary, this is how you write code in Emacs Lisp: you write a +function; install it; test it; and then make fixes or enhancements and +install it again. + +@node Interactive, Interactive Options, Install, Writing Defuns +@comment node-name, next, previous, up +@section Make a Function Interactive +@cindex Interactive functions +@findex interactive + +You make a function interactive by placing a list that begins with +the special form @code{interactive} immediately after the +documentation. A user can invoke an interactive function by typing +@kbd{M-x} and then the name of the function; or by typing the keys to +which it is bound, for example, by typing @kbd{C-n} for +@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. + +Interestingly, when you call an interactive function interactively, +the value returned is not automatically displayed in the echo area. +This is because you often call an interactive function for its side +effects, such as moving forward by a word or line, and not for the +value returned. If the returned value were displayed in the echo area +each time you typed a key, it would be very distracting. + +@menu +* Interactive multiply-by-seven:: An overview. +* multiply-by-seven in detail:: The interactive version. +@end menu + +@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive +@ifnottex +@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview +@end ifnottex + +Both the use of the special form @code{interactive} and one way to +display a value in the echo area can be illustrated by creating an +interactive version of @code{multiply-by-seven}. + +@need 1250 +Here is the code: + +@smallexample +@group +(defun multiply-by-seven (number) ; @r{Interactive version.} + "Multiply NUMBER by seven." + (interactive "p") + (message "The result is %d" (* 7 number))) +@end group +@end smallexample + +@noindent +You can install this code by placing your cursor after it and typing +@kbd{C-x C-e}. The name of the function will appear in your echo area. +Then, you can use this code by typing @kbd{C-u} and a number and then +typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase +@samp{The result is @dots{}} followed by the product will appear in the +echo area. + +Speaking more generally, you invoke a function like this in either of two +ways: + +@enumerate +@item +By typing a prefix argument that contains the number to be passed, and +then typing @kbd{M-x} and the name of the function, as with +@kbd{C-u 3 M-x forward-sentence}; or, + +@item +By typing whatever key or keychord the function is bound to, as with +@kbd{C-u 3 M-e}. +@end enumerate + +@noindent +Both the examples just mentioned work identically to move point forward +three sentences. (Since @code{multiply-by-seven} is not bound to a key, +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 +@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). + +@node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive +@comment node-name, next, previous, up +@subsection An Interactive @code{multiply-by-seven} + +Let's look at the use of the special form @code{interactive} and then at +the function @code{message} in the interactive version of +@code{multiply-by-seven}. You will recall that the function definition +looks like this: + +@smallexample +@group +(defun multiply-by-seven (number) ; @r{Interactive version.} + "Multiply NUMBER by seven." + (interactive "p") + (message "The result is %d" (* 7 number))) +@end group +@end smallexample + +In this function, the expression, @code{(interactive "p")}, is a list of +two elements. The @code{"p"} tells Emacs to pass the prefix argument to +the function and use its value for the argument of the function. + +@need 1000 +The argument will be a number. This means that the symbol +@code{number} will be bound to a number in the line: + +@smallexample +(message "The result is %d" (* 7 number)) +@end smallexample + +@need 1250 +@noindent +For example, if your prefix argument is 5, the Lisp interpreter will +evaluate the line as if it were: + +@smallexample +(message "The result is %d" (* 7 5)) +@end smallexample + +@noindent +(If you are reading this in GNU Emacs, you can evaluate this expression +yourself.) First, the interpreter will evaluate the inner list, which +is @code{(* 7 5)}. This returns a value of 35. Next, it +will evaluate the outer list, passing the values of the second and +subsequent elements of the list to the function @code{message}. + +As we have seen, @code{message} is an Emacs Lisp function especially +designed for sending a one line message to a user. (@xref{message, , +The @code{message} function}.) In summary, the @code{message} +function prints its first argument in the echo area as is, except for +occurrences of @samp{%d} or @samp{%s} (and various other %-sequences +which we have not mentioned). When it sees a control sequence, the +function looks to the second or subsequent arguments and prints the +value of the argument in the location in the string where the control +sequence is located. + +In the interactive @code{multiply-by-seven} function, the control string +is @samp{%d}, which requires a number, and the value returned by +evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 +is printed in place of the @samp{%d} and the message is @samp{The result +is 35}. + +(Note that when you call the function @code{multiply-by-seven}, the +message is printed without quotes, but when you call @code{message}, the +text is printed in double quotes. This is because the value returned by +@code{message} is what appears in the echo area when you evaluate an +expression whose first element is @code{message}; but when embedded in a +function, @code{message} prints the text as a side effect without +quotes.) + +@node Interactive Options, Permanent Installation, Interactive, Writing Defuns +@comment node-name, next, previous, up +@section Different Options for @code{interactive} +@cindex Options for @code{interactive} +@cindex Interactive options + +In the example, @code{multiply-by-seven} used @code{"p"} as the +argument to @code{interactive}. This argument told Emacs to interpret +your typing either @kbd{C-u} followed by a number or @key{META} +followed by a number as a command to pass that number to the function +as its argument. Emacs has more than twenty characters predefined for +use with @code{interactive}. In almost every case, one of these +options will enable you to pass the right information interactively to +a function. (@xref{Interactive Codes, , Code Characters for +@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) + +@need 1250 +Consider the function @code{zap-to-char}. Its interactive expression +is + +@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 +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 +specified character is @samp{x}, then you will delete all the text up +to and including the third next @samp{x}. If you do not set a prefix, +then you delete all the text up to and including the specified +character, but no more. + +The @samp{c} tells the function the name of the character to which to delete. + +More formally, a function with two or more arguments can have +information passed to each argument by adding parts to the string that +follows @code{interactive}. When you do this, the information is +passed to each argument in the same order it is specified in the +@code{interactive} list. In the string, each part is separated from +the next part by a @samp{\n}, which is a newline. For example, you +can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. +This causes Emacs to pass the value of the prefix argument (if there +is one) and the character. + +In this case, the function definition looks like the following, where +@code{arg} and @code{char} are the symbols to which @code{interactive} +binds the prefix argument and the specified character: + +@smallexample +@group +(defun @var{name-of-function} (arg char) + "@var{documentation}@dots{}" + (interactive "p\ncZap to char: ") + @var{body-of-function}@dots{}) +@end group +@end smallexample + +@noindent +(The space after the colon in the prompt makes it look better when you +are prompted. @xref{copy-to-buffer, , The Definition of +@code{copy-to-buffer}}, for an example.) + +When a function does not take arguments, @code{interactive} does not +require any. Such a function contains the simple expression +@code{(interactive)}. The @code{mark-whole-buffer} function is like +this. + +Alternatively, if the special letter-codes are not right for your +application, you can pass your own arguments to @code{interactive} as +a list. + +@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, +for an example. @xref{Using Interactive, , Using @code{Interactive}, +elisp, The GNU Emacs Lisp Reference Manual}, for a more complete +explanation about this technique. + +@node Permanent Installation, let, Interactive Options, Writing Defuns +@comment node-name, next, previous, up +@section Install Code Permanently +@cindex Install code permanently +@cindex Permanent code installation +@cindex Code installation + +When you install a function definition by evaluating it, it will stay +installed until you quit Emacs. The next time you start a new session +of Emacs, the function will not be installed unless you evaluate the +function definition again. + +At some point, you may want to have code installed automatically +whenever you start a new session of Emacs. There are several ways of +doing this: + +@itemize @bullet +@item +If you have code that is just for yourself, you can put the code for the +function definition in your @file{.emacs} initialization file. When you +start Emacs, your @file{.emacs} file is automatically evaluated and all +the function definitions within it are installed. +@xref{Emacs Initialization, , Your @file{.emacs} File}. + +@item +Alternatively, you can put the function definitions that you want +installed in one or more files of their own and use the @code{load} +function to cause Emacs to evaluate and thereby install each of the +functions in the files. +@xref{Loading Files, , Loading Files}. + +@item +Thirdly, if you have code that your whole site will use, it is usual +to put it in a file called @file{site-init.el} that is loaded when +Emacs is built. This makes the code available to everyone who uses +your machine. (See the @file{INSTALL} file that is part of the Emacs +distribution.) +@end itemize + +Finally, if you have code that everyone who uses Emacs may want, you +can post it on a computer network or send a copy to the Free Software +Foundation. (When you do this, please license the code and its +documentation under a license that permits other people to run, copy, +study, modify, and redistribute the code and which protects you from +having your work taken from you.) If you send a copy of your code to +the Free Software Foundation, and properly protect yourself and +others, it may be included in the next release of Emacs. In large +part, this is how Emacs has grown over the past years, by donations. + +@node let, if, Permanent Installation, Writing Defuns +@comment node-name, next, previous, up +@section @code{let} +@findex let + +The @code{let} expression is a special form in Lisp that you will need +to use in most function definitions. + +@code{let} is used to attach or bind a symbol to a value in such a way +that the Lisp interpreter will not confuse the variable with a +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 +likely to be referring to @emph{his} house, not yours, that is, to a +different house. + +If your friend is referring to his house and you think he is referring +to your house, you may be in for some confusion. The same thing could +happen in Lisp if a variable that is used inside of one function has +the same name as a variable that is used inside of another function, +and the two are not intended to refer to the same value. The +@code{let} special form prevents this kind of confusion. + +@menu +* Prevent confusion:: +* Parts of let Expression:: +* Sample let Expression:: +* Uninitialized let Variables:: +@end menu + +@node Prevent confusion, Parts of let Expression, let, let +@ifnottex +@unnumberedsubsec @code{let} Prevents Confusion +@end ifnottex + +@cindex @samp{local variable} defined +@cindex @samp{variable, local}, defined +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 +yours. (Symbols used in argument lists work the same way. +@xref{defun, , The @code{defun} Special Form}.) + +Local variables created by a @code{let} expression retain their value +@emph{only} within the @code{let} expression itself (and within +expressions called within the @code{let} expression); the local +variables have no effect outside the @code{let} expression. + +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 +a symbol is visible only in functions called in the @code{let} form; +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 +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 +term that means to evaluate a list; it comes from the use of the word +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'.) + +@node Parts of let Expression, Sample let Expression, Prevent confusion, let +@comment node-name, next, previous, up +@subsection The Parts of a @code{let} Expression +@cindex @code{let} expression, parts of +@cindex Parts of @code{let} expression + +@cindex @samp{varlist} defined +A @code{let} expression is a list of three parts. The first part is +the symbol @code{let}. The second part is a list, called a +@dfn{varlist}, each element of which is either a symbol by itself or a +two-element list, the first element of which is a symbol. The third +part of the @code{let} expression is the body of the @code{let}. The +body usually consists of one or more lists. + +@need 800 +A template for a @code{let} expression looks like this: + +@smallexample +(let @var{varlist} @var{body}@dots{}) +@end smallexample + +@noindent +The symbols in the varlist are the variables that are given initial +values by the @code{let} special form. Symbols by themselves are given +the initial value of @code{nil}; and each symbol that is the first +element of a two-element list is bound to the value that is returned +when the Lisp interpreter evaluates the second element. + +Thus, a varlist might look like this: @code{(thread (needles 3))}. In +this case, in a @code{let} expression, Emacs binds the symbol +@code{thread} to an initial value of @code{nil}, and binds the symbol +@code{needles} to an initial value of 3. + +When you write a @code{let} expression, what you do is put the +appropriate expressions in the slots of the @code{let} expression +template. + +If the varlist is composed of two-element lists, as is often the case, +the template for the @code{let} expression looks like this: + +@smallexample +@group +(let ((@var{variable} @var{value}) + (@var{variable} @var{value}) + @dots{}) + @var{body}@dots{}) +@end group +@end smallexample + +@node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let +@comment node-name, next, previous, up +@subsection Sample @code{let} Expression +@cindex Sample @code{let} expression +@cindex @code{let} expression sample + +The following expression creates and gives initial values +to the two variables @code{zebra} and @code{tiger}. The body of the +@code{let} expression is a list which calls the @code{message} function. + +@smallexample +@group +(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))}. + +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 +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} +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. + +@need 1500 +You may evaluate the example in the usual fashion, by placing the +cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do +this, the following will appear in the echo area: + +@smallexample +"One kind of animal has stripes and another is fierce." +@end smallexample + +As we have seen before, the @code{message} function prints its first +argument, except for @samp{%s}. In this example, the value of the variable +@code{zebra} is printed at the location of the first @samp{%s} and the +value of the variable @code{tiger} is printed at the location of the +second @samp{%s}. + +@node Uninitialized let Variables, , Sample let Expression, let +@comment node-name, next, previous, up +@subsection Uninitialized Variables in a @code{let} Statement +@cindex Uninitialized @code{let} variables +@cindex @code{let} variables uninitialized + +If you do not bind the variables in a @code{let} statement to specific +initial values, they will automatically be bound to an initial value of +@code{nil}, as in the following expression: + +@smallexample +@group +(let ((birch 3) + pine + fir + (oak 'some)) + (message + "Here are %d variables with %s, %s, and %s value." + birch pine fir oak)) +@end group +@end smallexample + +@noindent +Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. + +@need 1250 +If you evaluate this expression in the usual way, the following will +appear in your echo area: + +@smallexample +"Here are 3 variables with nil, nil, and some value." +@end smallexample + +@noindent +In this example, Emacs binds the symbol @code{birch} to the number 3, +binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds +the symbol @code{oak} to the value @code{some}. + +Note that in the first part of the @code{let}, the variables @code{pine} +and @code{fir} stand alone as atoms that are not surrounded by +parentheses; this is because they are being bound to @code{nil}, the +empty list. But @code{oak} is bound to @code{some} and so is a part of +the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the +number 3 and so is in a list with that number. (Since a number +evaluates to itself, the number does not need to be quoted. Also, the +number is printed in the message using a @samp{%d} rather than a +@samp{%s}.) The four variables as a group are put into a list to +delimit them from the body of the @code{let}. + +@node if, else, let, Writing Defuns +@comment node-name, next, previous, up +@section The @code{if} Special Form +@findex if +@cindex Conditional with @code{if} + +A third special form, in addition to @code{defun} and @code{let}, is the +conditional @code{if}. This form is used to instruct the computer to +make decisions. You can write function definitions without using +@code{if}, but it is used often enough, and is important enough, to be +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 +expression is not evaluated. For example, you might make a decision +such as, ``if it is warm and sunny, then go to the beach!'' + +@menu +* if in more detail:: +* type-of-animal in detail:: An example of an @code{if} expression. +@end menu + +@node if in more detail, type-of-animal in detail, if, if +@ifnottex +@unnumberedsubsec @code{if} in more detail +@end ifnottex + +@cindex @samp{if-part} defined +@cindex @samp{then-part} defined +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 +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 +on the second and subsequent lines. This makes the @code{if} +expression easier to read. + +@smallexample +@group +(if @var{true-or-false-test} + @var{action-to-carry-out-if-test-is-true}) +@end group +@end smallexample + +@noindent +The true-or-false-test will be an expression that +is evaluated by the Lisp interpreter. + +Here is an example that you can evaluate in the usual manner. The test +is whether the number 5 is greater than the number 4. Since it is, the +message @samp{5 is greater than 4!} will be printed. + +@smallexample +@group +(if (> 5 4) ; @r{if-part} + (message "5 is greater than 4!")) ; @r{then-part} +@end group +@end smallexample + +@noindent +(The function @code{>} tests whether its first argument is greater than +its second argument and returns true if it is.) +@findex > (greater than) + +Of course, in actual use, the test in an @code{if} expression will not +be fixed for all time as it is by the expression @code{(> 5 4)}. +Instead, at least one of the variables used in the test will be bound to +a value that is not known ahead of time. (If the value were known ahead +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 +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', +then warn of a tiger." + (if (equal characteristic 'fierce) + (message "It's a tiger!"))) +@end group +@end smallexample + +@need 1500 +@noindent +If you are reading this inside of GNU Emacs, you can evaluate the +function definition in the usual way to install it in Emacs, and then you +can evaluate the following two expressions to see the results: + +@smallexample +@group +(type-of-animal 'fierce) + +(type-of-animal 'zebra) + +@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} +printed in the echo area. + +@node type-of-animal in detail, , if in more detail, if +@comment node-name, next, previous, up +@subsection The @code{type-of-animal} Function in Detail + +Let's look at the @code{type-of-animal} function in detail. + +The function definition for @code{type-of-animal} was written by filling +the slots of two templates, one for a function definition as a whole, and +a second for an @code{if} expression. + +@need 1250 +The template for every function that is not interactive is: + +@smallexample +@group +(defun @var{name-of-function} (@var{argument-list}) + "@var{documentation}@dots{}" + @var{body}@dots{}) +@end group +@end smallexample + +@need 800 +The parts of the function that match this template look like this: + +@smallexample +@group +(defun type-of-animal (characteristic) + "Print message in echo area depending on CHARACTERISTIC. +If the CHARACTERISTIC is the symbol `fierce', +then warn of a tiger." + @var{body: the} @code{if} @var{expression}) +@end group +@end smallexample + +The name of function is @code{type-of-animal}; it is passed the value +of one argument. The argument list is followed by a multi-line +documentation string. The documentation string is included in the +example because it is a good habit to write documentation string for +every function definition. The body of the function definition +consists of the @code{if} expression. + +@need 800 +The template for an @code{if} expression looks like this: + +@smallexample +@group +(if @var{true-or-false-test} + @var{action-to-carry-out-if-the-test-returns-true}) +@end group +@end smallexample + +@need 1250 +In the @code{type-of-animal} function, the code for the @code{if} +looks like this: + +@smallexample +@group +(if (equal characteristic 'fierce) + (message "It's a tiger!"))) +@end group +@end smallexample + +@need 800 +Here, the true-or-false-test is the expression: + +@smallexample +(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 +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} +evaluates the second argument or then-part of the @code{if}: +@code{(message "It's 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 +@code{nil} is returned by the @code{if} expression. + +@node else, Truth & Falsehood, if, Writing Defuns +@comment node-name, next, previous, up +@section If--then--else Expressions +@cindex Else + +An @code{if} expression may have an optional third argument, called +the @dfn{else-part}, for the case when the true-or-false-test returns +false. When this happens, the second argument or then-part of the +overall @code{if} expression is @emph{not} evaluated, but the third or +else-part @emph{is} evaluated. You might think of this as the cloudy +day alternative for the decision ``if it is warm and sunny, then go to +the beach, else read a book!''. + +The word ``else'' is not written in the Lisp code; the else-part of an +@code{if} expression comes after the then-part. In the written Lisp, the +else-part is usually written to start on a line of its own and is +indented less than the then-part: + +@smallexample +@group +(if @var{true-or-false-test} + @var{action-to-carry-out-if-the-test-returns-true} + @var{action-to-carry-out-if-the-test-returns-false}) +@end group +@end smallexample + +For example, the following @code{if} expression prints the message @samp{4 +is not greater than 5!} when you evaluate it in the usual way: + +@smallexample +@group +(if (> 4 5) ; @r{if-part} + (message "4 falsely greater than 5!") ; @r{then-part} + (message "4 is not greater than 5!")) ; @r{else-part} +@end group +@end smallexample + +@noindent +Note that the different levels of indentation make it easy to +distinguish the then-part from the else-part. (GNU Emacs has several +commands that automatically indent @code{if} expressions correctly. +@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) + +We can extend the @code{type-of-animal} function to include an +else-part by simply incorporating an additional part to the @code{if} +expression. + +@need 1500 +You can see the consequences of doing this if you evaluate the following +version of the @code{type-of-animal} function definition to install it +and then evaluate the two subsequent expressions to pass different +arguments to the function. + +@smallexample +@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!"))) +@end group +@end smallexample +@sp 1 + +@smallexample +@group +(type-of-animal 'fierce) + +(type-of-animal 'zebra) + +@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!"}. + +(Of course, if the @var{characteristic} were @code{ferocious}, the +message @code{"It's 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.) + +@node Truth & Falsehood, save-excursion, else, Writing Defuns +@comment node-name, next, previous, up +@section Truth and Falsehood in Emacs Lisp +@cindex Truth and falsehood in Emacs Lisp +@cindex Falsehood and truth in Emacs Lisp +@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 +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'. + +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 +other words, the result of the test is considered true if the value +returned is a number such as 47, a string such as @code{"hello"}, or a +symbol (other than @code{nil}) such as @code{flowers}, or a list (so +long as it is not empty), or even a buffer! + +@menu +* nil explained:: @code{nil} has two meanings. +@end menu + +@node nil explained, , Truth & Falsehood, Truth & Falsehood +@ifnottex +@unnumberedsubsec An explanation of @code{nil} +@end ifnottex + +Before illustrating a test for truth, we need an explanation of @code{nil}. + +In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the +empty list. Second, it means false and is the value returned when a +true-or-false-test tests false. @code{nil} can be written as an empty +list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is +concerned, @code{()} and @code{nil} are the same. Humans, however, tend +to use @code{nil} for false and @code{()} for the empty list. + +In Emacs Lisp, any value that is not @code{nil}---is not the empty +list---is considered true. This means that if an evaluation returns +something that is not an empty list, an @code{if} expression will test +true. For example, if a number is put in the slot for the test, it +will be evaluated and will return itself, since that is what numbers +do when evaluated. In this conditional, the @code{if} expression will +test true. The expression tests false only when @code{nil}, an empty +list, is returned by evaluating the expression. + +You can see this by evaluating the two expressions in the following examples. + +In the first example, the number 4 is evaluated as the test in the +@code{if} expression and returns itself; consequently, the then-part +of the expression is evaluated and returned: @samp{true} appears in +the echo area. In the second example, the @code{nil} indicates false; +consequently, the else-part of the expression is evaluated and +returned: @samp{false} appears in the echo area. + +@smallexample +@group +(if 4 + 'true + 'false) +@end group + +@group +(if nil + 'true + 'false) +@end group +@end smallexample + +@need 1250 +Incidentally, if some other useful value is not available for a test that +returns true, then the Lisp interpreter will return the symbol @code{t} +for true. For example, the expression @code{(> 5 4)} returns @code{t} +when evaluated, as you can see by evaluating it in the usual way: + +@smallexample +(> 5 4) +@end smallexample + +@need 1250 +@noindent +On the other hand, this function returns @code{nil} if the test is false. + +@smallexample +(> 4 5) +@end smallexample + +@node save-excursion, Review, Truth & Falsehood, Writing Defuns +@comment node-name, next, previous, up +@section @code{save-excursion} +@findex save-excursion +@cindex Region, what it is +@cindex Preserving point, mark, and buffer +@cindex Point, mark, buffer preservation +@findex point +@findex mark + +The @code{save-excursion} function is the fourth 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 +purpose is to keep the user from being surprised and disturbed by +unexpected movement of point or mark. + +@menu +* Point and mark:: A review of various locations. +* Template for save-excursion:: +@end menu + +@node Point and mark, Template for save-excursion, save-excursion, save-excursion +@ifnottex +@unnumberedsubsec Point and Mark +@end ifnottex + +Before discussing @code{save-excursion}, however, it may be useful +first to review what point and mark are in GNU Emacs. @dfn{Point} is +the current location of the cursor. Wherever the cursor +is, that is point. More precisely, on terminals where the cursor +appears to be on top of a character, point is immediately before the +character. In Emacs Lisp, point is an integer. The first character in +a buffer is number one, the second is number two, and so on. The +function @code{point} returns the current position of the cursor as a +number. Each buffer has its own value for point. + +The @dfn{mark} is another position in the buffer; its value can be set +with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If +a mark has been set, you can use the command @kbd{C-x C-x} +(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark +and set the mark to be the previous position of point. In addition, if +you set another mark, the position of the previous mark is saved in the +mark ring. Many mark positions can be saved this way. You can jump the +cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more +times. + +The part of the buffer between point and mark is called @dfn{the +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 +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 +it was before, after the expressions in the body of the function were +evaluated. + +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 +@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 +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, +@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. +This is how @code{save-excursion} is used in @code{append-to-buffer}. +(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) + +@node Template for save-excursion, , Point and mark, save-excursion +@comment node-name, next, previous, up +@subsection Template for a @code{save-excursion} Expression + +@need 800 +The template for code using @code{save-excursion} is simple: + +@smallexample +@group +(save-excursion + @var{body}@dots{}) +@end group +@end smallexample + +@noindent +The body of the function is one or more expressions that will be +evaluated in sequence by the Lisp interpreter. If there is more than +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). + +@need 1250 +In more detail, the template for a @code{save-excursion} expression +looks like this: + +@smallexample +@group +(save-excursion + @var{first-expression-in-body} + @var{second-expression-in-body} + @var{third-expression-in-body} + @dots{} + @var{last-expression-in-body}) +@end group +@end smallexample + +@noindent +An expression, of course, may be a symbol on its own or a list. + +In Emacs Lisp code, a @code{save-excursion} expression often occurs +within the body of a @code{let} expression. It looks like this: + +@smallexample +@group +(let @var{varlist} + (save-excursion + @var{body}@dots{})) +@end group +@end smallexample + +@node Review, defun Exercises, save-excursion, Writing Defuns +@comment node-name, next, previous, up +@section Review + +In the last few chapters we have introduced a fair number of functions +and special forms. Here they are described in brief, along with a few +similar functions that have not been mentioned yet. + +@table @code +@item eval-last-sexp +Evaluate the last symbolic expression before the current location of +point. The value is printed in the echo area unless the function is +invoked with an argument; in that case, the output is printed in the +current buffer. This command is normally bound to @kbd{C-x C-e}. + +@item defun +Define function. This special form has up to five parts: the name, +a template for the arguments that will be passed to the function, +documentation, an optional interactive declaration, and the body of the +definition. + +@need 1250 +For example, in an early version of Emacs, the function definition was +as follows. (It is slightly more complex now that it seeks the first +non-whitespace character rather than the first visible character.) + +@smallexample +@group +(defun back-to-indentation () + "Move point to first visible character on line." + (interactive) + (beginning-of-line 1) + (skip-chars-forward " \t")) +@end group +@end smallexample + +@ignore +In GNU Emacs 22, + +(defun backward-to-indentation (&optional arg) + "Move backward ARG lines and position at first nonblank character." + (interactive "p") + (forward-line (- (or arg 1))) + (skip-chars-forward " \t")) + +(defun back-to-indentation () + "Move point to the first non-whitespace character on this line." + (interactive) + (beginning-of-line 1) + (skip-syntax-forward " " (line-end-position)) + ;; Move back over chars that have whitespace syntax but have the p flag. + (backward-prefix-chars)) +@end ignore + +@item interactive +Declare to the interpreter that the function can be used +interactively. This special form may be followed by a string with one +or more parts that pass the information to the arguments of the +function, in sequence. These parts may also tell the interpreter to +prompt for information. Parts of the string are separated by +newlines, @samp{\n}. + +@need 1000 +Common code characters are: + +@table @code +@item b +The name of an existing buffer. + +@item f +The name of an existing file. + +@item p +The numeric prefix argument. (Note that this `p' is lower case.) + +@item r +Point and the mark, as two numeric arguments, smallest first. This +is the only code letter that specifies two successive arguments +rather than one. +@end table + +@xref{Interactive Codes, , Code Characters for @samp{interactive}, +elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of +code characters. + +@item let +Declare that a list of variables is for use within the body of the +@code{let} and give them an initial value, either @code{nil} or a +specified value; then evaluate the rest of the expressions in the body +of the @code{let} and return the value of the last one. Inside the +body of the @code{let}, the Lisp interpreter does not see the values of +the variables of the same names that are bound outside of the +@code{let}. + +@need 1250 +For example, + +@smallexample +@group +(let ((foo (buffer-name)) + (bar (buffer-size))) + (message + "This buffer is %s and has %d characters." + foo bar)) +@end group +@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. + +@need 1250 +For example, + +@smallexample +@group +(message "We are %d characters into this buffer." + (- (point) + (save-excursion + (goto-char (point-min)) (point)))) +@end group +@end smallexample + +@item if +Evaluate the first argument to the function; if it is true, evaluate +the second argument; else evaluate the third argument, if there is one. + +The @code{if} special form is called a @dfn{conditional}. There are +other conditionals in Emacs Lisp, but @code{if} is perhaps the most +commonly used. + +@need 1250 +For example, + +@smallexample +@group +(if (= 22 emacs-major-version) + (message "This is version 22 Emacs") + (message "This is not version 22 Emacs")) +@end group +@end smallexample + +@need 1250 +@item < +@itemx > +@itemx <= +@itemx >= +The @code{<} function tests whether its first argument is smaller than +its second argument. A corresponding function, @code{>}, tests whether +the first argument is greater than the second. Likewise, @code{<=} +tests whether the first argument is less than or equal to the second and +@code{>=} tests whether the first argument is greater than or equal to +the second. In all cases, both arguments must be numbers or markers +(markers indicate positions in buffers). + +@need 800 +@item = +The @code{=} function tests whether two arguments, both numbers or +markers, are equal. + +@need 1250 +@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 +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. +@findex equal +@findex eq + +@need 1250 +@item string< +@itemx string-lessp +@itemx string= +@itemx string-equal +The @code{string-lessp} function tests whether its first argument is +smaller than the second argument. A shorter, alternative name for the +same function (a @code{defalias}) is @code{string<}. + +The arguments to @code{string-lessp} must be strings or symbols; the +ordering is lexicographic, so case is significant. The print names of +symbols are used instead of the symbols themselves. + +@cindex @samp{empty string} defined +An empty string, @samp{""}, a string with no characters in it, is +smaller than any string of characters. + +@code{string-equal} provides the corresponding test for equality. Its +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 +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 +number. The argument used by @samp{%c} must be an @sc{ascii} code +number; it will be printed as the character with that @sc{ascii} code. +(Various other %-sequences have not been mentioned.) + +@item setq +@itemx set +The @code{setq} function sets the value of its first argument to the +value of the second argument. The first argument is automatically +quoted by @code{setq}. It does the same for succeeding pairs of +arguments. Another function, @code{set}, takes only two arguments and +evaluates both of them before setting the value returned by its first +argument to the value returned by its second argument. + +@item buffer-name +Without an argument, return the name of the buffer, as a string. + +@itemx buffer-file-name +Without an argument, return the name of the file the buffer is +visiting. + +@item current-buffer +Return the buffer in which Emacs is active; it may not be +the buffer that is visible on the screen. + +@item other-buffer +Return the most recently selected buffer (other than the buffer passed +to @code{other-buffer} as an argument and other than the current +buffer). + +@item switch-to-buffer +Select a buffer for Emacs to be active in and display it in the current +window so users can look at it. Usually bound to @kbd{C-x b}. + +@item set-buffer +Switch Emacs' attention to a buffer on which programs will run. Don't +alter what the window is showing. + +@item buffer-size +Return the number of characters in the current buffer. + +@item point +Return the value of the current position of the cursor, as an +integer counting the number of characters from the beginning of the +buffer. + +@item point-min +Return the minimum permissible value of point in +the current buffer. This is 1, unless narrowing is in effect. + +@item point-max +Return the value of the maximum permissible value of point in the +current buffer. This is the end of the buffer, unless narrowing is in +effect. +@end table + +@need 1500 +@node defun Exercises, , Review, Writing Defuns +@section Exercises + +@itemize @bullet +@item +Write a non-interactive function that doubles the value of its +argument, a number. Make that function interactive. + +@item +Write a function that tests whether the current value of +@code{fill-column} is greater than the argument passed to the function, +and if so, prints an appropriate message. +@end itemize + +@node Buffer Walk Through, More Complex, Writing Defuns, Top +@comment node-name, next, previous, up +@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 +examples of Lisp code, but are not imaginary examples; with the +exception of the first, simplified function definition, these functions +show the actual code used in GNU Emacs. You can learn a great deal from +these definitions. The functions described here are all related to +buffers. Later, we will study other functions. + +@menu +* Finding More:: How to find more information. +* simplified-beginning-of-buffer:: Shows @code{goto-char}, + @code{point-min}, and @code{push-mark}. +* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. +* append-to-buffer:: Uses @code{save-excursion} and + @code{insert-buffer-substring}. +* Buffer Related Review:: Review. +* Buffer Exercises:: +@end menu + +@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through +@section Finding More Information + +@findex describe-function, @r{introduced} +@cindex Find function documentation +In this walk-through, I will describe each new function as we come to +it, sometimes in detail and sometimes briefly. If you are interested, +you can get the full documentation of any Emacs Lisp function at any +time by typing @kbd{C-h f} and then the name of the function (and then +@key{RET}). Similarly, you can get the full documentation for a +variable by typing @kbd{C-h v} and then the name of the variable (and +then @key{RET}). + +@cindex Find source of function +@c In version 22, tells location both of C and of Emacs Lisp +Also, @code{describe-function} will tell you the location of the +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 +you directly to the function definition. + +@ignore +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 +definition. +@end ignore + +More generally, if you want to see a function in its original source +file, you can use the @code{find-tags} function to jump to it. +@code{find-tags} works with a wide variety of languages, not just +Lisp, and C, and it works with non-programming text as well. For +example, @code{find-tags} will jump to the various nodes in the +Texinfo source file of this document. +The @code{find-tags} function depends on `tags tables' that record +the locations of the functions, variables, and other items to which +@code{find-tags} jumps. + +To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the +period key while holding down the @key{META} key, or else type the +@key{ESC} key and then type the period key), and then, at the prompt, +type in the name of the function whose source code you want to see, +such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will +switch buffers and display the source code for the function on your +screen. To switch back to your current buffer, type @kbd{C-x b +@key{RET}}. (On some keyboards, the @key{META} key is labelled +@key{ALT}.) + +@c !!! 22.1.1 tags table location in this paragraph +@cindex TAGS table, specifying +@findex find-tags +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', +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 +the @file{/usr/local/share/emacs/} directory; thus you would use the +@code{M-x visit-tags-table} command and specify a pathname such as +@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table +has not already been created, you will have to create it yourself. It +will in a file such as @file{/usr/local/src/emacs/src/TAGS}. + +@need 1250 +To create a @file{TAGS} file in a specific directory, switch to that +directory in Emacs using @kbd{M-x cd} command, or list the directory +with @kbd{C-x d} (@code{dired}). Then run the compile command, with +@w{@code{etags *.el}} as the command to execute: + +@smallexample +M-x compile RET etags *.el RET +@end smallexample + +For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. + +After you become more familiar with Emacs Lisp, you will find that you will +frequently use @code{find-tags} to navigate your way around source code; +and you will create your own @file{TAGS} tables. + +@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 +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 +@kbd{C-h p} command lets you search the standard Emacs Lisp libraries +by topic keywords.'' + +@node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through +@comment node-name, next, previous, up +@section A Simplified @code{beginning-of-buffer} Definition +@findex simplified-beginning-of-buffer + +The @code{beginning-of-buffer} command is a good function to start with +since you are likely to be familiar with it and it is easy to +understand. Used as an interactive command, @code{beginning-of-buffer} +moves the cursor to the beginning of the buffer, leaving the mark at the +previous position. It is generally bound to @kbd{M-<}. + +In this section, we will discuss a shortened version of the function +that shows how it is most frequently used. This shortened function +works as written, but it does not contain the code for a complex option. +In another section, we will describe the entire function. +(@xref{beginning-of-buffer, , Complete Definition of +@code{beginning-of-buffer}}.) + +Before looking at the code, let's consider what the function +definition has to contain: it must include an expression that makes +the function interactive so it can be called by typing @kbd{M-x +beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it +must include code to leave a mark at the original position in the +buffer; and it must include code to move the cursor to the beginning +of the buffer. + +@need 1250 +Here is the complete text of the shortened version of the function: + +@smallexample +@group +(defun simplified-beginning-of-buffer () + "Move point to the beginning of the buffer; +leave mark at previous position." + (interactive) + (push-mark) + (goto-char (point-min))) +@end group +@end smallexample + +Like all function definitions, this definition has five parts following +the special form @code{defun}: + +@enumerate +@item +The name: in this example, @code{simplified-beginning-of-buffer}. + +@item +A list of the arguments: in this example, an empty list, @code{()}, + +@item +The documentation string. + +@item +The interactive expression. + +@item +The body. +@end enumerate + +@noindent +In this function definition, the argument list is empty; this means that +this function does not require any arguments. (When we look at the +definition for the complete function, we will see that it may be passed +an optional argument.) + +The interactive expression tells Emacs that the function is intended to +be used interactively. In this example, @code{interactive} does not have +an argument because @code{simplified-beginning-of-buffer} does not +require one. + +@need 800 +The body of the function consists of the two lines: + +@smallexample +@group +(push-mark) +(goto-char (point-min)) +@end group +@end smallexample + +The first of these lines is the expression, @code{(push-mark)}. When +this expression is evaluated by the Lisp interpreter, it sets a mark at +the current position of the cursor, wherever that may be. The position +of this mark is saved in the mark ring. + +The next line is @code{(goto-char (point-min))}. This expression +jumps the cursor to the minimum point in the buffer, that is, to the +beginning of the buffer (or to the beginning of the accessible portion +of the buffer if it is narrowed. @xref{Narrowing & Widening, , +Narrowing and Widening}.) + +The @code{push-mark} command sets a mark at the place where the cursor +was located before it was moved to the beginning of the buffer by the +@code{(goto-char (point-min))} expression. Consequently, you can, if +you wish, go back to where you were originally by typing @kbd{C-x C-x}. + +That is all there is to the function definition! + +@findex describe-function +When you are reading code such as this and come upon an unfamiliar +function, such as @code{goto-char}, you can find out what it does by +using the @code{describe-function} command. To use this command, type +@kbd{C-h f} and then type in the name of the function and press +@key{RET}. The @code{describe-function} command will print the +function's documentation string in a @file{*Help*} window. For +example, the documentation for @code{goto-char} is: + +@smallexample +@group +Set point to POSITION, a number or marker. +Beginning of buffer is position (point-min), end is (point-max). +@end group +@end smallexample + +@noindent +The function's one argument is the desired position. + +@noindent +(The prompt for @code{describe-function} will offer you the symbol +under or preceding the cursor, so you can save typing by positioning +the cursor right over or after the function and then typing @kbd{C-h f +@key{RET}}.) + +The @code{end-of-buffer} function definition is written in the same way as +the @code{beginning-of-buffer} definition except that the body of the +function contains the expression @code{(goto-char (point-max))} in place +of @code{(goto-char (point-min))}. + +@node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through +@comment node-name, next, previous, up +@section The Definition of @code{mark-whole-buffer} +@findex mark-whole-buffer + +The @code{mark-whole-buffer} function is no harder to understand than the +@code{simplified-beginning-of-buffer} function. In this case, however, +we will look at the complete function, not a shortened version. + +The @code{mark-whole-buffer} function is not as commonly used as the +@code{beginning-of-buffer} function, but is useful nonetheless: it +marks a whole buffer as a region by putting point at the beginning and +a mark at the end of the buffer. It is generally bound to @kbd{C-x +h}. + +@menu +* mark-whole-buffer overview:: +* Body of mark-whole-buffer:: Only three lines of code. +@end menu + +@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer +@ifnottex +@unnumberedsubsec An overview of @code{mark-whole-buffer} +@end ifnottex + +@need 1250 +In GNU Emacs 22, the code for the complete function looks like this: + +@smallexample +@group +(defun mark-whole-buffer () + "Put point at beginning and mark at end of buffer. +You probably should not use this function in Lisp programs; +it is usually a mistake for a Lisp function to use any subroutine +that uses or sets the mark." + (interactive) + (push-mark (point)) + (push-mark (point-max) nil t) + (goto-char (point-min))) +@end group +@end smallexample + +@need 1250 +Like all other functions, the @code{mark-whole-buffer} function fits +into the template for a function definition. The template looks like +this: + +@smallexample +@group +(defun @var{name-of-function} (@var{argument-list}) + "@var{documentation}@dots{}" + (@var{interactive-expression}@dots{}) + @var{body}@dots{}) +@end group +@end smallexample + +Here is how the function works: the name of the function is +@code{mark-whole-buffer}; it is followed by an empty argument list, +@samp{()}, which means that the function does not require arguments. +The documentation comes next. + +The next line is an @code{(interactive)} expression that tells Emacs +that the function will be used interactively. These details are similar +to the @code{simplified-beginning-of-buffer} function described in the +previous section. + +@need 1250 +@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer +@comment node-name, next, previous, up +@subsection Body of @code{mark-whole-buffer} + +The body of the @code{mark-whole-buffer} function consists of three +lines of code: + +@c GNU Emacs 22 +@smallexample +@group +(push-mark (point)) +(push-mark (point-max) nil t) +(goto-char (point-min)) +@end group +@end smallexample + +The first of these lines is the expression, @code{(push-mark (point))}. + +This line does exactly the same job as the first line of the body of +the @code{simplified-beginning-of-buffer} function, which is written +@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark +at the current position of the cursor. + +I don't know why the expression in @code{mark-whole-buffer} is written +@code{(push-mark (point))} and the expression in +@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps +whoever wrote the code did not know that the arguments for +@code{push-mark} are optional and that if @code{push-mark} is not +passed an argument, the function automatically sets mark at the +location of point by default. Or perhaps the expression was written +so as to parallel the structure of the next line. In any case, the +line causes Emacs to determine the position of point and set a mark +there. + +In earlier versions of GNU Emacs, the next line of +@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This +expression sets a mark at the point in the buffer that has the highest +number. This will be the end of the buffer (or, if the buffer is +narrowed, the end of the accessible portion of the buffer. +@xref{Narrowing & Widening, , Narrowing and Widening}, for more about +narrowing.) After this mark has been set, the previous mark, the one +set at point, is no longer set, but Emacs remembers its position, just +as all other recent marks are always remembered. This means that you +can, if you wish, go back to that position by typing @kbd{C-u +C-@key{SPC}} twice. + +@need 1250 +In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. +The line reads + +@smallexample +(push-mark (point-max) nil t) +@end smallexample + +@noindent +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 +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 +region. It is often turned off. + +Finally, the last line of the function is @code{(goto-char +(point-min)))}. This is written exactly the same way as it is written +in @code{beginning-of-buffer}. The expression moves the cursor to +the minimum point in the buffer, that is, to the beginning of the buffer +(or to the beginning of the accessible portion of the buffer). As a +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. + +@node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through +@comment node-name, next, previous, up +@section The Definition of @code{append-to-buffer} +@findex append-to-buffer + +The @code{append-to-buffer} command is more complex than the +@code{mark-whole-buffer} command. What it does is copy the region +(that is, the part of the buffer between point and mark) from the +current buffer to a specified buffer. + +@menu +* append-to-buffer overview:: +* append interactive:: A two part interactive expression. +* append-to-buffer body:: Incorporates a @code{let} expression. +* append save-excursion:: How the @code{save-excursion} works. +@end menu + +@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer +@ifnottex +@unnumberedsubsec An Overview of @code{append-to-buffer} +@end ifnottex + +@findex insert-buffer-substring +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. + +Most of @code{append-to-buffer} is +concerned with setting up the conditions for +@code{insert-buffer-substring} to work: the code must specify both the +buffer to which the text will go, the window it comes from and goes +to, and the region that will be copied. + +@need 1250 +Here is the complete text of the function: + +@smallexample +@group +(defun append-to-buffer (buffer start end) + "Append to specified buffer the text of the region. +It is inserted into that buffer before its point. +@end group + +@group +When calling from a program, give three arguments: +BUFFER (or buffer name), START and END. +START and END specify the portion of the current buffer to be copied." + (interactive + (list (read-buffer "Append to buffer: " (other-buffer + (current-buffer) t)) + (region-beginning) (region-end))) +@end group +@group + (let ((oldbuf (current-buffer))) + (save-excursion + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) +@end group +@end smallexample + +The function can be understood by looking at it as a series of +filled-in templates. + +The outermost template is for the function definition. In this +function, it looks like this (with several slots filled in): + +@smallexample +@group +(defun append-to-buffer (buffer start end) + "@var{documentation}@dots{}" + (interactive @dots{}) + @var{body}@dots{}) +@end group +@end smallexample + +The first line of the function includes its name and three arguments. +The arguments are the @code{buffer} to which the text will be copied, and +the @code{start} and @code{end} of the region in the current buffer that +will be copied. + +The next part of the function is the documentation, which is clear and +complete. As is conventional, the three arguments are written in +upper case so you will notice them easily. Even better, they are +described in the same order as in the argument list. + +Note that the documentation distinguishes between a buffer and its +name. (The function can handle either.) + +@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer +@comment node-name, next, previous, up +@subsection The @code{append-to-buffer} Interactive Expression + +Since the @code{append-to-buffer} function will be used interactively, +the function must have an @code{interactive} expression. (For a +review of @code{interactive}, see @ref{Interactive, , Making a +Function Interactive}.) The expression reads as follows: + +@smallexample +@group +(interactive + (list (read-buffer + "Append to buffer: " + (other-buffer (current-buffer) t)) + (region-beginning) + (region-end))) +@end group +@end smallexample + +@noindent +This expression is not one with letters standing for parts, as +described earlier. Instead, it starts a list with these parts: + +The first part of the list is an expression to read the name of a +buffer and return it as a string. That is @code{read-buffer}. The +function requires a prompt as its first argument, @samp{"Append to +buffer: "}. Its second argument tells the command what value to +provide if you don't specify anything. + +In this case that second argument is an expression containing the +function @code{other-buffer}, an exception, and a @samp{t}, standing +for true. + +The first argument to @code{other-buffer}, the exception, is yet +another function, @code{current-buffer}. That is not going to be +returned. The second argument is the symbol for true, @code{t}. that +tells @code{other-buffer} that it may show visible buffers (except in +this case, it will not show the current buffer, which makes sense). + +@need 1250 +The expression looks like this: + +@smallexample +(other-buffer (current-buffer) t) +@end smallexample + +The second and third arguments to the @code{list} expression are +@code{(region-beginning)} and @code{(region-end)}. These two +functions specify the beginning and end of the text to be appended. + +@need 1250 +Originally, the command used the letters @samp{B} and @samp{r}. +The whole @code{interactive} expression looked like this: + +@smallexample +(interactive "BAppend to buffer:@: \nr") +@end smallexample + +@noindent +But when that was done, the default value of the buffer switched to +was invisible. That was not wanted. + +(The prompt was separated from the second argument with a newline, +@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the +two arguments that follow the symbol @code{buffer} in the function's +argument list (that is, @code{start} and @code{end}) to the values of +point and mark. That argument worked fine.) + +@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer +@comment node-name, next, previous, up +@subsection The Body of @code{append-to-buffer} + +@ignore +in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el + +(defun append-to-buffer (buffer start end) + "Append to specified buffer the text of the region. +It is inserted into that buffer before its point. + +When calling from a program, give three arguments: +BUFFER (or buffer name), START and END. +START and END specify the portion of the current buffer to be copied." + (interactive + (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) + (region-beginning) (region-end))) + (let ((oldbuf (current-buffer))) + (save-excursion + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) +@end ignore + +The body of the @code{append-to-buffer} function begins with @code{let}. + +As we have seen before (@pxref{let, , @code{let}}), the purpose of a +@code{let} expression is to create and give initial values to one or +more variables that will only be used within the body of the +@code{let}. This means that such a variable will not be confused with +any variable of the same name outside the @code{let} expression. + +We can see how the @code{let} expression fits into the function as a +whole by showing a template for @code{append-to-buffer} with the +@code{let} expression in outline: + +@smallexample +@group +(defun append-to-buffer (buffer start end) + "@var{documentation}@dots{}" + (interactive @dots{}) + (let ((@var{variable} @var{value})) + @var{body}@dots{}) +@end group +@end smallexample + +The @code{let} expression has three elements: + +@enumerate +@item +The symbol @code{let}; + +@item +A varlist containing, in this case, a single two-element list, +@code{(@var{variable} @var{value})}; + +@item +The body of the @code{let} expression. +@end enumerate + +@need 800 +In the @code{append-to-buffer} function, the varlist looks like this: + +@smallexample +(oldbuf (current-buffer)) +@end smallexample + +@noindent +In this part of the @code{let} expression, the one variable, +@code{oldbuf}, is bound to the value returned by the +@code{(current-buffer)} expression. The variable, @code{oldbuf}, is +used to keep track of the buffer in which you are working and from +which you will copy. + +The element or elements of a varlist are surrounded by a set of +parentheses so the Lisp interpreter can distinguish the varlist from +the body of the @code{let}. As a consequence, the two-element list +within the varlist is surrounded by a circumscribing set of parentheses. +The line looks like this: + +@smallexample +@group +(let ((oldbuf (current-buffer))) + @dots{} ) +@end group +@end smallexample + +@noindent +The two parentheses before @code{oldbuf} might surprise you if you did +not realize that the first parenthesis before @code{oldbuf} marks the +boundary of the varlist and the second parenthesis marks the beginning +of the two-element list, @code{(oldbuf (current-buffer))}. + +@node append save-excursion, , append-to-buffer body, append-to-buffer +@comment node-name, next, previous, up +@subsection @code{save-excursion} in @code{append-to-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 +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 +@code{append-to-buffer}. + +@need 1500 +@cindex Indentation for formatting +@cindex Formatting convention +Incidentally, it is worth noting here that a Lisp function is normally +formatted so that everything that is enclosed in a multi-line spread is +indented more to the right than the first symbol. In this function +definition, the @code{let} is indented more than the @code{defun}, and +the @code{save-excursion} is indented more than the @code{let}, like +this: + +@smallexample +@group +(defun @dots{} + @dots{} + @dots{} + (let@dots{} + (save-excursion + @dots{} +@end group +@end smallexample + +@need 1500 +@noindent +This formatting convention makes it easy to see that the lines in +the body of the @code{save-excursion} are enclosed by the parentheses +associated with @code{save-excursion}, just as the +@code{save-excursion} itself is enclosed by the parentheses associated +with the @code{let}: + +@smallexample +@group +(let ((oldbuf (current-buffer))) + (save-excursion + @dots{} + (set-buffer @dots{}) + (insert-buffer-substring oldbuf start end) + @dots{})) +@end group +@end smallexample + +@need 1200 +The use of the @code{save-excursion} function can be viewed as a process +of filling in the slots of a template: + +@smallexample +@group +(save-excursion + @var{first-expression-in-body} + @var{second-expression-in-body} + @dots{} + @var{last-expression-in-body}) +@end group +@end smallexample + +@need 1200 +@noindent +In this function, the body of the @code{save-excursion} contains only +one expression, the @code{let*} expression. You know about a +@code{let} function. The @code{let*} function is different. It has a +@samp{*} in its name. It enables Emacs to set each variable in its +varlist in sequence, one after another. + +Its critical feature is that variables later in the varlist can make +use of the values to which Emacs set variables earlier in the varlist. +@xref{fwd-para let, , The @code{let*} expression}. + +We will skip functions like @code{let*} and focus on two: the +@code{set-buffer} function and the @code{insert-buffer-substring} +function. + +@need 1250 +In the old days, the @code{set-buffer} expression was simply + +@smallexample +(set-buffer (get-buffer-create buffer)) +@end smallexample + +@need 1250 +@noindent +but now it is + +@smallexample +(set-buffer append-to) +@end smallexample + +@noindent +@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier +on in the @code{let*} expression. That extra binding would not be +necessary except for that @code{append-to} is used later in the +varlist as an argument to @code{get-buffer-window-list}. + +@ignore +in GNU Emacs 22 + + (let ((oldbuf (current-buffer))) + (save-excursion + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) +@end ignore + +The @code{append-to-buffer} function definition inserts text from the +buffer in which you are currently to a named buffer. It happens that +@code{insert-buffer-substring} copies text from another buffer to the +current buffer, just the reverse---that is why the +@code{append-to-buffer} definition starts out with a @code{let} that +binds the local symbol @code{oldbuf} to the value returned by +@code{current-buffer}. + +@need 1250 +The @code{insert-buffer-substring} expression looks like this: + +@smallexample +(insert-buffer-substring oldbuf start end) +@end smallexample + +@noindent +The @code{insert-buffer-substring} function copies a string +@emph{from} the buffer specified as its first argument and inserts the +string into the present buffer. In this case, the argument to +@code{insert-buffer-substring} is the value of the variable created +and bound by the @code{let}, namely the value of @code{oldbuf}, which +was the current buffer when you gave the @code{append-to-buffer} +command. + +After @code{insert-buffer-substring} has done its work, +@code{save-excursion} will restore the action to the original buffer +and @code{append-to-buffer} will have done its job. + +@need 800 +Written in skeletal form, the workings of the body look like this: + +@smallexample +@group +(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) + (save-excursion ; @r{Keep track of buffer.} + @var{change-buffer} + @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) + + @var{change-back-to-original-buffer-when-finished} +@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} +@end group +@end smallexample + +In summary, @code{append-to-buffer} works as follows: it saves the +value of the current buffer in the variable called @code{oldbuf}. It +gets the new buffer (creating one if need be) and switches Emacs' +attention to it. Using the value of @code{oldbuf}, it inserts the +region of text from the old buffer into the new buffer; and then using +@code{save-excursion}, it brings you back to your original buffer. + +In looking at @code{append-to-buffer}, you have explored a fairly +complex function. It shows how to use @code{let} and +@code{save-excursion}, and how to change to and come back from another +buffer. Many function definitions use @code{let}, +@code{save-excursion}, and @code{set-buffer} this way. + +@node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through +@comment node-name, next, previous, up +@section Review + +Here is a brief summary of the various functions discussed in this chapter. + +@table @code +@item describe-function +@itemx describe-variable +Print the documentation for a function or variable. +Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. + +@item find-tag +Find the file containing the source for a function or variable and +switch buffers to it, positioning point at the beginning of the item. +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 +arguments to @code{save-excursion} have been evaluated. Also, remember +the current buffer and return to it. + +@item push-mark +Set mark at a location and record the value of the previous mark on the +mark ring. The mark is a location in the buffer that will keep its +relative position even if text is added to or removed from the buffer. + +@item goto-char +Set point to the location specified by the value of the argument, which +can be a number, a marker, or an expression that returns the number of +a position, such as @code{(point-min)}. + +@item insert-buffer-substring +Copy a region of text from a buffer that is passed to the function as +an argument and insert the region into the current buffer. + +@item mark-whole-buffer +Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. + +@item set-buffer +Switch the attention of Emacs to another buffer, but do not change the +window being displayed. Used when the program rather than a human is +to work on a different buffer. + +@item get-buffer-create +@itemx get-buffer +Find a named buffer or create one if a buffer of that name does not +exist. The @code{get-buffer} function returns @code{nil} if the named +buffer does not exist. +@end table + +@need 1500 +@node Buffer Exercises, , Buffer Related Review, Buffer Walk Through +@section Exercises + +@itemize @bullet +@item +Write your own @code{simplified-end-of-buffer} function definition; +then test it to see whether it works. + +@item +Use @code{if} and @code{get-buffer} to write a function that prints a +message telling you whether a buffer exists. + +@item +Using @code{find-tag}, find the source for the @code{copy-to-buffer} +function. +@end itemize + +@node More Complex, Narrowing & Widening, Buffer Walk Through, Top +@comment node-name, next, previous, up +@chapter A Few More Complex Functions + +In this chapter, we build on what we have learned in previous chapters +by looking at more complex functions. The @code{copy-to-buffer} +function illustrates use of two @code{save-excursion} expressions in +one definition, while the @code{insert-buffer} function illustrates +use of an asterisk in an @code{interactive} expression, use of +@code{or}, and the important distinction between a name and the object +to which the name refers. + +@menu +* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. +* insert-buffer:: Read-only, and with @code{or}. +* beginning-of-buffer:: Shows @code{goto-char}, + @code{point-min}, and @code{push-mark}. +* Second Buffer Related Review:: +* optional Exercise:: +@end menu + +@node copy-to-buffer, insert-buffer, More Complex, More Complex +@comment node-name, next, previous, up +@section The Definition of @code{copy-to-buffer} +@findex copy-to-buffer + +After understanding how @code{append-to-buffer} works, it is easy to +understand @code{copy-to-buffer}. This function copies text into a +buffer, but instead of adding to the second buffer, it replaces all the +previous text in the second buffer. + +@need 800 +The body of @code{copy-to-buffer} looks like this, + +@smallexample +@group +@dots{} +(interactive "BCopy to buffer: \nr") +(let ((oldbuf (current-buffer))) + (with-current-buffer (get-buffer-create buffer) + (barf-if-buffer-read-only) + (erase-buffer) + (save-excursion + (insert-buffer-substring oldbuf start end))))) +@end group +@end smallexample + +The @code{copy-to-buffer} function has a simpler @code{interactive} +expression than @code{append-to-buffer}. + +@need 800 +The definition then says + +@smallexample +(with-current-buffer (get-buffer-create buffer) @dots{} +@end smallexample + +First, look at the earliest inner expression; that is evaluated first. +That expression starts with @code{get-buffer-create buffer}. The +function tells the computer to use the buffer with the name specified +as the one to which you are copying, or if such a buffer does not +exist, to create it. Then, the @code{with-current-buffer} function +evaluates its body with that buffer temporarily current. + +(This demonstrates another way to shift the computer's attention but +not the user's. The @code{append-to-buffer} function showed how to do +the same with @code{save-excursion} and @code{set-buffer}. +@code{with-current-buffer} is a newer, and arguably easier, +mechanism.) + +The @code{barf-if-buffer-read-only} function sends you an error +message saying the buffer is read-only if you cannot modify it. + +The next line has the @code{erase-buffer} function as its sole +contents. That function erases the buffer. + +Finally, the last two lines contain the @code{save-excursion} +expression with @code{insert-buffer-substring} as its body. +The @code{insert-buffer-substring} expression copies the text from +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, +Emacs erases the previous text and then inserts new text. + +@need 1250 +In outline, the body of @code{copy-to-buffer} looks like this: + +@smallexample +@group +(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) + (@var{with-the-buffer-you-are-copying-to} + (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) + (erase-buffer) + (save-excursion + @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) +@end group +@end smallexample + +@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex +@comment node-name, next, previous, up +@section The Definition of @code{insert-buffer} +@findex insert-buffer + +@code{insert-buffer} is yet another buffer-related function. This +command copies another buffer @emph{into} the current buffer. It is the +reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they +copy a region of text @emph{from} the current buffer to another buffer. + +Here is a discussion based on the original code. The code was +simplified in 2003 and is harder to understand. + +(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see +a discussion of the new body.) + +In addition, this code illustrates the use of @code{interactive} with a +buffer that might be @dfn{read-only} and the important distinction +between the name of an object and the object actually referred to. + +@menu +* insert-buffer code:: +* insert-buffer interactive:: When you can read, but not write. +* insert-buffer body:: The body has an @code{or} and a @code{let}. +* if & or:: Using an @code{if} instead of an @code{or}. +* Insert or:: How the @code{or} expression works. +* Insert let:: Two @code{save-excursion} expressions. +* New insert-buffer:: +@end menu + +@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer +@ifnottex +@unnumberedsubsec The Code for @code{insert-buffer} +@end ifnottex + +@need 800 +Here is the earlier code: + +@smallexample +@group +(defun insert-buffer (buffer) + "Insert after point the contents of BUFFER. +Puts mark after the inserted text. +BUFFER may be a buffer or a buffer name." + (interactive "*bInsert buffer:@: ") +@end group +@group + (or (bufferp buffer) + (setq buffer (get-buffer buffer))) + (let (start end newmark) + (save-excursion + (save-excursion + (set-buffer buffer) + (setq start (point-min) end (point-max))) +@end group +@group + (insert-buffer-substring buffer start end) + (setq newmark (point))) + (push-mark newmark))) +@end group +@end smallexample + +@need 1200 +As with other function definitions, you can use a template to see an +outline of the function: + +@smallexample +@group +(defun insert-buffer (buffer) + "@var{documentation}@dots{}" + (interactive "*bInsert buffer:@: ") + @var{body}@dots{}) +@end group +@end smallexample + +@node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer +@comment node-name, next, previous, up +@subsection The Interactive Expression in @code{insert-buffer} +@findex interactive, @r{example use of} + +In @code{insert-buffer}, the argument to the @code{interactive} +declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert +buffer:@: }. + +@menu +* Read-only buffer:: When a buffer cannot be modified. +* b for interactive:: An existing buffer or else its name. +@end menu + +@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive +@comment node-name, next, previous, up +@unnumberedsubsubsec A Read-only Buffer +@cindex Read-only buffer +@cindex Asterisk for read-only buffer +@findex * @r{for read-only buffer} + +The asterisk is for the situation when the current buffer is a +read-only buffer---a buffer that cannot be modified. If +@code{insert-buffer} is called when the current buffer is read-only, a +message to this effect is printed in the echo area and the terminal +may beep or blink at you; you will not be permitted to insert anything +into current buffer. The asterisk does not need to be followed by a +newline to separate it from the next argument. + +@node b for interactive, , Read-only buffer, insert-buffer interactive +@comment node-name, next, previous, up +@unnumberedsubsubsec @samp{b} in an Interactive Expression + +The next argument in the interactive expression starts with a lower +case @samp{b}. (This is different from the code for +@code{append-to-buffer}, which uses an upper-case @samp{B}. +@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) +The lower-case @samp{b} tells the Lisp interpreter that the argument +for @code{insert-buffer} should be an existing buffer or else its +name. (The upper-case @samp{B} option provides for the possibility +that the buffer does not exist.) Emacs will prompt you for the name +of the buffer, offering you a default buffer, with name completion +enabled. If the buffer does not exist, you receive a message that +says ``No match''; your terminal may beep at you as well. + +The new and simplified code generates a list for @code{interactive}. +It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} +functions with which we are already familiar and the @code{progn} +special form with which we are not. (It will be described later.) + +@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer +@comment node-name, next, previous, up +@subsection The Body of the @code{insert-buffer} Function + +The body of the @code{insert-buffer} function has two major parts: an +@code{or} expression and a @code{let} expression. The purpose of the +@code{or} expression is to ensure that the argument @code{buffer} is +bound to a buffer and not just the name of a buffer. The body of the +@code{let} expression contains the code which copies the other buffer +into the current buffer. + +@need 1250 +In outline, the two expressions fit into the @code{insert-buffer} +function like this: + +@smallexample +@group +(defun insert-buffer (buffer) + "@var{documentation}@dots{}" + (interactive "*bInsert buffer:@: ") + (or @dots{} + @dots{} +@end group +@group + (let (@var{varlist}) + @var{body-of-}@code{let}@dots{} ) +@end group +@end smallexample + +To understand how the @code{or} expression ensures that the argument +@code{buffer} is bound to a buffer and not to the name of a buffer, it +is first necessary to understand the @code{or} function. + +Before doing this, let me rewrite this part of the function using +@code{if} so that you can see what is done in a manner that will be familiar. + +@node if & or, Insert or, insert-buffer body, insert-buffer +@comment node-name, next, previous, up +@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} + +The job to be done is to make sure the value of @code{buffer} is a +buffer itself and not the name of a buffer. If the value is the name, +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. + +@need 800 +In Lisp, you might describe this situation like this: + +@smallexample +@group +(if (not (holding-on-to-guest)) + (find-and-take-arm-of-guest)) +@end group +@end smallexample + +We want to do the same thing with a buffer---if we do not have the +buffer itself, we want to get it. + +@need 1200 +Using a predicate called @code{bufferp} that tells us whether we have a +buffer (rather than its name), we can write the code like this: + +@smallexample +@group +(if (not (bufferp buffer)) ; @r{if-part} + (setq buffer (get-buffer buffer))) ; @r{then-part} +@end group +@end smallexample + +@noindent +Here, the true-or-false-test of the @code{if} expression is +@w{@code{(not (bufferp buffer))}}; and the then-part is the expression +@w{@code{(setq buffer (get-buffer buffer))}}. + +In the test, the function @code{bufferp} returns true if its argument is +a buffer---but false if its argument is the name of the buffer. (The +last character of the function name @code{bufferp} is the character +@samp{p}; as we saw earlier, such use of @samp{p} is a convention that +indicates that the function is a predicate, which is a term that means +that the function will determine whether some property is true or false. +@xref{Wrong Type of Argument, , Using the Wrong Type Object as an +Argument}.) + +@need 1200 +The function @code{not} precedes the expression @code{(bufferp buffer)}, +so the true-or-false-test looks like this: + +@smallexample +(not (bufferp buffer)) +@end smallexample + +@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. + +Using this test, the @code{if} expression works as follows: when the +value of the variable @code{buffer} is actually a buffer rather than +its name, the true-or-false-test returns false and the @code{if} +expression does not evaluate the then-part. This is fine, since we do +not need to do anything to the variable @code{buffer} if it really is +a buffer. + +On the other hand, when the value of @code{buffer} is not a buffer +itself, but the name of a buffer, the true-or-false-test returns true +and the then-part of the expression is evaluated. In this case, the +then-part is @code{(setq buffer (get-buffer buffer))}. This +expression uses the @code{get-buffer} function to return an actual +buffer itself, given its name. The @code{setq} then sets the variable +@code{buffer} to the value of the buffer itself, replacing its previous +value (which was the name of the buffer). + +@node Insert or, Insert let, if & or, insert-buffer +@comment node-name, next, previous, up +@subsection The @code{or} in the Body + +The purpose of the @code{or} expression in the @code{insert-buffer} +function is to ensure that the argument @code{buffer} is bound to a +buffer and not just to the name of a buffer. The previous section shows +how the job could have been done using an @code{if} expression. +However, the @code{insert-buffer} function actually uses @code{or}. +To understand this, it is necessary to understand how @code{or} works. + +@findex or +An @code{or} function can have any number of arguments. It evaluates +each argument in turn and returns the value of the first of its +arguments that is not @code{nil}. Also, and this is a crucial feature +of @code{or}, it does not evaluate any subsequent arguments after +returning the first non-@code{nil} value. + +@need 800 +The @code{or} expression looks like this: + +@smallexample +@group +(or (bufferp buffer) + (setq buffer (get-buffer buffer))) +@end group +@end smallexample + +@noindent +The first argument to @code{or} is the expression @code{(bufferp buffer)}. +This expression returns true (a non-@code{nil} value) if the buffer is +actually a buffer, and not just the name of a buffer. In the @code{or} +expression, if this is the case, the @code{or} expression returns this +true value and does not evaluate the next expression---and this is fine +with us, since we do not want to do anything to the value of +@code{buffer} if it really is a buffer. + +On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, +which it will be if the value of @code{buffer} is the name of a buffer, +the Lisp interpreter evaluates the next element of the @code{or} +expression. This is the expression @code{(setq buffer (get-buffer +buffer))}. This expression returns a non-@code{nil} value, which +is the value to which it sets the variable @code{buffer}---and this +value is a buffer itself, not the name of a buffer. + +The result of all this is that the symbol @code{buffer} is always +bound to a buffer itself rather than to the name of a buffer. All +this is necessary because the @code{set-buffer} function in a +following line only works with a buffer itself, not with the name to a +buffer. + +@need 1250 +Incidentally, using @code{or}, the situation with the usher would be +written like this: + +@smallexample +(or (holding-on-to-guest) (find-and-take-arm-of-guest)) +@end smallexample + +@node Insert let, New insert-buffer, Insert or, insert-buffer +@comment node-name, next, previous, up +@subsection The @code{let} Expression in @code{insert-buffer} + +After ensuring that the variable @code{buffer} refers to a buffer itself +and not just to the name of a buffer, the @code{insert-buffer function} +continues with a @code{let} expression. This specifies three local +variables, @code{start}, @code{end}, and @code{newmark} and binds them +to the initial value @code{nil}. These variables are used inside the +remainder of the @code{let} and temporarily hide any other occurrence of +variables of the same name in Emacs until the end of the @code{let}. + +@need 1200 +The body of the @code{let} contains two @code{save-excursion} +expressions. First, we will look at the inner @code{save-excursion} +expression in detail. The expression looks like this: + +@smallexample +@group +(save-excursion + (set-buffer buffer) + (setq start (point-min) end (point-max))) +@end group +@end smallexample + +@noindent +The expression @code{(set-buffer buffer)} changes Emacs' attention +from the current buffer to the one from which the text will copied. +In that buffer, the variables @code{start} and @code{end} are set to +the beginning and end of the buffer, using the commands +@code{point-min} and @code{point-max}. Note that we have here an +illustration of how @code{setq} is able to set two variables in the +same expression. The first argument of @code{setq} is set to the +value of its second, and its third argument is set to the value of its +fourth. + +After the body of the inner @code{save-excursion} is evaluated, the +@code{save-excursion} restores the original buffer, but @code{start} and +@code{end} remain set to the values of the beginning and end of the +buffer from which the text will be copied. + +@need 1250 +The outer @code{save-excursion} expression looks like this: + +@smallexample +@group +(save-excursion + (@var{inner-}@code{save-excursion}@var{-expression} + (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) + (insert-buffer-substring buffer start end) + (setq newmark (point))) +@end group +@end smallexample + +@noindent +The @code{insert-buffer-substring} function copies the text +@emph{into} the current buffer @emph{from} the region indicated by +@code{start} and @code{end} in @code{buffer}. Since the whole of the +second buffer lies between @code{start} and @code{end}, the whole of +the second buffer is copied into the buffer you are editing. Next, +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. + +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} +variable records the end of the inserted text. In the last line of +the @code{let} expression, the @code{(push-mark newmark)} expression +function sets a mark to this location. (The previous location of the +mark is still accessible; it is recorded on the mark ring and you can +go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is +located at the beginning of the inserted text, which is where it was +before you called the insert function, the position of which was saved +by the first @code{save-excursion}. + +@need 1250 +The whole @code{let} expression looks like this: + +@smallexample +@group +(let (start end newmark) + (save-excursion + (save-excursion + (set-buffer buffer) + (setq start (point-min) end (point-max))) + (insert-buffer-substring buffer start end) + (setq newmark (point))) + (push-mark newmark)) +@end group +@end smallexample + +Like the @code{append-to-buffer} function, the @code{insert-buffer} +function uses @code{let}, @code{save-excursion}, and +@code{set-buffer}. In addition, the function illustrates one way to +use @code{or}. All these functions are building blocks that we will +find and use again and again. + +@node New insert-buffer, , Insert let, insert-buffer +@comment node-name, next, previous, up +@subsection New Body for @code{insert-buffer} +@findex insert-buffer, new version body +@findex new version body for insert-buffer + +The body in the GNU Emacs 22 version is more confusing than the original. + +@need 1250 +It consists of two expressions, + +@smallexample +@group + (push-mark + (save-excursion + (insert-buffer-substring (get-buffer buffer)) + (point))) + + nil +@end group +@end smallexample + +@noindent +except, and this is what confuses novices, very important work is done +inside the @code{push-mark} expression. + +The @code{get-buffer} function returns a buffer with the name +provided. You will note that the function is @emph{not} called +@code{get-buffer-create}; it does not create a buffer if one does not +already exist. The buffer returned by @code{get-buffer}, an existing +buffer, is passed to @code{insert-buffer-substring}, which inserts the +whole of the buffer (since you did not specify anything else). + +The location into which the buffer is inserted is recorded by +@code{push-mark}. Then the function returns @code{nil}, the value of +its last command. Put another way, the @code{insert-buffer} function +exists only to produce a side effect, inserting another buffer, not to +return any value. + +@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex +@comment node-name, next, previous, up +@section Complete Definition of @code{beginning-of-buffer} +@findex beginning-of-buffer + +The basic structure of the @code{beginning-of-buffer} function has +already been discussed. (@xref{simplified-beginning-of-buffer, , A +Simplified @code{beginning-of-buffer} Definition}.) +This section describes the complex part of the definition. + +As previously described, when invoked without an argument, +@code{beginning-of-buffer} moves the cursor to the beginning of the +buffer (in truth, the beginning of the accessible portion of the +buffer), leaving the mark at the previous position. However, when the +command is invoked with a number between one and ten, the function +considers that number to be a fraction of the length of the buffer, +measured in tenths, and Emacs moves the cursor that fraction of the +way from the beginning of the buffer. Thus, you can either call this +function with the key command @kbd{M-<}, which will move the cursor to +the beginning of the buffer, or with a key command such as @kbd{C-u 7 +M-<} which will move the cursor to a point 70% of the way through the +buffer. If a number bigger than ten is used for the argument, it +moves to the end of the buffer. + +The @code{beginning-of-buffer} function can be called with or without an +argument. The use of the argument is optional. + +@menu +* Optional Arguments:: +* beginning-of-buffer opt arg:: Example with optional argument. +* beginning-of-buffer complete:: +@end menu + +@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer +@subsection Optional Arguments + +Unless told otherwise, Lisp expects that a function with an argument in +its function definition will be called with a value for that argument. +If that does not happen, you get an error and a message that says +@samp{Wrong number of arguments}. + +@cindex Optional arguments +@cindex Keyword +@findex optional +However, optional arguments are a feature of Lisp: a particular +@dfn{keyword} is used to tell the Lisp interpreter that an argument is +optional. The keyword is @code{&optional}. (The @samp{&} in front of +@samp{optional} is part of the keyword.) In a function definition, if +an argument follows the keyword @code{&optional}, no value need be +passed to that argument when the function is called. + +@need 1200 +The first line of the function definition of @code{beginning-of-buffer} +therefore looks like this: + +@smallexample +(defun beginning-of-buffer (&optional arg) +@end smallexample + +@need 1250 +In outline, the whole function looks like this: + +@smallexample +@group +(defun beginning-of-buffer (&optional arg) + "@var{documentation}@dots{}" + (interactive "P") + (or (@var{is-the-argument-a-cons-cell} arg) + (and @var{are-both-transient-mark-mode-and-mark-active-true}) + (push-mark)) + (let (@var{determine-size-and-set-it}) + (goto-char + (@var{if-there-is-an-argument} + @var{figure-out-where-to-go} + @var{else-go-to} + (point-min)))) + @var{do-nicety} +@end group +@end smallexample + +The function is similar to the @code{simplified-beginning-of-buffer} +function except that the @code{interactive} expression has @code{"P"} +as an argument and the @code{goto-char} function is followed by an +if-then-else expression that figures out where to put the cursor if +there is an argument that is not a cons cell. + +(Since I do not explain a cons cell for many more chapters, please +consider ignoring the function @code{consp}. @xref{List +Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, +, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference +Manual}.) + +The @code{"P"} in the @code{interactive} expression tells Emacs to +pass a prefix argument, if there is one, to the function in raw form. +A prefix argument is made by typing the @key{META} key followed by a +number, or by typing @kbd{C-u} and then a number. (If you don't type +a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase +@code{"p"} in the @code{interactive} expression causes the function to +convert a prefix arg to a number.) + +The true-or-false-test of the @code{if} expression looks complex, but +it is not: it checks whether @code{arg} has a value that is not +@code{nil} and whether it is a cons cell. (That is what @code{consp} +does; it checks whether its argument is a cons cell.) If @code{arg} +has a value that is not @code{nil} (and is not a cons cell), which +will be the case if @code{beginning-of-buffer} is called with a +numeric argument, then this true-or-false-test will return true and +the then-part of the @code{if} expression will be evaluated. On the +other hand, if @code{beginning-of-buffer} is not called with an +argument, the value of @code{arg} will be @code{nil} and the else-part +of the @code{if} expression will be evaluated. The else-part is +simply @code{point-min}, and when this is the outcome, the whole +@code{goto-char} expression is @code{(goto-char (point-min))}, which +is how we saw the @code{beginning-of-buffer} function in its +simplified form. + +@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer +@subsection @code{beginning-of-buffer} with an Argument + +When @code{beginning-of-buffer} is called with an argument, an +expression is evaluated which calculates what value to pass to +@code{goto-char}. This expression is rather complicated at first sight. +It includes an inner @code{if} expression and much arithmetic. It looks +like this: + +@smallexample +@group +(if (> (buffer-size) 10000) + ;; @r{Avoid overflow for large buffer sizes!} + (* (prefix-numeric-value arg) + (/ size 10)) + (/ + (+ 10 + (* + size (prefix-numeric-value arg))) 10))) +@end group +@end smallexample + +@menu +* Disentangle beginning-of-buffer:: +* Large buffer case:: +* Small buffer case:: +@end menu + +@node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg +@ifnottex +@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} +@end ifnottex + +Like other complex-looking expressions, the conditional expression +within @code{beginning-of-buffer} can be disentangled by looking at it +as parts of a template, in this case, the template for an if-then-else +expression. In skeletal form, the expression looks like this: + +@smallexample +@group +(if (@var{buffer-is-large} + @var{divide-buffer-size-by-10-and-multiply-by-arg} + @var{else-use-alternate-calculation} +@end group +@end smallexample + +The true-or-false-test of this inner @code{if} expression checks the +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 +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. + +There are two cases: if the buffer is large and if it is not. + +@node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg +@comment node-name, next, previous, up +@unnumberedsubsubsec What happens in a large buffer + +In @code{beginning-of-buffer}, the inner @code{if} expression tests +whether the size of the buffer is greater than 10,000 characters. To do +this, it uses the @code{>} function and the computation of @code{size} +that comes from the let expression. + +In the old days, the function @code{buffer-size} was used. Not only +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.) + +@need 800 +The line looks like this: + +@smallexample +(if (> size 10000) +@end smallexample + +@need 1200 +@noindent +When the buffer is large, the then-part of the @code{if} expression is +evaluated. It reads like this (after formatting for easy reading): + +@smallexample +@group +(* + (prefix-numeric-value arg) + (/ size 10)) +@end group +@end smallexample + +@noindent +This expression is a multiplication, with two arguments to the function +@code{*}. + +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 +the arithmetic, a conversion is necessary, and +@code{prefix-numeric-value} does the job. + +@findex / @r{(division)} +@cindex Division +The second argument is @code{(/ size 10)}. This expression divides +the numeric value by ten --- the numeric value of the size of the +accessible portion of the buffer. This produces a number that tells +how many characters make up one tenth of the buffer size. (In Lisp, +@code{/} is used for division, just as @code{*} is used for +multiplication.) + +@need 1200 +In the multiplication expression as a whole, this amount is multiplied +by the value of the prefix argument---the multiplication looks like this: + +@smallexample +@group +(* @var{numeric-value-of-prefix-arg} + @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) +@end group +@end smallexample + +@noindent +If, for example, the prefix argument is @samp{7}, the one-tenth value +will be multiplied by 7 to give a position 70% of the way through. + +@need 1200 +The result of all this is that if the accessible portion of the buffer +is large, the @code{goto-char} expression reads like this: + +@smallexample +@group +(goto-char (* (prefix-numeric-value arg) + (/ size 10))) +@end group +@end smallexample + +This puts the cursor where we want it. + +@node Small buffer case, , Large buffer case, beginning-of-buffer opt arg +@comment node-name, next, previous, up +@unnumberedsubsubsec What happens in a small buffer + +If the buffer contains fewer than 10,000 characters, a slightly +different computation is performed. You might think this is not +necessary, since the first computation could do the job. However, in +a small buffer, the first method may not put the cursor on exactly the +desired line; the second method does a better job. + +@need 800 +The code looks like this: + +@c Keep this on one line. +@smallexample +(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) +@end smallexample + +@need 1200 +@noindent +This is code in which you figure out what happens by discovering how the +functions are embedded in parentheses. It is easier to read if you +reformat it with each expression indented more deeply than its +enclosing expression: + +@smallexample +@group + (/ + (+ 10 + (* + size + (prefix-numeric-value arg))) + 10)) +@end group +@end smallexample + +@need 1200 +@noindent +Looking at parentheses, we see that the innermost operation is +@code{(prefix-numeric-value arg)}, which converts the raw argument to +a number. In the following expression, this number is multiplied by +the size of the accessible portion of the buffer: + +@smallexample +(* size (prefix-numeric-value arg)) +@end smallexample + +@noindent +This multiplication creates a number that may be larger than the size of +the buffer---seven times larger if the argument is 7, for example. Ten +is then added to this number and finally the large number is divided by +ten to provide a value that is one character larger than the percentage +position in the buffer. + +The number that results from all this is passed to @code{goto-char} and +the cursor is moved to that point. + +@need 1500 +@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer +@comment node-name, next, previous, up +@subsection The Complete @code{beginning-of-buffer} + +@need 1000 +Here is the complete text of the @code{beginning-of-buffer} function: +@sp 1 + +@c In GNU Emacs 22 +@smallexample +@group +(defun beginning-of-buffer (&optional arg) + "Move point to the beginning of the buffer; +leave mark at previous position. +With \\[universal-argument] prefix, +do not set mark at previous position. +With numeric arg N, +put point N/10 of the way from the beginning. + +If the buffer is narrowed, +this command uses the beginning and size +of the accessible part of the buffer. +@end group + +@group +Don't use this command in Lisp programs! +\(goto-char (point-min)) is faster +and avoids clobbering the mark." + (interactive "P") + (or (consp arg) + (and transient-mark-mode mark-active) + (push-mark)) +@end group +@group + (let ((size (- (point-max) (point-min)))) + (goto-char (if (and arg (not (consp arg))) + (+ (point-min) + (if (> size 10000) + ;; Avoid overflow for large buffer sizes! + (* (prefix-numeric-value arg) + (/ size 10)) + (/ (+ 10 (* size (prefix-numeric-value arg))) 10))) + (point-min)))) + (if arg (forward-line 1))) +@end group +@end smallexample + +@ignore +From before GNU Emacs 22 +@smallexample +@group +(defun beginning-of-buffer (&optional arg) + "Move point to the beginning of the buffer; +leave mark at previous position. +With arg N, put point N/10 of the way +from the true beginning. +@end group +@group +Don't use this in Lisp programs! +\(goto-char (point-min)) is faster +and does not set the mark." + (interactive "P") + (push-mark) +@end group +@group + (goto-char + (if arg + (if (> (buffer-size) 10000) + ;; @r{Avoid overflow for large buffer sizes!} + (* (prefix-numeric-value arg) + (/ (buffer-size) 10)) +@end group +@group + (/ (+ 10 (* (buffer-size) + (prefix-numeric-value arg))) + 10)) + (point-min))) + (if arg (forward-line 1))) +@end group +@end smallexample +@end ignore + +@noindent +Except for two small points, the previous discussion shows how this +function works. The first point deals with a detail in the +documentation string, and the second point concerns the last line of +the function. + +@need 800 +In the documentation string, there is reference to an expression: + +@smallexample +\\[universal-argument] +@end smallexample + +@noindent +A @samp{\\} is used before the first square bracket of this +expression. This @samp{\\} tells the Lisp interpreter to substitute +whatever key is currently bound to the @samp{[@dots{}]}. In the case +of @code{universal-argument}, that is usually @kbd{C-u}, but it might +be different. (@xref{Documentation Tips, , Tips for Documentation +Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more +information.) + +@need 1200 +Finally, the last line of the @code{beginning-of-buffer} command says +to move point to the beginning of the next line if the command is +invoked with an argument: + +@smallexample +(if arg (forward-line 1))) +@end smallexample + +@noindent +This puts the cursor at the beginning of the first line after the +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. + +@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex +@comment node-name, next, previous, up +@section Review + +Here is a brief summary of some of the topics covered in this chapter. + +@table @code +@item or +Evaluate each argument in sequence, and return the value of the first +argument that is not @code{nil}; if none return a value that is not +@code{nil}, return @code{nil}. In brief, return the first true value +of the arguments; return a true value if one @emph{or} any of the +others are true. + +@item and +Evaluate each argument in sequence, and if any are @code{nil}, return +@code{nil}; if none are @code{nil}, return the value of the last +argument. In brief, return a true value only if all the arguments are +true; return a true value if one @emph{and} each of the others is +true. + +@item &optional +A keyword used to indicate that an argument to a function definition +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 +"P")} to a numeric value. + +@item forward-line +Move point forward to the beginning of the next line, or if the argument +is greater than one, forward that many lines. If it can't move as far +forward as it is supposed to, @code{forward-line} goes forward as far as +it can and then returns a count of the number of additional lines it was +supposed to move but couldn't. + +@item erase-buffer +Delete the entire contents of the current buffer. + +@item bufferp +Return @code{t} if its argument is a buffer; otherwise return @code{nil}. +@end table + +@node optional Exercise, , Second Buffer Related Review, More Complex +@section @code{optional} Argument Exercise + +Write an interactive function with an optional argument that tests +whether its argument, a number, is greater than or equal to, or else, +less than the value of @code{fill-column}, and tells you which, in a +message. However, if you do not pass an argument to the function, use +56 as a default value. + +@node Narrowing & Widening, car cdr & cons, More Complex, Top +@comment node-name, next, previous, up +@chapter Narrowing and Widening +@cindex Focusing attention (narrowing) +@cindex Narrowing +@cindex Widening + +Narrowing is a feature of Emacs that makes it possible for you to focus +on a specific part of a buffer, and work without accidentally changing +other parts. Narrowing is normally disabled since it can confuse +novices. + +@menu +* Narrowing advantages:: The advantages of narrowing +* save-restriction:: The @code{save-restriction} special form. +* what-line:: The number of the line that point is on. +* narrow Exercise:: +@end menu + +@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening +@ifnottex +@unnumberedsec The Advantages of Narrowing +@end ifnottex + +With narrowing, the rest of a buffer is made invisible, as if it weren't +there. This is an advantage if, for example, you want to replace a word +in one part of a buffer but not in another: you narrow to the part you want +and the replacement is carried out only in that section, not in the rest +of the buffer. Searches will only work within a narrowed region, not +outside of one, so if you are fixing a part of a document, you can keep +yourself from accidentally finding parts you do not need to fix by +narrowing just to the region you want. +(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) + +However, narrowing does make the rest of the buffer invisible, which +can scare people who inadvertently invoke narrowing and think they +have deleted a part of their file. Moreover, the @code{undo} command +(which is usually bound to @kbd{C-x u}) does not turn off narrowing +(nor should it), so people can become quite desperate if they do not +know that they can return the rest of a buffer to visibility with the +@code{widen} command. +(The key binding for @code{widen} is @kbd{C-x n w}.) + +Narrowing is just as useful to the Lisp interpreter as to a human. +Often, an Emacs Lisp function is designed to work on just part of a +buffer; or conversely, an Emacs Lisp function needs to work on all of a +buffer that has been narrowed. The @code{what-line} function, for +example, removes the narrowing from a buffer, if it has any narrowing +and when it has finished its job, restores the narrowing to what it was. +On the other hand, the @code{count-lines} function, which is called by +@code{what-line}, uses narrowing to restrict itself to just that portion +of the buffer in which it is interested and then restores the previous +situation. + +@node save-restriction, what-line, Narrowing advantages, Narrowing & Widening +@comment node-name, next, previous, up +@section The @code{save-restriction} Special Form +@findex save-restriction + +In Emacs Lisp, you can use the @code{save-restriction} special form to +keep track of whatever narrowing is in effect, if any. When the Lisp +interpreter meets with @code{save-restriction}, it executes the code +in the body of the @code{save-restriction} expression, and then undoes +any changes to narrowing that the code caused. If, for example, the +buffer is narrowed and the code that follows @code{save-restriction} +gets rid of the narrowing, @code{save-restriction} returns the buffer +to its narrowed region afterwards. In the @code{what-line} command, +any narrowing the buffer may have is undone by the @code{widen} +command that immediately follows the @code{save-restriction} command. +Any original narrowing is restored just before the completion of the +function. + +@need 1250 +The template for a @code{save-restriction} expression is simple: + +@smallexample +@group +(save-restriction + @var{body}@dots{} ) +@end group +@end smallexample + +@noindent +The body of the @code{save-restriction} is one or more expressions that +will be evaluated in sequence by the Lisp interpreter. + +Finally, a point to note: when you use both @code{save-excursion} and +@code{save-restriction}, one right after the other, you should use +@code{save-excursion} outermost. If you write them in reverse order, +you may fail to record narrowing in the buffer to which Emacs switches +after calling @code{save-excursion}. Thus, when written together, +@code{save-excursion} and @code{save-restriction} should be written +like this: + +@smallexample +@group +(save-excursion + (save-restriction + @var{body}@dots{})) +@end group +@end smallexample + +In other circumstances, when not written together, the +@code{save-excursion} and @code{save-restriction} special forms must +be written in the order appropriate to the function. + +@need 1250 +For example, + +@smallexample +@group + (save-restriction + (widen) + (save-excursion + @var{body}@dots{})) +@end group +@end smallexample + +@ignore +Emacs 22 +/usr/local/src/emacs/lisp/simple.el + +(defun what-line () + "Print the current buffer line number and narrowed line number of point." + (interactive) + (let ((start (point-min)) + (n (line-number-at-pos))) + (if (= start 1) + (message "Line %d" n) + (save-excursion + (save-restriction + (widen) + (message "line %d (narrowed line %d)" + (+ n (line-number-at-pos start) -1) n)))))) + +(defun line-number-at-pos (&optional pos) + "Return (narrowed) buffer line number at position POS. +If POS is nil, use current buffer location. +Counting starts at (point-min), so the value refers +to the contents of the accessible portion of the buffer." + (let ((opoint (or pos (point))) start) + (save-excursion + (goto-char (point-min)) + (setq start (point)) + (goto-char opoint) + (forward-line 0) + (1+ (count-lines start (point)))))) + +(defun count-lines (start end) + "Return number of lines between START and END. +This is usually the number of newlines between them, +but can be one more if START is not equal to END +and the greater of them is not at the start of a line." + (save-excursion + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (if (eq selective-display t) + (save-match-data + (let ((done 0)) + (while (re-search-forward "[\n\C-m]" nil t 40) + (setq done (+ 40 done))) + (while (re-search-forward "[\n\C-m]" nil t 1) + (setq done (+ 1 done))) + (goto-char (point-max)) + (if (and (/= start end) + (not (bolp))) + (1+ done) + done))) + (- (buffer-size) (forward-line (buffer-size))))))) +@end ignore + +@node what-line, narrow Exercise, save-restriction, Narrowing & Widening +@comment node-name, next, previous, up +@section @code{what-line} +@findex what-line +@cindex Widening, example of + +The @code{what-line} command tells you the number of the line in which +the cursor is located. The function illustrates the use of the +@code{save-restriction} and @code{save-excursion} commands. Here is the +original text of the function: + +@smallexample +@group +(defun what-line () + "Print the current line number (in the buffer) of point." + (interactive) + (save-restriction + (widen) + (save-excursion + (beginning-of-line) + (message "Line %d" + (1+ (count-lines 1 (point))))))) +@end group +@end smallexample + +(In recent versions of GNU Emacs, the @code{what-line} function has +been expanded to tell you your line number in a narrowed buffer as +well as your line number in a widened buffer. The recent version is +more complex than the version shown here. If you feel adventurous, +you might want to look at it after figuring out how this version +works. You will probably need to use @kbd{C-h f} +(@code{describe-function}). The newer version uses a conditional to +determine whether the buffer has been narrowed. + +(Also, it uses @code{line-number-at-pos}, which among other simple +expressions, such as @code{(goto-char (point-min))}, moves point to +the beginning of the current line with @code{(forward-line 0)} rather +than @code{beginning-of-line}.) + +The @code{what-line} function as shown here has a documentation line +and is interactive, as you would expect. The next two lines use the +functions @code{save-restriction} and @code{widen}. + +The @code{save-restriction} special form notes whatever narrowing is in +effect, if any, in the current buffer and restores that narrowing after +the code in the body of the @code{save-restriction} has been evaluated. + +The @code{save-restriction} special form is followed by @code{widen}. +This function undoes any narrowing the current buffer may have had +when @code{what-line} was called. (The narrowing that was there is +the narrowing that @code{save-restriction} remembers.) This widening +makes it possible for the line counting commands to count from the +beginning of the buffer. Otherwise, they would have been limited to +counting within the accessible region. Any original narrowing is +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} +uses the @code{beginning-of-line} function to move point. + +(Note that the @code{(widen)} expression comes between the +@code{save-restriction} and @code{save-excursion} special forms. When +you write the two @code{save- @dots{}} expressions in sequence, write +@code{save-excursion} outermost.) + +@need 1200 +The last two lines of the @code{what-line} function are functions to +count the number of lines in the buffer and then print the number in the +echo area. + +@smallexample +@group +(message "Line %d" + (1+ (count-lines 1 (point))))))) +@end group +@end smallexample + +The @code{message} function prints a one-line message at the bottom of +the Emacs screen. The first argument is inside of quotation marks and +is printed as a string of characters. However, it may contain a +@samp{%d} expression to print a following argument. @samp{%d} prints +the argument as a decimal, so the message will say something such as +@samp{Line 243}. + +@need 1200 +The number that is printed in place of the @samp{%d} is computed by the +last line of the function: + +@smallexample +(1+ (count-lines 1 (point))) +@end smallexample + +@ignore +GNU Emacs 22 + +(defun count-lines (start end) + "Return number of lines between START and END. +This is usually the number of newlines between them, +but can be one more if START is not equal to END +and the greater of them is not at the start of a line." + (save-excursion + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (if (eq selective-display t) + (save-match-data + (let ((done 0)) + (while (re-search-forward "[\n\C-m]" nil t 40) + (setq done (+ 40 done))) + (while (re-search-forward "[\n\C-m]" nil t 1) + (setq done (+ 1 done))) + (goto-char (point-max)) + (if (and (/= start end) + (not (bolp))) + (1+ done) + done))) + (- (buffer-size) (forward-line (buffer-size))))))) +@end ignore + +@noindent +What this does is count the lines from the first position of the +buffer, indicated by the @code{1}, up to @code{(point)}, and then add +one to that number. (The @code{1+} function adds one to its +argument.) We add one to it because line 2 has only one line before +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 +the original narrowing, if any. + +@node narrow Exercise, , what-line, Narrowing & Widening +@section Exercise with Narrowing + +Write a function that will display the first 60 characters of the +current buffer, even if you have narrowed the buffer to its latter +half so that the first line is inaccessible. Restore point, mark, and +narrowing. For this exercise, you need to use a whole potpourri of +functions, including @code{save-restriction}, @code{widen}, +@code{goto-char}, @code{point-min}, @code{message}, and +@code{buffer-substring}. + +@cindex Properties, mention of @code{buffer-substring-no-properties} +(@code{buffer-substring} is a previously unmentioned function you will +have to investigate yourself; or perhaps you will have to use +@code{buffer-substring-no-properties} or +@code{filter-buffer-substring} @dots{}, yet other functions. Text +properties are a feature otherwise not discussed here. @xref{Text +Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference +Manual}.) + +Additionally, do you really need @code{goto-char} or @code{point-min}? +Or can you write the function without them? + +@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top +@comment node-name, next, previous, up +@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions +@findex car, @r{introduced} +@findex cdr, @r{introduced} + +In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental +functions. The @code{cons} function is used to construct lists, and +the @code{car} and @code{cdr} functions are used to take them apart. + +In the walk through of the @code{copy-region-as-kill} function, we +will see @code{cons} as well as two variants on @code{cdr}, +namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) + +@menu +* Strange Names:: An historical aside: why the strange names? +* car & cdr:: Functions for extracting part of a list. +* cons:: Constructing a list. +* nthcdr:: Calling @code{cdr} repeatedly. +* nth:: +* setcar:: Changing the first element of a list. +* setcdr:: Changing the rest of a list. +* cons Exercise:: +@end menu + +@node Strange Names, car & cdr, car cdr & cons, car cdr & cons +@ifnottex +@unnumberedsec Strange Names +@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 +@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 +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 +years to anyone thinking about Lisp. Nonetheless, although a few +brave scholars have begun to use more reasonable names for these +functions, the old terms are still in use. In particular, since the +terms are used in the Emacs Lisp source code, we will use them in this +introduction. + +@node car & cdr, cons, Strange Names, car cdr & cons +@comment node-name, next, previous, up +@section @code{car} and @code{cdr} + +The @sc{car} of a list is, quite simply, the first item in the list. +Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is +@code{rose}. + +@need 1200 +If you are reading this in Info in GNU Emacs, you can see this by +evaluating the following: + +@smallexample +(car '(rose violet daisy buttercup)) +@end smallexample + +@noindent +After evaluating the expression, @code{rose} will appear in the echo +area. + +Clearly, a more reasonable name for the @code{car} function would be +@code{first} and this is often suggested. + +@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. + +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 +first item. Thus, while the @sc{car} of the list @code{'(rose violet +daisy buttercup)} is @code{rose}, the rest of the list, the value +returned by the @code{cdr} function, is @code{(violet daisy +buttercup)}. + +@need 800 +You can see this by evaluating the following in the usual way: + +@smallexample +(cdr '(rose violet daisy buttercup)) +@end smallexample + +@noindent +When you evaluate this, @code{(violet daisy buttercup)} will appear in +the echo area. + +Like @code{car}, @code{cdr} does not remove any elements from the +list---it just returns a report of what the second and subsequent +elements are. + +Incidentally, in the example, the list of flowers is quoted. If it were +not, the Lisp interpreter would try to evaluate the list by calling +@code{rose} as a function. In this example, we do not want to do that. + +Clearly, a more reasonable name for @code{cdr} would be @code{rest}. + +(There is a lesson here: when you name new functions, consider very +carefully what you are doing, since you may be stuck with the names +for far longer than you expect. The reason this document perpetuates +these names is that the Emacs Lisp source code uses them, and if I did +not use them, you would have a hard time reading the code; but do, +please, try to avoid using these terms yourself. The people who come +after you will be grateful to you.) + +When @code{car} and @code{cdr} are applied to a list made up of symbols, +such as the list @code{(pine fir oak maple)}, the element of the list +returned by the function @code{car} is the symbol @code{pine} without +any parentheses around it. @code{pine} is the first element in the +list. However, the @sc{cdr} of the list is a list itself, @code{(fir +oak maple)}, as you can see by evaluating the following expressions in +the usual way: + +@smallexample +@group +(car '(pine fir oak maple)) + +(cdr '(pine fir oak maple)) +@end group +@end smallexample + +On the other hand, in a list of lists, the first element is itself a +list. @code{car} returns this first element as a list. For example, +the following list contains three sub-lists, a list of carnivores, a +list of herbivores and a list of sea mammals: + +@smallexample +@group +(car '((lion tiger cheetah) + (gazelle antelope zebra) + (whale dolphin seal))) +@end group +@end smallexample + +@noindent +In this example, the first element or @sc{car} of the list is the list of +carnivores, @code{(lion tiger cheetah)}, and the rest of the list is +@code{((gazelle antelope zebra) (whale dolphin seal))}. + +@smallexample +@group +(cdr '((lion tiger cheetah) + (gazelle antelope zebra) + (whale dolphin seal))) +@end group +@end smallexample + +It is worth saying again that @code{car} and @code{cdr} are +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 +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 +@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. +Conversely, the other fundamental function, @code{cons}, can put +together or construct a list, but not an array. (Arrays are handled +by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU +Emacs Lisp Reference Manual}.) + +@node cons, nthcdr, car & cdr, car cdr & cons +@comment node-name, next, previous, up +@section @code{cons} +@findex cons, @r{introduced} + +The @code{cons} function constructs lists; it is the inverse of +@code{car} and @code{cdr}. For example, @code{cons} can be used to make +a four element list from the three element list, @code{(fir oak maple)}: + +@smallexample +(cons 'pine '(fir oak maple)) +@end smallexample + +@need 800 +@noindent +After evaluating this list, you will see + +@smallexample +(pine fir oak maple) +@end smallexample + +@noindent +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 +phrasing can be misleading, since @code{cons} does not change an +existing list, but creates a new one. + +Like @code{car} and @code{cdr}, @code{cons} is non-destructive. + +@menu +* Build a list:: +* length:: How to find the length of a list. +@end menu + +@node Build a list, length, cons, cons +@ifnottex +@unnumberedsubsec Build a list +@end ifnottex + +@code{cons} must have a list to attach to.@footnote{Actually, you can +@code{cons} an element to an atom to produce a dotted pair. Dotted +pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted +Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You +cannot start from absolutely nothing. If you are building a list, you +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'. + +@smallexample +@group +(cons 'buttercup ()) + @result{} (buttercup) +@end group + +@group +(cons 'daisy '(buttercup)) + @result{} (daisy buttercup) +@end group + +@group +(cons 'violet '(daisy buttercup)) + @result{} (violet daisy buttercup) +@end group + +@group +(cons 'rose '(violet daisy buttercup)) + @result{} (rose violet daisy buttercup) +@end group +@end smallexample + +@noindent +In the first example, the empty list is shown as @code{()} and a list +made up of @code{buttercup} followed by the empty list is constructed. +As you can see, the empty list is not shown in the list that was +constructed. All that you see is @code{(buttercup)}. The empty list is +not counted as an element of a list because there is nothing in an empty +list. Generally speaking, an empty list is invisible. + +The second example, @code{(cons 'daisy '(buttercup))} constructs a new, +two element list by putting @code{daisy} in front of @code{buttercup}; +and the third example constructs a three element list by putting +@code{violet} in front of @code{daisy} and @code{buttercup}. + +@node length, , Build a list, cons +@comment node-name, next, previous, up +@subsection Find the Length of a List: @code{length} +@findex length + +You can find out how many elements there are in a list by using the Lisp +function @code{length}, as in the following examples: + +@smallexample +@group +(length '(buttercup)) + @result{} 1 +@end group + +@group +(length '(daisy buttercup)) + @result{} 2 +@end group + +@group +(length (cons 'violet '(daisy buttercup))) + @result{} 3 +@end group +@end smallexample + +@noindent +In the third example, the @code{cons} function is used to construct a +three element list which is then passed to the @code{length} function as +its argument. + +@need 1200 +We can also use @code{length} to count the number of elements in an +empty list: + +@smallexample +@group +(length ()) + @result{} 0 +@end group +@end smallexample + +@noindent +As you would expect, the number of elements in an empty list is zero. + +An interesting experiment is to find out what happens if you try to find +the length of no list at all; that is, if you try to call @code{length} +without giving it an argument, not even an empty list: + +@smallexample +(length ) +@end smallexample + +@need 800 +@noindent +What you see, if you evaluate this, is the error message + +@smallexample +Lisp error: (wrong-number-of-arguments length 0) +@end smallexample + +@noindent +This means that the function receives the wrong number of +arguments, zero, when it expects some other number of arguments. In +this case, one argument is expected, the argument being a list whose +length the function is measuring. (Note that @emph{one} list is +@emph{one} argument, even if the list has many elements inside it.) + +The part of the error message that says @samp{length} is the name of +the function. + +@ignore +@code{length} is still a subroutine, but you need C-h f to discover that. + +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 + Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more + about subroutines. +@end ignore + +@node nthcdr, nth, cons, car cdr & cons +@comment node-name, next, previous, up +@section @code{nthcdr} +@findex nthcdr + +The @code{nthcdr} function is associated with the @code{cdr} function. +What it does is take the @sc{cdr} of a list repeatedly. + +If you take the @sc{cdr} of the list @code{(pine fir +oak maple)}, you will be returned the list @code{(fir oak maple)}. If you +repeat this on what was returned, you will be returned the list +@code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original +list will just give you the original @sc{cdr} since the function does +not change the list. You need to evaluate the @sc{cdr} of the +@sc{cdr} and so on.) If you continue this, eventually you will be +returned an empty list, which in this case, instead of being shown as +@code{()} is shown as @code{nil}. + +@need 1200 +For review, here is a series of repeated @sc{cdr}s, the text following +the @samp{@result{}} shows what is returned. + +@smallexample +@group +(cdr '(pine fir oak maple)) + @result{}(fir oak maple) +@end group + +@group +(cdr '(fir oak maple)) + @result{} (oak maple) +@end group + +@group +(cdr '(oak maple)) + @result{}(maple) +@end group + +@group +(cdr '(maple)) + @result{} nil +@end group + +@group +(cdr 'nil) + @result{} nil +@end group + +@group +(cdr ()) + @result{} nil +@end group +@end smallexample + +@need 1200 +You can also do several @sc{cdr}s without printing the values in +between, like this: + +@smallexample +@group +(cdr (cdr '(pine fir oak maple))) + @result{} (oak maple) +@end group +@end smallexample + +@noindent +In this example, the Lisp interpreter evaluates the innermost list first. +The innermost list is quoted, so it just passes the list as it is to the +innermost @code{cdr}. This @code{cdr} passes a list made up of the +second and subsequent elements of the list to the outermost @code{cdr}, +which produces a list composed of the third and subsequent elements of +the original list. In this example, the @code{cdr} function is repeated +and returns a list that consists of the original list without its +first two elements. + +The @code{nthcdr} function does the same as repeating the call to +@code{cdr}. In the following example, the argument 2 is passed to the +function @code{nthcdr}, along with the list, and the value returned is +the list without its first two items, which is exactly the same +as repeating @code{cdr} twice on the list: + +@smallexample +@group +(nthcdr 2 '(pine fir oak maple)) + @result{} (oak maple) +@end group +@end smallexample + +@need 1200 +Using the original four element list, we can see what happens when +various numeric arguments are passed to @code{nthcdr}, including 0, 1, +and 5: + +@smallexample +@group +;; @r{Leave the list as it was.} +(nthcdr 0 '(pine fir oak maple)) + @result{} (pine fir oak maple) +@end group + +@group +;; @r{Return a copy without the first element.} +(nthcdr 1 '(pine fir oak maple)) + @result{} (fir oak maple) +@end group + +@group +;; @r{Return a copy of the list without three elements.} +(nthcdr 3 '(pine fir oak maple)) + @result{} (maple) +@end group + +@group +;; @r{Return a copy lacking all four elements.} +(nthcdr 4 '(pine fir oak maple)) + @result{} nil +@end group + +@group +;; @r{Return a copy lacking all elements.} +(nthcdr 5 '(pine fir oak maple)) + @result{} nil +@end group +@end smallexample + +@node nth, setcar, nthcdr, car cdr & cons +@comment node-name, next, previous, up +@section @code{nth} +@findex nth + +The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly. +The @code{nth} function takes the @sc{car} of the result returned by +@code{nthcdr}. It returns the Nth element of the list. + +@need 1500 +Thus, if it were not defined in C for speed, the definition of +@code{nth} would be: + +@smallexample +@group +(defun nth (n list) + "Returns the Nth element of LIST. +N counts from zero. If LIST is not that long, nil is returned." + (car (nthcdr n list))) +@end group +@end smallexample + +@noindent +(Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el}, +but its definition was redone in C in the 1980s.) + +The @code{nth} function returns a single element of a list. +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 +are accustomed to the first element in a list being number one, which +is `one-based'. + +@need 1250 +For example: + +@smallexample +@group +(nth 0 '("one" "two" "three")) + @result{} "one" + +(nth 1 '("one" "two" "three")) + @result{} "two" +@end group +@end smallexample + +It is worth mentioning that @code{nth}, like @code{nthcdr} and +@code{cdr}, does not change the original list---the function is +non-destructive. This is in sharp contrast to the @code{setcar} and +@code{setcdr} functions. + +@node setcar, setcdr, nth, car cdr & cons +@comment node-name, next, previous, up +@section @code{setcar} +@findex setcar + +As you might guess from their names, the @code{setcar} and @code{setcdr} +functions set the @sc{car} or the @sc{cdr} of a list to a new value. +They actually change the original list, unlike @code{car} and @code{cdr} +which leave the original list as it was. One way to find out how this +works is to experiment. We will start with the @code{setcar} function. + +@need 1200 +First, we can make a list and then set the value of a variable to the +list, using the @code{setq} function. Here is a list of animals: + +@smallexample +(setq animals '(antelope giraffe lion tiger)) +@end smallexample + +@noindent +If you are reading this in Info inside of GNU Emacs, you can evaluate +this expression in the usual fashion, by positioning the cursor after +the expression and typing @kbd{C-x C-e}. (I'm doing this right here +as I write this. This is one of the advantages of having the +interpreter built into the computing environment. Incidentally, when +there is nothing on the line after the final parentheses, such as a +comment, point can be on the next line. Thus, if your cursor is in +the first column of the next line, you do not need to move it. +Indeed, Emacs permits any amount of white space after the final +parenthesis.) + +@need 1200 +When we evaluate the variable @code{animals}, we see that it is bound to +the list @code{(antelope giraffe lion tiger)}: + +@smallexample +@group +animals + @result{} (antelope giraffe lion tiger) +@end group +@end smallexample + +@noindent +Put another way, the variable @code{animals} points to the list +@code{(antelope giraffe lion tiger)}. + +Next, evaluate the function @code{setcar} while passing it two +arguments, the variable @code{animals} and the quoted symbol +@code{hippopotamus}; this is done by writing the three element list +@code{(setcar animals 'hippopotamus)} and then evaluating it in the +usual fashion: + +@smallexample +(setcar animals 'hippopotamus) +@end smallexample + +@need 1200 +@noindent +After evaluating this expression, evaluate the variable @code{animals} +again. You will see that the list of animals has changed: + +@smallexample +@group +animals + @result{} (hippopotamus giraffe lion tiger) +@end group +@end smallexample + +@noindent +The first element on the list, @code{antelope} is replaced by +@code{hippopotamus}. + +So we can see that @code{setcar} did not add a new element to the list +as @code{cons} would have; it replaced @code{antelope} with +@code{hippopotamus}; it @emph{changed} the list. + +@node setcdr, cons Exercise, setcar, car cdr & cons +@comment node-name, next, previous, up +@section @code{setcdr} +@findex setcdr + +The @code{setcdr} function is similar to the @code{setcar} function, +except that the function replaces the second and subsequent elements of +a list rather than the first element. + +(To see how to change the last element of a list, look ahead to +@ref{kill-new function, , The @code{kill-new} function}, which uses +the @code{nthcdr} and @code{setcdr} functions.) + +@need 1200 +To see how this works, set the value of the variable to a list of +domesticated animals by evaluating the following expression: + +@smallexample +(setq domesticated-animals '(horse cow sheep goat)) +@end smallexample + +@need 1200 +@noindent +If you now evaluate the list, you will be returned the list +@code{(horse cow sheep goat)}: + +@smallexample +@group +domesticated-animals + @result{} (horse cow sheep goat) +@end group +@end smallexample + +@need 1200 +Next, evaluate @code{setcdr} with two arguments, the name of the +variable which has a list as its value, and the list to which the +@sc{cdr} of the first list will be set; + +@smallexample +(setcdr domesticated-animals '(cat dog)) +@end smallexample + +@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 +evaluating the variable @code{domesticated-animals}: + +@smallexample +@group +domesticated-animals + @result{} (horse cat dog) +@end group +@end smallexample + +@noindent +Indeed, the list is changed from @code{(horse cow sheep goat)} to +@code{(horse cat dog)}. The @sc{cdr} of the list is changed from +@code{(cow sheep goat)} to @code{(cat dog)}. + +@node cons Exercise, , setcdr, car cdr & cons +@section Exercise + +Construct a list of four birds by evaluating several expressions with +@code{cons}. Find out what happens when you @code{cons} a list onto +itself. Replace the first element of the list of four birds with a +fish. Replace the rest of that list with a list of other fish. + +@node Cutting & Storing Text, List Implementation, car cdr & cons, Top +@comment node-name, next, previous, up +@chapter Cutting and Storing Text +@cindex Cutting and storing text +@cindex Storing and cutting text +@cindex Killing text +@cindex Clipping text +@cindex Erasing text +@cindex Deleting text + +Whenever you cut or clip text out of a buffer with a `kill' command in +GNU Emacs, it is stored in a list and you can bring it back with a +`yank' command. + +(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 +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'.) + +@menu +* Storing Text:: Text is stored in a list. +* zap-to-char:: Cutting out text up to a character. +* kill-region:: Cutting text out of a region. +* copy-region-as-kill:: A definition for copying text. +* Digression into C:: Minor note on C programming language macros. +* defvar:: How to give a variable an initial value. +* cons & search-fwd Review:: +* search Exercises:: +@end menu + +@node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text +@ifnottex +@unnumberedsec Storing Text in a List +@end ifnottex + +When text is cut out of a buffer, it is stored on a list. Successive +pieces of text are stored on the list successively, so the list might +look like this: + +@smallexample +("a piece of text" "previous piece") +@end smallexample + +@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 +this: + +@smallexample +@group +(cons "another piece" + '("a piece of text" "previous piece")) +@end group +@end smallexample + +@need 1200 +@noindent +If you evaluate this expression, a list of three elements will appear in +the echo area: + +@smallexample +("another piece" "a piece of text" "previous piece") +@end smallexample + +With the @code{car} and @code{nthcdr} functions, you can retrieve +whichever piece of text you want. For example, in the following code, +@code{nthcdr 1 @dots{}} returns the list with the first item removed; +and the @code{car} returns the first element of that remainder---the +second element of the original list: + +@smallexample +@group +(car (nthcdr 1 '("another piece" + "a piece of text" + "previous piece"))) + @result{} "a piece of text" +@end group +@end smallexample + +The actual functions in Emacs are more complex than this, of course. +The code for cutting and retrieving text has to be written so that +Emacs can figure out which element in the list you want---the first, +second, third, or whatever. In addition, when you get to the end of +the list, Emacs should give you the first element of the list, rather +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 +manipulates the kill ring. Thus, before reaching the mountains, we +climb the foothills. + +A subsequent chapter describes how text that is cut from the buffer is +retrieved. @xref{Yanking, , Yanking Text Back}. + +@node zap-to-char, kill-region, Storing Text, Cutting & Storing Text +@comment node-name, next, previous, up +@section @code{zap-to-char} +@findex zap-to-char + +The @code{zap-to-char} function changed little between GNU Emacs +version 19 and GNU Emacs version 22. However, @code{zap-to-char} +calls another function, @code{kill-region}, which enjoyed a major +rewrite. + +The @code{kill-region} function in Emacs 19 is complex, but does not +use code that is important at this time. We will skip it. + +The @code{kill-region} function in Emacs 22 is easier to read than the +same function in Emacs 19 and introduces a very important concept, +that of error handling. We will walk through the function. + +But first, let us look at the interactive @code{zap-to-char} function. + +@menu +* Complete zap-to-char:: The complete implementation. +* zap-to-char interactive:: A three part interactive expression. +* zap-to-char body:: A short overview. +* search-forward:: How to search for a string. +* progn:: The @code{progn} special form. +* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. +@end menu + +@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char +@ifnottex +@unnumberedsubsec The Complete @code{zap-to-char} Implementation +@end ifnottex + +The @code{zap-to-char} function removes the text in the region between +the location of the cursor (i.e., of point) up to and including the +next occurrence of a specified character. The text that +@code{zap-to-char} removes is put in the kill ring; and it can be +retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If +the command is given an argument, it removes text through that number +of occurrences. Thus, if the cursor were at the beginning of this +sentence and the character were @samp{s}, @samp{Thus} would be +removed. If the argument were two, @samp{Thus, if the curs} would be +removed, up to and including the @samp{s} in @samp{cursor}. + +If the specified character is not found, @code{zap-to-char} will say +``Search failed'', tell you the character you typed, and not remove +any text. + +In order to determine how much text to remove, @code{zap-to-char} uses +a search function. Searches are used extensively in code that +manipulates text, and we will focus attention on them as well as on the +deletion command. + +@ignore +@c GNU Emacs version 19 +(defun zap-to-char (arg char) ; version 19 implementation + "Kill up to and including ARG'th occurrence of CHAR. +Goes backward if ARG is negative; error if CHAR not found." + (interactive "*p\ncZap to char: ") + (kill-region (point) + (progn + (search-forward + (char-to-string char) nil nil arg) + (point)))) +@end ignore + +@need 1250 +Here is the complete text of the version 22 implementation of the function: + +@c GNU Emacs 22 +@smallexample +@group +(defun zap-to-char (arg char) + "Kill up to and including ARG'th occurrence of CHAR. +Case is ignored if `case-fold-search' is non-nil in the current buffer. +Goes backward if ARG is negative; error if CHAR not found." + (interactive "p\ncZap to char: ") + (if (char-table-p translation-table-for-input) + (setq char (or (aref translation-table-for-input char) char))) + (kill-region (point) (progn + (search-forward (char-to-string char) nil nil arg) + (point)))) +@end group +@end smallexample + +The documentation is thorough. You do need to know the jargon meaning +of the word `kill'. + +@node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char +@comment node-name, next, previous, up +@subsection The @code{interactive} Expression + +@need 800 +The interactive expression in the @code{zap-to-char} command looks like +this: + +@smallexample +(interactive "p\ncZap to char: ") +@end smallexample + +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 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. + +The second part of @code{"p\ncZap to char:@: "} is +@samp{cZap to char:@: }. In this part, the lower case @samp{c} +indicates that @code{interactive} expects a prompt and that the +argument will be a character. The prompt follows the @samp{c} and is +the string @samp{Zap to char:@: } (with a space after the colon to +make it look good). + +What all this does is prepare the arguments to @code{zap-to-char} so they +are of the right type, and give the user a prompt. + +In a read-only buffer, the @code{zap-to-char} function copies the text +to the kill ring, but does not remove it. The echo area displays a +message saying that the buffer is read-only. Also, the terminal may +beep or blink at you. + +@node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char +@comment node-name, next, previous, up +@subsection The Body of @code{zap-to-char} + +The body of the @code{zap-to-char} function contains the code that +kills (that is, removes) the text in the region from the current +position of the cursor up to and including the specified character. + +The first part of the code looks like this: + +@smallexample +(if (char-table-p translation-table-for-input) + (setq char (or (aref translation-table-for-input char) char))) +(kill-region (point) (progn + (search-forward (char-to-string char) nil nil arg) + (point))) +@end smallexample + +@noindent +@code{char-table-p} is an hitherto unseen function. It determines +whether its argument is a character table. When it is, it sets the +character passed to @code{zap-to-char} to one of them, if that +character exists, or to the character itself. (This becomes important +for certain characters in non-European languages. The @code{aref} +function extracts an element from an array. It is an array-specific +function that is not described in this document. @xref{Arrays, , +Arrays, elisp, The GNU Emacs Lisp Reference Manual}.) + +@noindent +@code{(point)} is the current position of the cursor. + +The next part of the code is an expression using @code{progn}. The body +of the @code{progn} consists of calls to @code{search-forward} and +@code{point}. + +It is easier to understand how @code{progn} works after learning about +@code{search-forward}, so we will look at @code{search-forward} and +then at @code{progn}. + +@node search-forward, progn, zap-to-char body, zap-to-char +@comment node-name, next, previous, up +@subsection The @code{search-forward} Function +@findex search-forward + +The @code{search-forward} function is used to locate the +zapped-for-character in @code{zap-to-char}. If the search is +successful, @code{search-forward} leaves point immediately after the +last character in the target string. (In @code{zap-to-char}, the +target string is just one character long. @code{zap-to-char} uses the +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'.) + +@need 1250 +In @code{zap-to-char}, the @code{search-forward} function looks like this: + +@smallexample +(search-forward (char-to-string char) nil nil arg) +@end smallexample + +The @code{search-forward} function takes four arguments: + +@enumerate +@item +The first argument is the target, what is searched for. This must be a +string, such as @samp{"z"}. + +As it happens, the argument passed to @code{zap-to-char} is a single +character. Because of the way computers are built, the Lisp +interpreter may treat a single character as being different from a +string of characters. Inside the computer, a single character has a +different electronic format than a string of one character. (A single +character can often be recorded in the computer using exactly one +byte; but a string may be longer, and the computer needs to be ready +for this.) Since the @code{search-forward} function searches for a +string, the character that the @code{zap-to-char} function receives as +its argument must be converted inside the computer from one format to +the other; otherwise the @code{search-forward} function will fail. +The @code{char-to-string} function is used to make this conversion. + +@item +The second argument bounds the search; it is specified as a position in +the buffer. In this case, the search can go to the end of the buffer, +so no bound is set and the second argument is @code{nil}. + +@item +The third argument tells the function what it should do if the search +fails---it can signal an error (and print a message) or it can return +@code{nil}. A @code{nil} as the third argument causes the function to +signal an error when the search fails. + +@item +The fourth argument to @code{search-forward} is the repeat count---how +many occurrences of the string to look for. This argument is optional +and if the function is called without a repeat count, this argument is +passed the value 1. If this argument is negative, the search goes +backwards. +@end enumerate + +@need 800 +In template form, a @code{search-forward} expression looks like this: + +@smallexample +@group +(search-forward "@var{target-string}" + @var{limit-of-search} + @var{what-to-do-if-search-fails} + @var{repeat-count}) +@end group +@end smallexample + +We will look at @code{progn} next. + +@node progn, Summing up zap-to-char, search-forward, zap-to-char +@comment node-name, next, previous, up +@subsection The @code{progn} Special Form +@findex progn + +@code{progn} is a special form that causes each of its arguments to be +evaluated in sequence and then returns the value of the last one. The +preceding expressions are evaluated only for the side effects they +perform. The values produced by them are discarded. + +@need 800 +The template for a @code{progn} expression is very simple: + +@smallexample +@group +(progn + @var{body}@dots{}) +@end group +@end smallexample + +In @code{zap-to-char}, the @code{progn} expression has to do two things: +put point in exactly the right position; and return the location of +point so that @code{kill-region} will know how far to kill to. + +The first argument to the @code{progn} is @code{search-forward}. When +@code{search-forward} finds the string, the function leaves point +immediately after the last character in the target string. (In this +case the target string is just one character long.) If the search is +backwards, @code{search-forward} leaves point just before the first +character in the target. The movement of point is a side effect. + +The second and last argument to @code{progn} is the expression +@code{(point)}. This expression returns the value of point, which in +this case will be the location to which it has been moved by +@code{search-forward}. (In the source, a line that tells the function +to go to the previous character, if it is going forward, was commented +out in 1999; I don't remember whether that feature or mis-feature was +ever a part of the distributed source.) The value of @code{point} is +returned by the @code{progn} expression and is passed to +@code{kill-region} as @code{kill-region}'s second argument. + +@node Summing up zap-to-char, , progn, zap-to-char +@comment node-name, next, previous, up +@subsection Summing up @code{zap-to-char} + +Now that we have seen how @code{search-forward} and @code{progn} work, +we can see how the @code{zap-to-char} function works as a whole. + +The first argument to @code{kill-region} is the position of the cursor +when the @code{zap-to-char} command is given---the value of point at +that time. Within the @code{progn}, the search function then moves +point to just after the zapped-to-character and @code{point} returns the +value of this location. The @code{kill-region} function puts together +these two values of point, the first one as the beginning of the region +and the second one as the end of the region, and removes the region. + +The @code{progn} special form is necessary because the +@code{kill-region} command takes two arguments; and it would fail if +@code{search-forward} and @code{point} expressions were written in +sequence as two additional arguments. The @code{progn} expression is +a single argument to @code{kill-region} and returns the one value that +@code{kill-region} needs for its second argument. + +@node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text +@comment node-name, next, previous, up +@section @code{kill-region} +@findex kill-region + +The @code{zap-to-char} function uses the @code{kill-region} function. +This function clips text from a region and copies that text to +the kill ring, from which it may be retrieved. + +@ignore +GNU Emacs 22: + +(defun kill-region (beg end &optional yank-handler) + "Kill (\"cut\") text between point and mark. +This deletes the text from the buffer and saves it in the kill ring. +The command \\[yank] can retrieve it from there. +\(If you want to kill and then yank immediately, use \\[kill-ring-save].) + +If you want to append the killed region to the last killed text, +use \\[append-next-kill] before \\[kill-region]. + +If the buffer is read-only, Emacs will beep and refrain from deleting +the text, but put the text in the kill ring anyway. This means that +you can use the killing commands to copy text from a read-only buffer. + +This is the primitive for programs to kill text (as opposed to deleting it). +Supply two arguments, character positions indicating the stretch of text + to be killed. +Any command that calls this function is a \"kill command\". +If the previous command was also a kill command, +the text killed this time appends to the text killed last time +to make one entry in the kill ring. + +In Lisp code, optional third arg YANK-HANDLER, if non-nil, +specifies the yank-handler text property to be set on the killed +text. See `insert-for-yank'." + ;; Pass point first, then mark, because the order matters + ;; when calling kill-append. + (interactive (list (point) (mark))) + (unless (and beg end) + (error "The mark is not set now, so there is no region")) + (condition-case nil + (let ((string (filter-buffer-substring beg end t))) + (when string ;STRING is nil if BEG = END + ;; Add that string to the kill ring, one way or another. + (if (eq last-command 'kill-region) + (kill-append string (< end beg) yank-handler) + (kill-new string nil yank-handler))) + (when (or string (eq last-command 'kill-region)) + (setq this-command 'kill-region)) + nil) + ((buffer-read-only text-read-only) + ;; The code above failed because the buffer, or some of the characters + ;; in the region, are read-only. + ;; We should beep, in case the user just isn't aware of this. + ;; However, there's no harm in putting + ;; the region's text in the kill ring, anyway. + (copy-region-as-kill beg end) + ;; Set this-command now, so it will be set even if we get an error. + (setq this-command 'kill-region) + ;; This should barf, if appropriate, and give us the correct error. + (if kill-read-only-ok + (progn (message "Read only text copied to kill ring") nil) + ;; Signal an error if the buffer is read-only. + (barf-if-buffer-read-only) + ;; If the buffer isn't read-only, the text is. + (signal 'text-read-only (list (current-buffer))))))) +@end ignore + +The Emacs 22 version of that function uses @code{condition-case} and +@code{copy-region-as-kill}, both of which we will explain. +@code{condition-case} is an important special form. + +In essence, the @code{kill-region} function calls +@code{condition-case}, which takes three arguments. In this function, +the first argument does nothing. The second argument contains the +code that does the work when all goes well. The third argument +contains the code that is called in the event of an error. + +@menu +* Complete kill-region:: The function definition. +* condition-case:: Dealing with a problem. +* Lisp macro:: +@end menu + +@node Complete kill-region, condition-case, kill-region, kill-region +@ifnottex +@unnumberedsubsec The Complete @code{kill-region} Definition +@end ifnottex + +@need 1200 +We will go through the @code{condition-case} code in a moment. First, +let us look at the definition of @code{kill-region}, with comments +added: + +@c GNU Emacs 22: +@smallexample +@group +(defun kill-region (beg end) + "Kill (\"cut\") text between point and mark. +This deletes the text from the buffer and saves it in the kill ring. +The command \\[yank] can retrieve it from there. @dots{} " +@end group + +@group + ;; @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 (and beg end) + (error "The mark is not set now, so there is no region")) +@end group + +@group + ;; @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. + (condition-case nil +@end group + +@group + ;; @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 + ;; and tests whether it exists. If so (that is what the + ;; `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 + ;; the previous text; if not, then a different function, + ;; `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 + ;; item in the kill ring. +@end group + +@group + ;; `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 + ;; condition is true, then it sets the current command to + ;; be `kill-region'. +@end group +@group + (let ((string (filter-buffer-substring beg end t))) + (when string ;STRING is nil if BEG = END + ;; Add that string to the kill ring, one way or another. + (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'. + (kill-append string (< end beg) yank-handler) + (kill-new string nil yank-handler))) + (when (or string (eq last-command 'kill-region)) + (setq this-command 'kill-region)) + nil) +@end group + +@group + ;; @bullet{} The third argument to `condition-case' tells the interpreter + ;; what to do with an error. +@end group +@group + ;; The third argument has a conditions part and a body part. + ;; If the conditions are met (in this case, + ;; if text or buffer are read-only) + ;; then the body is executed. +@end group +@group + ;; The first part of the third argument is the following: + ((buffer-read-only text-read-only) ;; the if-part + ;; @dots{} the then-part + (copy-region-as-kill beg end) +@end group +@group + ;; Next, also as part of the then-part, set this-command, so + ;; it will be set in an error + (setq this-command 'kill-region) + ;; Finally, in the then-part, send a message if you may copy + ;; the text to the kill ring without signally an error, but + ;; don't if you may not. +@end group +@group + (if kill-read-only-ok + (progn (message "Read only text copied to kill ring") nil) + (barf-if-buffer-read-only) + ;; If the buffer isn't read-only, the text is. + (signal 'text-read-only (list (current-buffer))))) +@end group +@end smallexample + +@ignore +@c v 21 +@smallexample +@group +(defun kill-region (beg end) + "Kill between point and mark. +The text is deleted but saved in the kill ring." + (interactive "r") +@end group + +@group + ;; 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. + (condition-case nil +@end group + +@group + ;; 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 + ;; work. If the beginning and ending of the region are both + ;; 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 + ;; 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. + (when string + (if (eq last-command 'kill-region) + ;; if true, prepend string + (kill-append string (< end beg)) + (kill-new string))) + (setq this-command 'kill-region)) +@end group + +@group + ;; 3. The third argument to `condition-case' tells the interpreter + ;; what to do with an error. +@end group +@group + ;; The third argument has a conditions part and a body part. + ;; If the conditions are met (in this case, + ;; if text or buffer are read-only) + ;; then the body is executed. +@end group +@group + ((buffer-read-only text-read-only) ;; this is the if-part + ;; then... + (copy-region-as-kill beg end) +@end group +@group + (if kill-read-only-ok ;; usually this variable is nil + (message "Read only text copied to kill ring") + ;; or else, signal an error if the buffer is read-only; + (barf-if-buffer-read-only) + ;; and, in any case, signal that the text is read-only. + (signal 'text-read-only (list (current-buffer))))))) +@end group +@end smallexample +@end ignore + +@node condition-case, Lisp macro, Complete kill-region, kill-region +@comment node-name, next, previous, up +@subsection @code{condition-case} +@findex condition-case + +As we have seen earlier (@pxref{Making Errors, , Generate an Error +Message}), when the Emacs Lisp interpreter has trouble evaluating an +expression, it provides you with help; in the jargon, this is called +``signaling an error''. Usually, the computer stops the program and +shows you a message. + +However, some programs undertake complicated actions. They should not +simply stop on an error. In the @code{kill-region} function, the most +likely error is that you will try to kill text that is read-only and +cannot be removed. So the @code{kill-region} function contains code +to handle this circumstance. This code, which makes up the body of +the @code{kill-region} function, is inside of a @code{condition-case} +special form. + +@need 800 +The template for @code{condition-case} looks like this: + +@smallexample +@group +(condition-case + @var{var} + @var{bodyform} + @var{error-handler}@dots{}) +@end group +@end smallexample + +The second argument, @var{bodyform}, is straightforward. The +@code{condition-case} special form causes the Lisp interpreter to +evaluate the code in @var{bodyform}. If no error occurs, the special +form returns the code's value and produces the side-effects, if any. + +In short, the @var{bodyform} part of a @code{condition-case} +expression determines what should happen when everything works +correctly. + +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 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} +part of the error handler is run. + +As you will expect, the @var{condition-name} part of an error handler +may be either a single condition name or a list of condition names. + +Also, a complete @code{condition-case} expression may contain more +than one error handler. When an error occurs, the first applicable +handler is run. + +Lastly, the first argument to the @code{condition-case} expression, +the @var{var} argument, is sometimes bound to a variable that +contains information about the error. However, if that argument is +nil, as is the case in @code{kill-region}, that information is +discarded. + +@need 1200 +In brief, in the @code{kill-region} function, the code +@code{condition-case} works like this: + +@smallexample +@group +@var{If no errors}, @var{run only this code} + @var{but}, @var{if errors}, @var{run this other code}. +@end group +@end smallexample + +@ignore +2006 Oct 24 +In Emacs 22, +copy-region-as-kill is short, 12 lines, and uses +filter-buffer-substring, which is longer, 39 lines +and has delete-and-extract-region in it. +delete-and-extract-region is written in C. + +see Initializing a Variable with @code{defvar} +this is line 8054 +Initializing a Variable with @code{defvar} includes line 8350 +@end ignore + +@node Lisp macro, , condition-case, kill-region +@comment node-name, next, previous, up +@subsection Lisp macro +@cindex Macro, lisp +@cindex Lisp macro + +The part of the @code{condition-case} expression that is evaluated in +the expectation that all goes well has a @code{when}. The code uses +@code{when} to determine whether the @code{string} variable points to +text that exists. + +A @code{when} expression is simply a programmers' convenience. It is +an @code{if} without the possibility of an else clause. In your mind, +you can replace @code{when} with @code{if} and understand what goes +on. That is what the Lisp interpreter does. + +Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{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. + +The @code{kill-region} function definition also has an @code{unless} +macro; it is the converse of @code{when}. The @code{unless} macro is +an @code{if} without a then clause + +For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU +Emacs Lisp Reference Manual}. The C programming language also +provides macros. These are different, but also useful. + +@ignore +We will briefly look at C macros in +@ref{Digression into C}. +@end ignore + +@need 1200 +Regarding the @code{when} macro, in the @code{condition-case} +expression, when the string has content, then another conditional +expression is executed. This is an @code{if} with both a then-part +and an else-part. + +@smallexample +@group +(if (eq last-command 'kill-region) + (kill-append string (< end beg) yank-handler) + (kill-new string nil yank-handler)) +@end group +@end smallexample + +The then-part is evaluated if the previous command was another call to +@code{kill-region}; if not, the else-part is evaluated. + +@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'. + +@code{last-command} is a variable that comes with Emacs that we have +not seen before. Normally, whenever a function is executed, Emacs +sets the value of @code{last-command} to the previous command. + +@need 1200 +In this segment of the definition, the @code{if} expression checks +whether the previous command was @code{kill-region}. If it was, + +@smallexample +(kill-append string (< end beg) yank-handler) +@end smallexample + +@noindent +concatenates a copy of the newly clipped text to the just previously +clipped text in the kill ring. + +@node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text +@comment node-name, next, previous, up +@section @code{copy-region-as-kill} +@findex copy-region-as-kill +@findex nthcdr + +The @code{copy-region-as-kill} function copies a region of text from a +buffer and (via either @code{kill-append} or @code{kill-new}) saves it +in the @code{kill-ring}. + +If you call @code{copy-region-as-kill} immediately after a +@code{kill-region} command, Emacs appends the newly copied text to the +previously copied text. This means that if you yank back the text, you +get it all, from both this and the previous operation. On the other +hand, if some other command precedes the @code{copy-region-as-kill}, +the function copies the text into a separate entry in the kill ring. + +@menu +* Complete copy-region-as-kill:: The complete function definition. +* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. +@end menu + +@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill +@ifnottex +@unnumberedsubsec The complete @code{copy-region-as-kill} function definition +@end ifnottex + +@need 1200 +Here is the complete text of the version 22 @code{copy-region-as-kill} +function: + +@smallexample +@group +(defun copy-region-as-kill (beg end) + "Save the region as if killed, but don't kill it. +In Transient Mark mode, deactivate the mark. +If `interprogram-cut-function' is non-nil, also save the text for a window +system cut and paste." + (interactive "r") +@end group +@group + (if (eq last-command 'kill-region) + (kill-append (filter-buffer-substring beg end) (< end beg)) + (kill-new (filter-buffer-substring beg end))) +@end group +@group + (if transient-mark-mode + (setq deactivate-mark t)) + nil) +@end group +@end smallexample + +@need 800 +As usual, this function can be divided into its component parts: + +@smallexample +@group +(defun copy-region-as-kill (@var{argument-list}) + "@var{documentation}@dots{}" + (interactive "r") + @var{body}@dots{}) +@end group +@end smallexample + +The arguments are @code{beg} and @code{end} and the function is +interactive with @code{"r"}, so the two arguments must refer to the +beginning and end of the region. If you have been reading though this +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' +and @code{interprogram-cut-function} comments explain certain +side-effects. + +After you once set a mark, a buffer always contains a region. If you +wish, you can use Transient Mark mode to highlight the region +temporarily. (No one wants to highlight the region all the time, so +Transient Mark mode highlights it only at appropriate times. Many +people turn off Transient Mark mode, so the region is never +highlighted.) + +Also, a windowing system allows you to copy, cut, and paste among +different programs. In the X windowing system, for example, the +@code{interprogram-cut-function} function is @code{x-select-text}, +which works with the windowing system's equivalent of the Emacs kill +ring. + +The body of the @code{copy-region-as-kill} function starts with an +@code{if} clause. What this clause does is distinguish between two +different situations: whether or not this command is executed +immediately after a previous @code{kill-region} command. In the first +case, the new region is appended to the previously copied text. +Otherwise, it is inserted into the beginning of the kill ring as a +separate piece of text from the previous piece. + +The last two lines of the function prevent the region from lighting up +if Transient Mark mode is turned on. + +The body of @code{copy-region-as-kill} merits discussion in detail. + +@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill +@comment node-name, next, previous, up +@subsection The Body of @code{copy-region-as-kill} + +The @code{copy-region-as-kill} function works in much the same way as +the @code{kill-region} function. Both are written so that two or more +kills in a row combine their text into a single entry. If you yank +back the text from the kill ring, you get it all in one piece. +Moreover, kills that kill forward from the current position of the +cursor are added to the end of the previously copied text and commands +that copy text backwards add it to the beginning of the previously +copied text. This way, the words in the text stay in the proper +order. + +Like @code{kill-region}, the @code{copy-region-as-kill} function makes +use of the @code{last-command} variable that keeps track of the +previous Emacs command. + +@menu +* last-command & this-command:: +* kill-append function:: +* kill-new function:: +@end menu + +@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body +@ifnottex +@unnumberedsubsubsec @code{last-command} and @code{this-command} +@end ifnottex + +Normally, whenever a function is executed, Emacs sets the value of +@code{this-command} to the function being executed (which in this case +would be @code{copy-region-as-kill}). At the same time, Emacs sets +the value of @code{last-command} to the previous value of +@code{this-command}. + +In the first part of the body of the @code{copy-region-as-kill} +function, an @code{if} expression determines whether the value of +@code{last-command} is @code{kill-region}. If so, the then-part of +the @code{if} expression is evaluated; it uses the @code{kill-append} +function to concatenate the text copied at this call to the function +with the text already in the first element (the @sc{car}) of the kill +ring. On the other hand, if the value of @code{last-command} is not +@code{kill-region}, then the @code{copy-region-as-kill} function +attaches a new element to the kill ring using the @code{kill-new} +function. + +@need 1250 +The @code{if} expression reads as follows; it uses @code{eq}: + +@smallexample +@group + (if (eq last-command 'kill-region) + ;; @r{then-part} + (kill-append (filter-buffer-substring beg end) (< end beg)) + ;; @r{else-part} + (kill-new (filter-buffer-substring beg end))) +@end group +@end smallexample + +@findex filter-buffer-substring +(The @code{filter-buffer-substring} function returns a filtered +substring of the buffer, if any. Optionally---the arguments are not +here, so neither is done---the function may delete the initial text or +return the text without its properties; this function is a replacement +for the older @code{buffer-substring} function, which came before text +properties were implemented.) + +@findex eq @r{(example of use)} +@noindent +The @code{eq} function tests whether its first argument is the same Lisp +object as its second argument. The @code{eq} function is similar to the +@code{equal} function in that it is used to test for equality, but +differs in that it determines whether two representations are actually +the same object inside the computer, but with different names. +@code{equal} determines whether the structure and contents of two +expressions are the same. + +If the previous command was @code{kill-region}, then the Emacs Lisp +interpreter calls the @code{kill-append} function + +@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body +@unnumberedsubsubsec The @code{kill-append} function +@findex kill-append + +@need 800 +The @code{kill-append} function looks like this: + +@c in GNU Emacs 22 +@smallexample +@group +(defun kill-append (string before-p &optional yank-handler) + "Append STRING to the end of the latest kill in the kill ring. +If BEFORE-P is non-nil, prepend STRING to the kill. +@dots{} " + (let* ((cur (car kill-ring))) + (kill-new (if before-p (concat string cur) (concat cur string)) + (or (= (length cur) 0) + (equal yank-handler + (get-text-property 0 'yank-handler cur))) + yank-handler))) +@end group +@end smallexample + +@ignore +was: +(defun kill-append (string before-p) + "Append STRING to the end of the latest kill in the kill ring. +If BEFORE-P is non-nil, prepend STRING to the kill. +If `interprogram-cut-function' is set, pass the resulting kill to +it." + (kill-new (if before-p + (concat string (car kill-ring)) + (concat (car kill-ring) string)) + t)) +@end ignore + +@noindent +The @code{kill-append} function is fairly straightforward. It uses +the @code{kill-new} function, which we will discuss in more detail in +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'.) + +@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 +the kill ring to @code{cur}. (I do not know why the function does not +use @code{let} instead; only one value is set in the expression. +Perhaps this is a bug that produces no problems?) + +Consider the conditional that is one of the two arguments to +@code{kill-new}. It uses @code{concat} to concatenate the new text to +the @sc{car} of the kill ring. Whether it prepends or appends the +text depends on the results of an @code{if} expression: + +@smallexample +@group +(if before-p ; @r{if-part} + (concat string cur) ; @r{then-part} + (concat cur string)) ; @r{else-part} +@end group +@end smallexample + +@noindent +If the region being killed is before the region that was killed in the +last command, then it should be prepended before the material that was +saved in the previous kill; and conversely, if the killed text follows +what was just killed, it should be appended after the previous text. +The @code{if} expression depends on the predicate @code{before-p} to +decide whether the newly saved text should be put before or after the +previously saved text. + +The symbol @code{before-p} is the name of one of the arguments to +@code{kill-append}. When the @code{kill-append} function is +evaluated, it is bound to the value returned by evaluating the actual +argument. In this case, this is the expression @code{(< end beg)}. +This expression does not directly determine whether the killed text in +this command is located before or after the kill text of the last +command; what it does is determine whether the value of the variable +@code{end} is less than the value of the variable @code{beg}. If it +is, it means that the user is most likely heading towards the +beginning of the buffer. Also, the result of evaluating the predicate +expression, @code{(< end beg)}, will be true and the text will be +prepended before the previous text. On the other hand, if the value of +the variable @code{end} is greater than the value of the variable +@code{beg}, the text will be appended after the previous text. + +@need 800 +When the newly saved text will be prepended, then the string with the new +text will be concatenated before the old text: + +@smallexample +(concat string cur) +@end smallexample + +@need 1200 +@noindent +But if the text will be appended, it will be concatenated +after the old text: + +@smallexample +(concat cur string)) +@end smallexample + +To understand how this works, we first need to review the +@code{concat} function. The @code{concat} function links together or +unites two strings of text. The result is a string. For example: + +@smallexample +@group +(concat "abc" "def") + @result{} "abcdef" +@end group + +@group +(concat "new " + (car '("first element" "second element"))) + @result{} "new first element" + +(concat (car + '("first element" "second element")) " modified") + @result{} "first element modified" +@end group +@end smallexample + +We can now make sense of @code{kill-append}: it modifies the contents +of the kill ring. The kill ring is a list, each element of which is +saved text. The @code{kill-append} function uses the @code{kill-new} +function which in turn uses the @code{setcar} function. + +@node kill-new function, , kill-append function, copy-region-as-kill body +@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: + +@smallexample +@group +(defun kill-new (string &optional replace yank-handler) + "Make STRING the latest kill in the kill ring. +Set `kill-ring-yank-pointer' to point to it. + +If `interprogram-cut-function' is non-nil, apply it to STRING. +Optional second argument REPLACE non-nil means that STRING will replace +the front of the kill ring, rather than being added to the list. +@dots{}" +@end group +@group + (if (> (length string) 0) + (if yank-handler + (put-text-property 0 (length string) + 'yank-handler yank-handler string)) + (if yank-handler + (signal 'args-out-of-range + (list string "yank-handler specified for empty string")))) +@end group +@group + (if (fboundp 'menu-bar-update-yank-menu) + (menu-bar-update-yank-menu string (and replace (car kill-ring)))) +@end group +@group + (if (and replace kill-ring) + (setcar kill-ring string) + (push string kill-ring) + (if (> (length kill-ring) kill-ring-max) + (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) +@end group +@group + (setq kill-ring-yank-pointer kill-ring) + (if interprogram-cut-function + (funcall interprogram-cut-function string (not replace)))) +@end group +@end smallexample +@ignore +was: +(defun kill-new (string &optional replace) + "Make STRING the latest kill in the kill ring. +Set the kill-ring-yank pointer to point to it. +If `interprogram-cut-function' is non-nil, apply it to STRING. +Optional second argument REPLACE non-nil means that STRING will replace +the front of the kill ring, rather than being added to the list." + (and (fboundp 'menu-bar-update-yank-menu) + (menu-bar-update-yank-menu string (and replace (car kill-ring)))) + (if (and replace kill-ring) + (setcar kill-ring string) + (setq kill-ring (cons string kill-ring)) + (if (> (length kill-ring) kill-ring-max) + (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) + (setq kill-ring-yank-pointer kill-ring) + (if interprogram-cut-function + (funcall interprogram-cut-function string (not replace)))) +@end ignore + +(Notice that the function is not interactive.) + +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. + +@need 1200 +The first line of the documentation makes sense: + +@smallexample +Make STRING the latest kill in the kill ring. +@end smallexample + +@noindent +Let's skip over the rest of the documentation for the moment. + +@noindent +Also, let's skip over the initial @code{if} expression and those lines +of code involving @code{menu-bar-update-yank-menu}. We will explain +them below. + +@need 1200 +The critical lines are these: + +@smallexample +@group + (if (and replace kill-ring) + ;; @r{then} + (setcar kill-ring string) +@end group +@group + ;; @r{else} + (push string kill-ring) +@end group +@group + (setq kill-ring (cons string kill-ring)) + (if (> (length kill-ring) kill-ring-max) + ;; @r{avoid overly long kill ring} + (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) +@end group +@group + (setq kill-ring-yank-pointer kill-ring) + (if interprogram-cut-function + (funcall interprogram-cut-function string (not replace)))) +@end group +@end smallexample + +The conditional test is @w{@code{(and replace kill-ring)}}. +This will be true when two conditions are met: the kill ring has +something in it, and the @code{replace} variable is true. + +@need 1250 +When the @code{kill-append} function sets @code{replace} to be true +and when the kill ring has at least one item in it, the @code{setcar} +expression is executed: + +@smallexample +(setcar kill-ring string) +@end smallexample + +The @code{setcar} function actually changes the first element of the +@code{kill-ring} list to the value of @code{string}. It replaces the +first element. + +@need 1250 +On the other hand, if the kill ring is empty, or replace is false, the +else-part of the condition is executed: + +@smallexample +(push string kill-ring) +@end smallexample + +@noindent +@need 1250 +@code{push} puts its first argument onto the second. It is similar to +the older + +@smallexample +(setq kill-ring (cons string kill-ring)) +@end smallexample + +@noindent +@need 1250 +or the newer + +@smallexample +(add-to-list kill-ring string) +@end smallexample + +@noindent +When it is false, the expression first constructs a new version of the +kill ring by prepending @code{string} to the existing kill ring as a +new element (that is what the @code{push} does). Then it executes a +second @code{if} clause. This second @code{if} clause keeps the kill +ring from growing too long. + +Let's look at these two expressions in order. + +The @code{push} line of the else-part sets the new value of the kill +ring to what results from adding the string being killed to the old +kill ring. + +We can see how this works with an example. + +@need 800 +First, + +@smallexample +(setq example-list '("here is a clause" "another clause")) +@end smallexample + +@need 1200 +@noindent +After evaluating this expression with @kbd{C-x C-e}, you can evaluate +@code{example-list} and see what it returns: + +@smallexample +@group +example-list + @result{} ("here is a clause" "another clause") +@end group +@end smallexample + +@need 1200 +@noindent +Now, we can add a new element on to this list by evaluating the +following expression: +@findex push, @r{example} + +@smallexample +(push "a third clause" example-list) +@end smallexample + +@need 800 +@noindent +When we evaluate @code{example-list}, we find its value is: + +@smallexample +@group +example-list + @result{} ("a third clause" "here is a clause" "another clause") +@end group +@end smallexample + +@noindent +Thus, the third clause is added to the list by @code{push}. + +@need 1200 +Now for the second part of the @code{if} clause. This expression +keeps the kill ring from growing too long. It looks like this: + +@smallexample +@group +(if (> (length kill-ring) kill-ring-max) + (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) +@end group +@end smallexample + +The code checks whether the length of the kill ring is greater than +the maximum permitted length. This is the value of +@code{kill-ring-max} (which is 60, by default). If the length of the +kill ring is too long, then this code sets the last element of the +kill ring to @code{nil}. It does this by using two functions, +@code{nthcdr} and @code{setcdr}. + +We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). +It sets the @sc{cdr} of a list, just as @code{setcar} sets the +@sc{car} of a list. In this case, however, @code{setcdr} will not be +setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} +function is used to cause it to set the @sc{cdr} of the next to last +element of the kill ring---this means that since the @sc{cdr} of the +next to last element is the last element of the kill ring, it will set +the last element of the kill ring. + +@findex nthcdr, @r{example} +The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a +list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} +@dots{} It does this @var{N} times and returns the results. +(@xref{nthcdr, , @code{nthcdr}}.) + +@findex setcdr, @r{example} +Thus, if we had a four element list that was supposed to be three +elements long, we could set the @sc{cdr} of the next to last element +to @code{nil}, and thereby shorten the list. (If you set the last +element to some other value than @code{nil}, which you could do, then +you would not have shortened the list. @xref{setcdr, , +@code{setcdr}}.) + +You can see shortening by evaluating the following three expressions +in turn. First set the value of @code{trees} to @code{(maple oak pine +birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} +and then find the value of @code{trees}: + +@smallexample +@group +(setq trees '(maple oak pine birch)) + @result{} (maple oak pine birch) +@end group + +@group +(setcdr (nthcdr 2 trees) nil) + @result{} nil + +trees + @result{} (maple oak pine) +@end group +@end smallexample + +@noindent +(The value returned by the @code{setcdr} expression is @code{nil} since +that is what the @sc{cdr} is set to.) + +To repeat, in @code{kill-new}, the @code{nthcdr} function takes the +@sc{cdr} a number of times that is one less than the maximum permitted +size of the kill ring and @code{setcdr} sets the @sc{cdr} of that +element (which will be the rest of the elements in the kill ring) to +@code{nil}. This prevents the kill ring from growing too long. + +@need 800 +The next to last expression in the @code{kill-new} function is + +@smallexample +(setq kill-ring-yank-pointer kill-ring) +@end smallexample + +The @code{kill-ring-yank-pointer} is a global variable that is set to be +the @code{kill-ring}. + +Even though the @code{kill-ring-yank-pointer} is called a +@samp{pointer}, it is a variable just like the kill ring. However, the +name has been chosen to help humans understand how the variable is used. + +@need 1200 +Now, to return to an early expression in the body of the function: + +@smallexample +@group + (if (fboundp 'menu-bar-update-yank-menu) + (menu-bar-update-yank-menu string (and replace (car kill-ring)))) +@end group +@end smallexample + +@noindent +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 +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}). + +@noindent +The then-part contains an expression whose first element is the +function @code{and}. + +@findex and +The @code{and} special form evaluates each of its arguments until one +of the arguments returns a value of @code{nil}, in which case the +@code{and} expression returns @code{nil}; however, if none of the +arguments returns a value of @code{nil}, the value resulting from +evaluating the last argument is returned. (Since such a value is not +@code{nil}, it is considered true in Emacs Lisp.) In other words, an +@code{and} expression returns a true value only if all its arguments +are true. (@xref{Second Buffer Related Review}.) + +The expression determines whether the second argument to +@code{menu-bar-update-yank-menu} is true or not. +@ignore + ;; If we're supposed to be extending an existing string, and that + ;; string really is at the front of the menu, then update it in place. +@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 +bar; using a mouse, you can look at the various pieces of text you +have saved and select one piece to paste. + +The last expression in the @code{kill-new} function adds the newly +copied string to whatever facility exists for copying and pasting +among different programs running in a windowing system. In the X +Windowing system, for example, the @code{x-select-text} function takes +the string and stores it in memory operated by X. You can paste the +string in another program, such as an Xterm. + +@need 1200 +The expression looks like this: + +@smallexample +@group + (if interprogram-cut-function + (funcall interprogram-cut-function string (not replace)))) +@end group +@end smallexample + +If an @code{interprogram-cut-function} exists, then Emacs executes +@code{funcall}, which in turn calls its first argument as a function +and passes the remaining arguments to it. (Incidentally, as far as I +can see, this @code{if} expression could be replaced by an @code{and} +expression similar to the one in the first part of the function.) + +We are not going to discuss windowing systems and other programs +further, but merely note that this is a mechanism that enables GNU +Emacs to work easily and well with other programs. + +This code for placing text in the kill ring, either concatenated with +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 +that, we will digress into C. + +@ignore +@c is this true in Emacs 22? Does not seems to be + + (If the @w{@code{(< end beg))}} +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 +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 +order is correct.) + +On the other hand, if the previous command is not @code{kill-region}, +then the @code{kill-new} function is called, which adds the text to +the kill ring as the latest item, and sets the +@code{kill-ring-yank-pointer} variable to point to it. +@end ignore +@ignore + +@c Evidently, changed for Emacs 22. The zap-to-char command does not +@c use the delete-and-extract-region function + +2006 Oct 26, the Digression into C is now OK but should come after +copy-region-as-kill and filter-buffer-substring + +2006 Oct 24 +In Emacs 22, +copy-region-as-kill is short, 12 lines, and uses +filter-buffer-substring, which is longer, 39 lines +and has delete-and-extract-region in it. +delete-and-extract-region is written in C. + +see Initializing a Variable with @code{defvar} +@end ignore + +@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text +@comment node-name, next, previous, up +@section Digression into C +@findex delete-and-extract-region +@cindex C, a digression into +@cindex Digression into C + +The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , +@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} +function, which in turn uses the @code{delete-and-extract-region} +function. It removes the contents of a region and you cannot get them +back. + +Unlike the other code discussed here, the +@code{delete-and-extract-region} function is not written in Emacs +Lisp; it is written in C and is one of the primitives of the GNU Emacs +system. Since it is very simple, I will digress briefly from Lisp and +describe it here. + +@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c +@c the DEFUN for buffer-substring-no-properties + +@need 1500 +Like many of the other Emacs primitives, +@code{delete-and-extract-region} is written as an instance of a C +macro, a macro being a template for code. The complete macro looks +like this: + +@smallexample +@group +DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, + Sbuffer_substring_no_properties, 2, 2, 0, + doc: /* Return the characters of part of the buffer, +without the text properties. +The two arguments START and END are character positions; +they can be in either order. */) + (start, end) + Lisp_Object start, end; +@{ + register int b, e; + + validate_region (&start, &end); + b = XINT (start); + e = XINT (end); + + return make_buffer_string (b, e, 0); +@} +@end group +@end smallexample + +Without going into the details of the macro writing process, let me +point out that this macro starts with the word @code{DEFUN}. The word +@code{DEFUN} was chosen since the code serves the same purpose as +@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in +@file{emacs/src/lisp.h}.) + +The word @code{DEFUN} is followed by seven parts inside of +parentheses: + +@itemize @bullet +@item +The first part is the name given to the function in Lisp, +@code{delete-and-extract-region}. + +@item +The second part is the name of the function in C, +@code{Fdelete_and_extract_region}. By convention, it starts with +@samp{F}. Since C does not use hyphens in names, underscores are used +instead. + +@item +The third part is the name for the C constant structure that records +information on this function for internal use. It is the name of the +function in C but begins with an @samp{S} instead of an @samp{F}. + +@item +The fourth and fifth parts specify the minimum and maximum number of +arguments the function can have. This function demands exactly 2 +arguments. + +@item +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. + +If you were to specify arguments, you would place them between +quotation marks. The C macro for @code{goto-char} includes +@code{"NGoto char: "} in this position to indicate that the function +expects a raw prefix, in this case, a numerical location in a buffer, +and provides a prompt. + +@item +The seventh part is a documentation string, just like the one for a +function written in Emacs Lisp, except that every newline must be +written explicitly as @samp{\n} followed by a backslash and carriage +return. + +@need 1000 +Thus, the first two lines of documentation for @code{goto-char} are +written like this: + +@smallexample +@group + "Set point to POSITION, a number or marker.\n\ +Beginning of buffer is position (point-min), end is (point-max)." +@end group +@end smallexample +@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' +consists of the following four lines: + +@smallexample +@group +validate_region (&start, &end); +if (XINT (start) == XINT (end)) + return build_string (""); +return del_range_1 (XINT (start), XINT (end), 1, 1); +@end group +@end smallexample + +The @code{validate_region} function checks whether the values +passed as the beginning and end of the region are the proper type and +are within range. If the beginning and end positions are the same, +then return and empty string. + +The @code{del_range_1} function actually deletes the text. It is a +complex function we will not look into. It updates the buffer and +does other things. However, it is worth looking at the two arguments +passed to @code{del_range}. These are @w{@code{XINT (start)}} and +@w{@code{XINT (end)}}. + +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 +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'. + +@samp{XINT} is a C macro that extracts the relevant number from the +longer collection of bits; the three other bits are discarded. + +@need 800 +The command in @code{delete-and-extract-region} looks like this: + +@smallexample +del_range_1 (XINT (start), XINT (end), 1, 1); +@end smallexample + +@noindent +It deletes the region between the beginning position, @code{start}, +and the ending position, @code{end}. + +From the point of view of the person writing Lisp, Emacs is all very +simple; but hidden underneath is a great deal of complexity to make it +all work. + +@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text +@comment node-name, next, previous, up +@section Initializing a Variable with @code{defvar} +@findex defvar +@cindex Initializing a variable +@cindex Variable initialization + +@ignore +2006 Oct 24 +In Emacs 22, +copy-region-as-kill is short, 12 lines, and uses +filter-buffer-substring, which is longer, 39 lines +and has delete-and-extract-region in it. +delete-and-extract-region is written in C. + +see Initializing a Variable with @code{defvar} + +@end ignore + +The @code{copy-region-as-kill} function is written in Emacs Lisp. Two +functions within it, @code{kill-append} and @code{kill-new}, copy a +region in a buffer and save it in a variable called the +@code{kill-ring}. This section describes how the @code{kill-ring} +variable is created and initialized using the @code{defvar} special +form. + +(Again we note that the term @code{kill-ring} is a misnomer. The text +that is clipped out of the buffer can be brought back; it is not a ring +of corpses, but a ring of resurrectable text.) + +In Emacs Lisp, a variable such as the @code{kill-ring} is created and +given an initial value by using the @code{defvar} special form. The +name comes from ``define variable''. + +The @code{defvar} special form is similar to @code{setq} in that it sets +the value of a variable. It is unlike @code{setq} in two ways: first, +it only sets the value of the variable if the variable does not already +have a value. If the variable already has a value, @code{defvar} does +not override the existing value. Second, @code{defvar} has a +documentation string. + +(Another special form, @code{defcustom}, is designed for variables +that people customize. It has more features than @code{defvar}. +(@xref{defcustom, , Setting Variables with @code{defcustom}}.) + +@menu +* See variable current value:: +* defvar and asterisk:: +@end menu + +@node See variable current value, defvar and asterisk, defvar, defvar +@ifnottex +@unnumberedsubsec Seeing the Current Value of a Variable +@end ifnottex + +You can see the current value of a variable, any variable, by using +the @code{describe-variable} function, which is usually invoked by +typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} +(followed by @key{RET}) when prompted, you will see what is in your +current kill ring---this may be quite a lot! Conversely, if you have +been doing nothing this Emacs session except read this document, you +may have nothing in it. Also, you will see the documentation for +@code{kill-ring}: + +@smallexample +@group +Documentation: +List of killed text sequences. +Since the kill ring is supposed to interact nicely with cut-and-paste +facilities offered by window systems, use of this variable should +@end group +@group +interact nicely with `interprogram-cut-function' and +`interprogram-paste-function'. The functions `kill-new', +`kill-append', and `current-kill' are supposed to implement this +interaction; you may want to use them instead of manipulating the kill +ring directly. +@end group +@end smallexample + +@need 800 +The kill ring is defined by a @code{defvar} in the following way: + +@smallexample +@group +(defvar kill-ring nil + "List of killed text sequences. +@dots{}") +@end group +@end smallexample + +@noindent +In this variable definition, the variable is given an initial value of +@code{nil}, which makes sense, since if you have saved nothing, you want +nothing back if you give a @code{yank} command. The documentation +string is written just like the documentation string of a @code{defun}. +As with the documentation string of the @code{defun}, the first line of +the documentation should be a complete sentence, since some commands, +like @code{apropos}, print only the first line of documentation. +Succeeding lines should not be indented; otherwise they look odd when +you use @kbd{C-h v} (@code{describe-variable}). + +@node defvar and asterisk, , See variable current value, defvar +@subsection @code{defvar} and an asterisk +@findex defvar @r{for a user customizable variable} +@findex defvar @r{with an asterisk} + +In the past, Emacs used the @code{defvar} special form both for +internal variables that you would not expect a user to change and for +variables that you do expect a user to change. Although you can still +use @code{defvar} for user customizable variables, please use +@code{defcustom} instead, since that special form provides a path into +the Customization commands. (@xref{defcustom, , Specifying Variables +using @code{defcustom}}.) + +When you specified a variable using the @code{defvar} special form, +you could distinguish a readily settable variable from others by +typing an asterisk, @samp{*}, in the first column of its documentation +string. For example: + +@smallexample +@group +(defvar shell-command-default-error-buffer nil + "*Buffer name for `shell-command' @dots{} error output. +@dots{} ") +@end group +@end smallexample + +@findex set-variable +@noindent +You could (and still can) use the @code{set-variable} command to +change the value of @code{shell-command-default-error-buffer} +temporarily. However, options set using @code{set-variable} are set +only for the duration of your editing session. The new values are not +saved between sessions. Each time Emacs starts, it reads the original +value, unless you change the value within your @file{.emacs} file, +either by setting it manually or by using @code{customize}. +@xref{Emacs Initialization, , Your @file{.emacs} File}. + +For me, the major use of the @code{set-variable} command is to suggest +variables that I might want to set in my @file{.emacs} file. There +are now more than 700 such variables --- far too many to remember +readily. Fortunately, you can press @key{TAB} after calling the +@code{M-x set-variable} command to see the list of variables. +(@xref{Examining, , Examining and Setting Variables, emacs, +The GNU Emacs Manual}.) + +@need 1250 +@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text +@comment node-name, next, previous, up +@section Review + +Here is a brief summary of some recently introduced functions. + +@table @code +@item car +@itemx cdr +@code{car} returns the first element of a list; @code{cdr} returns the +second and subsequent elements of a list. + +@need 1250 +For example: + +@smallexample +@group +(car '(1 2 3 4 5 6 7)) + @result{} 1 +(cdr '(1 2 3 4 5 6 7)) + @result{} (2 3 4 5 6 7) +@end group +@end smallexample + +@item cons +@code{cons} constructs a list by prepending its first argument to its +second argument. + +@need 1250 +For example: + +@smallexample +@group +(cons 1 '(2 3 4)) + @result{} (1 2 3 4) +@end group +@end smallexample + +@item funcall +@code{funcall} evaluates its first argument as a function. It passes +its remaining arguments to its first argument. + +@item nthcdr +Return the result of taking @sc{cdr} `n' times on a list. +@iftex +The +@tex +$n^{th}$ +@end tex +@code{cdr}. +@end iftex +The `rest of the rest', as it were. + +@need 1250 +For example: + +@smallexample +@group +(nthcdr 3 '(1 2 3 4 5 6 7)) + @result{} (4 5 6 7) +@end group +@end smallexample + +@item setcar +@itemx setcdr +@code{setcar} changes the first element of a list; @code{setcdr} +changes the second and subsequent elements of a list. + +@need 1250 +For example: + +@smallexample +@group +(setq triple '(1 2 3)) + +(setcar triple '37) + +triple + @result{} (37 2 3) + +(setcdr triple '("foo" "bar")) + +triple + @result{} (37 "foo" "bar") +@end group +@end smallexample + +@item progn +Evaluate each argument in sequence and then return the value of the +last. + +@need 1250 +For example: + +@smallexample +@group +(progn 1 2 3 4) + @result{} 4 +@end group +@end smallexample + +@item save-restriction +Record whatever narrowing is in effect in the current buffer, if any, +and restore that narrowing after evaluating the arguments. + +@item search-forward +Search for a string, and if the string is found, move point. With a +regular expression, use the similar @code{re-search-forward}. +(@xref{Regexp Search, , Regular Expression Searches}, for an +explanation of regular expression patterns and searches.) + +@need 1250 +@noindent +@code{search-forward} and @code{re-search-forward} take four +arguments: + +@enumerate +@item +The string or regular expression to search for. + +@item +Optionally, the limit of the search. + +@item +Optionally, what to do if the search fails, return @code{nil} or an +error message. + +@item +Optionally, how many times to repeat the search; if negative, the +search goes backwards. +@end enumerate + +@item kill-region +@itemx delete-and-extract-region +@itemx copy-region-as-kill + +@code{kill-region} cuts the text between point and mark from the +buffer and stores that text in the kill ring, so you can get it back +by yanking. + +@code{copy-region-as-kill} copies the text between point and mark into +the kill ring, from which you can get it by yanking. The function +does not cut or remove the text from the buffer. +@end table + +@code{delete-and-extract-region} removes the text between point and +mark from the buffer and throws it away. You cannot get it back. +(This is not an interactive command.) + +@need 1500 +@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text +@section Searching Exercises + +@itemize @bullet +@item +Write an interactive function that searches for a string. If the +search finds the string, leave point after it and display a message +that says ``Found!''. (Do not use @code{search-forward} for the name +of this function; if you do, you will overwrite the existing version of +@code{search-forward} that comes with Emacs. Use a name such as +@code{test-search} instead.) + +@item +Write a function that prints the third element of the kill ring in the +echo area, if any; if the kill ring does not contain a third element, +print an appropriate message. +@end itemize + +@node List Implementation, Yanking, Cutting & Storing Text, Top +@comment node-name, next, previous, up +@chapter How Lists are Implemented +@cindex Lists in a computer + +In Lisp, atoms are recorded in a straightforward fashion; if the +implementation is not straightforward in practice, it is, nonetheless, +straightforward in theory. The atom @samp{rose}, for example, is +recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, +@samp{e}. A list, on the other hand, is kept differently. The mechanism +is equally simple, but it takes a moment to get used to the idea. A +list is kept using a series of pairs of pointers. In the series, the +first pointer in each pair points to an atom or to another list, and the +second pointer in each pair points to the next pair, or to the symbol +@code{nil}, which marks the end of the list. + +A pointer itself is quite simply the electronic address of what is +pointed to. Hence, a list is kept as a series of electronic addresses. + +@menu +* Lists diagrammed:: +* Symbols as Chest:: Exploring a powerful metaphor. +* List Exercise:: +@end menu + +@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation +@ifnottex +@unnumberedsec Lists diagrammed +@end ifnottex + +For example, the list @code{(rose violet buttercup)} has three elements, +@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the +electronic address of @samp{rose} is recorded in a segment of computer +memory along with the address that gives the electronic address of where +the atom @samp{violet} is located; and that address (the one that tells +where @samp{violet} is located) is kept along with an address that tells +where the address for the atom @samp{buttercup} is located. + +@need 1200 +This sounds more complicated than it is and is easier seen in a diagram: + +@c clear print-postscript-figures +@c !!! cons-cell-diagram #1 +@ifnottex +@smallexample +@group + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-1} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@end iftex +@end ifclear + +@noindent +In the diagram, each box represents a word of computer memory that +holds a Lisp object, usually in the form of a memory address. The boxes, +i.e.@: the addresses, are in pairs. Each arrow points to what the address +is the address of, either an atom or another pair of addresses. The +first box is the electronic address of @samp{rose} and the arrow points +to @samp{rose}; the second box is the address of the next pair of boxes, +the first part of which is the address of @samp{violet} and the second +part of which is the address of the next pair. The very last box +points to the symbol @code{nil}, which marks the end of the list. + +@need 1200 +When a variable is set to a list with a function such as @code{setq}, +it stores the address of the first box in the variable. Thus, +evaluation of the expression + +@smallexample +(setq bouquet '(rose violet buttercup)) +@end smallexample + +@need 1250 +@noindent +creates a situation like this: + +@c cons-cell-diagram #2 +@ifnottex +@smallexample +@group +bouquet + | + | ___ ___ ___ ___ ___ ___ + --> |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-2} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +bouquet + | + | ___ ___ ___ ___ ___ ___ + --> |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@end iftex +@end ifclear + +@noindent +In this example, the symbol @code{bouquet} holds the address of the first +pair of boxes. + +@need 1200 +This same list can be illustrated in a different sort of box notation +like this: + +@c cons-cell-diagram #2a +@ifnottex +@smallexample +@group +bouquet + | + | -------------- --------------- ---------------- + | | car | cdr | | car | cdr | | car | cdr | + -->| rose | o------->| violet | o------->| butter- | nil | + | | | | | | | cup | | + -------------- --------------- ---------------- +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-2a} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +bouquet + | + | -------------- --------------- ---------------- + | | car | cdr | | car | cdr | | car | cdr | + -->| rose | o------->| violet | o------->| butter- | nil | + | | | | | | | cup | | + -------------- --------------- ---------------- +@end group +@end smallexample +@end iftex +@end ifclear + +(Symbols consist of more than pairs of addresses, but the structure of +a symbol is made up of addresses. Indeed, the symbol @code{bouquet} +consists of a group of address-boxes, one of which is the address of +the printed word @samp{bouquet}, a second of which is the address of a +function definition attached to the symbol, if any, a third of which +is the address of the first pair of address-boxes for the list +@code{(rose violet buttercup)}, and so on. Here we are showing that +the symbol's third address-box points to the first pair of +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, +evaluation of the following expression + +@smallexample +(setq flowers (cdr bouquet)) +@end smallexample + +@need 800 +@noindent +produces this: + +@c cons-cell-diagram #3 +@ifnottex +@sp 1 +@smallexample +@group +bouquet flowers + | | + | ___ ___ | ___ ___ ___ ___ + --> | | | --> | | | | | | + |___|___|----> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@sp 1 +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-3} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@sp 1 +@smallexample +@group +bouquet flowers + | | + | ___ ___ | ___ ___ ___ ___ + --> | | | --> | | | | | | + |___|___|----> |___|___|--> |___|___|--> nil + | | | + | | | + --> rose --> violet --> buttercup +@end group +@end smallexample +@sp 1 +@end iftex +@end ifclear + +@noindent +The value of @code{flowers} is @code{(violet buttercup)}, which is +to say, the symbol @code{flowers} holds the address of the pair of +address-boxes, the first of which holds the address of @code{violet}, +and the second of which holds the address of @code{buttercup}. + +A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted +pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp +Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair +Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more +information about cons cells and dotted pairs. + +@need 1200 +The function @code{cons} adds a new pair of addresses to the front of +a series of addresses like that shown above. For example, evaluating +the expression + +@smallexample +(setq bouquet (cons 'lily bouquet)) +@end smallexample + +@need 1500 +@noindent +produces: + +@c cons-cell-diagram #4 +@ifnottex +@sp 1 +@smallexample +@group +bouquet flowers + | | + | ___ ___ ___ ___ | ___ ___ ___ ___ + --> | | | | | | --> | | | | | | + |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil + | | | | + | | | | + --> lily --> rose --> violet --> buttercup +@end group +@end smallexample +@sp 1 +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-4} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@sp 1 +@smallexample +@group +bouquet flowers + | | + | ___ ___ ___ ___ | ___ ___ ___ ___ + --> | | | | | | --> | | | | | | + |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil + | | | | + | | | | + --> lily --> rose --> violet --> buttercup +@end group +@end smallexample +@sp 1 +@end iftex +@end ifclear + +@need 1200 +@noindent +However, this does not change the value of the symbol +@code{flowers}, as you can see by evaluating the following, + +@smallexample +(eq (cdr (cdr bouquet)) flowers) +@end smallexample + +@noindent +which returns @code{t} for true. + +Until it is reset, @code{flowers} still has the value +@code{(violet buttercup)}; that is, it has the address of the cons +cell whose first address is of @code{violet}. Also, this does not +alter any of the pre-existing cons cells; they are all still there. + +Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address +of the next cons cell in the series; to get the @sc{car} of a list, +you get the address of the first element of the list; to @code{cons} a +new element on a list, you add a new cons cell to the front of the list. +That is all there is to it! The underlying structure of Lisp is +brilliantly simple! + +And what does the last address in a series of cons cells refer to? It +is the address of the empty list, of @code{nil}. + +In summary, when a Lisp variable is set to a value, it is provided with +the address of the list to which the variable refers. + +@node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation +@section Symbols as a Chest of Drawers +@cindex Symbols as a Chest of Drawers +@cindex Chest of Drawers, metaphor for a symbol +@cindex Drawers, Chest of, metaphor for a symbol + +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. + +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, +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 +record other information. Property lists are not discussed here; see +@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp +Reference Manual}.) + +@need 1500 +Here is a fanciful representation: + +@c chest-of-drawers diagram +@ifnottex +@sp 1 +@smallexample +@group + Chest of Drawers Contents of Drawers + + __ o0O0o __ + / \ + --------------------- + | directions to | [map to] + | symbol name | bouquet + | | + +---------------------+ + | directions to | + | symbol definition | [none] + | | + +---------------------+ + | directions to | [map to] + | variable value | (rose violet buttercup) + | | + +---------------------+ + | directions to | + | property list | [not described here] + | | + +---------------------+ + |/ \| +@end group +@end smallexample +@sp 1 +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{drawers} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@sp 1 +@smallexample +@group + Chest of Drawers Contents of Drawers + + __ o0O0o __ + / \ + --------------------- + | directions to | [map to] + | symbol name | bouquet + | | + +---------------------+ + | directions to | + | symbol definition | [none] + | | + +---------------------+ + | directions to | [map to] + | variable value | (rose violet buttercup) + | | + +---------------------+ + | directions to | + | property list | [not described here] + | | + +---------------------+ + |/ \| +@end group +@end smallexample +@sp 1 +@end iftex +@end ifclear + +@node List Exercise, , Symbols as Chest, List Implementation +@section Exercise + +Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two +more flowers on to this list and set this new list to +@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. +What does the @code{more-flowers} list now contain? + +@node Yanking, Loops & Recursion, List Implementation, Top +@comment node-name, next, previous, up +@chapter Yanking Text Back +@findex yank +@cindex Text retrieval +@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 +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). + +A simple @kbd{C-y} (@code{yank}) command inserts the first item from +the kill ring into the current buffer. If the @kbd{C-y} command is +followed immediately by @kbd{M-y}, the first element is replaced by +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 +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.) + +@menu +* Kill Ring Overview:: +* kill-ring-yank-pointer:: The kill ring is a list. +* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. +@end menu + +@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking +@comment node-name, next, previous, up +@section Kill Ring Overview +@cindex Kill ring overview + +The kill ring is a list of textual strings. This is what it looks like: + +@smallexample +("some text" "a different piece of text" "yet more text") +@end smallexample + +If this were the contents of my kill ring and I pressed @kbd{C-y}, the +string of characters saying @samp{some text} would be inserted in this +buffer where my cursor is located. + +The @code{yank} command is also used for duplicating text by copying it. +The copied text is not cut from the buffer, but a copy of it is put on the +kill ring and is inserted by yanking it back. + +Three functions are used for bringing text back from the kill ring: +@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, +which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, +which is used by the two other functions. + +These functions refer to the kill ring through a variable called the +@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the +@code{yank} and @code{yank-pop} functions is: + +@smallexample +(insert (car kill-ring-yank-pointer)) +@end smallexample + +@noindent +(Well, no more. In GNU Emacs 22, the function has been replaced by +@code{insert-for-yank} which calls @code{insert-for-yank-1} +repetitively for each @code{yank-handler} segment. In turn, +@code{insert-for-yank-1} strips text properties from the inserted text +according to @code{yank-excluded-properties}. Otherwise, it is just +like @code{insert}. We will stick with plain @code{insert} since it +is easier to understand.) + +To begin to understand how @code{yank} and @code{yank-pop} work, it is +first necessary to look at the @code{kill-ring-yank-pointer} variable. + +@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking +@comment node-name, next, previous, up +@section The @code{kill-ring-yank-pointer} Variable + +@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is +a variable. It points to something by being bound to the value of what +it points to, like any other Lisp variable. + +@need 1000 +Thus, if the value of the kill ring is: + +@smallexample +("some text" "a different piece of text" "yet more text") +@end smallexample + +@need 1250 +@noindent +and the @code{kill-ring-yank-pointer} points to the second clause, the +value of @code{kill-ring-yank-pointer} is: + +@smallexample +("a different piece of text" "yet more text") +@end smallexample + +As explained in the previous chapter (@pxref{List Implementation}), the +computer does not keep two different copies of the text being pointed to +by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The +words ``a different piece of text'' and ``yet more text'' are not +duplicated. Instead, the two Lisp variables point to the same pieces of +text. Here is a diagram: + +@c cons-cell-diagram #5 +@ifnottex +@smallexample +@group +kill-ring kill-ring-yank-pointer + | | + | ___ ___ | ___ ___ ___ ___ + ---> | | | --> | | | | | | + |___|___|----> |___|___|--> |___|___|--> nil + | | | + | | | + | | --> "yet more text" + | | + | --> "a different piece of text" + | + --> "some text" +@end group +@end smallexample +@sp 1 +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{cons-5} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +kill-ring kill-ring-yank-pointer + | | + | ___ ___ | ___ ___ ___ ___ + ---> | | | --> | | | | | | + |___|___|----> |___|___|--> |___|___|--> nil + | | | + | | | + | | --> "yet more text" + | | + | --> "a different piece of text + | + --> "some text" +@end group +@end smallexample +@sp 1 +@end iftex +@end ifclear + +Both the variable @code{kill-ring} and the variable +@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is +usually described as if it were actually what it is composed of. The +@code{kill-ring} is spoken of as if it were the list rather than that it +points to the list. Conversely, the @code{kill-ring-yank-pointer} is +spoken of as pointing to a list. + +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 +of the kill ring of which the first element (the @sc{car}) will be +inserted. + +@ignore +In GNU Emacs 22, the @code{kill-new} function calls + +@code{(setq kill-ring-yank-pointer kill-ring)} + +(defun rotate-yank-pointer (arg) + "Rotate the yanking point in the kill ring. +With argument, rotate that many kills forward (or backward, if negative)." + (interactive "p") + (current-kill arg)) + +(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 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)))) + (if interprogram-paste + (progn + ;; Disable the interprogram cut function when we add the new + ;; 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) + (or kill-ring (error "Kill ring is empty")) + (let ((ARGth-kill-element + (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)) + (car ARGth-kill-element))))) + +@end ignore + +@need 1500 +@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking +@section Exercises with @code{yank} and @code{nthcdr} + +@itemize @bullet +@item +Using @kbd{C-h v} (@code{describe-variable}), look at the value of +your kill ring. Add several items to your kill ring; look at its +value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way +around the kill ring. How many items were in your kill ring? Find +the value of @code{kill-ring-max}. Was your kill ring full, or could +you have kept more blocks of text within it? + +@item +Using @code{nthcdr} and @code{car}, construct a series of expressions +to return the first, second, third, and fourth elements of a list. +@end itemize + +@node Loops & Recursion, Regexp Search, Yanking, Top +@comment node-name, next, previous, up +@chapter Loops and Recursion +@cindex Loops and recursion +@cindex Recursion and loops +@cindex Repetition (loops) + +Emacs Lisp has two primary ways to cause an expression, or a series of +expressions, to be evaluated repeatedly: one uses a @code{while} +loop, and the other uses @dfn{recursion}. + +Repetition can be very valuable. For example, to move forward four +sentences, you need only write a program that will move forward one +sentence and then repeat the process four times. Since a computer does +not get bored or tired, such repetitive action does not have the +deleterious effects that excessive or the wrong kinds of repetition can +have on humans. + +People mostly write Emacs Lisp functions using @code{while} loops and +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 +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 +@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to +15 and 30 times their default value.}. + +@menu +* while:: Causing a stretch of code to repeat. +* dolist dotimes:: +* Recursion:: Causing a function to call itself. +* Looping exercise:: +@end menu + +@node while, dolist dotimes, Loops & Recursion, Loops & Recursion +@comment node-name, next, previous, up +@section @code{while} +@cindex Loops +@findex while + +The @code{while} special form tests whether the value returned by +evaluating its first argument is true or false. This is similar to what +the Lisp interpreter does with an @code{if}; what the interpreter does +next, however, is different. + +In a @code{while} expression, if the value returned by evaluating the +first argument is false, the Lisp interpreter skips the rest of the +expression (the @dfn{body} of the expression) and does not evaluate it. +However, if the value is true, the Lisp interpreter evaluates the body +of the expression and then again tests whether the first argument to +@code{while} is true or false. If the value returned by evaluating the +first argument is again true, the Lisp interpreter again evaluates the +body of the expression. + +@need 1200 +The template for a @code{while} expression looks like this: + +@smallexample +@group +(while @var{true-or-false-test} + @var{body}@dots{}) +@end group +@end smallexample + +@menu +* Looping with while:: Repeat so long as test returns true. +* Loop Example:: A @code{while} loop that uses a list. +* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. +* Incrementing Loop:: A loop with an incrementing counter. +* Incrementing Loop Details:: +* Decrementing Loop:: A loop with a decrementing counter. +@end menu + +@node Looping with while, Loop Example, while, while +@ifnottex +@unnumberedsubsec Looping with @code{while} +@end ifnottex + +So long as the true-or-false-test of the @code{while} expression +returns a true value when it is evaluated, the body is repeatedly +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'. + +Clearly, if the value returned by evaluating the first argument to +@code{while} is always true, the body following will be evaluated +again and again @dots{} and again @dots{} forever. Conversely, if the +value returned is never true, the expressions in the body will never +be evaluated. The craft of writing a @code{while} loop consists of +choosing a mechanism such that the true-or-false-test returns true +just the number of times that you want the subsequent expressions to +be evaluated, and then have the test return false. + +The value returned by evaluating a @code{while} is the value of the +true-or-false-test. An interesting consequence of this is that a +@code{while} loop that evaluates without error will return @code{nil} +or false regardless of whether it has looped 1 or 100 times or none at +all. A @code{while} expression that evaluates successfully never +returns a true value! What this means is that @code{while} is always +evaluated for its side effects, which is to say, the consequences of +evaluating the expressions within the body of the @code{while} loop. +This makes sense. It is not the mere act of looping that is desired, +but the consequences of what happens when the expressions in the loop +are repeatedly evaluated. + +@node Loop Example, print-elements-of-list, Looping with while, while +@comment node-name, next, previous, up +@subsection A @code{while} Loop and a List + +A common way to control a @code{while} loop is to test whether a list +has any elements. If it does, the loop is repeated; but if it does not, +the repetition is ended. Since this is an important technique, we will +create a short example to illustrate it. + +A simple way to test whether a list has elements is to evaluate the +list: if it has no elements, it is an empty list and will return the +empty list, @code{()}, which is a synonym for @code{nil} or false. On +the other hand, a list with elements will return those elements when it +is evaluated. Since Emacs Lisp considers as true any value that is not +@code{nil}, a list that returns elements will test true in a +@code{while} loop. + +@need 1200 +For example, you can set the variable @code{empty-list} to @code{nil} by +evaluating the following @code{setq} expression: + +@smallexample +(setq empty-list ()) +@end smallexample + +@noindent +After evaluating the @code{setq} expression, you can evaluate the +variable @code{empty-list} in the usual way, by placing the cursor after +the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your +echo area: + +@smallexample +empty-list +@end smallexample + +On the other hand, if you set a variable to be a list with elements, the +list will appear when you evaluate the variable, as you can see by +evaluating the following two expressions: + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +animals +@end group +@end smallexample + +Thus, to create a @code{while} loop that tests whether there are any +items in the list @code{animals}, the first part of the loop will be +written like this: + +@smallexample +@group +(while animals + @dots{} +@end group +@end smallexample + +@noindent +When the @code{while} tests its first argument, the variable +@code{animals} is evaluated. It returns a list. So long as the list +has elements, the @code{while} considers the results of the test to be +true; but when the list is empty, it considers the results of the test +to be false. + +To prevent the @code{while} loop from running forever, some mechanism +needs to be provided to empty the list eventually. An oft-used +technique is to have one of the subsequent forms in the @code{while} +expression set the value of the list to be the @sc{cdr} of the list. +Each time the @code{cdr} function is evaluated, the list will be made +shorter, until eventually only the empty list will be left. At this +point, the test of the @code{while} loop will return false, and the +arguments to the @code{while} will no longer be evaluated. + +For example, the list of animals bound to the variable @code{animals} +can be set to be the @sc{cdr} of the original list with the +following expression: + +@smallexample +(setq animals (cdr animals)) +@end smallexample + +@noindent +If you have evaluated the previous expressions and then evaluate this +expression, you will see @code{(giraffe lion tiger)} appear in the echo +area. If you evaluate the expression again, @code{(lion tiger)} will +appear in the echo area. If you evaluate it again and yet again, +@code{(tiger)} appears and then the empty list, shown by @code{nil}. + +A template for a @code{while} loop that uses the @code{cdr} function +repeatedly to cause the true-or-false-test eventually to test false +looks like this: + +@smallexample +@group +(while @var{test-whether-list-is-empty} + @var{body}@dots{} + @var{set-list-to-cdr-of-list}) +@end group +@end smallexample + +This test and use of @code{cdr} can be put together in a function that +goes through a list and prints each element of the list on a line of its +own. + +@node print-elements-of-list, Incrementing Loop, Loop Example, while +@subsection An Example: @code{print-elements-of-list} +@findex print-elements-of-list + +The @code{print-elements-of-list} function illustrates a @code{while} +loop with a list. + +@cindex @file{*scratch*} buffer +The function requires several lines for its output. If you are +reading this in a recent instance of GNU Emacs, +@c GNU Emacs 21, GNU Emacs 22, or a later version, +you can evaluate the following expression inside of Info, as usual. + +If you are using an earlier version of Emacs, you need to copy the +necessary expressions to your @file{*scratch*} buffer and evaluate +them there. This is because the echo area had only one line in the +earlier versions. + +You can copy the expressions by marking the beginning of the region +with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to +the end of the region and then copying the region using @kbd{M-w} +(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and +then provides visual feedback). In the @file{*scratch*} +buffer, you can yank the expressions back by typing @kbd{C-y} +(@code{yank}). + +After you have copied the expressions to the @file{*scratch*} buffer, +evaluate each expression in turn. Be sure to evaluate the last +expression, @code{(print-elements-of-list animals)}, by typing +@kbd{C-u C-x C-e}, that is, by giving an argument to +@code{eval-last-sexp}. This will cause the result of the evaluation +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'.) + +@need 1500 +In a recent instance of GNU Emacs, you can evaluate these expressions +directly in the Info buffer, and the echo area will grow to show the +results. + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +(defun print-elements-of-list (list) + "Print each element of LIST on a line of its own." + (while list + (print (car list)) + (setq list (cdr list)))) + +(print-elements-of-list animals) +@end group +@end smallexample + +@need 1200 +@noindent +When you evaluate the three expressions in sequence, you will see +this: + +@smallexample +@group +gazelle + +giraffe + +lion + +tiger +nil +@end group +@end smallexample + +Each element of the list is printed on a line of its own (that is what +the function @code{print} does) and then the value returned by the +function is printed. Since the last expression in the function is the +@code{while} loop, and since @code{while} loops always return +@code{nil}, a @code{nil} is printed after the last element of the list. + +@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while +@comment node-name, next, previous, up +@subsection A Loop with an Incrementing Counter + +A loop is not useful unless it stops when it ought. Besides +controlling a loop with a list, a common way of stopping a loop is to +write the first argument as a test that returns false when the correct +number of repetitions are complete. This means that the loop must +have a counter---an expression that counts how many times the loop +repeats itself. + +@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while +@ifnottex +@unnumberedsubsec Details of an Incrementing Loop +@end ifnottex + +The test for a loop with an incrementing counter can be an expression +such as @code{(< count desired-number)} which returns @code{t} for +true if the value of @code{count} is less than the +@code{desired-number} of repetitions and @code{nil} for false if the +value of @code{count} is equal to or is greater than the +@code{desired-number}. The expression that increments the count can +be a simple @code{setq} such as @code{(setq count (1+ count))}, where +@code{1+} is a built-in function in Emacs Lisp that adds 1 to its +argument. (The expression @w{@code{(1+ count)}} has the same result +as @w{@code{(+ count 1)}}, but is easier for a human to read.) + +@need 1250 +The template for a @code{while} loop controlled by an incrementing +counter looks like this: + +@smallexample +@group +@var{set-count-to-initial-value} +(while (< count desired-number) ; @r{true-or-false-test} + @var{body}@dots{} + (setq count (1+ count))) ; @r{incrementer} +@end group +@end smallexample + +@noindent +Note that you need to set the initial value of @code{count}; usually it +is set to 1. + +@menu +* Incrementing Example:: Counting pebbles in a triangle. +* Inc Example parts:: The parts of the function definition. +* Inc Example altogether:: Putting the function definition together. +@end menu + +@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details +@unnumberedsubsubsec Example with incrementing counter + +Suppose you are playing on the beach and decide to make a triangle of +pebbles, putting one pebble in the first row, two in the second row, +three in the third row and so on, like this: + +@sp 1 +@c pebble diagram +@ifnottex +@smallexample +@group + * + * * + * * * + * * * * +@end group +@end smallexample +@end ifnottex +@iftex +@smallexample +@group + @bullet{} + @bullet{} @bullet{} + @bullet{} @bullet{} @bullet{} + @bullet{} @bullet{} @bullet{} @bullet{} +@end group +@end smallexample +@end iftex +@sp 1 + +@noindent +(About 2500 years ago, Pythagoras and others developed the beginnings of +number theory by considering questions such as this.) + +Suppose you want to know how many pebbles you will need to make a +triangle with 7 rows? + +Clearly, what you need to do is add up the numbers from 1 to 7. There +are two ways to do this; start with the smallest number, one, and add up +the list in sequence, 1, 2, 3, 4 and so on; or start with the largest +number and add the list going down: 7, 6, 5, 4 and so on. Because both +mechanisms illustrate common ways of writing @code{while} loops, we will +create two examples, one counting up and the other counting down. In +this first example, we will start with 1 and add 2, 3, 4 and so on. + +If you are just adding up a short list of numbers, the easiest way to do +it is to add up all the numbers at once. However, if you do not know +ahead of time how many numbers your list will have, or if you want to be +prepared for a very long list, then you need to design your addition so +that what you do is repeat a simple process many times instead of doing +a more complex process once. + +For example, instead of adding up all the pebbles all at once, what you +can do is add the number of pebbles in the first row, 1, to the number +in the second row, 2, and then add the total of those two rows to the +third row, 3. Then you can add the number in the fourth row, 4, to the +total of the first three rows; and so on. + +The critical characteristic of the process is that each repetitive +action is simple. In this case, at each step we add only two numbers, +the number of pebbles in the row and the total already found. This +process of adding two numbers is repeated again and again until the last +row has been added to the total of all the preceding rows. In a more +complex loop the repetitive action might not be so simple, but it will +be simpler than doing everything all at once. + +@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details +@unnumberedsubsubsec The parts of the function definition + +The preceding analysis gives us the bones of our function definition: +first, we will need a variable that we can call @code{total} that will +be the total number of pebbles. This will be the value returned by +the function. + +Second, we know that the function will require an argument: this +argument will be the total number of rows in the triangle. It can be +called @code{number-of-rows}. + +Finally, we need a variable to use as a counter. We could call this +variable @code{counter}, but a better name is @code{row-number}. That +is because what the counter does in this function is count rows, and a +program should be written to be as understandable as possible. + +When the Lisp interpreter first starts evaluating the expressions in the +function, the value of @code{total} should be set to zero, since we have +not added anything to it. Then the function should add the number of +pebbles in the first row to the total, and then add the number of +pebbles in the second to the total, and then add the number of +pebbles in the third row to the total, and so on, until there are no +more rows left to add. + +Both @code{total} and @code{row-number} are used only inside the +function, so they can be declared as local variables with @code{let} +and given initial values. Clearly, the initial value for @code{total} +should be 0. The initial value of @code{row-number} should be 1, +since we start with the first row. This means that the @code{let} +statement will look like this: + +@smallexample +@group + (let ((total 0) + (row-number 1)) + @var{body}@dots{}) +@end group +@end smallexample + +After the internal variables are declared and bound to their initial +values, we can begin the @code{while} loop. The expression that serves +as the test should return a value of @code{t} for true so long as the +@code{row-number} is less than or equal to the @code{number-of-rows}. +(If the expression tests true only so long as the row number is less +than the number of rows in the triangle, the last row will never be +added to the total; hence the row number has to be either less than or +equal to the number of rows.) + +@need 1500 +@findex <= @r{(less than or equal)} +Lisp provides the @code{<=} function that returns true if the value of +its first argument is less than or equal to the value of its second +argument and false otherwise. So the expression that the @code{while} +will evaluate as its test should look like this: + +@smallexample +(<= row-number number-of-rows) +@end smallexample + +The total number of pebbles can be found by repeatedly adding the number +of pebbles in a row to the total already found. Since the number of +pebbles in the row is equal to the row number, the total can be found by +adding the row number to the total. (Clearly, in a more complex +situation, the number of pebbles in the row might be related to the row +number in a more complicated way; if this were the case, the row number +would be replaced by the appropriate expression.) + +@smallexample +(setq total (+ total row-number)) +@end smallexample + +@noindent +What this does is set the new value of @code{total} to be equal to the +sum of adding the number of pebbles in the row to the previous total. + +After setting the value of @code{total}, the conditions need to be +established for the next repetition of the loop, if there is one. This +is done by incrementing the value of the @code{row-number} variable, +which serves as a counter. After the @code{row-number} variable has +been incremented, the true-or-false-test at the beginning of the +@code{while} loop tests whether its value is still less than or equal to +the value of the @code{number-of-rows} and if it is, adds the new value +of the @code{row-number} variable to the @code{total} of the previous +repetition of the loop. + +@need 1200 +The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the +@code{row-number} variable can be incremented with this expression: + +@smallexample +(setq row-number (1+ row-number)) +@end smallexample + +@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details +@unnumberedsubsubsec Putting the function definition together + +We have created the parts for the function definition; now we need to +put them together. + +@need 800 +First, the contents of the @code{while} expression: + +@smallexample +@group +(while (<= row-number number-of-rows) ; @r{true-or-false-test} + (setq total (+ total row-number)) + (setq row-number (1+ row-number))) ; @r{incrementer} +@end group +@end smallexample + +Along with the @code{let} expression varlist, this very nearly +completes the body of the function definition. However, it requires +one final element, the need for which is somewhat subtle. + +The final touch is to place the variable @code{total} on a line by +itself after the @code{while} expression. Otherwise, the value returned +by the whole function is the value of the last expression that is +evaluated in the body of the @code{let}, and this is the value +returned by the @code{while}, which is always @code{nil}. + +This may not be evident at first sight. It almost looks as if the +incrementing expression is the last expression of the whole function. +But that expression is part of the body of the @code{while}; it is the +last element of the list that starts with the symbol @code{while}. +Moreover, the whole of the @code{while} loop is a list within the body +of the @code{let}. + +@need 1250 +In outline, the function will look like this: + +@smallexample +@group +(defun @var{name-of-function} (@var{argument-list}) + "@var{documentation}@dots{}" + (let (@var{varlist}) + (while (@var{true-or-false-test}) + @var{body-of-while}@dots{} ) + @dots{} )) ; @r{Need final expression here.} +@end group +@end smallexample + +The result of evaluating the @code{let} is what is going to be returned +by the @code{defun} since the @code{let} is not embedded within any +containing list, except for the @code{defun} as a whole. However, if +the @code{while} is the last element of the @code{let} expression, the +function will always return @code{nil}. This is not what we want! +Instead, what we want is the value of the variable @code{total}. This +is returned by simply placing the symbol as the last element of the list +starting with @code{let}. It gets evaluated after the preceding +elements of the list are evaluated, which means it gets evaluated after +it has been assigned the correct value for the total. + +It may be easier to see this by printing the list starting with +@code{let} all on one line. This format makes it evident that the +@var{varlist} and @code{while} expressions are the second and third +elements of the list starting with @code{let}, and the @code{total} is +the last element: + +@smallexample +@group +(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) +@end group +@end smallexample + +@need 1200 +Putting everything together, the @code{triangle} function definition +looks like this: + +@smallexample +@group +(defun triangle (number-of-rows) ; @r{Version with} + ; @r{ incrementing counter.} + "Add up the number of pebbles in a triangle. +The first row has one pebble, the second row two pebbles, +the third row three pebbles, and so on. +The argument is NUMBER-OF-ROWS." +@end group +@group + (let ((total 0) + (row-number 1)) + (while (<= row-number number-of-rows) + (setq total (+ total row-number)) + (setq row-number (1+ row-number))) + total)) +@end group +@end smallexample + +@need 1200 +After you have installed @code{triangle} by evaluating the function, you +can try it out. Here are two examples: + +@smallexample +@group +(triangle 4) + +(triangle 7) +@end group +@end smallexample + +@noindent +The sum of the first four numbers is 10 and the sum of the first seven +numbers is 28. + +@node Decrementing Loop, , Incrementing Loop Details, while +@comment node-name, next, previous, up +@subsection Loop with a Decrementing Counter + +Another common way to write a @code{while} loop is to write the test +so that it determines whether a counter is greater than zero. So long +as the counter is greater than zero, the loop is repeated. But when +the counter is equal to or less than zero, the loop is stopped. For +this to work, the counter has to start out greater than zero and then +be made smaller and smaller by a form that is evaluated +repeatedly. + +The test will be an expression such as @code{(> counter 0)} which +returns @code{t} for true if the value of @code{counter} is greater +than zero, and @code{nil} for false if the value of @code{counter} is +equal to or less than zero. The expression that makes the number +smaller and smaller can be a simple @code{setq} such as @code{(setq +counter (1- counter))}, where @code{1-} is a built-in function in +Emacs Lisp that subtracts 1 from its argument. + +@need 1250 +The template for a decrementing @code{while} loop looks like this: + +@smallexample +@group +(while (> counter 0) ; @r{true-or-false-test} + @var{body}@dots{} + (setq counter (1- counter))) ; @r{decrementer} +@end group +@end smallexample + +@menu +* Decrementing Example:: More pebbles on the beach. +* Dec Example parts:: The parts of the function definition. +* Dec Example altogether:: Putting the function definition together. +@end menu + +@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop +@unnumberedsubsubsec Example with decrementing counter + +To illustrate a loop with a decrementing counter, we will rewrite the +@code{triangle} function so the counter decreases to zero. + +This is the reverse of the earlier version of the function. In this +case, to find out how many pebbles are needed to make a triangle with +3 rows, add the number of pebbles in the third row, 3, to the number +in the preceding row, 2, and then add the total of those two rows to +the row that precedes them, which is 1. + +Likewise, to find the number of pebbles in a triangle with 7 rows, add +the number of pebbles in the seventh row, 7, to the number in the +preceding row, which is 6, and then add the total of those two rows to +the row that precedes them, which is 5, and so on. As in the previous +example, each addition only involves adding two numbers, the total of +the rows already added up and the number of pebbles in the row that is +being added to the total. This process of adding two numbers is +repeated again and again until there are no more pebbles to add. + +We know how many pebbles to start with: the number of pebbles in the +last row is equal to the number of rows. If the triangle has seven +rows, the number of pebbles in the last row is 7. Likewise, we know how +many pebbles are in the preceding row: it is one less than the number in +the row. + +@node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop +@unnumberedsubsubsec The parts of the function definition + +We start with three variables: the total number of rows in the +triangle; the number of pebbles in a row; and the total number of +pebbles, which is what we want to calculate. These variables can be +named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and +@code{total}, respectively. + +Both @code{total} and @code{number-of-pebbles-in-row} are used only +inside the function and are declared with @code{let}. The initial +value of @code{total} should, of course, be zero. However, the +initial value of @code{number-of-pebbles-in-row} should be equal to +the number of rows in the triangle, since the addition will start with +the longest row. + +@need 1250 +This means that the beginning of the @code{let} expression will look +like this: + +@smallexample +@group +(let ((total 0) + (number-of-pebbles-in-row number-of-rows)) + @var{body}@dots{}) +@end group +@end smallexample + +The total number of pebbles can be found by repeatedly adding the number +of pebbles in a row to the total already found, that is, by repeatedly +evaluating the following expression: + +@smallexample +(setq total (+ total number-of-pebbles-in-row)) +@end smallexample + +@noindent +After the @code{number-of-pebbles-in-row} is added to the @code{total}, +the @code{number-of-pebbles-in-row} should be decremented by one, since +the next time the loop repeats, the preceding row will be +added to the total. + +The number of pebbles in a preceding row is one less than the number of +pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be +used to compute the number of pebbles in the preceding row. This can be +done with the following expression: + +@smallexample +@group +(setq number-of-pebbles-in-row + (1- number-of-pebbles-in-row)) +@end group +@end smallexample + +Finally, we know that the @code{while} loop should stop making repeated +additions when there are no pebbles in a row. So the test for +the @code{while} loop is simply: + +@smallexample +(while (> number-of-pebbles-in-row 0) +@end smallexample + +@node Dec Example altogether, , Dec Example parts, Decrementing Loop +@unnumberedsubsubsec Putting the function definition together + +We can put these expressions together to create a function definition +that works. However, on examination, we find that one of the local +variables is unneeded! + +@need 1250 +The function definition looks like this: + +@smallexample +@group +;;; @r{First subtractive version.} +(defun triangle (number-of-rows) + "Add up the number of pebbles in a triangle." + (let ((total 0) + (number-of-pebbles-in-row number-of-rows)) + (while (> number-of-pebbles-in-row 0) + (setq total (+ total number-of-pebbles-in-row)) + (setq number-of-pebbles-in-row + (1- number-of-pebbles-in-row))) + total)) +@end group +@end smallexample + +As written, this function works. + +However, we do not need @code{number-of-pebbles-in-row}. + +@cindex Argument as local variable +When the @code{triangle} function is evaluated, the symbol +@code{number-of-rows} will be bound to a number, giving it an initial +value. That number can be changed in the body of the function as if +it were a local variable, without any fear that such a change will +effect the value of the variable outside of the function. This is a +very useful characteristic of Lisp; it means that the variable +@code{number-of-rows} can be used anywhere in the function where +@code{number-of-pebbles-in-row} is used. + +@need 800 +Here is a second version of the function written a bit more cleanly: + +@smallexample +@group +(defun triangle (number) ; @r{Second version.} + "Return sum of numbers 1 through NUMBER inclusive." + (let ((total 0)) + (while (> number 0) + (setq total (+ total number)) + (setq number (1- number))) + total)) +@end group +@end smallexample + +In brief, a properly written @code{while} loop will consist of three parts: + +@enumerate +@item +A test that will return false after the loop has repeated itself the +correct number of times. + +@item +An expression the evaluation of which will return the value desired +after being repeatedly evaluated. + +@item +An expression to change the value passed to the true-or-false-test so +that the test returns false after the loop has repeated itself the right +number of times. +@end enumerate + +@node dolist dotimes, Recursion, while, Loops & Recursion +@comment node-name, next, previous, up +@section Save your time: @code{dolist} and @code{dotimes} + +In addition to @code{while}, both @code{dolist} and @code{dotimes} +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 +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. + +@code{dotimes} loops a specific number of times: you specify the number. + +@menu +* dolist:: +* dotimes:: +@end menu + +@node dolist, dotimes, dolist dotimes, dolist dotimes +@unnumberedsubsubsec The @code{dolist} Macro +@findex dolist + +Suppose, for example, you want to reverse a list, so that +``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. + +@need 1250 +In practice, you would use the @code{reverse} function, like this: + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +(reverse animals) +@end group +@end smallexample + +@need 800 +@noindent +Here is how you could reverse the list using a @code{while} loop: + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +(defun reverse-list-with-while (list) + "Using while, reverse the order of LIST." + (let (value) ; make sure list starts empty + (while list + (setq value (cons (car list) value)) + (setq list (cdr list))) + value)) + +(reverse-list-with-while animals) +@end group +@end smallexample + +@need 800 +@noindent +And here is how you could use the @code{dolist} macro: + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +(defun reverse-list-with-dolist (list) + "Using dolist, reverse the order of LIST." + (let (value) ; make sure list starts empty + (dolist (element list value) + (setq value (cons element value))))) + +(reverse-list-with-dolist animals) +@end group +@end smallexample + +@need 1250 +@noindent +In Info, you can place your cursor after the closing parenthesis of +each expression and type @kbd{C-x C-e}; in each case, you should see + +@smallexample +(tiger lion giraffe gazelle) +@end smallexample + +@noindent +in the echo area. + +For this example, the existing @code{reverse} function is obviously best. +The @code{while} loop is just like our first example (@pxref{Loop +Example, , A @code{while} Loop and a List}). The @code{while} first +checks whether the list has elements; if so, it constructs a new list +by adding the first element of the list to the existing list (which in +the first iteration of the loop is @code{nil}). Since the second +element is prepended in front of the first element, and the third +element is prepended in front of the second element, the list is reversed. + +In the expression using a @code{while} loop, +the @w{@code{(setq list (cdr list))}} +expression shortens the list, so the @code{while} loop eventually +stops. In addition, it provides the @code{cons} expression with a new +first element by creating a new and shorter list at each repetition of +the loop. + +The @code{dolist} expression does very much the same as the +@code{while} expression, except that the @code{dolist} macro does some +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 +the @sc{car} of each shorter version of the list to the first of its +arguments. + +In the example, the @sc{car} of each shorter version of the list is +referred to using the symbol @samp{element}, the list itself is called +@samp{list}, and the value returned is called @samp{value}. The +remainder of the @code{dolist} expression is the body. + +The @code{dolist} expression binds the @sc{car} of each shorter +version of the list to @code{element} and then evaluates the body of +the expression; and repeats the loop. The result is returned in +@code{value}. + +@node dotimes, , dolist, dolist dotimes +@unnumberedsubsubsec The @code{dotimes} Macro +@findex dotimes + +The @code{dotimes} macro is similar to @code{dolist}, except that it +loops a specific number of times. + +The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 +and so forth each time around the loop, and the value of the third +argument is returned. You need to provide the value of the second +argument, which is how many times the macro loops. + +@need 1250 +For example, the following binds the numbers from 0 up to, but not +including, the number 3 to the first argument, @var{number}, and then +constructs a list of the three numbers. (The first number is 0, the +second number is 1, and the third number is 2; this makes a total of +three numbers in all, starting with zero as the first number.) + +@smallexample +@group +(let (value) ; otherwise a value is a void variable + (dotimes (number 3 value) + (setq value (cons number value)))) + +@result{} (2 1 0) +@end group +@end smallexample + +@noindent +@code{dotimes} returns @code{value}, so the way to use +@code{dotimes} is to operate on some expression @var{number} number of +times and then return the result, either as a list or an atom. + +@need 1250 +Here is an example of a @code{defun} that uses @code{dotimes} to add +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." +(let ((total 0)) ; otherwise a total is a void variable + (dotimes (number number-of-rows total) + (setq total (+ total (1+ number)))))) + +(triangle-using-dotimes 4) +@end group +@end smallexample + +@node Recursion, Looping exercise, dolist dotimes, Loops & Recursion +@comment node-name, next, previous, up +@section Recursion +@cindex Recursion + +A recursive function contains code that tells the Lisp interpreter to +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'. + +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 +* Building Robots:: Same model, different serial number ... +* Recursive Definition Parts:: Walk until you stop ... +* Recursion with list:: Using a list as the test whether to recurse. +* Recursive triangle function:: +* Recursion with cond:: +* Recursive Patterns:: Often used templates. +* No Deferment:: Don't store up work ... +* No deferment solution:: +@end menu + +@node Building Robots, Recursive Definition Parts, Recursion, Recursion +@comment node-name, next, previous, up +@subsection Building Robots: Extending the Metaphor +@cindex Building robots +@cindex Robots, building + +It is sometimes helpful to think of a running program as a robot that +does a job. In doing its job, a recursive function calls on a second +robot to help it. The second robot is identical to the first in every +way, except that the second robot helps the first and has been +passed different arguments than the first. + +In a recursive function, the second robot may call a third; and the +third may call a fourth, and so on. Each of these is a different +entity; but all are clones. + +Since each robot has slightly different instructions---the arguments +will differ from one robot to the next---the last robot should know +when to stop. + +Let's expand on the metaphor in which a computer program is a robot. + +A function definition provides the blueprints for a robot. When you +install a function definition, that is, when you evaluate a +@code{defun} special form, 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'. + +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. + +It is important that the arguments differ from one instance to the +next; otherwise, the process will never stop. + +@node Recursive Definition Parts, Recursion with list, Building Robots, Recursion +@comment node-name, next, previous, up +@subsection The Parts of a Recursive Definition +@cindex Parts of a Recursive Definition +@cindex Recursive Definition Parts + +A recursive function typically contains a conditional expression which +has three parts: + +@enumerate +@item +A true-or-false-test that determines whether the function is called +again, here called the @dfn{do-again-test}. + +@item +The name of the function. When this name is called, a new instance of +the function---a new robot, as it were---is created and told what to do. + +@item +An expression that returns a different value each time the function is +called, here called the @dfn{next-step-expression}. Consequently, the +argument (or arguments) passed to the new instance of the function +will be different from that passed to the previous instance. This +causes the conditional expression, the @dfn{do-again-test}, to test +false after the correct number of repetitions. +@end enumerate + +Recursive functions can be much simpler than any other kind of +function. Indeed, when people first start to use them, they often look +so mysteriously simple as to be incomprehensible. Like riding a +bicycle, reading a recursive function definition takes a certain knack +which is hard at first but then seems simple. + +@need 1200 +There are several different common recursive patterns. A very simple +pattern looks like this: + +@smallexample +@group +(defun @var{name-of-recursive-function} (@var{argument-list}) + "@var{documentation}@dots{}" + (if @var{do-again-test} + @var{body}@dots{} + (@var{name-of-recursive-function} + @var{next-step-expression}))) +@end group +@end smallexample + +Each time a recursive function is evaluated, a new instance of it is +created and told what to do. The arguments tell the instance what to do. + +An argument is bound to the value of the next-step-expression. Each +instance runs with a different value of the next-step-expression. + +The value in the next-step-expression is used in the do-again-test. + +The value returned by the next-step-expression is passed to the new +instance of the function, which evaluates it (or some +transmogrification of it) to determine whether to continue or stop. +The next-step-expression is designed so that the do-again-test returns +false when the function should no longer be repeated. + +The do-again-test is sometimes called the @dfn{stop condition}, +since it stops the repetitions when it tests false. + +@node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion +@comment node-name, next, previous, up +@subsection Recursion with a List + +The example of a @code{while} loop that printed the elements of a list +of numbers can be written recursively. Here is the code, including +an expression to set the value of the variable @code{animals} to a list. + +If you are using GNU Emacs 20 or before, this example must be copied +to the @file{*scratch*} buffer and each expression must be evaluated +there. Use @kbd{C-u C-x C-e} to evaluate the +@code{(print-elements-recursively animals)} expression so that the +results are printed in the buffer; otherwise the Lisp interpreter will +try to squeeze the results into the one line of the echo area. + +Also, place your cursor immediately after the last closing parenthesis +of the @code{print-elements-recursively} function, before the comment. +Otherwise, the Lisp interpreter will try to evaluate the comment. + +If you are using a more recent version of Emacs, you can evaluate this +expression directly in Info. + +@findex print-elements-recursively +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) + +(defun print-elements-recursively (list) + "Print each element of LIST on a line of its own. +Uses recursion." + (when list ; @r{do-again-test} + (print (car list)) ; @r{body} + (print-elements-recursively ; @r{recursive call} + (cdr list)))) ; @r{next-step-expression} + +(print-elements-recursively animals) +@end group +@end smallexample + +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 +whole list, but the second and subsequent elements of the list, the +@sc{cdr} of the list. + +Put another way, if the list is not empty, the function invokes +another instance of code that is similar to the initial code, but is a +different thread of execution, with different arguments than the first +instance. + +Put in yet another way, if the list is not empty, the first robot +assemblies a second robot and tells it what to do; the second robot is +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 +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 +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 +shorter version of the original list. It creates a new instance that +works on a shorter list. + +Eventually, the function invokes itself on an empty list. It creates +a new instance whose argument is @code{nil}. The conditional expression +tests the value of @code{list}. Since the value of @code{list} is +@code{nil}, the @code{when} expression tests false so the then-part is +not evaluated. The function as a whole then returns @code{nil}. + +@need 1200 +When you evaluate @code{(print-elements-recursively animals)} in the +@file{*scratch*} buffer, you see this result: + +@smallexample +@group +gazelle + +giraffe + +lion + +tiger +nil +@end group +@end smallexample + +@need 2000 +@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion +@comment node-name, next, previous, up +@subsection Recursion in Place of a Counter +@findex triangle-recursively + +@need 1200 +The @code{triangle} function described in a previous section can also +be written recursively. It looks like this: + +@smallexample +@group +(defun triangle-recursively (number) + "Return the sum of the numbers 1 through NUMBER inclusive. +Uses recursion." + (if (= number 1) ; @r{do-again-test} + 1 ; @r{then-part} + (+ number ; @r{else-part} + (triangle-recursively ; @r{recursive call} + (1- number))))) ; @r{next-step-expression} + +(triangle-recursively 7) +@end group +@end smallexample + +@noindent +You can install this function by evaluating it and then try it by +evaluating @code{(triangle-recursively 7)}. (Remember to put your +cursor immediately after the last parenthesis of the function +definition, before the comment.) The function evaluates to 28. + +To understand how this function works, let's consider what happens in the +various cases when the function is passed 1, 2, 3, or 4 as the value of +its argument. + +@menu +* Recursive Example arg of 1 or 2:: +* Recursive Example arg of 3 or 4:: +@end menu + +@node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function +@ifnottex +@unnumberedsubsubsec An argument of 1 or 2 +@end ifnottex + +First, what happens if the value of the argument is 1? + +The function has an @code{if} expression after the documentation +string. It tests whether the value of @code{number} is equal to 1; if +so, Emacs evaluates the then-part of the @code{if} expression, which +returns the number 1 as the value of the function. (A triangle with +one row has one pebble in it.) + +Suppose, however, that the value of the argument is 2. In this case, +Emacs evaluates the else-part of the @code{if} expression. + +@need 1200 +The else-part consists of an addition, the recursive call to +@code{triangle-recursively} and a decrementing action; and it looks like +this: + +@smallexample +(+ number (triangle-recursively (1- number))) +@end smallexample + +When Emacs evaluates this expression, the innermost expression is +evaluated first; then the other parts in sequence. Here are the steps +in detail: + +@table @i +@item Step 1 @w{ } Evaluate the innermost expression. + +The innermost expression is @code{(1- number)} so Emacs decrements the +value of @code{number} from 2 to 1. + +@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. + +The Lisp interpreter creates an individual instance of +@code{triangle-recursively}. It does not matter that this function is +contained within itself. Emacs passes the result Step 1 as the +argument used by this instance of the @code{triangle-recursively} +function + +In this case, Emacs evaluates @code{triangle-recursively} with an +argument of 1. This means that this evaluation of +@code{triangle-recursively} returns 1. + +@item Step 3 @w{ } Evaluate the value of @code{number}. + +The variable @code{number} is the second element of the list that +starts with @code{+}; its value is 2. + +@item Step 4 @w{ } Evaluate the @code{+} expression. + +The @code{+} expression receives two arguments, the first +from the evaluation of @code{number} (Step 3) and the second from the +evaluation of @code{triangle-recursively} (Step 2). + +The result of the addition is the sum of 2 plus 1, and the number 3 is +returned, which is correct. A triangle with two rows has three +pebbles in it. +@end table + +@node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function +@unnumberedsubsubsec An argument of 3 or 4 + +Suppose that @code{triangle-recursively} is called with an argument of +3. + +@table @i +@item Step 1 @w{ } Evaluate the do-again-test. + +The @code{if} expression is evaluated first. This is the do-again +test and returns false, so the else-part of the @code{if} expression +is evaluated. (Note that in this example, the do-again-test causes +the function to call itself when it tests false, not when it tests +true.) + +@item Step 2 @w{ } Evaluate the innermost expression of the else-part. + +The innermost expression of the else-part is evaluated, which decrements +3 to 2. This is the next-step-expression. + +@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. + +The number 2 is passed to the @code{triangle-recursively} function. + +We know what happens when Emacs evaluates @code{triangle-recursively} with +an argument of 2. After going through the sequence of actions described +earlier, it returns a value of 3. So that is what will happen here. + +@item Step 4 @w{ } Evaluate the addition. + +3 will be passed as an argument to the addition and will be added to the +number with which the function was called, which is 3. +@end table + +@noindent +The value returned by the function as a whole will be 6. + +Now that we know what will happen when @code{triangle-recursively} is +called with an argument of 3, it is evident what will happen if it is +called with an argument of 4: + +@quotation +@need 800 +In the recursive call, the evaluation of + +@smallexample +(triangle-recursively (1- 4)) +@end smallexample + +@need 800 +@noindent +will return the value of evaluating + +@smallexample +(triangle-recursively 3) +@end smallexample + +@noindent +which is 6 and this value will be added to 4 by the addition in the +third line. +@end quotation + +@noindent +The value returned by the function as a whole will be 10. + +Each time @code{triangle-recursively} is evaluated, it evaluates a +version of itself---a different instance of itself---with a smaller +argument, until the argument is small enough so that it does not +evaluate itself. + +Note that this particular design for a recursive function +requires that operations be deferred. + +Before @code{(triangle-recursively 7)} can calculate its answer, it +must call @code{(triangle-recursively 6)}; and before +@code{(triangle-recursively 6)} can calculate its answer, it must call +@code{(triangle-recursively 5)}; and so on. That is to say, the +calculation that @code{(triangle-recursively 7)} makes must be +deferred until @code{(triangle-recursively 6)} makes its calculation; +and @code{(triangle-recursively 6)} must defer until +@code{(triangle-recursively 5)} completes; and so on. + +If each of these instances of @code{triangle-recursively} are thought +of as different robots, the first robot must wait for the second to +complete its job, which must wait until the third completes, and so +on. + +There is a way around this kind of waiting, which we will discuss in +@ref{No Deferment, , Recursion without Deferments}. + +@node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion +@comment node-name, next, previous, up +@subsection Recursion Example Using @code{cond} +@findex cond + +The version of @code{triangle-recursively} described earlier is written +with the @code{if} special form. It can also be written using another +special form called @code{cond}. The name of the special form +@code{cond} is an abbreviation of the word @samp{conditional}. + +Although the @code{cond} special form is not used as often in the +Emacs Lisp sources as @code{if}, it is used often enough to justify +explaining it. + +@need 800 +The template for a @code{cond} expression looks like this: + +@smallexample +@group +(cond + @var{body}@dots{}) +@end group +@end smallexample + +@noindent +where the @var{body} is a series of lists. + +@need 800 +Written out more fully, the template looks like this: + +@smallexample +@group +(cond + (@var{first-true-or-false-test} @var{first-consequent}) + (@var{second-true-or-false-test} @var{second-consequent}) + (@var{third-true-or-false-test} @var{third-consequent}) + @dots{}) +@end group +@end smallexample + +When the Lisp interpreter evaluates the @code{cond} expression, it +evaluates the first element (the @sc{car} or true-or-false-test) of +the first expression in a series of expressions within the body of the +@code{cond}. + +If the true-or-false-test returns @code{nil} the rest of that +expression, the consequent, is skipped and the true-or-false-test of the +next expression is evaluated. When an expression is found whose +true-or-false-test returns a value that is not @code{nil}, the +consequent of that expression is evaluated. The consequent can be one +or more expressions. If the consequent consists of more than one +expression, the expressions are evaluated in sequence and the value of +the last one is returned. If the expression does not have a consequent, +the value of the true-or-false-test is returned. + +If none of the true-or-false-tests test true, the @code{cond} expression +returns @code{nil}. + +@need 1250 +Written using @code{cond}, the @code{triangle} function looks like this: + +@smallexample +@group +(defun triangle-using-cond (number) + (cond ((<= number 0) 0) + ((= number 1) 1) + ((> number 1) + (+ number (triangle-using-cond (1- number)))))) +@end group +@end smallexample + +@noindent +In this example, the @code{cond} returns 0 if the number is less than or +equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ +number (triangle-using-cond (1- number)))} if the number is greater than +1. + +@node Recursive Patterns, No Deferment, Recursion with cond, Recursion +@comment node-name, next, previous, up +@subsection Recursive Patterns +@cindex Recursive Patterns + +Here are three common recursive patterns. Each involves a list. +Recursion does not need to involve lists, but Lisp is designed for lists +and this provides a sense of its primal capabilities. + +@menu +* Every:: +* Accumulate:: +* Keep:: +@end menu + +@node Every, Accumulate, Recursive Patterns, Recursive Patterns +@comment node-name, next, previous, up +@unnumberedsubsubsec Recursive Pattern: @emph{every} +@cindex Every, type of recursive pattern +@cindex Recursive pattern: every + +In the @code{every} recursive pattern, an action is performed on every +element of a list. + +@need 1500 +The basic pattern is: + +@itemize @bullet +@item +If a list be empty, return @code{nil}. +@item +Else, act on the beginning of the list (the @sc{car} of the list) + @itemize @minus + @item + through a recursive call by the function on the rest (the + @sc{cdr}) of the list, + @item + and, optionally, combine the acted-on element, using @code{cons}, + with the results of acting on the rest. + @end itemize +@end itemize + +@need 1500 +Here is example: + +@smallexample +@group +(defun square-each (numbers-list) + "Square each of a NUMBERS LIST, recursively." + (if (not numbers-list) ; do-again-test + nil + (cons + (* (car numbers-list) (car numbers-list)) + (square-each (cdr numbers-list))))) ; next-step-expression +@end group + +@group +(square-each '(1 2 3)) + @result{} (1 4 9) +@end group +@end smallexample + +@need 1200 +@noindent +If @code{numbers-list} is empty, do nothing. But if it has content, +construct a list combining the square of the first number in the list +with the result of the recursive call. + +(The example follows the pattern exactly: @code{nil} is returned if +the numbers' list is empty. In practice, you would write the +conditional so it carries out the action when the numbers' list is not +empty.) + +The @code{print-elements-recursively} function (@pxref{Recursion with +list, , Recursion with a List}) is another example of an @code{every} +pattern, except in this case, rather than bring the results together +using @code{cons}, we print each element of output. + +@need 1250 +The @code{print-elements-recursively} function looks like this: + +@smallexample +@group +(setq animals '(gazelle giraffe lion tiger)) +@end group + +@group +(defun print-elements-recursively (list) + "Print each element of LIST on a line of its own. +Uses recursion." + (when list ; @r{do-again-test} + (print (car list)) ; @r{body} + (print-elements-recursively ; @r{recursive call} + (cdr list)))) ; @r{next-step-expression} + +(print-elements-recursively animals) +@end group +@end smallexample + +@need 1500 +The pattern for @code{print-elements-recursively} is: + +@itemize @bullet +@item +When the list is empty, do nothing. +@item +But when the list has at least one element, + @itemize @minus + @item + act on the beginning of the list (the @sc{car} of the list), + @item + and make a recursive call on the rest (the @sc{cdr}) of the list. + @end itemize +@end itemize + +@node Accumulate, Keep, Every, Recursive Patterns +@comment node-name, next, previous, up +@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} +@cindex Accumulate, type of recursive pattern +@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 +@code{cons} is not used, but some other combiner. + +@need 1500 +The pattern is: + +@itemize @bullet +@item +If a list be empty, return zero or some other constant. +@item +Else, act on the beginning of the list (the @sc{car} of the list), + @itemize @minus + @item + and combine that acted-on element, using @code{+} or + some other combining function, with + @item + a recursive call by the function on the rest (the @sc{cdr}) of the list. + @end itemize +@end itemize + +@need 1500 +Here is an example: + +@smallexample +@group +(defun add-elements (numbers-list) + "Add the elements of NUMBERS-LIST together." + (if (not numbers-list) + 0 + (+ (car numbers-list) (add-elements (cdr numbers-list))))) +@end group + +@group +(add-elements '(1 2 3 4)) + @result{} 10 +@end group +@end smallexample + +@xref{Files List, , Making a List of Files}, for an example of the +accumulate pattern. + +@node Keep, , Accumulate, Recursive Patterns +@comment node-name, next, previous, up +@unnumberedsubsubsec Recursive Pattern: @emph{keep} +@cindex Keep, type of recursive pattern +@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 +skipped unless it meets a criterion. + +@need 1500 +The pattern has three parts: + +@itemize @bullet +@item +If a list be empty, return @code{nil}. +@item +Else, if the beginning of the list (the @sc{car} of the list) passes + a test + @itemize @minus + @item + act on that element and combine it, using @code{cons} with + @item + a recursive call by the function on the rest (the @sc{cdr}) of the list. + @end itemize +@item +Otherwise, if the beginning of the list (the @sc{car} of the list) fails +the test + @itemize @minus + @item + skip on that element, + @item + and, recursively call the function on the rest (the @sc{cdr}) of the list. + @end itemize +@end itemize + +@need 1500 +Here is an example that uses @code{cond}: + +@smallexample +@group +(defun keep-three-letter-words (word-list) + "Keep three letter words in WORD-LIST." + (cond + ;; First do-again-test: stop-condition + ((not word-list) nil) + + ;; Second do-again-test: when to act + ((eq 3 (length (symbol-name (car word-list)))) + ;; combine acted-on element with recursive call on shorter list + (cons (car word-list) (keep-three-letter-words (cdr word-list)))) + + ;; Third do-again-test: when to skip element; + ;; recursively call shorter list with next-step expression + (t (keep-three-letter-words (cdr word-list))))) +@end group + +@group +(keep-three-letter-words '(one two three four five six)) + @result{} (one two six) +@end group +@end smallexample + +It goes without saying that you need not use @code{nil} as the test for +when to stop; and you can, of course, combine these patterns. + +@node No Deferment, No deferment solution, Recursive Patterns, Recursion +@subsection Recursion without Deferments +@cindex Deferment in recursion +@cindex Recursion without Deferments + +Let's consider again what happens with the @code{triangle-recursively} +function. We will find that the intermediate calculations are +deferred until all can be done. + +@need 800 +Here is the function definition: + +@smallexample +@group +(defun triangle-recursively (number) + "Return the sum of the numbers 1 through NUMBER inclusive. +Uses recursion." + (if (= number 1) ; @r{do-again-test} + 1 ; @r{then-part} + (+ number ; @r{else-part} + (triangle-recursively ; @r{recursive call} + (1- number))))) ; @r{next-step-expression} +@end group +@end smallexample + +What happens when we call this function with a argument of 7? + +The first instance of the @code{triangle-recursively} function adds +the number 7 to the value returned by a second instance of +@code{triangle-recursively}, an instance that has been passed an +argument of 6. That is to say, the first calculation is: + +@smallexample +(+ 7 (triangle-recursively 6)) +@end smallexample + +@noindent +The first instance of @code{triangle-recursively}---you may want to +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 +robot. It is the same model as the first; it calculates triangle +numbers recursively; but it has a different serial number. + +And what does @code{(triangle-recursively 6)} return? It returns the +number 6 added to the value returned by evaluating +@code{triangle-recursively} with an argument of 5. Using the robot +metaphor, it asks yet another robot to help it. + +@need 800 +Now the total is: + +@smallexample +(+ 7 6 (triangle-recursively 5)) +@end smallexample + +@need 800 +And what happens next? + +@smallexample +(+ 7 6 5 (triangle-recursively 4)) +@end smallexample + +Each time @code{triangle-recursively} is called, except for the last +time, it creates another instance of the program---another robot---and +asks it to make a calculation. + +@need 800 +Eventually, the full addition is set up and performed: + +@smallexample +(+ 7 6 5 4 3 2 1) +@end smallexample + +This design for the function defers the calculation of the first step +until the second can be done, and defers that until the third can be +done, and so on. Each deferment means the computer must remember what +is being waited on. This is not a problem when there are only a few +steps, as in this example. But it can be a problem when there are +more steps. + +@node No deferment solution, , No Deferment, Recursion +@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 +writing to a different pattern, often one that involves writing two +function definitions, an `initialization' function and a `helper' +function. + +The `initialization' function sets up the job; the `helper' function +does the work. + +@need 1200 +Here are the two function definitions for adding up numbers. They are +so simple, I find them hard to understand. + +@smallexample +@group +(defun triangle-initialization (number) + "Return the sum of the numbers 1 through NUMBER inclusive. +This is the `initialization' component of a two function +duo that uses recursion." + (triangle-recursive-helper 0 0 number)) +@end group +@end smallexample + +@smallexample +@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 +that uses recursion." + (if (> counter number) + sum + (triangle-recursive-helper (+ sum counter) ; @r{sum} + (1+ counter) ; @r{counter} + number))) ; @r{number} +@end group +@end smallexample + +@need 1250 +Install both function definitions by evaluating them, then call +@code{triangle-initialization} with 2 rows: + +@smallexample +@group +(triangle-initialization 2) + @result{} 3 +@end group +@end smallexample + +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 +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 +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.} + +Let's see what happens when we have a triangle that has one row. (This +triangle will have one pebble in it!) + +@need 1200 +@code{triangle-initialization} will call its helper with +the arguments @w{@code{0 0 1}}. That function will run the conditional +test whether @code{(> counter number)}: + +@smallexample +(> 0 1) +@end smallexample + +@need 1200 +@noindent +and find that the result is false, so it will invoke +the else-part of the @code{if} clause: + +@smallexample +@group + (triangle-recursive-helper + (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} + (1+ counter) ; @r{increment counter} @result{} @r{counter} + number) ; @r{number stays the same} +@end group +@end smallexample + +@need 800 +@noindent +which will first compute: + +@smallexample +@group +(triangle-recursive-helper (+ 0 0) ; @r{sum} + (1+ 0) ; @r{counter} + 1) ; @r{number} +@exdent which is: + +(triangle-recursive-helper 0 1 1) +@end group +@end smallexample + +Again, @code{(> counter number)} will be false, so again, the Lisp +interpreter will evaluate @code{triangle-recursive-helper}, creating a +new instance with new arguments. + +@need 800 +This new instance will be; + +@smallexample +@group + (triangle-recursive-helper + (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} + (1+ counter) ; @r{increment counter} @result{} @r{counter} + number) ; @r{number stays the same} + +@exdent which is: + +(triangle-recursive-helper 1 2 1) +@end group +@end smallexample + +In this case, the @code{(> counter number)} test will be true! So the +instance will return the value of the sum, which will be 1, as +expected. + +Now, let's pass @code{triangle-initialization} an argument +of 2, to find out how many pebbles there are in a triangle with two rows. + +That function calls @code{(triangle-recursive-helper 0 0 2)}. + +@need 800 +In stages, the instances called will be: + +@smallexample +@group + @r{sum counter number} +(triangle-recursive-helper 0 1 2) + +(triangle-recursive-helper 1 2 2) + +(triangle-recursive-helper 3 3 2) +@end group +@end smallexample + +When the last instance is called, the @code{(> counter number)} test +will be true, so the instance will return the value of @code{sum}, +which will be 3. + +This kind of pattern helps when you are writing functions that can use +many resources in a computer. + +@need 1500 +@node Looping exercise, , Recursion, Loops & Recursion +@section Looping Exercise + +@itemize @bullet +@item +Write a function similar to @code{triangle} in which each row has a +value which is the square of the row number. Use a @code{while} loop. + +@item +Write a function similar to @code{triangle} that multiplies instead of +adds the values. + +@item +Rewrite these two functions recursively. Rewrite these functions +using @code{cond}. + +@c comma in printed title causes problem in Info cross reference +@item +Write a function for Texinfo mode that creates an index entry at the +beginning of a paragraph for every @samp{@@dfn} within the paragraph. +(In a Texinfo file, @samp{@@dfn} marks a definition. This book is +written in Texinfo.) + +Many of the functions you will need are described in two of the +previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing +Text}, and @ref{Yanking, , Yanking Text Back}. If you use +@code{forward-paragraph} to put the index entry at the beginning of +the paragraph, you will have to use @w{@kbd{C-h f}} +(@code{describe-function}) to find out how to make the command go +backwards. + +For more information, see +@ifinfo +@ref{Indicating, , Indicating Definitions, texinfo}. +@end ifinfo +@ifhtml +@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to +a Texinfo manual in the current directory. Or, if you are on the +Internet, see +@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} +@end ifhtml +@iftex +``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU +Documentation Format}. +@end iftex +@end itemize + +@node Regexp Search, Counting Words, Loops & Recursion, Top +@comment node-name, next, previous, up +@chapter Regular Expression Searches +@cindex Searches, illustrating +@cindex Regular expression searches +@cindex Patterns, searching for +@cindex Motion by sentence and paragraph +@cindex Sentences, movement by +@cindex Paragraphs, movement by + +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'. + +Regular expression searches are described in @ref{Regexp Search, , +Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in +@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference +Manual}. In writing this chapter, I am presuming that you have at +least a mild acquaintance with them. The major point to remember is +that regular expressions permit you to search for patterns as well as +for literal strings of characters. For example, the code in +@code{forward-sentence} searches for the pattern of possible +characters that could mark the end of a sentence, and moves point to +that spot. + +Before looking at the code for the @code{forward-sentence} function, it +is worth considering what the pattern that marks the end of a sentence +must be. The pattern is discussed in the next section; following that +is a description of the regular expression search function, +@code{re-search-forward}. The @code{forward-sentence} function +is described in the section following. Finally, the +@code{forward-paragraph} function is described in the last section of +this chapter. @code{forward-paragraph} is a complex function that +introduces several new features. + +@menu +* sentence-end:: The regular expression for @code{sentence-end}. +* re-search-forward:: Very similar to @code{search-forward}. +* forward-sentence:: A straightforward example of regexp search. +* forward-paragraph:: A somewhat complex example. +* etags:: How to create your own @file{TAGS} table. +* Regexp Review:: +* re-search Exercises:: +@end menu + +@node sentence-end, re-search-forward, Regexp Search, Regexp Search +@comment node-name, next, previous, up +@section The Regular Expression for @code{sentence-end} +@findex sentence-end + +The symbol @code{sentence-end} is bound to the pattern that marks the +end of a sentence. What should this regular expression be? + +Clearly, a sentence may be ended by a period, a question mark, or an +exclamation mark. Indeed, in English, only clauses that end with one +of those three characters should be considered the end of a sentence. +This means that the pattern should include the character set: + +@smallexample +[.?!] +@end smallexample + +However, we do not want @code{forward-sentence} merely to jump to a +period, a question mark, or an exclamation mark, because such a character +might be used in the middle of a sentence. A period, for example, is +used after abbreviations. So other information is needed. + +According to convention, you type two spaces after every sentence, but +only one space after a period, a question mark, or an exclamation mark in +the body of a sentence. So a period, a question mark, or an exclamation +mark followed by two spaces is a good indicator of an end of sentence. +However, in a file, the two spaces may instead be a tab or the end of a +line. This means that the regular expression should include these three +items as alternatives. + +@need 800 +This group of alternatives will look like this: + +@smallexample +@group +\\($\\| \\| \\) + ^ ^^ + TAB SPC +@end group +@end smallexample + +@noindent +Here, @samp{$} indicates the end of the line, and I have pointed out +where the tab and two spaces are inserted in the expression. Both are +inserted by putting the actual characters into the expression. + +Two backslashes, @samp{\\}, are required before the parentheses and +vertical bars: the first backslash quotes the following backslash in +Emacs; and the second indicates that the following character, the +parenthesis or the vertical bar, is special. + +@need 1000 +Also, a sentence may be followed by one or more carriage returns, like +this: + +@smallexample +@group +[ +]* +@end group +@end smallexample + +@noindent +Like tabs and spaces, a carriage return is inserted into a regular +expression by inserting it literally. The asterisk indicates that the +@key{RET} is repeated zero or more times. + +But a sentence end does not consist only of a period, a question mark or +an exclamation mark followed by appropriate space: a closing quotation +mark or a closing brace of some kind may precede the space. Indeed more +than one such mark or brace may precede the space. These require a +expression that looks like this: + +@smallexample +[]\"')@}]* +@end smallexample + +In this expression, the first @samp{]} is the first character in the +expression; the second character is @samp{"}, which is preceded by a +@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last +three characters are @samp{'}, @samp{)}, and @samp{@}}. + +All this suggests what the regular expression pattern for matching the +end of a sentence should be; and, indeed, if we evaluate +@code{sentence-end} we find that it returns the following value: + +@smallexample +@group +sentence-end + @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ +]*" +@end group +@end smallexample + +@noindent +(Well, not in GNU Emacs 22; that is because of an effort to make the +process simpler and to handle more glyphs and languages. When the +value of @code{sentence-end} is @code{nil}, then use the value defined +by the function @code{sentence-end}. (Here is a use of the difference +between a value and a function in Emacs Lisp.) The function returns a +value constructed from the variables @code{sentence-end-base}, +@code{sentence-end-double-space}, @code{sentence-end-without-period}, +and @code{sentence-end-without-space}. The critical variable is +@code{sentence-end-base}; its global value is similar to the one +described above but it also contains two additional quotation marks. +These have differing degrees of curliness. The +@code{sentence-end-without-period} variable, when true, tells Emacs +that a sentence may end without a period, such as text in Thai.) + +@ignore +@noindent +(Note that here the @key{TAB}, two spaces, and @key{RET} are shown +literally in the pattern.) + +This regular expression can be deciphered as follows: + +@table @code +@item [.?!] +The first part of the pattern is the three characters, a period, a question +mark and an exclamation mark, within square brackets. The pattern must +begin with one or other of these characters. + +@item []\"')@}]* +The second part of the pattern is the group of closing braces and +quotation marks, which can appear zero or more times. These may follow +the period, question mark or exclamation mark. In a regular expression, +the backslash, @samp{\}, followed by the double quotation mark, +@samp{"}, indicates the class of string-quote characters. Usually, the +double quotation mark is the only character in this class. The +asterisk, @samp{*}, indicates that the items in the previous group (the +group surrounded by square brackets, @samp{[]}) may be repeated zero or +more times. + +@item \\($\\| \\| \\) +The third part of the pattern is one or other of: either the end of a +line, or two blank spaces, or a tab. The double back-slashes are used +to prevent Emacs from reading the parentheses and vertical bars as part +of the search pattern; the parentheses are used to mark the group and +the vertical bars are used to indicated that the patterns to either side +of them are alternatives. The dollar sign is used to indicate the end +of a line and both the two spaces and the tab are each inserted as is to +indicate what they are. + +@item [@key{RET}]* +Finally, the last part of the pattern indicates that the end of the line +or the whitespace following the period, question mark or exclamation +mark may, but need not, be followed by one or more carriage returns. In +the pattern, the carriage return is inserted as an actual carriage +return between square brackets but here it is shown as @key{RET}. +@end table +@end ignore + +@node re-search-forward, forward-sentence, sentence-end, Regexp Search +@comment node-name, next, previous, up +@section The @code{re-search-forward} Function +@findex re-search-forward + +The @code{re-search-forward} function is very like the +@code{search-forward} function. (@xref{search-forward, , The +@code{search-forward} Function}.) + +@code{re-search-forward} searches for a regular expression. If the +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'.) + +Like @code{search-forward}, the @code{re-search-forward} function takes +four arguments: + +@enumerate +@item +The first argument is the regular expression that the function searches +for. The regular expression will be a string between quotations marks. + +@item +The optional second argument limits how far the function will search; it is a +bound, which is specified as a position in the buffer. + +@item +The optional third argument specifies how the function responds to +failure: @code{nil} as the third argument causes the function to +signal an error (and print a message) when the search fails; any other +value causes it to return @code{nil} if the search fails and @code{t} +if the search succeeds. + +@item +The optional fourth argument is the repeat count. A negative repeat +count causes @code{re-search-forward} to search backwards. +@end enumerate + +@need 800 +The template for @code{re-search-forward} looks like this: + +@smallexample +@group +(re-search-forward "@var{regular-expression}" + @var{limit-of-search} + @var{what-to-do-if-search-fails} + @var{repeat-count}) +@end group +@end smallexample + +The second, third, and fourth arguments are optional. However, if you +want to pass a value to either or both of the last two arguments, you +must also pass a value to all the preceding arguments. Otherwise, the +Lisp interpreter will mistake which argument you are passing the value +to. + +@need 1200 +In the @code{forward-sentence} function, the regular expression will be +the value of the variable @code{sentence-end}. In simple form, that is: + +@smallexample +@group +"[.?!][]\"')@}]*\\($\\| \\| \\)[ +]*" +@end group +@end smallexample + +@noindent +The limit of the search will be the end of the paragraph (since a +sentence cannot go beyond a paragraph). If the search fails, the +function will return @code{nil}; and the repeat count will be provided +by the argument to the @code{forward-sentence} function. + +@node forward-sentence, forward-paragraph, re-search-forward, Regexp Search +@comment node-name, next, previous, up +@section @code{forward-sentence} +@findex forward-sentence + +The command to move the cursor forward a sentence is a straightforward +illustration of how to use regular expression searches in Emacs Lisp. +Indeed, the function looks longer and more complicated than it is; this +is because the function is designed to go backwards as well as forwards; +and, optionally, over more than one sentence. The function is usually +bound to the key command @kbd{M-e}. + +@menu +* Complete forward-sentence:: +* fwd-sentence while loops:: Two @code{while} loops. +* fwd-sentence re-search:: A regular expression search. +@end menu + +@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence +@ifnottex +@unnumberedsubsec Complete @code{forward-sentence} function definition +@end ifnottex + +@need 1250 +Here is the code for @code{forward-sentence}: + +@c in GNU Emacs 22 +@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'. + +The variable `sentence-end' is a regular expression that matches ends of +sentences. Also, every paragraph boundary terminates sentences as well." +@end group +@group + (interactive "p") + (or arg (setq arg 1)) + (let ((opoint (point)) + (sentence-end (sentence-end))) + (while (< arg 0) + (let ((pos (point)) + (par-beg (save-excursion (start-of-paragraph-text) (point)))) + (if (and (re-search-backward sentence-end par-beg t) + (or (< (match-end 0) pos) + (re-search-backward sentence-end par-beg t))) + (goto-char (match-end 0)) + (goto-char par-beg))) + (setq arg (1+ arg))) +@end group +@group + (while (> arg 0) + (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) + (if (re-search-forward sentence-end par-end t) + (skip-chars-backward " \t\n") + (goto-char par-end))) + (setq arg (1- arg))) + (constrain-to-field nil opoint t))) +@end group +@end smallexample + +@ignore +GNU Emacs 21 +@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. +Sentence ends are identified by the value of sentence-end +treated as a regular expression. Also, every paragraph boundary +terminates sentences as well." +@end group +@group + (interactive "p") + (or arg (setq arg 1)) + (while (< arg 0) + (let ((par-beg + (save-excursion (start-of-paragraph-text) (point)))) + (if (re-search-backward + (concat sentence-end "[^ \t\n]") par-beg t) + (goto-char (1- (match-end 0))) + (goto-char par-beg))) + (setq arg (1+ arg))) + (while (> arg 0) + (let ((par-end + (save-excursion (end-of-paragraph-text) (point)))) + (if (re-search-forward sentence-end par-end t) + (skip-chars-backward " \t\n") + (goto-char par-end))) + (setq arg (1- arg)))) +@end group +@end smallexample +@end ignore + +The function looks long at first sight and it is best to look at its +skeleton first, and then its muscle. The way to see the skeleton is to +look at the expressions that start in the left-most columns: + +@smallexample +@group +(defun forward-sentence (&optional arg) + "@var{documentation}@dots{}" + (interactive "p") + (or arg (setq arg 1)) + (let ((opoint (point)) (sentence-end (sentence-end))) + (while (< arg 0) + (let ((pos (point)) + (par-beg (save-excursion (start-of-paragraph-text) (point)))) + @var{rest-of-body-of-while-loop-when-going-backwards} + (while (> arg 0) + (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) + @var{rest-of-body-of-while-loop-when-going-forwards} + @var{handle-forms-and-equivalent} +@end group +@end smallexample + +This looks much simpler! The function definition consists of +documentation, an @code{interactive} expression, an @code{or} +expression, a @code{let} expression, and @code{while} loops. + +Let's look at each of these parts in turn. + +We note that the documentation is thorough and understandable. + +The function has an @code{interactive "p"} declaration. This means +that the processed prefix argument, if any, is passed to the +function as its argument. (This will be a number.) If the function +is not passed an argument (it is optional) then the argument +@code{arg} will be bound to 1. + +When @code{forward-sentence} is called non-interactively without an +argument, @code{arg} is bound to @code{nil}. The @code{or} expression +handles this. What it does is either leave the value of @code{arg} as +it is, but only if @code{arg} is bound to a value; or it sets the +value of @code{arg} to 1, in the case when @code{arg} is bound to +@code{nil}. + +Next is a @code{let}. That specifies the values of two local +variables, @code{point} and @code{sentence-end}. The local value of +point, from before the search, is used in the +@code{constrain-to-field} function which handles forms and +equivalents. The @code{sentence-end} variable is set by the +@code{sentence-end} function. + +@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence +@unnumberedsubsec The @code{while} loops + +Two @code{while} loops follow. The first @code{while} has a +true-or-false-test that tests true if the prefix argument for +@code{forward-sentence} is a negative number. This is for going +backwards. The body of this loop is similar to the body of the second +@code{while} clause, but it is not exactly the same. We will skip +this @code{while} loop and concentrate on the second @code{while} +loop. + +@need 1500 +The second @code{while} loop is for moving point forward. Its skeleton +looks like this: + +@smallexample +@group +(while (> arg 0) ; @r{true-or-false-test} + (let @var{varlist} + (if (@var{true-or-false-test}) + @var{then-part} + @var{else-part} + (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} +@end group +@end smallexample + +The @code{while} loop is of the decrementing kind. +(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It +has a true-or-false-test that tests true so long as the counter (in +this case, the variable @code{arg}) is greater than zero; and it has a +decrementer that subtracts 1 from the value of the counter every time +the loop repeats. + +If no prefix argument is given to @code{forward-sentence}, which is +the most common way the command is used, this @code{while} loop will +run once, since the value of @code{arg} will be 1. + +The body of the @code{while} loop consists of a @code{let} expression, +which creates and binds a local variable, and has, as its body, an +@code{if} expression. + +@need 1250 +The body of the @code{while} loop looks like this: + +@smallexample +@group +(let ((par-end + (save-excursion (end-of-paragraph-text) (point)))) + (if (re-search-forward sentence-end par-end t) + (skip-chars-backward " \t\n") + (goto-char par-end))) +@end group +@end smallexample + +The @code{let} expression creates and binds the local variable +@code{par-end}. As we shall see, this local variable is designed to +provide a bound or limit to the regular expression search. If the +search fails to find a proper sentence ending in the paragraph, it will +stop on reaching the end of the paragraph. + +But first, let us examine how @code{par-end} is bound to the value of +the end of the paragraph. What happens is that the @code{let} sets the +value of @code{par-end} to the value returned when the Lisp interpreter +evaluates the expression + +@smallexample +@group +(save-excursion (end-of-paragraph-text) (point)) +@end group +@end smallexample + +@noindent +In this expression, @code{(end-of-paragraph-text)} moves point to the +end of the paragraph, @code{(point)} returns the value of point, and then +@code{save-excursion} restores point to its original position. Thus, +the @code{let} binds @code{par-end} to the value returned by the +@code{save-excursion} expression, which is the position of the end of +the paragraph. (The @code{end-of-paragraph-text} function uses +@code{forward-paragraph}, which we will discuss shortly.) + +@need 1200 +Emacs next evaluates the body of the @code{let}, which is an @code{if} +expression that looks like this: + +@smallexample +@group +(if (re-search-forward sentence-end par-end t) ; @r{if-part} + (skip-chars-backward " \t\n") ; @r{then-part} + (goto-char par-end))) ; @r{else-part} +@end group +@end smallexample + +The @code{if} tests whether its first argument is true and if so, +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 +the @code{forward-sentence} function buried here, but this is a common +way this kind of operation is carried out in Lisp. + +@node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence +@unnumberedsubsec The regular expression search + +The @code{re-search-forward} function searches for the end of the +sentence, that is, for the pattern defined by the @code{sentence-end} +regular expression. If the pattern is found---if the end of the sentence is +found---then the @code{re-search-forward} function does two things: + +@enumerate +@item +The @code{re-search-forward} function carries out a side effect, which +is to move point to the end of the occurrence found. + +@item +The @code{re-search-forward} function returns a value of true. This is +the value received by the @code{if}, and means that the search was +successful. +@end enumerate + +@noindent +The side effect, the movement of point, is completed before the +@code{if} function is handed the value returned by the successful +conclusion of the search. + +When the @code{if} function receives the value of true from a successful +call to @code{re-search-forward}, the @code{if} evaluates the then-part, +which is the expression @code{(skip-chars-backward " \t\n")}. This +expression moves backwards over any blank spaces, tabs or carriage +returns until a printed character is found and then leaves point after +the character. Since point has already been moved to the end of the +pattern that marks the end of the sentence, this action leaves point +right after the closing printed character of the sentence, which is +usually a period. + +On the other hand, if the @code{re-search-forward} function fails to +find a pattern marking the end of the sentence, the function returns +false. The false then causes the @code{if} to evaluate its third +argument, which is @code{(goto-char par-end)}: it moves point to the +end of the paragraph. + +(And if the text is in a form or equivalent, and point may not move +fully, then the @code{constrain-to-field} function comes into play.) + +Regular expression searches are exceptionally useful and the pattern +illustrated by @code{re-search-forward}, in which the search is the +test of an @code{if} expression, is handy. You will see or write code +incorporating this pattern often. + +@node forward-paragraph, etags, forward-sentence, Regexp Search +@comment node-name, next, previous, up +@section @code{forward-paragraph}: a Goldmine of Functions +@findex forward-paragraph + +@ignore +@c in GNU Emacs 22 +(defun forward-paragraph (&optional arg) + "Move forward to end of paragraph. +With argument ARG, do it ARG times; +a negative argument ARG = -N means move backward N paragraphs. + +A line which `paragraph-start' matches either separates paragraphs +\(if `paragraph-separate' matches it also) or is the first line of a paragraph. +A paragraph end is the beginning of a line which is not part of the paragraph +to which the end of the previous line belongs, or the end of the buffer. +Returns the count of paragraphs left to move." + (interactive "p") + (or arg (setq arg 1)) + (let* ((opoint (point)) + (fill-prefix-regexp + (and fill-prefix (not (equal fill-prefix "")) + (not paragraph-ignore-fill-prefix) + (regexp-quote fill-prefix))) + ;; Remove ^ from paragraph-start and paragraph-sep if they are there. + ;; These regexps shouldn't be anchored, because we look for them + ;; starting at the left-margin. This allows paragraph commands to + ;; work normally with indented text. + ;; This hack will not find problem cases like "whatever\\|^something". + (parstart (if (and (not (equal "" paragraph-start)) + (equal ?^ (aref paragraph-start 0))) + (substring paragraph-start 1) + paragraph-start)) + (parsep (if (and (not (equal "" paragraph-separate)) + (equal ?^ (aref paragraph-separate 0))) + (substring paragraph-separate 1) + paragraph-separate)) + (parsep + (if fill-prefix-regexp + (concat parsep "\\|" + fill-prefix-regexp "[ \t]*$") + parsep)) + ;; This is used for searching. + (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) + start found-start) + (while (and (< arg 0) (not (bobp))) + (if (and (not (looking-at parsep)) + (re-search-backward "^\n" (max (1- (point)) (point-min)) t) + (looking-at parsep)) + (setq arg (1+ arg)) + (setq start (point)) + ;; Move back over paragraph-separating lines. + (forward-char -1) (beginning-of-line) + (while (and (not (bobp)) + (progn (move-to-left-margin) + (looking-at parsep))) + (forward-line -1)) + (if (bobp) + nil + (setq arg (1+ arg)) + ;; Go to end of the previous (non-separating) line. + (end-of-line) + ;; Search back for line that starts or separates paragraphs. + (if (if fill-prefix-regexp + ;; There is a fill prefix; it overrides parstart. + (let (multiple-lines) + (while (and (progn (beginning-of-line) (not (bobp))) + (progn (move-to-left-margin) + (not (looking-at parsep))) + (looking-at fill-prefix-regexp)) + (unless (= (point) start) + (setq multiple-lines t)) + (forward-line -1)) + (move-to-left-margin) + ;; This deleted code caused a long hanging-indent line + ;; not to be filled together with the following lines. + ;; ;; Don't move back over a line before the paragraph + ;; ;; which doesn't start with fill-prefix + ;; ;; unless that is the only line we've moved over. + ;; (and (not (looking-at fill-prefix-regexp)) + ;; multiple-lines + ;; (forward-line 1)) + (not (bobp))) + (while (and (re-search-backward sp-parstart nil 1) + (setq found-start t) + ;; Found a candidate, but need to check if it is a + ;; REAL parstart. + (progn (setq start (point)) + (move-to-left-margin) + (not (looking-at parsep))) + (not (and (looking-at parstart) + (or (not use-hard-newlines) + (bobp) + (get-text-property + (1- start) 'hard))))) + (setq found-start nil) + (goto-char start)) + found-start) + ;; Found one. + (progn + ;; Move forward over paragraph separators. + ;; We know this cannot reach the place we started + ;; because we know we moved back over a non-separator. + (while (and (not (eobp)) + (progn (move-to-left-margin) + (looking-at parsep))) + (forward-line 1)) + ;; If line before paragraph is just margin, back up to there. + (end-of-line 0) + (if (> (current-column) (current-left-margin)) + (forward-char 1) + (skip-chars-backward " \t") + (if (not (bolp)) + (forward-line 1)))) + ;; No starter or separator line => use buffer beg. + (goto-char (point-min)))))) + + (while (and (> arg 0) (not (eobp))) + ;; Move forward over separator lines... + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (looking-at parsep)) + (forward-line 1)) + (unless (eobp) (setq arg (1- arg))) + ;; ... and one more line. + (forward-line 1) + (if fill-prefix-regexp + ;; There is a fill prefix; it overrides parstart. + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (not (looking-at parsep)) + (looking-at fill-prefix-regexp)) + (forward-line 1)) + (while (and (re-search-forward sp-parstart nil 1) + (progn (setq start (match-beginning 0)) + (goto-char start) + (not (eobp))) + (progn (move-to-left-margin) + (not (looking-at parsep))) + (or (not (looking-at parstart)) + (and use-hard-newlines + (not (get-text-property (1- start) 'hard))))) + (forward-char 1)) + (if (< (point) (point-max)) + (goto-char start)))) + (constrain-to-field nil opoint t) + ;; Return the number of steps that could not be done. + arg)) +@end ignore + +The @code{forward-paragraph} function moves point forward to the end +of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a +number of functions that are important in themselves, including +@code{let*}, @code{match-beginning}, and @code{looking-at}. + +The function definition for @code{forward-paragraph} is considerably +longer than the function definition for @code{forward-sentence} +because it works with a paragraph, each line of which may begin with a +fill prefix. + +A fill prefix consists of a string of characters that are repeated at +the beginning of each line. For example, in Lisp code, it is a +convention to start each line of a paragraph-long comment with +@samp{;;; }. In Text mode, four blank spaces make up another common +fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , +emacs, The GNU Emacs Manual}, for more information about fill +prefixes.) + +The existence of a fill prefix means that in addition to being able to +find the end of a paragraph whose lines begin on the left-most +column, the @code{forward-paragraph} function must be able to find the +end of a paragraph when all or many of the lines in the buffer begin +with the fill prefix. + +Moreover, it is sometimes practical to ignore a fill prefix that +exists, especially when blank lines separate paragraphs. +This is an added complication. + +@menu +* forward-paragraph in brief:: Key parts of the function definition. +* fwd-para let:: The @code{let*} expression. +* fwd-para while:: The forward motion @code{while} loop. +@end menu + +@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph +@ifnottex +@unnumberedsubsec Shortened @code{forward-paragraph} function definition +@end ifnottex + +Rather than print all of the @code{forward-paragraph} function, we +will only print parts of it. Read without preparation, the function +can be daunting! + +@need 800 +In outline, the function looks like this: + +@smallexample +@group +(defun forward-paragraph (&optional arg) + "@var{documentation}@dots{}" + (interactive "p") + (or arg (setq arg 1)) + (let* + @var{varlist} + (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} + @dots{} + (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} + @dots{} +@end group +@end smallexample + +The first parts of the function are routine: the function's argument +list consists of one optional argument. Documentation follows. + +The lower case @samp{p} in the @code{interactive} declaration means +that the processed prefix argument, if any, is passed to the function. +This will be a number, and is the repeat count of how many paragraphs +point will move. The @code{or} expression in the next line handles +the common case when no argument is passed to the function, which occurs +if the function is called from other code rather than interactively. +This case was described earlier. (@xref{forward-sentence, The +@code{forward-sentence} function}.) Now we reach the end of the +familiar part of this function. + +@node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph +@unnumberedsubsec The @code{let*} expression + +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}. + +The @code{let*} special form is like @code{let} except that Emacs sets +each variable in sequence, one after another, and variables in the +latter part of the varlist can make use of the values to which Emacs +set variables in the earlier part of the varlist. + +@ignore +( refappend save-excursion, , code save-excursion in code append-to-buffer .) +@end ignore + +(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) + +In the @code{let*} expression in this function, Emacs binds a total of +seven variables: @code{opoint}, @code{fill-prefix-regexp}, +@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and +@code{found-start}. + +The variable @code{parsep} appears twice, first, to remove instances +of @samp{^}, and second, to handle fill prefixes. + +The variable @code{opoint} is just the value of @code{point}. As you +can guess, it is used in a @code{constrain-to-field} expression, just +as in @code{forward-sentence}. + +The variable @code{fill-prefix-regexp} is set to the value returned by +evaluating the following list: + +@smallexample +@group +(and fill-prefix + (not (equal fill-prefix "")) + (not paragraph-ignore-fill-prefix) + (regexp-quote fill-prefix)) +@end group +@end smallexample + +@noindent +This is an expression whose first element is the @code{and} special form. + +As we learned earlier (@pxref{kill-new function, , The @code{kill-new} +function}), the @code{and} special form evaluates each of its +arguments until one of the arguments returns a value of @code{nil}, in +which case the @code{and} expression returns @code{nil}; however, if +none of the arguments returns a value of @code{nil}, the value +resulting from evaluating the last argument is returned. (Since such +a value is not @code{nil}, it is considered true in Lisp.) In other +words, an @code{and} expression returns a true value only if all its +arguments are true. +@findex and + +In this case, the variable @code{fill-prefix-regexp} is bound to a +non-@code{nil} value only if the following four expressions produce a +true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, +@code{fill-prefix-regexp} is bound to @code{nil}. + +@table @code +@item fill-prefix +When this variable is evaluated, the value of the fill prefix, if any, +is returned. If there is no fill prefix, this variable returns +@code{nil}. + +@item (not (equal fill-prefix "") +This expression checks whether an existing fill prefix is an empty +string, that is, a string with no characters in it. An empty string is +not a useful fill prefix. + +@item (not paragraph-ignore-fill-prefix) +This expression returns @code{nil} if the variable +@code{paragraph-ignore-fill-prefix} has been turned on by being set to a +true value such as @code{t}. + +@item (regexp-quote fill-prefix) +This is the last argument to the @code{and} special form. If all the +arguments to the @code{and} are true, the value resulting from +evaluating this expression will be returned by the @code{and} expression +and bound to the variable @code{fill-prefix-regexp}, +@end table + +@findex regexp-quote +@noindent +The result of evaluating this @code{and} expression successfully is that +@code{fill-prefix-regexp} will be bound to the value of +@code{fill-prefix} as modified by the @code{regexp-quote} function. +What @code{regexp-quote} does is read a string and return a regular +expression that will exactly match the string and match nothing else. +This means that @code{fill-prefix-regexp} will be set to a value that +will exactly match the fill prefix if the fill prefix exists. +Otherwise, the variable will be set to @code{nil}. + +The next two local variables in the @code{let*} expression are +designed to remove instances of @samp{^} from @code{parstart} and +@code{parsep}, the local variables which indicate the paragraph start +and the paragraph separator. The next expression sets @code{parsep} +again. That is to handle fill prefixes. + +This is the setting that requires the definition call @code{let*} +rather than @code{let}. The true-or-false-test for the @code{if} +depends on whether the variable @code{fill-prefix-regexp} evaluates to +@code{nil} or some other value. + +If @code{fill-prefix-regexp} does not have a value, Emacs evaluates +the else-part of the @code{if} expression and binds @code{parsep} to +its local value. (@code{parsep} is a regular expression that matches +what separates paragraphs.) + +But if @code{fill-prefix-regexp} does have a value, Emacs evaluates +the then-part of the @code{if} expression and binds @code{parsep} to a +regular expression that includes the @code{fill-prefix-regexp} as part +of the pattern. + +Specifically, @code{parsep} is set to the original value of the +paragraph separate regular expression concatenated with an alternative +expression that consists of the @code{fill-prefix-regexp} followed by +optional whitespace to the end of the line. The whitespace is defined +by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the +regexp as an alternative to @code{parsep}. + +According to a comment in the code, the next local variable, +@code{sp-parstart}, is used for searching, and then the final two, +@code{start} and @code{found-start}, are set to @code{nil}. + +Now we get into the body of the @code{let*}. The first part of the body +of the @code{let*} deals with the case when the function is given a +negative argument and is therefore moving backwards. We will skip this +section. + +@node fwd-para while, , fwd-para let, forward-paragraph +@unnumberedsubsec The forward motion @code{while} loop + +The second part of the body of the @code{let*} deals with forward +motion. It is a @code{while} loop that repeats itself so long as the +value of @code{arg} is greater than zero. In the most common use of +the function, the value of the argument is 1, so the body of the +@code{while} loop is evaluated exactly once, and the cursor moves +forward one paragraph. + +@ignore +(while (and (> arg 0) (not (eobp))) + + ;; Move forward over separator lines... + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (looking-at parsep)) + (forward-line 1)) + (unless (eobp) (setq arg (1- arg))) + ;; ... and one more line. + (forward-line 1) + + (if fill-prefix-regexp + ;; There is a fill prefix; it overrides parstart. + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (not (looking-at parsep)) + (looking-at fill-prefix-regexp)) + (forward-line 1)) + + (while (and (re-search-forward sp-parstart nil 1) + (progn (setq start (match-beginning 0)) + (goto-char start) + (not (eobp))) + (progn (move-to-left-margin) + (not (looking-at parsep))) + (or (not (looking-at parstart)) + (and use-hard-newlines + (not (get-text-property (1- start) 'hard))))) + (forward-char 1)) + + (if (< (point) (point-max)) + (goto-char start)))) +@end ignore + +This part handles three situations: when point is between paragraphs, +when there is a fill prefix and when there is no fill prefix. + +@need 800 +The @code{while} loop looks like this: + +@smallexample +@group +;; @r{going forwards and not at the end of the buffer} +(while (and (> arg 0) (not (eobp))) + + ;; @r{between paragraphs} + ;; Move forward over separator lines... + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (looking-at parsep)) + (forward-line 1)) + ;; @r{This decrements the loop} + (unless (eobp) (setq arg (1- arg))) + ;; ... and one more line. + (forward-line 1) +@end group + +@group + (if fill-prefix-regexp + ;; There is a fill prefix; it overrides parstart; + ;; we go forward line by line + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (not (looking-at parsep)) + (looking-at fill-prefix-regexp)) + (forward-line 1)) +@end group + +@group + ;; There is no fill prefix; + ;; we go forward character by character + (while (and (re-search-forward sp-parstart nil 1) + (progn (setq start (match-beginning 0)) + (goto-char start) + (not (eobp))) + (progn (move-to-left-margin) + (not (looking-at parsep))) + (or (not (looking-at parstart)) + (and use-hard-newlines + (not (get-text-property (1- start) 'hard))))) + (forward-char 1)) +@end group + +@group + ;; and if there is no fill prefix and if we are not at the end, + ;; go to whatever was found in the regular expression search + ;; for sp-parstart + (if (< (point) (point-max)) + (goto-char start)))) +@end group +@end smallexample + +@findex eobp +We can see that this is a decrementing counter @code{while} loop, +using the expression @code{(setq arg (1- arg))} as the decrementer. +That expression is not far from the @code{while}, but is hidden in +another Lisp macro, an @code{unless} macro. Unless we are at the end +of the buffer --- that is what the @code{eobp} function determines; it +is an abbreviation of @samp{End Of Buffer P} --- we decrease the value +of @code{arg} by one. + +(If we are at the end of the buffer, we cannot go forward any more and +the next loop of the @code{while} expression will test false since the +test is an @code{and} with @code{(not (eobp))}. The @code{not} +function means exactly as you expect; it is another name for +@code{null}, a function that returns true when its argument is false.) + +Interestingly, the loop count is not decremented until we leave the +space between paragraphs, unless we come to the end of buffer or stop +seeing the local value of the paragraph separator. + +That second @code{while} also has a @code{(move-to-left-margin)} +expression. The function is self-explanatory. It is inside a +@code{progn} expression and not the last element of its body, so it is +only invoked for its side effect, which is to move point to the left +margin of the current line. + +@findex looking-at +The @code{looking-at} function is also self-explanatory; it returns +true if the text after point matches the regular expression given as +its argument. + +The rest of the body of the loop looks difficult at first, but makes +sense as you come to understand it. + +@need 800 +First consider what happens if there is a fill prefix: + +@smallexample +@group + (if fill-prefix-regexp + ;; There is a fill prefix; it overrides parstart; + ;; we go forward line by line + (while (and (not (eobp)) + (progn (move-to-left-margin) (not (eobp))) + (not (looking-at parsep)) + (looking-at fill-prefix-regexp)) + (forward-line 1)) +@end group +@end smallexample + +@noindent +This expression moves point forward line by line so long +as four conditions are true: + +@enumerate +@item +Point is not at the end of the buffer. + +@item +We can move to the left margin of the text and are +not at the end of the buffer. + +@item +The text following point does not separate paragraphs. + +@item +The pattern following point is the fill prefix regular expression. +@end enumerate + +The last condition may be puzzling, until you remember that point was +moved to the beginning of the line early in the @code{forward-paragraph} +function. This means that if the text has a fill prefix, the +@code{looking-at} function will see it. + +@need 1250 +Consider what happens when there is no fill prefix. + +@smallexample +@group + (while (and (re-search-forward sp-parstart nil 1) + (progn (setq start (match-beginning 0)) + (goto-char start) + (not (eobp))) + (progn (move-to-left-margin) + (not (looking-at parsep))) + (or (not (looking-at parstart)) + (and use-hard-newlines + (not (get-text-property (1- start) 'hard))))) + (forward-char 1)) +@end group +@end smallexample + +@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 +separator. (The latter two are within an expression starting +@code{\(?:} so that they are not referenced by the +@code{match-beginning} function.) + +@need 800 +The two expressions, + +@smallexample +@group +(setq start (match-beginning 0)) +(goto-char start) +@end group +@end smallexample + +@noindent +mean go to the start of the text matched by the regular expression +search. + +The @code{(match-beginning 0)} expression is new. It returns a number +specifying the location of the start of the text that was matched by +the last search. + +The @code{match-beginning} function is used here because of a +characteristic of a forward search: a successful forward search, +regardless of whether it is a plain search or a regular expression +search, moves point to the end of the text that is found. In this +case, a successful search moves point to the end of the pattern for +@code{sp-parstart}. + +However, we want to put point at the end of the current paragraph, not +somewhere else. Indeed, since the search possibly includes the +paragraph separator, point may end up at the beginning of the next one +unless we use an expression that includes @code{match-beginning}. + +@findex match-beginning +When given an argument of 0, @code{match-beginning} returns the +position that is the start of the text matched by the most recent +search. In this case, the most recent search looks for +@code{sp-parstart}. The @code{(match-beginning 0)} expression returns +the beginning position of that pattern, rather than the end position +of that pattern. + +(Incidentally, when passed a positive number as an argument, the +@code{match-beginning} function returns the location of point at that +parenthesized expression in the last search unless that parenthesized +expression begins with @code{\(?:}. I don't know why @code{\(?:} +appears here since the argument is 0.) + +@need 1250 +The last expression when there is no fill prefix is + +@smallexample +@group +(if (< (point) (point-max)) + (goto-char start)))) +@end group +@end smallexample + +@noindent +This says that if there is no fill prefix and if we are not at the +end, point should move to the beginning of whatever was found by the +regular expression search for @code{sp-parstart}. + +The full definition for the @code{forward-paragraph} function not only +includes code for going forwards, but also code for going backwards. + +If you are reading this inside of GNU Emacs and you want to see the +whole function, you can type @kbd{C-h f} (@code{describe-function}) +and the name of the function. This gives you the function +documentation and the name of the library containing the function's +source. Place point over the name of the library and press the RET +key; you will be taken directly to the source. (Be sure to install +your sources! Without them, you are like a person who tries to drive +a car with his eyes shut!) + +@node etags, Regexp Review, forward-paragraph, Regexp Search +@section Create Your Own @file{TAGS} File +@findex etags +@cindex @file{TAGS} file, create own + +Besides @kbd{C-h f} (@code{describe-function}), another way to see the +source of a function is to type @kbd{M-.} (@code{find-tag}) and the +name of the function when prompted for it. This is a good habit to +get into. The @kbd{M-.} (@code{find-tag}) command takes you directly +to the source for a function, variable, or node. The function depends +on tags tables to tell it where to go. + +If the @code{find-tag} function first asks you for the name of a +@file{TAGS} table, give it the name of a @file{TAGS} file such as +@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your +@file{TAGS} file depends on how your copy of Emacs was installed. I +just told you the location that provides both my C and my Emacs Lisp +sources.) + +You can also create your own @file{TAGS} file for directories that +lack one. + +You often need to build and install tags tables yourself. They are +not built automatically. A tags table is called a @file{TAGS} file; +the name is in upper case letters. + +You can create a @file{TAGS} file by calling the @code{etags} program +that comes as a part of the Emacs distribution. Usually, @code{etags} +is compiled and installed when Emacs is built. (@code{etags} is not +an Emacs Lisp function or a part of Emacs; it is a C program.) + +@need 1250 +To create a @file{TAGS} file, first switch to the directory in which +you want to create the file. In Emacs you can do this with the +@kbd{M-x cd} command, or by visiting a file in the directory, or by +listing the directory with @kbd{C-x d} (@code{dired}). Then run the +compile command, with @w{@code{etags *.el}} as the command to execute + +@smallexample +M-x compile RET etags *.el RET +@end smallexample + +@noindent +to create a @file{TAGS} file for Emacs Lisp. + +For example, if you have a large number of files in your +@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, +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 +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: + +@smallexample +M-x compile RET etags *.el ../elisp/*.el RET +@end smallexample + +@need 1250 +Type + +@smallexample +M-x compile RET etags --help RET +@end smallexample + +@noindent +to see a list of the options accepted by @code{etags} as well as a +list of supported languages. + +The @code{etags} program handles more than 20 languages, including +Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, +LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and +most assemblers. The program has no switches for specifying the +language; it recognizes the language in an input file according to its +file name and contents. + +@file{etags} is very helpful when you are writing code yourself and +want to refer back to functions you have already written. Just run +@code{etags} again at intervals as you write new functions, so they +become part of the @file{TAGS} file. + +If you think an appropriate @file{TAGS} file already exists for what +you want, but do not know where it is, you can use the @code{locate} +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 +@file{TAGS} files. + +If the tags table you want has been created, you can use the @code{M-x +visit-tags-table} command to specify it. Otherwise, you will need to +create the tag table yourself and then use @code{M-x +visit-tags-table}. + +@subsubheading Building Tags in the Emacs sources +@cindex Building Tags in the Emacs sources +@cindex Tags in the Emacs sources +@findex make tags + +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 +@file{src/} directory is below the top level of your Emacs directory.) + +@need 1250 +To build this @file{TAGS} file, go to the top level of your Emacs +source directory and run the compile command @code{make tags}: + +@smallexample +M-x compile RET make tags RET +@end smallexample + +@noindent +(The @code{make tags} command works well with the GNU Emacs sources, +as well as with some other source packages.) + +For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs +Manual}. + +@node Regexp Review, re-search Exercises, etags, Regexp Search +@comment node-name, next, previous, up +@section Review + +Here is a brief summary of some recently introduced functions. + +@table @code +@item while +Repeatedly evaluate the body of the expression so long as the first +element of the body tests true. Then return @code{nil}. (The +expression is evaluated only for its side effects.) + +@need 1250 +For example: + +@smallexample +@group +(let ((foo 2)) + (while (> foo 0) + (insert (format "foo is %d.\n" foo)) + (setq foo (1- foo)))) + + @result{} foo is 2. + foo is 1. + nil +@end group +@end smallexample + +@noindent +(The @code{insert} function inserts its arguments at point; the +@code{format} function returns a string formatted from its arguments +the way @code{message} formats its arguments; @code{\n} produces a new +line.) + +@item re-search-forward +Search for a pattern, and if the pattern is found, move point to rest +just after it. + +@noindent +Takes four arguments, like @code{search-forward}: + +@enumerate +@item +A regular expression that specifies the pattern to search for. +(Remember to put quotation marks around this argument!) + +@item +Optionally, the limit of the search. + +@item +Optionally, what to do if the search fails, return @code{nil} or an +error message. + +@item +Optionally, how many times to repeat the search; if negative, the +search goes backwards. +@end enumerate + +@item let* +Bind some variables locally to particular values, +and then evaluate the remaining arguments, returning the value of the +last one. While binding the local variables, use the local values of +variables bound earlier, if any. + +@need 1250 +For example: + +@smallexample +@group +(let* ((foo 7) + (bar (* 3 foo))) + (message "`bar' is %d." bar)) + @result{} `bar' is 21. +@end group +@end smallexample + +@item match-beginning +Return the position of the start of the text found by the last regular +expression search. + +@item looking-at +Return @code{t} for true if the text after point matches the argument, +which should be a regular expression. + +@item eobp +Return @code{t} for true if point is at the end of the accessible part +of a buffer. The end of the accessible part is the end of the buffer +if the buffer is not narrowed; it is the end of the narrowed part if +the buffer is narrowed. +@end table + +@need 1500 +@node re-search Exercises, , Regexp Review, Regexp Search +@section Exercises with @code{re-search-forward} + +@itemize @bullet +@item +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'. +@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 +halves. You can devise several regexps; some are better than others. +The function I use is described in an appendix, along with several +regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. +@end itemize + +@node Counting Words, Words in a defun, Regexp Search, Top +@chapter Counting: Repetition and Regexps +@cindex Repetition for word counting +@cindex Regular expressions for word counting + +Repetition and regular expression searches are powerful tools that you +often use when you write code in Emacs Lisp. This chapter illustrates +the use of regular expression searches through the construction of +word count commands using @code{while} loops and recursion. + +@menu +* Why Count Words:: +* count-words-region:: Use a regexp, but find a problem. +* recursive-count-words:: Start with case of no words in region. +* Counting Exercise:: +@end menu + +@node Why Count Words, count-words-region, Counting Words, Counting Words +@ifnottex +@unnumberedsec Counting words +@end ifnottex + +The standard Emacs distribution contains a function for counting the +number of lines within a region. However, there is no corresponding +function for counting words. + +Certain types of writing ask you to count words. Thus, if you write +an essay, you may be limited to 800 words; if you write a novel, you +may discipline yourself to write 1000 words a day. It seems odd to me +that Emacs lacks a word count command. Perhaps people use Emacs +mostly for code or types of documentation that do not require word +counts; or perhaps they restrict themselves to the operating system +word count command, @code{wc}. Alternatively, people may follow +the publishers' convention and compute a word count by dividing the +number of characters in a document by five. In any event, here are +commands to count words. + +@node count-words-region, recursive-count-words, Why Count Words, Counting Words +@comment node-name, next, previous, up +@section The @code{count-words-region} Function +@findex count-words-region + +A word count command could count words in a line, paragraph, region, +or buffer. What should the command cover? You could design the +command to count the number of words in a complete buffer. However, +the Emacs tradition encourages flexibility---you may want to count +words in just a section, rather than all of a buffer. So it makes +more sense to design the command to count the number of words in a +region. Once you have a @code{count-words-region} command, you can, +if you wish, count words in a whole buffer by marking it with +@w{@kbd{C-x h}} (@code{mark-whole-buffer}). + +Clearly, counting words is a repetitive act: starting from the +beginning of the region, you count the first word, then the second +word, then the third word, and so on, until you reach the end of the +region. This means that word counting is ideally suited to recursion +or to a @code{while} loop. + +@menu +* Design count-words-region:: The definition using a @code{while} loop. +* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. +@end menu + +@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region +@ifnottex +@unnumberedsubsec Designing @code{count-words-region} +@end ifnottex + +First, we will implement the word count command with a @code{while} +loop, then with recursion. The command will, of course, be +interactive. + +@need 800 +The template for an interactive function definition is, as always: + +@smallexample +@group +(defun @var{name-of-function} (@var{argument-list}) + "@var{documentation}@dots{}" + (@var{interactive-expression}@dots{}) + @var{body}@dots{}) +@end group +@end smallexample + +What we need to do is fill in the slots. + +The name of the function should be self-explanatory and similar to the +existing @code{count-lines-region} name. This makes the name easier +to remember. @code{count-words-region} is a good choice. + +The function counts words within a region. This means that the +argument list must contain symbols that are bound to the two +positions, the beginning and end of the region. These two positions +can be called @samp{beginning} and @samp{end} respectively. The first +line of the documentation should be a single sentence, since that is +all that is printed as documentation by a command such as +@code{apropos}. The interactive expression will be of the form +@samp{(interactive "r")}, since that will cause Emacs to pass the +beginning and end of the region to the function's argument list. All +this is routine. + +The body of the function needs to be written to do three tasks: +first, to set up conditions under which the @code{while} loop can +count words, second, to run the @code{while} loop, and third, to send +a message to the user. + +When a user calls @code{count-words-region}, point may be at the +beginning or the end of the region. However, the counting process +must start at the beginning of the region. This means we will want +to put point there if it is not already there. Executing +@code{(goto-char beginning)} ensures this. Of course, we will want to +return point to its expected position when the function finishes its +work. For this reason, the body must be enclosed in a +@code{save-excursion} expression. + +The central part of the body of the function consists of a +@code{while} loop in which one expression jumps point forward word by +word, and another expression counts those jumps. The true-or-false-test +of the @code{while} loop should test true so long as point should jump +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. + +A regular expression search that finds the pattern for which it is +searching leaves point after the last character matched. This means +that a succession of successful word searches will move point forward +word by word. + +As a practical matter, we want the regular expression search to jump +over whitespace and punctuation between words as well as over the +words themselves. A regexp that refuses to jump over interword +whitespace would never jump more than one word! This means that +the regexp should include the whitespace and punctuation that follows +a word, if any, as well as the word itself. (A word may end a buffer +and not have any following whitespace or punctuation, so that part of +the regexp must be optional.) + +Thus, what we want for the regexp is a pattern defining one or more +word constituent characters followed, optionally, by one or more +characters that are not word constituents. The regular expression for +this is: + +@smallexample +\w+\W* +@end smallexample + +@noindent +The buffer's syntax table determines which characters are and are not +word constituents. (@xref{Syntax, , What Constitutes a Word or +Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The +Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , +Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) + +@need 800 +The search expression looks like this: + +@smallexample +(re-search-forward "\\w+\\W*") +@end smallexample + +@noindent +(Note that paired backslashes precede the @samp{w} and @samp{W}. A +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 +Emacs Lisp interpreter ends of seeing a single backslash followed by a +letter. So it discovers the letter is special.) + +We need a counter to count how many words there are; this variable +must first be set to 0 and then incremented each time Emacs goes +around the @code{while} loop. The incrementing expression is simply: + +@smallexample +(setq count (1+ count)) +@end smallexample + +Finally, we want to tell the user how many words there are in the +region. The @code{message} function is intended for presenting this +kind of information to the user. The message has to be phrased so +that it reads properly regardless of how many words there are in the +region: we don't want to say that ``there are 1 words in the region''. +The conflict between singular and plural is ungrammatical. We can +solve this problem by using a conditional expression that evaluates +different messages depending on the number of words in the region. +There are three possibilities: no words in the region, one word in the +region, and more than one word. This means that the @code{cond} +special form is appropriate. + +@need 1500 +All this leads to the following function definition: + +@smallexample +@group +;;; @r{First version; has bugs!} +(defun count-words-region (beginning end) + "Print number of words in the region. +Words are defined as at least one word-constituent +character followed by at least one character that +is not a word-constituent. The buffer's syntax +table determines which characters these are." + (interactive "r") + (message "Counting words in region ... ") +@end group + +@group +;;; @r{1. Set up appropriate conditions.} + (save-excursion + (goto-char beginning) + (let ((count 0)) +@end group + +@group +;;; @r{2. Run the} while @r{loop.} + (while (< (point) end) + (re-search-forward "\\w+\\W*") + (setq count (1+ count))) +@end group + +@group +;;; @r{3. Send a message to the user.} + (cond ((zerop count) + (message + "The region does NOT have any words.")) + ((= 1 count) + (message + "The region has 1 word.")) + (t + (message + "The region has %d words." count)))))) +@end group +@end smallexample + +@noindent +As written, the function works, but not in all circumstances. + +@node Whitespace Bug, , Design count-words-region, count-words-region +@comment node-name, next, previous, up +@subsection The Whitespace Bug in @code{count-words-region} + +The @code{count-words-region} command described in the preceding +section has two bugs, or rather, one bug with two manifestations. +First, if you mark a region containing only whitespace in the middle +of some text, the @code{count-words-region} command tells you that the +region contains one word! Second, if you mark a region containing +only whitespace at the end of the buffer or the accessible portion of +a narrowed buffer, the command displays an error message that looks +like this: + +@smallexample +Search failed: "\\w+\\W*" +@end smallexample + +If you are reading this in Info in GNU Emacs, you can test for these +bugs yourself. + +First, evaluate the function in the usual manner to install it. +@ifinfo +Here is a copy of the definition. Place your cursor after the closing +parenthesis and type @kbd{C-x C-e} to install it. + +@smallexample +@group +;; @r{First version; has bugs!} +(defun count-words-region (beginning end) + "Print number of words in the region. +Words are defined as at least one word-constituent character followed +by at least one character that is not a word-constituent. The buffer's +syntax table determines which characters these are." +@end group +@group + (interactive "r") + (message "Counting words in region ... ") +@end group + +@group +;;; @r{1. Set up appropriate conditions.} + (save-excursion + (goto-char beginning) + (let ((count 0)) +@end group + +@group +;;; @r{2. Run the} while @r{loop.} + (while (< (point) end) + (re-search-forward "\\w+\\W*") + (setq count (1+ count))) +@end group + +@group +;;; @r{3. Send a message to the user.} + (cond ((zerop count) + (message "The region does NOT have any words.")) + ((= 1 count) (message "The region has 1 word.")) + (t (message "The region has %d words." count)))))) +@end group +@end smallexample +@end ifinfo + +@need 1000 +If you wish, you can also install this keybinding by evaluating it: + +@smallexample +(global-set-key "\C-c=" 'count-words-region) +@end smallexample + +To conduct the first test, set mark and point to the beginning and end +of the following line and then type @kbd{C-c =} (or @kbd{M-x +count-words-region} if you have not bound @kbd{C-c =}): + +@smallexample + one two three +@end smallexample + +@noindent +Emacs will tell you, correctly, that the region has three words. + +Repeat the test, but place mark at the beginning of the line and place +point just @emph{before} the word @samp{one}. Again type the command +@kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you +that the region has no words, since it is composed only of the +whitespace at the beginning of the line. But instead Emacs tells you +that the region has one word! + +For the third test, copy the sample line to the end of the +@file{*scratch*} buffer and then type several spaces at the end of the +line. Place mark right after the word @samp{three} and point at the +end of line. (The end of the line will be the end of the buffer.) +Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before. +Again, Emacs should tell you that the region has no words, since it is +composed only of the whitespace at the end of the line. Instead, +Emacs displays an error message saying @samp{Search failed}. + +The two bugs stem from the same problem. + +Consider the first manifestation of the bug, in which the command +tells you that the whitespace at the beginning of the line contains +one word. What happens is this: The @code{M-x count-words-region} +command moves point to the beginning of the region. The @code{while} +tests whether the value of point is smaller than the value of +@code{end}, which it is. Consequently, the regular expression search +looks for and finds the first word. It leaves point after the word. +@code{count} is set to one. The @code{while} loop repeats; but this +time the value of point is larger than the value of @code{end}, the +loop is exited; and the function displays a message saying the number +of words in the region is one. In brief, the regular expression +search looks for and finds the word even though it is outside +the marked region. + +In the second manifestation of the bug, the region is whitespace at +the end of the buffer. Emacs says @samp{Search failed}. What happens +is that the true-or-false-test in the @code{while} loop tests true, so +the search expression is executed. But since there are no more words +in the buffer, the search fails. + +In both manifestations of the bug, the search extends or attempts to +extend outside of the region. + +The solution is to limit the search to the region---this is a fairly +simple action, but as you may have come to expect, it is not quite as +simple as you might think. + +As we have seen, the @code{re-search-forward} function takes a search +pattern as its first argument. But in addition to this first, +mandatory argument, it accepts three optional arguments. The optional +second argument bounds the search. The optional third argument, if +@code{t}, causes the function to return @code{nil} rather than signal +an error if the search fails. The optional fourth argument is a +repeat count. (In Emacs, you can see a function's documentation by +typing @kbd{C-h f}, the name of the function, and then @key{RET}.) + +In the @code{count-words-region} definition, the value of the end of +the region is held by the variable @code{end} which is passed as an +argument to the function. Thus, we can add @code{end} as an argument +to the regular expression search expression: + +@smallexample +(re-search-forward "\\w+\\W*" end) +@end smallexample + +However, if you make only this change to the @code{count-words-region} +definition and then test the new version of the definition on a +stretch of whitespace, you will receive an error message saying +@samp{Search failed}. + +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." + +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 +@code{nil} rather than signal an error if the search fails. + +However, if you make this change and try it, you will see the message +``Counting words in region ... '' and @dots{} you will keep on seeing +that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). + +Here is what happens: the search is limited to the region, as before, +and it fails because there are no word-constituent characters in the +region, as expected. Consequently, the @code{re-search-forward} +expression returns @code{nil}. It does nothing else. In particular, +it does not move point, which it does as a side effect if it finds the +search target. After the @code{re-search-forward} expression returns +@code{nil}, the next expression in the @code{while} loop is evaluated. +This expression increments the count. Then the loop repeats. The +true-or-false-test tests true because the value of point is still less +than the value of end, since the @code{re-search-forward} expression +did not move point. @dots{} and the cycle repeats @dots{} + +The @code{count-words-region} definition requires yet another +modification, to cause the true-or-false-test of the @code{while} loop +to test false if the search fails. Put another way, there are two +conditions that must be satisfied in the true-or-false-test before the +word count variable is incremented: point must still be within the +region and the search expression must have found a word to count. + +Since both the first condition and the second condition must be true +together, the two expressions, the region test and the search +expression, can be joined with an @code{and} special form and embedded in +the @code{while} loop as the true-or-false-test, like this: + +@smallexample +(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) +@end smallexample + +@c colon in printed section title causes problem in Info cross reference +@c also trouble with an overfull hbox +@iftex +@noindent +(For information about @code{and}, see +@ref{kill-new function, , The @code{kill-new} function}.) +@end iftex +@ifinfo +@noindent +(@xref{kill-new function, , The @code{kill-new} function}, for +information about @code{and}.) +@end ifinfo + +The @code{re-search-forward} expression returns @code{t} if the search +succeeds and as a side effect moves point. Consequently, as words are +found, point is moved through the region. When the search expression +fails to find another word, or when point reaches the end of the +region, the true-or-false-test tests false, the @code{while} loop +exits, and the @code{count-words-region} function displays one or +other of its messages. + +After incorporating these final changes, the @code{count-words-region} +works without bugs (or at least, without bugs that I have found!). +Here is what it looks like: + +@smallexample +@group +;;; @r{Final version:} @code{while} +(defun count-words-region (beginning end) + "Print number of words in the region." + (interactive "r") + (message "Counting words in region ... ") +@end group + +@group +;;; @r{1. Set up appropriate conditions.} + (save-excursion + (let ((count 0)) + (goto-char beginning) +@end group + +@group +;;; @r{2. Run the} while @r{loop.} + (while (and (< (point) end) + (re-search-forward "\\w+\\W*" end t)) + (setq count (1+ count))) +@end group + +@group +;;; @r{3. Send a message to the user.} + (cond ((zerop count) + (message + "The region does NOT have any words.")) + ((= 1 count) + (message + "The region has 1 word.")) + (t + (message + "The region has %d words." count)))))) +@end group +@end smallexample + +@node recursive-count-words, Counting Exercise, count-words-region, Counting Words +@comment node-name, next, previous, up +@section Count Words Recursively +@cindex Count words recursively +@cindex Recursively counting words +@cindex Words, counted recursively + +You can write the function for counting words recursively as well as +with a @code{while} loop. Let's see how this is done. + +First, we need to recognize that the @code{count-words-region} +function has three jobs: it sets up the appropriate conditions for +counting to occur; it counts the words in the region; and it sends a +message to the user telling how many words there are. + +If we write a single recursive function to do everything, we will +receive a message for every recursive call. If the region contains 13 +words, we will receive thirteen messages, one right after the other. +We don't want this! Instead, we must write two functions to do the +job, one of which (the recursive function) will be used inside of the +other. One function will set up the conditions and display the +message; the other will return the word count. + +Let us start with the function that causes the message to be displayed. +We can continue to call this @code{count-words-region}. + +This is the function that the user will call. It will be interactive. +Indeed, it will be similar to our previous versions of this +function, except that it will call @code{recursive-count-words} to +determine how many words are in the region. + +@need 1250 +We can readily construct a template for this function, based on our +previous versions: + +@smallexample +@group +;; @r{Recursive version; uses regular expression search} +(defun count-words-region (beginning end) + "@var{documentation}@dots{}" + (@var{interactive-expression}@dots{}) +@end group +@group + +;;; @r{1. Set up appropriate conditions.} + (@var{explanatory message}) + (@var{set-up functions}@dots{} +@end group +@group + +;;; @r{2. Count the words.} + @var{recursive call} +@end group +@group + +;;; @r{3. Send a message to the user.} + @var{message providing word count})) +@end group +@end smallexample + +The definition looks straightforward, except that somehow the count +returned by the recursive call must be passed to the message +displaying the word count. A little thought suggests that this can be +done by making use of a @code{let} expression: we can bind a variable +in the varlist of a @code{let} expression to the number of words in +the region, as returned by the recursive call; and then the +@code{cond} expression, using binding, can display the value to 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, +counting words, is done within the @code{let} expression. + +@need 1250 +Using @code{let}, the function definition looks like this: + +@smallexample +@group +(defun count-words-region (beginning end) + "Print number of words in the region." + (interactive "r") +@end group + +@group +;;; @r{1. Set up appropriate conditions.} + (message "Counting words in region ... ") + (save-excursion + (goto-char beginning) +@end group + +@group +;;; @r{2. Count the words.} + (let ((count (recursive-count-words end))) +@end group + +@group +;;; @r{3. Send a message to the user.} + (cond ((zerop count) + (message + "The region does NOT have any words.")) + ((= 1 count) + (message + "The region has 1 word.")) + (t + (message + "The region has %d words." count)))))) +@end group +@end smallexample + +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. + +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 +function that moves point forward for every word, the do-again-test +can check whether point is still within the region. The do-again-test +should find the value of point and determine whether point is before, +at, or after the value of the end of the region. We can use the +@code{point} function to locate point. Clearly, we must pass the +value of the end of the region to the recursive counting function as an +argument. + +In addition, the do-again-test should also test whether the search finds a +word. If it does not, the function should not call itself again. + +The next-step-expression changes a value so that when the recursive +function is supposed to stop calling itself, it stops. More +precisely, the next-step-expression changes a value so that at the +right time, the do-again-test stops the recursive function from +calling itself again. In this case, the next-step-expression can be +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 +function, a part that does the counting. A vital part! + +@need 1250 +But already, we have an outline of the recursive counting function: + +@smallexample +@group +(defun recursive-count-words (region-end) + "@var{documentation}@dots{}" + @var{do-again-test} + @var{next-step-expression} + @var{recursive call}) +@end group +@end smallexample + +Now we need to fill in the slots. Let's start with the simplest cases +first: if point is at or beyond the end of the region, there cannot +be any words in the region, so the function should return zero. +Likewise, if the search fails, there are no words to count, so the +function should return zero. + +On the other hand, if point is within the region and the search +succeeds, the function should call itself again. + +@need 800 +Thus, the do-again-test should look like this: + +@smallexample +@group +(and (< (point) region-end) + (re-search-forward "\\w+\\W*" region-end t)) +@end group +@end smallexample + +Note that the search expression is part of the do-again-test---the +function returns @code{t} if its search succeeds and @code{nil} if it +fails. (@xref{Whitespace Bug, , The Whitespace Bug in +@code{count-words-region}}, for an explanation of how +@code{re-search-forward} works.) + +The do-again-test is the true-or-false test of an @code{if} clause. +Clearly, if the do-again-test succeeds, the then-part of the @code{if} +clause should call the function again; but if it fails, the else-part +should return zero since either point is outside the region or the +search failed because there were no words to find. + +But before considering the recursive call, we need to consider the +next-step-expression. What is it? Interestingly, it is the search +part of the do-again-test. + +In addition to returning @code{t} or @code{nil} for the +do-again-test, @code{re-search-forward} moves point forward as a side +effect of a successful search. This is the action that changes the +value of point so that the recursive function stops calling itself +when point completes its movement through the region. Consequently, +the @code{re-search-forward} expression is the next-step-expression. + +@need 1200 +In outline, then, the body of the @code{recursive-count-words} +function looks like this: + +@smallexample +@group +(if @var{do-again-test-and-next-step-combined} + ;; @r{then} + @var{recursive-call-returning-count} + ;; @r{else} + @var{return-zero}) +@end group +@end smallexample + +How to incorporate the mechanism that counts? + +If you are not used to writing recursive functions, a question like +this can be troublesome. But it can and should be approached +systematically. + +We know that the counting mechanism should be associated in some way +with the recursive call. Indeed, since the next-step-expression moves +point forward by one word, and since a recursive call is made for +each word, the counting mechanism must be an expression that adds one +to the value returned by a call to @code{recursive-count-words}. + +@need 800 +Consider several cases: + +@itemize @bullet +@item +If there are two words in the region, the function should return +a value resulting from adding one to the value returned when it counts +the first word, plus the number returned when it counts the remaining +words in the region, which in this case is one. + +@item +If there is one word in the region, the function should return +a value resulting from adding one to the value returned when it counts +that word, plus the number returned when it counts the remaining +words in the region, which in this case is zero. + +@item +If there are no words in the region, the function should return zero. +@end itemize + +From the sketch we can see that the else-part of the @code{if} returns +zero for the case of no words. This means that the then-part of the +@code{if} must return a value resulting from adding one to the value +returned from a count of the remaining words. + +@need 1200 +The expression will look like this, where @code{1+} is a function that +adds one to its argument. + +@smallexample +(1+ (recursive-count-words region-end)) +@end smallexample + +@need 1200 +The whole @code{recursive-count-words} function will then look like +this: + +@smallexample +@group +(defun recursive-count-words (region-end) + "@var{documentation}@dots{}" + +;;; @r{1. do-again-test} + (if (and (< (point) region-end) + (re-search-forward "\\w+\\W*" region-end t)) +@end group + +@group +;;; @r{2. then-part: the recursive call} + (1+ (recursive-count-words region-end)) + +;;; @r{3. else-part} + 0)) +@end group +@end smallexample + +@need 1250 +Let's examine how this works: + +If there are no words in the region, the else part of the @code{if} +expression is evaluated and consequently the function returns zero. + +If there is one word in the region, the value of point is less than +the value of @code{region-end} and the search succeeds. In this case, +the true-or-false-test of the @code{if} expression tests true, and the +then-part of the @code{if} expression is evaluated. The counting +expression is evaluated. This expression returns a value (which will +be the value returned by the whole function) that is the sum of one +added to the value returned by a recursive call. + +Meanwhile, the next-step-expression has caused point to jump over the +first (and in this case only) word in the region. This means that +when @code{(recursive-count-words region-end)} is evaluated a second +time, as a result of the recursive call, the value of point will be +equal to or greater than the value of region end. So this time, +@code{recursive-count-words} will return zero. The zero will be added +to one, and the original evaluation of @code{recursive-count-words} +will return one plus zero, which is one, which is the correct amount. + +Clearly, if there are two words in the region, the first call to +@code{recursive-count-words} returns one added to the value returned +by calling @code{recursive-count-words} on a region containing the +remaining word---that is, it adds one to one, producing two, which is +the correct amount. + +Similarly, if there are three words in the region, the first call to +@code{recursive-count-words} returns one added to the value returned +by calling @code{recursive-count-words} on a region containing the +remaining two words---and so on and so on. + +@need 1250 +@noindent +With full documentation the two functions look like this: + +@need 1250 +@noindent +The recursive function: + +@findex recursive-count-words +@smallexample +@group +(defun recursive-count-words (region-end) + "Number of words between point and REGION-END." +@end group + +@group +;;; @r{1. do-again-test} + (if (and (< (point) region-end) + (re-search-forward "\\w+\\W*" region-end t)) +@end group + +@group +;;; @r{2. then-part: the recursive call} + (1+ (recursive-count-words region-end)) + +;;; @r{3. else-part} + 0)) +@end group +@end smallexample + +@need 800 +@noindent +The wrapper: + +@smallexample +@group +;;; @r{Recursive version} +(defun count-words-region (beginning end) + "Print number of words in the region. +@end group + +@group +Words are defined as at least one word-constituent +character followed by at least one character that is +not a word-constituent. The buffer's syntax table +determines which characters these are." +@end group +@group + (interactive "r") + (message "Counting words in region ... ") + (save-excursion + (goto-char beginning) + (let ((count (recursive-count-words end))) +@end group +@group + (cond ((zerop count) + (message + "The region does NOT have any words.")) +@end group +@group + ((= 1 count) + (message "The region has 1 word.")) + (t + (message + "The region has %d words." count)))))) +@end group +@end smallexample + +@node Counting Exercise, , recursive-count-words, Counting Words +@section Exercise: Counting Punctuation + +Using a @code{while} loop, write a function to count the number of +punctuation marks in a region---period, comma, semicolon, colon, +exclamation mark, and question mark. Do the same using recursion. + +@node Words in a defun, Readying a Graph, Counting Words, Top +@chapter Counting Words in a @code{defun} +@cindex Counting words in a @code{defun} +@cindex Word counting in a @code{defun} + +Our next project is to count the number of words in a function +definition. Clearly, this can be done using some variant of +@code{count-word-region}. @xref{Counting Words, , Counting Words: +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 +@code{count-word-region}. + +However, I am more ambitious: I want to count the words and symbols in +every definition in the Emacs sources and then print a graph that +shows how many functions there are of each length: how many contain 40 +to 49 words or symbols, how many contain 50 to 59 words or symbols, +and so on. I have often been curious how long a typical function is, +and this will tell. + +@menu +* Divide and Conquer:: +* Words and Symbols:: What to count? +* Syntax:: What constitutes a word or symbol? +* count-words-in-defun:: Very like @code{count-words}. +* Several defuns:: Counting several defuns in a file. +* Find a File:: Do you want to look at a file? +* lengths-list-file:: A list of the lengths of many definitions. +* Several files:: Counting in definitions in different files. +* Several files recursively:: Recursively counting in different files. +* Prepare the data:: Prepare the data for display in a graph. +@end menu + +@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun +@ifnottex +@unnumberedsec Divide and Conquer +@end ifnottex + +Described in one phrase, the histogram project is daunting; but +divided into numerous small steps, each of which we can take one at a +time, the project becomes less fearsome. Let us consider what the +steps must be: + +@itemize @bullet +@item +First, write a function to count the words in one definition. This +includes the problem of handling symbols as well as words. + +@item +Second, write a function to list the numbers of words in each function +in a file. This function can use the @code{count-words-in-defun} +function. + +@item +Third, write a function to list the numbers of words in each function +in each of several files. This entails automatically finding the +various files, switching to them, and counting the words in the +definitions within them. + +@item +Fourth, write a function to convert the list of numbers that we +created in step three to a form that will be suitable for printing as +a graph. + +@item +Fifth, write a function to print the results as a graph. +@end itemize + +This is quite a project! But if we take each step slowly, it will not +be difficult. + +@node Words and Symbols, Syntax, Divide and Conquer, Words in a defun +@section What to Count? +@cindex Words and symbols in defun + +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 +function definition, we are actually speaking, in large part, of +`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 +@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The +symbol @samp{number} is repeated, so the definition contains a total +of ten words and symbols. + +@smallexample +@group +(defun multiply-by-seven (number) + "Multiply NUMBER by seven." + (* 7 number)) +@end group +@end smallexample + +@noindent +However, if we mark the @code{multiply-by-seven} definition with +@kbd{C-M-h} (@code{mark-defun}), and then call +@code{count-words-region} on it, we will find that +@code{count-words-region} claims the definition has eleven words, not +ten! Something is wrong! + +The problem is twofold: @code{count-words-region} does not count the +@samp{*} as a word, and it counts the single symbol, +@code{multiply-by-seven}, as containing three words. The hyphens are +treated as if they were interword spaces rather than intraword +connectors: @samp{multiply-by-seven} is counted as if it were written +@samp{multiply by seven}. + +The cause of this confusion is the regular expression search within +the @code{count-words-region} definition that moves point forward word +by word. In the canonical version of @code{count-words-region}, the +regexp is: + +@smallexample +"\\w+\\W*" +@end smallexample + +@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 +of its own. + +@node Syntax, count-words-in-defun, Words and Symbols, Words in a defun +@section What Constitutes a Word or Symbol? +@cindex Syntax categories and tables + +Emacs treats different characters as belonging to different +@dfn{syntax categories}. For example, the regular expression, +@samp{\\w+}, is a pattern specifying one or more @emph{word +constituent} characters. Word constituent characters are members of +one syntax category. Other syntax categories include the class of +punctuation characters, such as the period and the comma, and the +class of whitespace characters, such as the blank space and the tab +character. (For more information, see @ref{Syntax, Syntax, The Syntax +Table, emacs, The GNU Emacs Manual}, and @ref{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 +@code{count-words-region} function treats it in the same way it treats +an interword white space, which is why @code{count-words-region} +counts @samp{multiply-by-seven} as three words. + +There are two ways to cause Emacs to count @samp{multiply-by-seven} as +one symbol: modify the syntax table or modify the regular expression. + +We could redefine a hyphen as a word constituent character by +modifying the syntax table that Emacs keeps for each mode. This +action would serve our purpose, except that a hyphen is merely the +most common character within symbols that is not typically a word +constituent character; there are others, too. + +Alternatively, we can redefine the regular expression used in the +@code{count-words} definition so as to include symbols. This +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: + +@smallexample +"\\(\\w\\|\\s_\\)+" +@end smallexample + +@noindent +The @samp{\\(} is the first part of the grouping construct that +includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated +by the @samp{\\|}. The @samp{\\w} matches any word-constituent +character and the @samp{\\s_} matches any character that is part of a +symbol name but not a word-constituent character. The @samp{+} +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, +I thought I could define this with the following: + +@smallexample +"\\(\\W\\|\\S_\\)*" +@end smallexample + +@noindent +The upper case @samp{W} and @samp{S} match characters that are +@emph{not} word or symbol constituents. Unfortunately, this +expression matches any character that is either not a word constituent +or not a symbol constituent. This matches any character! + +I then noticed that every word or symbol in my test region was +followed by white space (blank space, tab, or newline). So I tried +placing a pattern to match one or more blank spaces after the pattern +for one or more word or symbol constituents. This failed, too. Words +and symbols are often separated by whitespace, but in actual code +parentheses may follow symbols and punctuation may follow words. So +finally, I designed a pattern in which the word or symbol constituents +are followed optionally by characters that are not white space and +then followed optionally by white space. + +@need 800 +Here is the full regular expression: + +@smallexample +"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" +@end smallexample + +@node count-words-in-defun, Several defuns, Syntax, Words in a defun +@section The @code{count-words-in-defun} Function +@cindex Counting words in a @code{defun} + +We have seen that there are several ways to write a +@code{count-word-region} function. To write a +@code{count-words-in-defun}, we need merely adapt one of these +versions. + +The version that uses a @code{while} loop is easy to understand, so I +am going to adapt that. Because @code{count-words-in-defun} will be +part of a more complex program, it need not be interactive and it need +not display a message but just return the count. These considerations +simplify the definition a little. + +On the other hand, @code{count-words-in-defun} will be used within a +buffer that contains function definitions. Consequently, it is +reasonable to ask that the function determine whether it is called +when point is within a function definition, and if it is, to return +the count for that definition. This adds complexity to the +definition, but saves us from needing to pass arguments to the +function. + +@need 1250 +These considerations lead us to prepare the following template: + +@smallexample +@group +(defun count-words-in-defun () + "@var{documentation}@dots{}" + (@var{set up}@dots{} + (@var{while loop}@dots{}) + @var{return count}) +@end group +@end smallexample + +@noindent +As usual, our job is to fill in the slots. + +First, the set up. + +We are presuming that this function will be called within a buffer +containing function definitions. Point will either be within a +function definition or not. For @code{count-words-in-defun} to work, +point must move to the beginning of the definition, a counter must +start at zero, and the counting loop must stop when point reaches the +end of the definition. + +The @code{beginning-of-defun} function searches backwards for an +opening delimiter such as a @samp{(} at the beginning of a line, and +moves point to that position, or else to the limit of the search. In +practice, this means that @code{beginning-of-defun} moves point to the +beginning of an enclosing or preceding function definition, or else to +the beginning of the buffer. We can use @code{beginning-of-defun} to +place point where we wish to start. + +The @code{while} loop requires a counter to keep track of the words or +symbols being counted. A @code{let} expression can be used to create +a local variable for this purpose, and bind it to an initial value of zero. + +The @code{end-of-defun} function works like @code{beginning-of-defun} +except that it moves point to the end of the definition. +@code{end-of-defun} can be used as part of an expression that +determines the position of the end of the definition. + +The set up for @code{count-words-in-defun} takes shape rapidly: first +we move point to the beginning of the definition, then we create a +local variable to hold the count, and finally, we record the position +of the end of the definition so the @code{while} loop will know when to stop +looping. + +@need 1250 +The code looks like this: + +@smallexample +@group +(beginning-of-defun) +(let ((count 0) + (end (save-excursion (end-of-defun) (point)))) +@end group +@end smallexample + +@noindent +The code is simple. The only slight complication is likely to concern +@code{end}: it is bound to the position of the end of the definition +by a @code{save-excursion} expression that returns the value of point +after @code{end-of-defun} temporarily moves it to the end of the +definition. + +The second part of the @code{count-words-in-defun}, after the set up, +is the @code{while} loop. + +The loop must contain an expression that jumps point forward word by +word and symbol by symbol, and another expression that counts the +jumps. The true-or-false-test for the @code{while} loop should test +true so long as point should jump forward, and false when point is at +the end of the definition. We have already redefined the regular +expression for this (@pxref{Syntax}), so the loop is straightforward: + +@smallexample +@group +(while (and (< (point) end) + (re-search-forward + "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t) + (setq count (1+ count))) +@end group +@end smallexample + +The third part of the function definition returns the count of words +and symbols. This part is the last expression within the body of the +@code{let} expression, and can be, very simply, the local variable +@code{count}, which when evaluated returns the count. + +@need 1250 +Put together, the @code{count-words-in-defun} definition looks like this: + +@findex count-words-in-defun +@smallexample +@group +(defun count-words-in-defun () + "Return the number of words and symbols in a defun." + (beginning-of-defun) + (let ((count 0) + (end (save-excursion (end-of-defun) (point)))) +@end group +@group + (while + (and (< (point) end) + (re-search-forward + "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" + end t)) + (setq count (1+ count))) + count)) +@end group +@end smallexample + +How to test this? The function is not interactive, but it is easy to +put a wrapper around the function to make it interactive; we can use +almost the same code as for the recursive version of +@code{count-words-region}: + +@smallexample +@group +;;; @r{Interactive version.} +(defun count-words-defun () + "Number of words and symbols in a function definition." + (interactive) + (message + "Counting words and symbols in function definition ... ") +@end group +@group + (let ((count (count-words-in-defun))) + (cond + ((zerop count) + (message + "The definition does NOT have any words or symbols.")) +@end group +@group + ((= 1 count) + (message + "The definition has 1 word or symbol.")) + (t + (message + "The definition has %d words or symbols." count))))) +@end group +@end smallexample + +@need 800 +@noindent +Let's re-use @kbd{C-c =} as a convenient keybinding: + +@smallexample +(global-set-key "\C-c=" 'count-words-defun) +@end smallexample + +Now we can try out @code{count-words-defun}: install both +@code{count-words-in-defun} and @code{count-words-defun}, and set the +keybinding, and then place the cursor within the following definition: + +@smallexample +@group +(defun multiply-by-seven (number) + "Multiply NUMBER by seven." + (* 7 number)) + @result{} 10 +@end group +@end smallexample + +@noindent +Success! The definition has 10 words and symbols. + +The next problem is to count the numbers of words and symbols in +several definitions within a single file. + +@node Several defuns, Find a File, count-words-in-defun, Words in a defun +@section Count Several @code{defuns} Within a File + +A file such as @file{simple.el} may have a hundred or more function +definitions within it. Our long term goal is to collect statistics on +many files, but as a first step, our immediate goal is to collect +statistics on one file. + +The information will be a series of numbers, each number being the +length of a function definition. We can store the numbers in a list. + +We know that we will want to incorporate the information regarding one +file with information about many other files; this means that the +function for counting definition lengths within one file need only +return the list of lengths. It need not and should not display any +messages. + +The word count commands contain one expression to jump point forward +word by word and another expression to count the jumps. The function +to return the lengths of definitions can be designed to work the same +way, with one expression to jump point forward definition by +definition and another expression to construct the lengths' list. + +This statement of the problem makes it elementary to write the +function definition. Clearly, we will start the count at the +beginning of the file, so the first command will be @code{(goto-char +(point-min))}. Next, we start the @code{while} loop; and the +true-or-false test of the loop can be a regular expression search for +the next function definition---so long as the search succeeds, point +is moved forward and then the body of the loop is evaluated. The body +needs an expression that constructs the lengths' list. @code{cons}, +the list construction command, can be used to create the list. That +is almost all there is to it. + +@need 800 +Here is what this fragment of code looks like: + +@smallexample +@group +(goto-char (point-min)) +(while (re-search-forward "^(defun" nil t) + (setq lengths-list + (cons (count-words-in-defun) lengths-list))) +@end group +@end smallexample + +What we have left out is the mechanism for finding the file that +contains the function definitions. + +In previous examples, we either used this, the Info file, or we +switched back and forth to some other buffer, such as the +@file{*scratch*} buffer. + +Finding a file is a new process that we have not yet discussed. + +@node Find a File, lengths-list-file, Several defuns, Words in a defun +@comment node-name, next, previous, up +@section Find a File +@cindex Find a File + +To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) +command. This command is almost, but not quite right for the lengths +problem. + +@need 1200 +Let's look at the source for @code{find-file}: + +@smallexample +@group +(defun find-file (filename) + "Edit file FILENAME. +Switch to a buffer visiting file FILENAME, +creating one if none already exists." + (interactive "FFind file: ") + (switch-to-buffer (find-file-noselect filename))) +@end group +@end smallexample + +@noindent +(The most recent version of the @code{find-file} function definition +permits you to specify optional wildcards to visit multiple files; that +makes the definition more complex and we will not discuss it here, +since it is not relevant. You can see its source using either +@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) + +@ignore +In Emacs 22 +(defun find-file (filename &optional wildcards) + "Edit file FILENAME. +Switch to a buffer visiting file FILENAME, +creating one if none already exists. +Interactively, the default if you just type RET is the current directory, +but the visited file name is available through the minibuffer history: +type M-n to pull it into the minibuffer. + +Interactively, or if WILDCARDS is non-nil in a call from Lisp, +expand wildcards (if any) and visit multiple files. You can +suppress wildcard expansion by setting `find-file-wildcards' to nil. + +To visit a file without any kind of conversion and without +automatically choosing a major mode, use \\[find-file-literally]." + (interactive (find-file-read-args "Find file: " nil)) + (let ((value (find-file-noselect filename nil nil wildcards))) + (if (listp value) + (mapcar 'switch-to-buffer (nreverse value)) + (switch-to-buffer value)))) +@end ignore + +The definition I am showing possesses short but complete documentation +and an interactive specification that prompts you for a file name when +you use the command interactively. The body of the definition +contains two functions, @code{find-file-noselect} and +@code{switch-to-buffer}. + +According to its documentation as shown by @kbd{C-h f} (the +@code{describe-function} command), the @code{find-file-noselect} +function reads the named file into a buffer and returns the buffer. +(Its most recent version includes an optional wildcards argument, +too, as well as another to read a file literally and an other you +suppress warning messages. These optional arguments are irrelevant.) + +However, the @code{find-file-noselect} function does not select the +buffer in which it puts the file. Emacs does not switch its attention +(or yours if you are using @code{find-file-noselect}) to the selected +buffer. That is what @code{switch-to-buffer} does: it switches the +buffer to which Emacs attention is directed; and it switches the +buffer displayed in the window to the new buffer. We have discussed +buffer switching elsewhere. (@xref{Switching Buffers}.) + +In this histogram project, we do not need to display each file on the +screen as the program determines the length of each definition within +it. Instead of employing @code{switch-to-buffer}, we can work with +@code{set-buffer}, which redirects the attention of the computer +program to a different buffer but does not redisplay it on the screen. +So instead of calling on @code{find-file} to do the job, we must write +our own expression. + +The task is easy: use @code{find-file-noselect} and @code{set-buffer}. + +@node lengths-list-file, Several files, Find a File, Words in a defun +@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 +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 +beginning of the file. The function definition looks like this: +@findex lengths-list-file + +@smallexample +@group +(defun lengths-list-file (filename) + "Return list of definitions' lengths within FILE. +The returned list is a list of numbers. +Each number is the number of words or +symbols in one function definition." +@end group +@group + (message "Working on `%s' ... " filename) + (save-excursion + (let ((buffer (find-file-noselect filename)) + (lengths-list)) + (set-buffer buffer) + (setq buffer-read-only t) + (widen) + (goto-char (point-min)) + (while (re-search-forward "^(defun" nil t) + (setq lengths-list + (cons (count-words-in-defun) lengths-list))) + (kill-buffer buffer) + lengths-list))) +@end group +@end smallexample + +@noindent +The function is passed one argument, the name of the file on which it +will work. It has four lines of documentation, but no interactive +specification. Since people worry that a computer is broken if they +don't see anything going on, the first line of the body is a +message. + +The next line contains a @code{save-excursion} that returns Emacs' +attention to the current buffer when the function completes. This is +useful in case you embed this function in another function that +presumes point is restored to the original buffer. + +In the varlist of the @code{let} expression, Emacs finds the file and +binds the local variable @code{buffer} to the buffer containing the +file. At the same time, Emacs creates @code{lengths-list} as a local +variable. + +Next, Emacs switches its attention to the buffer. + +In the following line, Emacs makes the buffer read-only. Ideally, +this line is not necessary. None of the functions for counting words +and symbols in a function definition should change the buffer. +Besides, the buffer is not going to be saved, even if it were changed. +This line is entirely the consequence of great, perhaps excessive, +caution. The reason for the caution is that this function and those +it calls work on the sources for Emacs and it is inconvenient if they +are inadvertently modified. It goes without saying that I did not +realize a need for this line until an experiment went awry and started +to modify my Emacs source files @dots{} + +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 +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 +carried out. In the loop, Emacs determines the length of each +definition and constructs a lengths' list containing the information. + +Emacs kills the buffer after working through it. This is to save +space inside of Emacs. My version of GNU Emacs 19 contained over 300 +source files of interest; GNU Emacs 22 contains over a thousand source +files. Another function will apply @code{lengths-list-file} to each +of the files. + +Finally, the last expression within the @code{let} expression is the +@code{lengths-list} variable; its value is returned as the value of +the whole function. + +You can try this function by installing it in the usual fashion. Then +place your cursor after the following expression and type @kbd{C-x +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") +@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 +the @file{*scratch*} buffer and edit it. + +@need 1200 +@noindent +(Also, to see the full length of the list, rather than a truncated +version, you may have to evaluate the following: + +@smallexample +(custom-set-variables '(eval-expression-print-length nil)) +@end smallexample + +@noindent +(@xref{defcustom, , Specifying Variables using @code{defcustom}}. +Then evaluate the @code{lengths-list-file} expression.) + +@need 1200 +The lengths' list for @file{debug.el} takes less than a second to +produce and looks like this in GNU Emacs 22: + +@smallexample +(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) +@end smallexample + +@need 1500 +(Using my old machine, the version 19 lengths' list for @file{debug.el} +took seven seconds to produce and looked like this: + +@smallexample +(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 +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 +the list. + +@node Several files, Several files recursively, lengths-list-file, Words in a defun +@section Count Words in @code{defuns} in Different Files + +In the previous section, we created a function that returns a list of +the lengths of each definition in a file. Now, we want to define a +function to return a master list of the lengths of the definitions in +a list of files. + +Working on each of a list of files is a repetitious act, so we can use +either a @code{while} loop or recursion. + +@menu +* lengths-list-many-files:: Return a list of the lengths of defuns. +* append:: Attach one list to another. +@end menu + +@node lengths-list-many-files, append, Several files, Several files +@ifnottex +@unnumberedsubsec Determine the lengths of @code{defuns} +@end ifnottex + +The design using a @code{while} loop is routine. The argument passed +the function is a list of files. As we saw earlier (@pxref{Loop +Example}), you can write a @code{while} loop so that the body of the +loop is evaluated if such a list contains elements, but to exit the +loop if the list is empty. For this design to work, the body of the +loop must contain an expression that shortens the list each time the +body is evaluated, so that eventually the list is empty. The usual +technique is to set the value of the list to the value of the @sc{cdr} +of the list each time the body is evaluated. + +@need 800 +The template looks like this: + +@smallexample +@group +(while @var{test-whether-list-is-empty} + @var{body}@dots{} + @var{set-list-to-cdr-of-list}) +@end group +@end smallexample + +Also, we remember that a @code{while} loop returns @code{nil} (the +result of evaluating the true-or-false-test), not the result of any +evaluation within its body. (The evaluations within the body of the +loop are done for their side effects.) However, the expression that +sets the lengths' list is part of the body---and that is the value +that we want returned by the function as a whole. To do this, we +enclose the @code{while} loop within a @code{let} expression, and +arrange that the last element of the @code{let} expression contains +the value of the lengths' list. (@xref{Incrementing Example, , Loop +Example with an Incrementing Counter}.) + +@findex lengths-list-many-files +@need 1250 +These considerations lead us directly to the function itself: + +@smallexample +@group +;;; @r{Use @code{while} loop.} +(defun lengths-list-many-files (list-of-files) + "Return list of lengths of defuns in LIST-OF-FILES." +@end group +@group + (let (lengths-list) + +;;; @r{true-or-false-test} + (while list-of-files + (setq lengths-list + (append + lengths-list + +;;; @r{Generate a lengths' list.} + (lengths-list-file + (expand-file-name (car list-of-files))))) +@end group + +@group +;;; @r{Make files' list shorter.} + (setq list-of-files (cdr list-of-files))) + +;;; @r{Return final value of lengths' list.} + lengths-list)) +@end group +@end smallexample + +@code{expand-file-name} is a built-in function that converts a file +name to the absolute, long, path name form. The function employs the +name of the directory in which the function is called. + +@c !!! 22.1.1 lisp sources location here +@need 1500 +Thus, if @code{expand-file-name} is called on @code{debug.el} when +Emacs is visiting the +@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, + +@smallexample +debug.el +@end smallexample + +@need 800 +@noindent +becomes + +@c !!! 22.1.1 lisp sources location here +@smallexample +/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el +@end smallexample + +The only other new element of this function definition is the as yet +unstudied function @code{append}, which merits a short section for +itself. + +@node append, , lengths-list-many-files, Several files +@subsection The @code{append} Function + +@need 800 +The @code{append} function attaches one list to another. Thus, + +@smallexample +(append '(1 2 3 4) '(5 6 7 8)) +@end smallexample + +@need 800 +@noindent +produces the list + +@smallexample +(1 2 3 4 5 6 7 8) +@end smallexample + +This is exactly how we want to attach two lengths' lists produced by +@code{lengths-list-file} to each other. The results contrast with +@code{cons}, + +@smallexample +(cons '(1 2 3 4) '(5 6 7 8)) +@end smallexample + +@need 1250 +@noindent +which constructs a new list in which the first argument to @code{cons} +becomes the first element of the new list: + +@smallexample +((1 2 3 4) 5 6 7 8) +@end smallexample + +@node Several files recursively, Prepare the data, Several files, Words in a defun +@section Recursively Count Words in Different Files + +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' +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 +@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! +@findex recursive-lengths-list-many-files + +@smallexample +@group +(defun recursive-lengths-list-many-files (list-of-files) + "Return list of lengths of each defun in LIST-OF-FILES." + (if list-of-files ; @r{do-again-test} + (append + (lengths-list-file + (expand-file-name (car list-of-files))) + (recursive-lengths-list-many-files + (cdr list-of-files))))) +@end group +@end smallexample + +@noindent +In a sentence, the function returns the lengths' list for the first of +the @code{list-of-files} appended to the result of calling itself on +the rest of the @code{list-of-files}. + +Here is a test of @code{recursive-lengths-list-many-files}, along with +the results of running @code{lengths-list-file} on each of the files +individually. + +Install @code{recursive-lengths-list-many-files} and +@code{lengths-list-file}, if necessary, and then evaluate the +following expressions. You may need to change the files' pathnames; +those here work when this Info file and the Emacs sources are located +in their customary places. To change the expressions, copy them to +the @file{*scratch*} buffer, edit them, and then evaluate them. + +The results are shown after the @samp{@result{}}. (These results are +for files from Emacs version 22.1.1; files from other versions of +Emacs may produce different results.) + +@c !!! 22.1.1 lisp sources location here +@smallexample +@group +(cd "/usr/local/share/emacs/22.1.1/") + +(lengths-list-file "./lisp/macros.el") + @result{} (283 263 480 90) +@end group + +@group +(lengths-list-file "./lisp/mail/mailalias.el") + @result{} (38 32 29 95 178 180 321 218 324) +@end group + +@group +(lengths-list-file "./lisp/makesum.el") + @result{} (85 181) +@end group + +@group + (recursive-lengths-list-many-files + '("./lisp/macros.el" + "./lisp/mail/mailalias.el" + "./lisp/makesum.el")) + @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) +@end group +@end smallexample + +The @code{recursive-lengths-list-many-files} function produces the +output we want. + +The next step is to prepare the data in the list for display in a graph. + +@node Prepare the data, , Several files recursively, Words in a defun +@section Prepare the Data for Display in a Graph + +The @code{recursive-lengths-list-many-files} function returns a list +of numbers. Each number records the length of a function definition. +What we need to do now is transform this data into a list of numbers +suitable for generating a graph. The new list will tell how many +functions definitions contain less than 10 words and +symbols, how many contain between 10 and 19 words and symbols, how +many contain between 20 and 29 words and symbols, and so on. + +In brief, we need to go through the lengths' list produced by the +@code{recursive-lengths-list-many-files} function and count the number +of defuns within each range of lengths, and produce a list of those +numbers. + +@menu +* Data for Display in Detail:: +* Sorting:: Sorting lists. +* Files List:: Making a list of files. +* Counting function definitions:: +@end menu + +@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data +@ifnottex +@unnumberedsubsec The Data for Display in Detail +@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 +lengths' list, looks at each element, determines which length range it +is in, and increments a counter for that range. + +However, before beginning to write such a function, we should consider +the advantages of sorting the lengths' list first, so the numbers are +ordered from smallest to largest. First, sorting will make it easier +to count the numbers in each range, since two adjacent numbers will +either be in the same length range or in adjacent ranges. Second, by +inspecting a sorted list, we can discover the highest and lowest +number, and thereby determine the largest and smallest length range +that we will need. + +@node Sorting, Files List, Data for Display in Detail, Prepare the data +@subsection Sorting Lists +@findex sort + +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. + +As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong +Type Object as an Argument}), a predicate is a function that +determines whether some property is true or false. The @code{sort} +function will reorder a list according to whatever property the +predicate uses; this means that @code{sort} can be used to sort +non-numeric lists by non-numeric criteria---it can, for example, +alphabetize a list. + +@need 1250 +The @code{<} function is used when sorting a numeric list. For example, + +@smallexample +(sort '(4 8 21 17 33 7 21 7) '<) +@end smallexample + +@need 800 +@noindent +produces this: + +@smallexample +(4 7 7 8 17 21 21 33) +@end smallexample + +@noindent +(Note that in this example, both the arguments are quoted so that the +symbols are not evaluated before being passed to @code{sort} as +arguments.) + +Sorting the list returned by the +@code{recursive-lengths-list-many-files} function is straightforward; +it uses the @code{<} function: + +@ignore +2006 Oct 29 +In GNU Emacs 22, eval +(progn + (cd "/usr/local/share/emacs/22.0.50/") + (sort + (recursive-lengths-list-many-files + '("./lisp/macros.el" + "./lisp/mail/mailalias.el" + "./lisp/makesum.el")) + '<)) + +@end ignore + +@smallexample +@group +(sort + (recursive-lengths-list-many-files + '("./lisp/macros.el" + "./lisp/mailalias.el" + "./lisp/makesum.el")) + '<) +@end group +@end smallexample + +@need 800 +@noindent +which produces: + +@smallexample +(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) +@end smallexample + +@noindent +(Note that in this example, the first argument to @code{sort} is not +quoted, since the expression must be evaluated so as to produce the +list that is passed to @code{sort}.) + +@node Files List, Counting function definitions, Sorting, Prepare the data +@subsection Making a List of Files + +The @code{recursive-lengths-list-many-files} function requires a list +of files as its argument. For our test examples, we constructed such +a list by hand; but the Emacs Lisp source directory is too large for +us to do for that. Instead, we will write a function to do the job +for us. In this function, we will use both a @code{while} loop and a +recursive call. + +@findex directory-files +We did not have to write a function like this for older versions of +GNU Emacs, since they placed all the @samp{.el} files in one +directory. Instead, we were able to use the @code{directory-files} +function, which lists the names of files that match a specified +pattern within a single directory. + +However, recent versions of Emacs place Emacs Lisp files in +sub-directories of the top level @file{lisp} directory. This +re-arrangement eases navigation. For example, all the mail related +files are in a @file{lisp} sub-directory called @file{mail}. But at +the same time, this arrangement forces us to create a file listing +function that descends into the sub-directories. + +@findex files-in-below-directory +We can create this function, called @code{files-in-below-directory}, +using familiar functions such as @code{car}, @code{nthcdr}, and +@code{substring} in conjunction with an existing function called +@code{directory-files-and-attributes}. This latter function not only +lists all the filenames in a directory, including the names +of sub-directories, but also their attributes. + +To restate our goal: to create a function that will enable us +to feed filenames to @code{recursive-lengths-list-many-files} +as a list that looks like this (but with more elements): + +@smallexample +@group +("./lisp/macros.el" + "./lisp/mail/rmail.el" + "./lisp/makesum.el") +@end group +@end smallexample + +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 +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}. + +For example, the first @samp{.el} file in the @file{lisp/} directory +is @file{abbrev.el}. Its name is +@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a +directory or a symbolic link. + +@need 1000 +This is how @code{directory-files-and-attributes} lists that file and +its attributes: + +@smallexample +@group +("abbrev.el" +nil +1 +1000 +100 +@end group +@group +(17733 259) +(17491 28834) +(17596 62124) +13157 +"-rw-rw-r--" +@end group +@group +nil +2971624 +773) +@end group +@end smallexample + +@need 1200 +On the other hand, @file{mail/} is a directory within the @file{lisp/} +directory. The beginning of its listing looks like this: + +@smallexample +@group +("mail" +t +@dots{} +) +@end group +@end smallexample + +(To learn about the different attributes, look at the documentation of +@code{file-attributes}. Bear in mind that the @code{file-attributes} +function does not list the filename, so its first element is +@code{directory-files-and-attributes}'s second element.) + +We will want our new function, @code{files-in-below-directory}, to +list the @samp{.el} files in the directory it is told to check, and in +any directories below that directory. + +This gives us a hint on how to construct +@code{files-in-below-directory}: within a directory, the function +should add @samp{.el} filenames to a list; and if, within a directory, +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 +@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, +since they always lead us, directly or indirectly, to the current +directory. + +Consequently, our @code{files-in-below-directory} function must do +several tasks: + +@itemize @bullet +@item +Check to see whether it is looking at a filename that ends in +@samp{.el}; and if so, add its name to a list. + +@item +Check to see whether it is looking at a filename that is the name of a +directory; and if so, + +@itemize @minus +@item +Check to see whether it is looking at @file{.} or @file{..}; and if +so skip it. + +@item +Or else, go into that directory and repeat the process. +@end itemize +@end itemize + +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}}), +using @code{append} as the combiner. + +@ignore +(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") +(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") + +(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") +(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") +@end ignore + +@c /usr/local/share/emacs/22.1.1/lisp/ + +@need 800 +Here is the function: + +@smallexample +@group +(defun files-in-below-directory (directory) + "List the .el files in DIRECTORY and in its sub-directories." + ;; Although the function will be used non-interactively, + ;; it will be easier to test if we make it interactive. + ;; The directory will have a name such as + ;; "/usr/local/share/emacs/22.1.1/lisp/" + (interactive "DDirectory name: ") +@end group +@group + (let (el-files-list + (current-directory-list + (directory-files-and-attributes directory t))) + ;; while we are in the current directory + (while current-directory-list +@end group +@group + (cond + ;; 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 + (cons (car (car current-directory-list)) el-files-list))) +@end group +@group + ;; check whether filename is that of a directory + ((eq t (car (cdr (car current-directory-list)))) + ;; decide whether to skip or recurse + (if + (equal "." + (substring (car (car current-directory-list)) -1)) + ;; then do nothing since filename is that of + ;; current directory or parent, "." or ".." + () +@end group +@group + ;; else descend into the directory and repeat the process + (setq el-files-list + (append + (files-in-below-directory + (car (car current-directory-list))) + el-files-list))))) + ;; move to the next filename in the list; this also + ;; shortens the list so the while loop eventually comes to an end + (setq current-directory-list (cdr current-directory-list))) + ;; return the filenames + el-files-list)) +@end group +@end smallexample + +@c (files-in-below-directory "/usr/local/src/emacs/lisp/") +@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") + +The @code{files-in-below-directory} @code{directory-files} function +takes one argument, the name of a directory. + +@need 1250 +Thus, on my system, + +@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) + +@c !!! 22.1.1 lisp sources location here +@smallexample +@group +(length + (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) +@end group +@end smallexample + +@noindent +tells me that in and below my Lisp sources directory are 1031 +@samp{.el} files. + +@code{files-in-below-directory} returns a list in reverse alphabetical +order. An expression to sort the list in alphabetical order looks +like this: + +@smallexample +@group +(sort + (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") + 'string-lessp) +@end group +@end smallexample + +@ignore +(defun test () + "Test how long it takes to find lengths of all sorted elisp defuns." + (insert "\n" (current-time-string) "\n") + (sit-for 0) + (sort + (recursive-lengths-list-many-files + (files-in-below-directory "/usr/local/src/emacs/lisp/")) + '<) + (insert (format "%s" (current-time-string)))) +@end ignore + +@node Counting function definitions, , Files List, Prepare the data +@subsection Counting function definitions + +Our immediate goal is to generate a list that tells us how many +function definitions contain fewer than 10 words and symbols, how many +contain between 10 and 19 words and symbols, how many contain between +20 and 29 words and symbols, and so on. + +With a sorted list of numbers, this is easy: count how many elements +of the list are smaller than 10, then, after moving past the numbers +just counted, count how many are smaller than 20, then, after moving +past the numbers just counted, count how many are smaller than 30, and +so on. Each of the numbers, 10, 20, 30, 40, and the like, is one +larger than the top of that range. We can call the list of such +numbers the @code{top-of-ranges} list. + +@need 1200 +If we wished, we could generate this list automatically, but it is +simpler to write a list manually. Here it is: +@vindex top-of-ranges + +@smallexample +@group +(defvar top-of-ranges + '(10 20 30 40 50 + 60 70 80 90 100 + 110 120 130 140 150 + 160 170 180 190 200 + 210 220 230 240 250 + 260 270 280 290 300) + "List specifying ranges for `defuns-per-range'.") +@end group +@end smallexample + +To change the ranges, we edit this list. + +Next, we need to write the function that creates the list of the +number of definitions within each range. Clearly, this function must +take the @code{sorted-lengths} and the @code{top-of-ranges} lists +as arguments. + +The @code{defuns-per-range} function must do two things again and +again: it must count the number of definitions within a range +specified by the current top-of-range value; and it must shift to the +next higher value in the @code{top-of-ranges} list after counting the +number of definitions in the current range. Since each of these +actions is repetitive, we can use @code{while} loops for the job. +One loop counts the number of definitions in the range defined by the +current top-of-range value, and the other loop selects each of the +top-of-range values in turn. + +Several entries of the @code{sorted-lengths} list are counted for each +range; this means that the loop for the @code{sorted-lengths} list +will be inside the loop for the @code{top-of-ranges} list, like a +small gear inside a big gear. + +The inner loop counts the number of definitions within the range. It +is a simple counting loop of the type we have seen before. +(@xref{Incrementing Loop, , A loop with an incrementing counter}.) +The true-or-false test of the loop tests whether the value from the +@code{sorted-lengths} list is smaller than the current value of the +top of the range. If it is, the function increments the counter and +tests the next value from the @code{sorted-lengths} list. + +@need 1250 +The inner loop looks like this: + +@smallexample +@group +(while @var{length-element-smaller-than-top-of-range} + (setq number-within-range (1+ number-within-range)) + (setq sorted-lengths (cdr sorted-lengths))) +@end group +@end smallexample + +The outer loop must start with the lowest value of the +@code{top-of-ranges} list, and then be set to each of the succeeding +higher values in turn. This can be done with a loop like this: + +@smallexample +@group +(while top-of-ranges + @var{body-of-loop}@dots{} + (setq top-of-ranges (cdr top-of-ranges))) +@end group +@end smallexample + +@need 1200 +Put together, the two loops look like this: + +@smallexample +@group +(while top-of-ranges + + ;; @r{Count the number of elements within the current range.} + (while @var{length-element-smaller-than-top-of-range} + (setq number-within-range (1+ number-within-range)) + (setq sorted-lengths (cdr sorted-lengths))) + + ;; @r{Move to next range.} + (setq top-of-ranges (cdr top-of-ranges))) +@end group +@end smallexample + +In addition, in each circuit of the outer loop, Emacs should record +the number of definitions within that range (the value of +@code{number-within-range}) in a list. We can use @code{cons} for +this purpose. (@xref{cons, , @code{cons}}.) + +The @code{cons} function works fine, except that the list it +constructs will contain the number of definitions for the highest +range at its beginning and the number of definitions for the lowest +range at its end. This is because @code{cons} attaches new elements +of the list to the beginning of the list, and since the two loops are +working their way through the lengths' list from the lower end first, +the @code{defuns-per-range-list} will end up largest number first. +But we will want to print our graph with smallest values first and the +larger later. The solution is to reverse the order of the +@code{defuns-per-range-list}. We can do this using the +@code{nreverse} function, which reverses the order of a list. +@findex nreverse + +@need 800 +For example, + +@smallexample +(nreverse '(1 2 3 4)) +@end smallexample + +@need 800 +@noindent +produces: + +@smallexample +(4 3 2 1) +@end smallexample + +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}, +so it does not matter that it is destroyed. (The @code{reverse} +function provides a reversed copy of a list, leaving the original list +as is.) +@findex reverse + +@need 1250 +Put all together, the @code{defuns-per-range} looks like this: + +@smallexample +@group +(defun defuns-per-range (sorted-lengths top-of-ranges) + "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." + (let ((top-of-range (car top-of-ranges)) + (number-within-range 0) + defuns-per-range-list) +@end group + +@group + ;; @r{Outer loop.} + (while top-of-ranges +@end group + +@group + ;; @r{Inner loop.} + (while (and + ;; @r{Need number for numeric test.} + (car sorted-lengths) + (< (car sorted-lengths) top-of-range)) +@end group + +@group + ;; @r{Count number of definitions within current range.} + (setq number-within-range (1+ number-within-range)) + (setq sorted-lengths (cdr sorted-lengths))) + + ;; @r{Exit inner loop but remain within outer loop.} +@end group + +@group + (setq defuns-per-range-list + (cons number-within-range defuns-per-range-list)) + (setq number-within-range 0) ; @r{Reset count to zero.} +@end group + +@group + ;; @r{Move to next range.} + (setq top-of-ranges (cdr top-of-ranges)) + ;; @r{Specify next top of range value.} + (setq top-of-range (car top-of-ranges))) +@end group + +@group + ;; @r{Exit outer loop and count the number of defuns larger than} + ;; @r{ the largest top-of-range value.} + (setq defuns-per-range-list + (cons + (length sorted-lengths) + defuns-per-range-list)) +@end group + +@group + ;; @r{Return a list of the number of definitions within each range,} + ;; @r{ smallest to largest.} + (nreverse defuns-per-range-list))) +@end group +@end smallexample + +@need 1200 +@noindent +The function is straightforward except for one subtle feature. The +true-or-false test of the inner loop looks like this: + +@smallexample +@group +(and (car sorted-lengths) + (< (car sorted-lengths) top-of-range)) +@end group +@end smallexample + +@need 800 +@noindent +instead of like this: + +@smallexample +(< (car sorted-lengths) top-of-range) +@end smallexample + +The purpose of the test is to determine whether the first item in the +@code{sorted-lengths} list is less than the value of the top of the +range. + +The simple version of the test works fine unless the +@code{sorted-lengths} list has a @code{nil} value. In that case, the +@code{(car sorted-lengths)} expression function returns +@code{nil}. The @code{<} function cannot compare a number to +@code{nil}, which is an empty list, so Emacs signals an error and +stops the function from attempting to continue to execute. + +The @code{sorted-lengths} list always becomes @code{nil} when the +counter reaches the end of the list. This means that any attempt to +use the @code{defuns-per-range} function with the simple version of +the test will fail. + +We solve the problem by using the @code{(car sorted-lengths)} +expression in conjunction with the @code{and} expression. The +@code{(car sorted-lengths)} expression returns a non-@code{nil} +value so long as the list has at least one number within it, but +returns @code{nil} if the list is empty. The @code{and} expression +first evaluates the @code{(car sorted-lengths)} expression, and +if it is @code{nil}, returns false @emph{without} evaluating the +@code{<} expression. But if the @code{(car sorted-lengths)} +expression returns a non-@code{nil} value, the @code{and} expression +evaluates the @code{<} expression, and returns that value as the value +of the @code{and} expression. + +@c colon in printed section title causes problem in Info cross reference +This way, we avoid an error. +@iftex +@noindent +(For information about @code{and}, see +@ref{kill-new function, , The @code{kill-new} function}.) +@end iftex +@ifinfo +@noindent +(@xref{kill-new function, , The @code{kill-new} function}, for +information about @code{and}.) +@end ifinfo + +Here is a short test of the @code{defuns-per-range} function. First, +evaluate the expression that binds (a shortened) +@code{top-of-ranges} list to the list of values, then evaluate the +expression for binding the @code{sorted-lengths} list, and then +evaluate the @code{defuns-per-range} function. + +@smallexample +@group +;; @r{(Shorter list than we will use later.)} +(setq top-of-ranges + '(110 120 130 140 150 + 160 170 180 190 200)) + +(setq sorted-lengths + '(85 86 110 116 122 129 154 176 179 200 265 300 300)) + +(defuns-per-range sorted-lengths top-of-ranges) +@end group +@end smallexample + +@need 800 +@noindent +The list returned looks like this: + +@smallexample +(2 2 2 0 0 1 0 2 0 0 4) +@end smallexample + +@noindent +Indeed, there are two elements of the @code{sorted-lengths} list +smaller than 110, two elements between 110 and 119, two elements +between 120 and 129, and so on. There are four elements with a value +of 200 or larger. + +@c The next step is to turn this numbers' list into a graph. +@node Readying a Graph, Emacs Initialization, Words in a defun, Top +@chapter Readying a Graph +@cindex Readying a graph +@cindex Graph prototype +@cindex Prototype graph +@cindex Body of graph + +Our goal is to construct a graph showing the numbers of function +definitions of various lengths in the Emacs lisp sources. + +As a practical matter, if you were creating a graph, you would +probably use a program such as @code{gnuplot} to do the job. +(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, +however, we create one from scratch, and in the process we will +re-acquaint ourselves with some of what we learned before and learn +more. + +In this chapter, we will first write a simple graph printing function. +This first definition will be a @dfn{prototype}, a rapidly written +function that enables us to reconnoiter this unknown graph-making +territory. We will discover dragons, or find that they are myth. +After scouting the terrain, we will feel more confident and enhance +the function to label the axes automatically. + +@menu +* Columns of a graph:: +* graph-body-print:: How to print the body of a graph. +* recursive-graph-body-print:: +* Printed Axes:: +* Line Graph Exercise:: +@end menu + +@node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph +@ifnottex +@unnumberedsec Printing the Columns of a Graph +@end ifnottex + +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 +we enhance the graph-printing function, we can make the choice of +symbol a user option. + +We can call this function @code{graph-body-print}; it will take a +@code{numbers-list} as its only argument. At this stage, we will not +label the graph, but only print its body. + +The @code{graph-body-print} function inserts a vertical column of +asterisks for each element in the @code{numbers-list}. The height of +each line is determined by the value of that element of the +@code{numbers-list}. + +Inserting columns is a repetitive act; that means that this function can +be written either with a @code{while} loop or recursively. + +Our first challenge is to discover how to print a column of asterisks. +Usually, in Emacs, we print characters onto a screen horizontally, +line by line, by typing. We have two routes we can follow: write our +own column-insertion function or discover whether one exists in Emacs. + +To see whether there is one in Emacs, we can use the @kbd{M-x apropos} +command. This command is like the @kbd{C-h a} (@code{command-apropos}) +command, except that the latter finds only those functions that are +commands. The @kbd{M-x apropos} command lists all symbols that match +a regular expression, including functions that are not interactive. +@findex apropos + +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'. +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 +functions and variables. Now it does not take much time at all and +produces a list of 211 functions and variables. Scanning down the +list, the only function that looks as if it might do the job is +@code{insert-rectangle}. + +@need 1200 +Indeed, this is the function we want; its documentation says: + +@smallexample +@group +insert-rectangle: +Insert text of RECTANGLE with upper left corner at point. +RECTANGLE's first line is inserted at point, +its second line is inserted at a point vertically under point, etc. +RECTANGLE should be a list of strings. +After this command, the mark is at the upper left corner +and point is at the lower right corner. +@end group +@end smallexample + +We can run a quick test, to make sure it does what we expect of it. + +Here is the result of placing the cursor after the +@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} +(@code{eval-last-sexp}). The function inserts the strings +@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below +point. Also the function returns @code{nil}. + +@smallexample +@group +(insert-rectangle '("first" "second" "third"))first + second + thirdnil +@end group +@end smallexample + +@noindent +Of course, we won't be inserting the text of the +@code{insert-rectangle} expression itself into the buffer in which we +are making the graph, but will call the function from our program. We +shall, however, have to make sure that point is in the buffer at the +place where the @code{insert-rectangle} function will insert its +column of strings. + +If you are reading this in Info, you can see how this works by +switching to another buffer, such as the @file{*scratch*} buffer, +placing point somewhere in the buffer, typing @kbd{M-:}, typing the +@code{insert-rectangle} expression into the minibuffer at the prompt, +and then typing @key{RET}. This causes Emacs to evaluate the +expression in the minibuffer, but to use as the value of point the +position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the +keybinding for @code{eval-expression}. Also, @code{nil} does not +appear in the @file{*scratch*} buffer since the expression is +evaluated in the minibuffer.) + +We find when we do this that point ends up at the end of the last +inserted line---that is to say, this function moves point as a +side-effect. If we were to repeat the command, with point at this +position, the next insertion would be below and to the right of the +previous insertion. We don't want this! If we are going to make a +bar graph, the columns need to be beside each other. + +So we discover that each cycle of the column-inserting @code{while} +loop must reposition point to the place we want it, and that place +will be at the top, not the bottom, of the column. Moreover, we +remember that when we print a graph, we do not expect all the columns +to be the same height. This means that the top of each column may be +at a different height from the previous one. We cannot simply +reposition point to the same line each time, but moved over to the +right---or perhaps we can@dots{} + +We are planning to make the columns of the bar graph out of asterisks. +The number of asterisks in the column is the number specified by the +current element of the @code{numbers-list}. We need to construct a +list of asterisks of the right length for each call to +@code{insert-rectangle}. If this list consists solely of the requisite +number of asterisks, then we will have position point the right number +of lines above the base for the graph to print correctly. This could +be difficult. + +Alternatively, if we can figure out some way to pass +@code{insert-rectangle} a list of the same length each time, then we +can place point on the same line each time, but move it over one +column to the right for each new column. If we do this, however, some +of the entries in the list passed to @code{insert-rectangle} must be +blanks rather than asterisks. For example, if the maximum height of +the graph is 5, but the height of the column is 3, then +@code{insert-rectangle} requires an argument that looks like this: + +@smallexample +(" " " " "*" "*" "*") +@end smallexample + +This last proposal is not so difficult, so long as we can determine +the column height. There are two ways for us to specify the column +height: we can arbitrarily state what it will be, which would work +fine for graphs of that height; or we can search through the list of +numbers and use the maximum height of the list as the maximum height +of the graph. If the latter operation were difficult, then the former +procedure would be easiest, but there is a function built into Emacs +that determines the maximum of its arguments. We can use that +function. The function is called @code{max} and it returns the +largest of all its arguments, which must be numbers. Thus, for +example, + +@smallexample +(max 3 4 6 5 7 3) +@end smallexample + +@noindent +returns 7. (A corresponding function called @code{min} returns the +smallest of all its arguments.) +@findex max +@findex min + +However, we cannot simply call @code{max} on the @code{numbers-list}; +the @code{max} function expects numbers as its argument, not a list of +numbers. Thus, the following expression, + +@smallexample +(max '(3 4 6 5 7 3)) +@end smallexample + +@need 800 +@noindent +produces the following error message; + +@smallexample +Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) +@end smallexample + +@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 +argument (a function) to its remaining arguments, the last of which +may be a list. + +@need 1250 +For example, + +@smallexample +(apply 'max 3 4 7 3 '(4 8 5)) +@end smallexample + +@noindent +returns 8. + +(Incidentally, I don't know how you would learn of this function +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 +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 +it.) + +The second and subsequent arguments to @code{apply} are optional, so +we can use @code{apply} to call a function and pass the elements of a +list to it, like this, which also returns 8: + +@smallexample +(apply 'max '(4 8 5)) +@end smallexample + +This latter way is how we will use @code{apply}. The +@code{recursive-lengths-list-many-files} function returns a numbers' +list to which we can apply @code{max} (we could also apply @code{max} to +the sorted numbers' list; it does not matter whether the list is +sorted or not.) + +@need 800 +Hence, the operation for finding the maximum height of the graph is this: + +@smallexample +(setq max-graph-height (apply 'max numbers-list)) +@end smallexample + +Now we can return to the question of how to create a list of strings +for a column of the graph. Told the maximum height of the graph +and the number of asterisks that should appear in the column, the +function should return a list of strings for the +@code{insert-rectangle} command to insert. + +Each column is made up of asterisks or blanks. Since the function is +passed the value of the height of the column and the number of +asterisks in the column, the number of blanks can be found by +subtracting the number of asterisks from the height of the column. +Given the number of blanks and the number of asterisks, two +@code{while} loops can be used to construct the list: + +@smallexample +@group +;;; @r{First version.} +(defun column-of-graph (max-graph-height actual-height) + "Return list of strings that is one column of a graph." + (let ((insert-list nil) + (number-of-top-blanks + (- max-graph-height actual-height))) +@end group + +@group + ;; @r{Fill in asterisks.} + (while (> actual-height 0) + (setq insert-list (cons "*" insert-list)) + (setq actual-height (1- actual-height))) +@end group + +@group + ;; @r{Fill in blanks.} + (while (> number-of-top-blanks 0) + (setq insert-list (cons " " insert-list)) + (setq number-of-top-blanks + (1- number-of-top-blanks))) +@end group + +@group + ;; @r{Return whole list.} + insert-list)) +@end group +@end smallexample + +If you install this function and then evaluate the following +expression you will see that it returns the list as desired: + +@smallexample +(column-of-graph 5 3) +@end smallexample + +@need 800 +@noindent +returns + +@smallexample +(" " " " "*" "*" "*") +@end smallexample + +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, +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 +each time the @code{insert-rectangle} function is called; or you might +want to substitute a @samp{+} sign or other symbol for the asterisk. +You might even want to make a graph-column that is more than one +display column wide. The program should be more flexible. The way to +do that is to replace the blank and the asterisk with two variables +that we can call @code{graph-blank} and @code{graph-symbol} and define +those variables separately. + +Also, the documentation is not well written. These considerations +lead us to the second version of the function: + +@smallexample +@group +(defvar graph-symbol "*" + "String used as symbol in graph, usually an asterisk.") +@end group + +@group +(defvar graph-blank " " + "String used as blank in graph, usually a blank space. +graph-blank must be the same number of columns wide +as graph-symbol.") +@end group +@end smallexample + +@noindent +(For an explanation of @code{defvar}, see +@ref{defvar, , Initializing a Variable with @code{defvar}}.) + +@smallexample +@group +;;; @r{Second version.} +(defun column-of-graph (max-graph-height actual-height) + "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. + +@end group +@group +The graph-symbols are contiguous entries at the end +of the list. +The list will be inserted as one column of a graph. +The strings are either graph-blank or graph-symbol." +@end group + +@group + (let ((insert-list nil) + (number-of-top-blanks + (- max-graph-height actual-height))) +@end group + +@group + ;; @r{Fill in @code{graph-symbols}.} + (while (> actual-height 0) + (setq insert-list (cons graph-symbol insert-list)) + (setq actual-height (1- actual-height))) +@end group + +@group + ;; @r{Fill in @code{graph-blanks}.} + (while (> number-of-top-blanks 0) + (setq insert-list (cons graph-blank insert-list)) + (setq number-of-top-blanks + (1- number-of-top-blanks))) + + ;; @r{Return whole list.} + insert-list)) +@end group +@end smallexample + +If we wished, we could rewrite @code{column-of-graph} a third time to +provide optionally for a line graph as well as for a bar graph. This +would not be hard to do. One way to think of a line graph is that it +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 +the list. + +It is easy to see how to write such a function, but since we don't +need it, we will not do it. But the job could be done, and if it were +done, it would be done with @code{column-of-graph}. Even more +important, it is worth noting that few changes would have to be made +anywhere else. The enhancement, if we ever wish to make it, is +simple. + +Now, finally, we come to our first actual graph printing function. +This prints the body of a graph, not the labels for the vertical and +horizontal axes, so we can call this @code{graph-body-print}. + +@node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph +@section The @code{graph-body-print} Function +@findex graph-body-print + +After our preparation in the preceding section, the +@code{graph-body-print} function is straightforward. The function +will print column after column of asterisks and blanks, using the +elements of a numbers' list to specify the number of asterisks in each +column. This is a repetitive act, which means we can use a +decrementing @code{while} loop or recursive function for the job. In +this section, we will write the definition using a @code{while} loop. + +The @code{column-of-graph} function requires the height of the graph +as an argument, so we should determine and record that as a local variable. + +This leads us to the following template for the @code{while} loop +version of this function: + +@smallexample +@group +(defun graph-body-print (numbers-list) + "@var{documentation}@dots{}" + (let ((height @dots{} + @dots{})) +@end group + +@group + (while numbers-list + @var{insert-columns-and-reposition-point} + (setq numbers-list (cdr numbers-list))))) +@end group +@end smallexample + +@noindent +We need to fill in the slots of the template. + +Clearly, we can use the @code{(apply 'max numbers-list)} expression to +determine the height of the graph. + +The @code{while} loop will cycle through the @code{numbers-list} one +element at a time. As it is shortened by the @code{(setq numbers-list +(cdr numbers-list))} expression, the @sc{car} of each instance of the +list is the value of the argument for @code{column-of-graph}. + +At each cycle of the @code{while} loop, the @code{insert-rectangle} +function inserts the list returned by @code{column-of-graph}. Since +the @code{insert-rectangle} function moves point to the lower right of +the inserted rectangle, we need to save the location of point at the +time the rectangle is inserted, move back to that position after the +rectangle is inserted, and then move horizontally to the next place +from which @code{insert-rectangle} is called. + +If the inserted columns are one character wide, as they will be if +single blanks and asterisks are used, the repositioning command is +simply @code{(forward-char 1)}; however, the width of a column may be +greater than one. This means that the repositioning command should be +written @code{(forward-char symbol-width)}. The @code{symbol-width} +itself is the length of a @code{graph-blank} and can be found using +the expression @code{(length graph-blank)}. The best place to bind +the @code{symbol-width} variable to the value of the width of graph +column is in the varlist of the @code{let} expression. + +@need 1250 +These considerations lead to the following function definition: + +@smallexample +@group +(defun graph-body-print (numbers-list) + "Print a bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values." + + (let ((height (apply 'max numbers-list)) + (symbol-width (length graph-blank)) + from-position) +@end group + +@group + (while numbers-list + (setq from-position (point)) + (insert-rectangle + (column-of-graph height (car numbers-list))) + (goto-char from-position) + (forward-char symbol-width) +@end group +@group + ;; @r{Draw graph column by column.} + (sit-for 0) + (setq numbers-list (cdr numbers-list))) +@end group +@group + ;; @r{Place point for X axis labels.} + (forward-line height) + (insert "\n") +)) +@end group +@end smallexample + +@noindent +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 +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. + +We can test @code{graph-body-print} with a short list of numbers. + +@enumerate +@item +Install @code{graph-symbol}, @code{graph-blank}, +@code{column-of-graph}, which are in +@iftex +@ref{Readying a Graph, , Readying a Graph}, +@end iftex +@ifinfo +@ref{Columns of a graph}, +@end ifinfo +and @code{graph-body-print}. + +@need 800 +@item +Copy the following expression: + +@smallexample +(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) +@end smallexample + +@item +Switch to the @file{*scratch*} buffer and place the cursor where you +want the graph to start. + +@item +Type @kbd{M-:} (@code{eval-expression}). + +@item +Yank the @code{graph-body-print} expression into the minibuffer +with @kbd{C-y} (@code{yank)}. + +@item +Press @key{RET} to evaluate the @code{graph-body-print} expression. +@end enumerate + +@need 800 +Emacs will print a graph like this: + +@smallexample +@group + * + * ** + * **** + *** **** + ********* * + ************ + ************* +@end group +@end smallexample + +@node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph +@section The @code{recursive-graph-body-print} Function +@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' +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: + +@smallexample +@group +(defun recursive-graph-body-print (numbers-list) + "Print a bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values." + (let ((height (apply 'max numbers-list)) + (symbol-width (length graph-blank)) + from-position) + (recursive-graph-body-print-internal + numbers-list + height + symbol-width))) +@end group +@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} +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 +version of the @code{numbers-list}. + +@smallexample +@group +(defun recursive-graph-body-print-internal + (numbers-list height symbol-width) + "Print a bar graph. +Used within recursive-graph-body-print function." +@end group + +@group + (when numbers-list + (setq from-position (point)) + (insert-rectangle + (column-of-graph height (car numbers-list))) +@end group +@group + (goto-char from-position) + (forward-char symbol-width) + (sit-for 0) ; @r{Draw graph column by column.} + (recursive-graph-body-print-internal + (cdr numbers-list) height symbol-width))) +@end group +@end smallexample + +@need 1250 +After installation, this expression can be tested; here is a sample: + +@smallexample +(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) +@end smallexample + +@need 800 +Here is what @code{recursive-graph-body-print} produces: + +@smallexample +@group + * + ** * + **** * + **** *** + * ********* + ************ + ************* +@end group +@end smallexample + +Either of these two functions, @code{graph-body-print} or +@code{recursive-graph-body-print}, create the body of a graph. + +@node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph +@section Need for Printed Axes + +A graph needs printed axes, so you can orient yourself. For a do-once +project, it may be reasonable to draw the axes by hand using Emacs' +Picture mode; but a graph drawing function may be used more than once. + +For this reason, I have written enhancements to the basic +@code{print-graph-body} function that automatically print labels for +the horizontal and vertical axes. Since the label printing functions +do not contain much new material, I have placed their description in +an appendix. @xref{Full Graph, , A Graph with Labelled Axes}. + +@node Line Graph Exercise, , Printed Axes, Readying a Graph +@section Exercise + +Write a line graph version of the graph printing functions. + +@node Emacs Initialization, Debugging, Readying a Graph, Top +@chapter Your @file{.emacs} File +@cindex @file{.emacs} file +@cindex Customizing your @file{.emacs} file +@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 +it to suit themselves. + +GNU Emacs is mostly written in Emacs Lisp; this means that by writing +expressions in Emacs Lisp you can change or extend Emacs. + +@menu +* Default Configuration:: +* Site-wide Init:: You can write site-wide init files. +* defcustom:: Emacs will write code for you. +* Beginning a .emacs File:: How to write a @code{.emacs file}. +* Text and Auto-fill:: Automatically wrap lines. +* Mail Aliases:: Use abbreviations for email addresses. +* Indent Tabs Mode:: Don't use tabs with @TeX{} +* Keybindings:: Create some personal keybindings. +* Keymaps:: More about key binding. +* Loading Files:: Load (i.e., evaluate) files automatically. +* Autoload:: Make functions available. +* Simple Extension:: Define a function; bind it to a key. +* X11 Colors:: Colors in X. +* Miscellaneous:: +* Mode Line:: How to customize your mode line. +@end menu + +@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization +@ifnottex +@unnumberedsec Emacs' Default Configuration +@end ifnottex + +There are those who appreciate Emacs' default configuration. After +all, Emacs starts you in C mode when you edit a C file, starts you in +Fortran mode when you edit a Fortran file, and starts you in +Fundamental mode when you edit an unadorned file. This all makes +sense, if you do not know who is going to use Emacs. Who knows what a +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 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. + +For example, I seldom want Fundamental mode when I edit an +otherwise undistinguished file; I want Text mode. This is why I +customize Emacs: so it suits me. + +You can customize and extend Emacs by writing or adapting a +@file{~/.emacs} file. This is your personal initialization file; its +contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You +may also add @file{.el} to @file{~/.emacs} and call it a +@file{~/.emacs.el} file. In the past, you were forbidden to type the +extra keystrokes that the name @file{~/.emacs.el} requires, but now +you may. The new format is consistent with the Emacs Lisp file +naming conventions; the old format saves typing.} + +A @file{~/.emacs} file contains Emacs Lisp code. You can write this +code yourself; or you can use Emacs' @code{customize} feature to write +the code for you. You can combine your own expressions and +auto-written Customize expressions in your @file{.emacs} file. + +(I myself prefer to write my own expressions, except for those, +particularly fonts, that I find easier to manipulate using the +@code{customize} command. I combine the two methods.) + +Most of this chapter is about writing expressions yourself. It +describes a simple @file{.emacs} file; for more information, see +@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and +@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference +Manual}. + +@node Site-wide Init, defcustom, Default Configuration, Emacs Initialization +@section Site-wide Initialization Files + +@cindex @file{default.el} init file +@cindex @file{site-init.el} init file +@cindex @file{site-load.el} init file +In addition to your personal initialization file, Emacs automatically +loads various site-wide initialization files, if they exist. These +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 +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 +Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the +@file{INSTALL} file.) + +Three other site-wide initialization files are loaded automatically +each time you start Emacs, if they exist. These are +@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} +file, and @file{default.el}, and the terminal type file, which are both +loaded @emph{after} your @file{.emacs} file. + +Settings and definitions in your @file{.emacs} file will overwrite +conflicting settings and definitions in a @file{site-start.el} file, +if it exists; but the settings and definitions in a @file{default.el} +or terminal type file will overwrite those in your @file{.emacs} file. +(You can prevent interference from a terminal type file by setting +@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A +Simple Extension}.) + +@c Rewritten to avoid overfull hbox. +The @file{INSTALL} file that comes in the distribution contains +descriptions of the @file{site-init.el} and @file{site-load.el} files. + +The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files +control loading. These files are in the @file{lisp} directory of the +Emacs distribution and are worth perusing. + +The @file{loaddefs.el} file contains a good many suggestions as to +what to put into your own @file{.emacs} file, or into a site-wide +initialization file. + +@node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization +@section Specifying Variables using @code{defcustom} +@findex defcustom + +You can specify variables using @code{defcustom} so that you and +others can then use Emacs' @code{customize} feature to set their +values. (You cannot use @code{customize} to write function +definitions; but you can write @code{defuns} in your @file{.emacs} +file. Indeed, you can write any Lisp expression in your @file{.emacs} +file.) + +The @code{customize} feature depends on the @code{defcustom} special +form. Although you can use @code{defvar} or @code{setq} for variables +that users set, the @code{defcustom} special form is designed for the +job. + +You can use your knowledge of @code{defvar} for writing the +first three arguments for @code{defcustom}. The first argument to +@code{defcustom} is the name of the variable. The second argument is +the variable's initial value, if any; and this value is set only if +the value has not already been set. The third argument is the +documentation. + +The fourth and subsequent arguments to @code{defcustom} specify types +and options; these are not featured in @code{defvar}. (These +arguments are optional.) + +Each of these arguments consists of a keyword followed by a value. +Each keyword starts with the colon character @samp{:}. + +@need 1250 +For example, the customizable user option variable +@code{text-mode-hook} looks like this: + +@smallexample +@group +(defcustom text-mode-hook nil + "Normal hook run when entering Text mode and many related modes." + :type 'hook + :options '(turn-on-auto-fill flyspell-mode) + :group 'data) +@end group +@end smallexample + +@noindent +The name of the variable is @code{text-mode-hook}; it has no default +value; and its documentation string tells you what it does. + +The @code{:type} keyword tells Emacs the kind of data to which +@code{text-mode-hook} should be set and how to display the value in a +Customization buffer. + +The @code{:options} keyword specifies a suggested list of values for +the variable. Usually, @code{:options} applies to a hook. +The list is only a suggestion; it is not exclusive; a person who sets +the variable may set it to other values; the list shown following the +@code{:options} keyword is intended to offer convenient choices to a +user. + +Finally, the @code{:group} keyword tells the Emacs Customization +command in which group the variable is located. This tells where to +find it. + +The @code{defcustom} function recognizes more than a dozen keywords. +For more information, see @ref{Customization, , Writing Customization +Definitions, elisp, The GNU Emacs Lisp Reference Manual}. + +Consider @code{text-mode-hook} as an example. + +There are two ways to customize this variable. You can use the +customization command or write the appropriate expressions yourself. + +@need 800 +Using the customization command, you can type: + +@smallexample +M-x customize +@end smallexample + +@noindent +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 + +@smallexample +Save for Future Sessions +@end smallexample + +@noindent +Emacs will write an expression into your @file{.emacs} file. +It will look like this: + +@smallexample +@group +(custom-set-variables + ;; custom-set-variables was added by Custom. + ;; If you edit it by hand, you could mess it up, so be careful. + ;; Your init file should contain only one such instance. + ;; If there is more than one, they won't work right. + '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) +@end group +@end smallexample + +@noindent +(The @code{text-mode-hook-identify} function tells +@code{toggle-text-mode-auto-fill} which buffers are in Text mode. +It comes on automatically.) + +The @code{custom-set-variables} function works somewhat differently +than a @code{setq}. While I have never learned the differences, I +modify the @code{custom-set-variables} expressions in my @file{.emacs} +file by hand: I make the changes in what appears to me to be a +reasonable manner and have not had any problems. Others prefer to use +the Customization command and let Emacs do the work for them. + +Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. +This function sets the various font faces. Over time, I have set a +considerable number of faces. Some of the time, I re-set them using +@code{customize}; other times, I simply edit the +@code{custom-set-faces} expression in my @file{.emacs} file itself. + +The second way to customize your @code{text-mode-hook} is to set it +yourself in your @file{.emacs} file using code that has nothing to do +with the @code{custom-set-@dots{}} functions. + +@need 800 +When you do this, and later use @code{customize}, you will see a +message that says + +@smallexample +CHANGED outside Customize; operating on it here may be unreliable. +@end smallexample + +@need 800 +This message is only a warning. If you click on the button to + +@smallexample +Save for Future Sessions +@end smallexample + +@noindent +Emacs will write a @code{custom-set-@dots{}} expression near the end +of your @file{.emacs} file that will be evaluated after your +hand-written expression. It will, therefore, overrule your +hand-written expression. No harm will be done. When you do this, +however, be careful to remember which expression is active; if you +forget, you may confuse yourself. + +So long as you remember where the values are set, you will have no +trouble. In any event, the values are always set in your +initialization file, which is usually called @file{.emacs}. + +I myself use @code{customize} for hardly anything. Mostly, I write +expressions myself. + +@findex defsubst +@findex defconst +Incidentally, to be more complete concerning defines: @code{defsubst} +defines an inline function. The syntax is just like that of +@code{defun}. @code{defconst} defines a symbol as a constant. The +intent is that neither programs nor users should ever change a value +set by @code{defconst}. (You can change it; the value set is a +variable; but please do not.) + +@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization +@section Beginning a @file{.emacs} File +@cindex @file{.emacs} file, beginning of + +When you start Emacs, it loads your @file{.emacs} file unless you tell +it not to by specifying @samp{-q} on the command line. (The +@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) + +A @file{.emacs} file contains Lisp expressions. Often, these are no +more than expressions to set values; sometimes they are function +definitions. + +@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs +Manual}, for a short description of initialization files. + +This chapter goes over some of the same ground, but is a walk among +extracts from a complete, long-used @file{.emacs} file---my own. + +The first part of the file consists of comments: reminders to myself. +By now, of course, I remember these things, but when I started, I did +not. + +@need 1200 +@smallexample +@group +;;;; Bob's .emacs file +; Robert J. Chassell +; 26 September 1985 +@end group +@end smallexample + +@noindent +Look at that date! I started this file a long time ago. I have been +adding to it ever since. + +@smallexample +@group +; Each section in this file is introduced by a +; line beginning with four semicolons; and each +; entry is introduced by a line beginning with +; three semicolons. +@end group +@end smallexample + +@noindent +This describes the usual conventions for comments in Emacs Lisp. +Everything on a line that follows a semicolon is a comment. Two, +three, and four semicolons are used as subsection and section markers. +(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for +more about comments.) + +@smallexample +@group +;;;; The Help Key +; Control-h is the help key; +; after typing control-h, type a letter to +; indicate the subject about which you want help. +; For an explanation of the help facility, +; type control-h two times in a row. +@end group +@end smallexample + +@noindent +Just remember: type @kbd{C-h} two times for help. + +@smallexample +@group +; To find out about any mode, type control-h m +; while in that mode. For example, to find out +; about mail mode, enter mail mode and then type +; control-h m. +@end group +@end smallexample + +@noindent +`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 +@file{.emacs} file. I included them in mine because I kept forgetting +about Mode help or the conventions for comments---but I was able to +remember to look here to remind myself. + +@node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization +@section Text and Auto Fill Mode + +Now we come to the part that `turns on' Text mode and +Auto Fill mode. + +@smallexample +@group +;;; Text mode and Auto Fill mode +; The next two lines put Emacs into Text mode +; and Auto Fill mode, and are for writers who +; want to start writing prose rather than code. +(setq default-major-mode 'text-mode) +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end group +@end smallexample + +Here is the first part of this @file{.emacs} file that does something +besides remind a forgetful human! + +The first of the two lines in parentheses tells Emacs to turn on Text +mode when you find a file, @emph{unless} that file should go into some +other mode, such as C mode. + +@cindex Per-buffer, local variables list +@cindex Local variables list, per-buffer, +@cindex Automatic mode selection +@cindex Mode selection, automatic +When Emacs reads a file, it looks at the extension to the file name, +if any. (The extension is the part that comes after a @samp{.}.) If +the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns +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. + +@ifinfo +@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU +Emacs Manual}. + +@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs +Manual}. +@end ifinfo +@iftex +See sections ``How Major Modes are Chosen'' and ``Local Variables in +Files'' in @cite{The GNU Emacs Manual}. +@end iftex + +Now, back to the @file{.emacs} file. + +@need 800 +Here is the line again; how does it work? + +@cindex Text Mode turned on +@smallexample +(setq default-major-mode 'text-mode) +@end smallexample + +@noindent +This line is a short, but complete Emacs Lisp expression. + +We are already familiar with @code{setq}. It sets the following variable, +@code{default-major-mode}, to the subsequent value, which is +@code{text-mode}. The single quote mark before @code{text-mode} tells +Emacs to deal directly with the @code{text-mode} variable, not with +whatever it might stand for. @xref{set & setq, , Setting the Value of +a Variable}, for a reminder of how @code{setq} works. The main point +is that there is no difference between the procedure you use to set +a value in your @file{.emacs} file and the procedure you use anywhere +else in Emacs. + +@need 800 +Here is the next line: + +@cindex Auto Fill mode turned on +@findex add-hook +@smallexample +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end smallexample + +@noindent +In this line, the @code{add-hook} command adds +@code{turn-on-auto-fill} to the variable. + +@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' +onto Text mode. So every time Emacs turns on Text mode, Emacs also +turns on Auto Fill mode. + +In brief, the first line causes Emacs to enter Text mode when you edit a +file, unless the file name extension, a first non-blank line, or local +variables to tell Emacs otherwise. + +Text mode among other actions, sets the syntax table to work +conveniently for writers. In Text mode, Emacs considers an apostrophe +as part of a word like a letter; but Emacs does not consider a period +or a space as part of a word. Thus, @kbd{M-f} moves you over +@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after +the @samp{t} of @samp{it's}. + +The second line causes Emacs to turn on Auto Fill mode when it turns +on Text mode. In Auto Fill mode, Emacs automatically breaks a line +that is too wide and brings the excessively wide part of the line down +to the next line. Emacs breaks lines between words, not within them. + +When Auto Fill mode is turned off, lines continue to the right as you +type them. Depending on how you set the value of +@code{truncate-lines}, the words you type either disappear off the +right side of the screen, or else are shown, in a rather ugly and +unreadable manner, as a continuation line on the screen. + +@need 1250 +In addition, in this part of my @file{.emacs} file, I tell the Emacs +fill commands to insert two spaces after a colon: + +@smallexample +(setq colon-double-space t) +@end smallexample + +@node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization +@section Mail Aliases + +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 RMAIL (for reading mail), +; type `M-x rmail' +(setq mail-aliases t) +@end group +@end smallexample + +@cindex Mail aliases +@noindent +This @code{setq} command sets the value of the variable +@code{mail-aliases} to @code{t}. Since @code{t} means true, the line +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' +is @file{~/.mailrc}. You write an alias like this: + +@smallexample +alias geo george@@foobar.wiz.edu +@end smallexample + +@noindent +When you write a message to George, address it to @samp{geo}; the +mailer will automatically expand @samp{geo} to the full address. + +@node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization +@section Indent Tabs Mode +@cindex Tabs, preventing +@findex indent-tabs-mode + +By default, Emacs inserts tabs in place of multiple spaces when it +formats a region. (For example, you might indent many lines of text +all at once with the @code{indent-region} command.) Tabs look fine on +a terminal or with ordinary printing, but they produce badly indented +output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. + +@need 1250 +The following turns off Indent Tabs mode: + +@smallexample +@group +;;; Prevent Extraneous Tabs +(setq-default indent-tabs-mode nil) +@end group +@end smallexample + +Note that this line uses @code{setq-default} rather than the +@code{setq} command that we have seen before. The @code{setq-default} +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{File Variables, , Local Variables in Files, emacs, The GNU Emacs +Manual}. +@end ifinfo +@iftex +See sections ``Tabs vs.@: Spaces'' and ``Local Variables in +Files'' in @cite{The GNU Emacs Manual}. +@end iftex + +@need 1700 +@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization +@section Some Keybindings + +Now for some personal keybindings: + +@smallexample +@group +;;; Compare windows +(global-set-key "\C-cw" 'compare-windows) +@end group +@end smallexample + +@findex compare-windows +@code{compare-windows} is a nifty command that compares the text in +your current window with text in the next window. It makes the +comparison by starting at point in each window, moving over text in +each window as far as they match. I use this command all the time. + +This also shows how to set a key globally, for all modes. + +@cindex Setting a key globally +@cindex Global set key +@cindex Key setting globally +@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 +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 +@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , +Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for +details.) + +The command invoked by the keys is @code{compare-windows}. Note that +@code{compare-windows} is preceded by a single quote; otherwise, Emacs +would first try to evaluate the symbol to determine its value. + +These three things, the double quotation marks, the backslash before +the @samp{C}, and the single quote mark are necessary parts of +keybinding that I tend to forget. Fortunately, I have come to +remember that I should look at my existing @file{.emacs} file, and +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 +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. + +@need 1250 +Here is another keybinding, with a comment: + +@smallexample +@group +;;; Keybinding for `occur' +; I use occur a lot, so let's bind it to a key: +(global-set-key "\C-co" 'occur) +@end group +@end smallexample + +@findex occur +The @code{occur} command shows all the lines in the current buffer +that contain a match for a regular expression. Matching lines are +shown in a buffer called @file{*Occur*}. That buffer serves as a menu +to jump to occurrences. + +@findex global-unset-key +@cindex Unbinding key +@cindex Key unbinding +@need 1250 +Here is how to unbind a key, so it does not +work: + +@smallexample +@group +;;; Unbind `C-x f' +(global-unset-key "\C-xf") +@end group +@end smallexample + +There is a reason for this unbinding: I found I inadvertently typed +@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a +file, as I intended, I accidentally set the width for filled text, +almost always to a width I did not want. Since I hardly ever reset my +default width, I simply unbound the key. + +@findex list-buffers, @r{rebound} +@findex buffer-menu, @r{bound to key} +@need 1250 +The following rebinds an existing key: + +@smallexample +@group +;;; Rebind `C-x C-b' for `buffer-menu' +(global-set-key "\C-x\C-b" 'buffer-menu) +@end group +@end smallexample + +By default, @kbd{C-x C-b} runs the +@code{list-buffers} command. This command lists +your buffers in @emph{another} window. Since I +almost always want to do something in that +window, I prefer the @code{buffer-menu} +command, which not only lists the buffers, +but moves point into that window. + +@node Keymaps, Loading Files, Keybindings, Emacs Initialization +@section Keymaps +@cindex Keymaps +@cindex Rebinding keys + +Emacs uses @dfn{keymaps} to record which keys call which commands. +When you use @code{global-set-key} to set the keybinding for a single +command in all parts of Emacs, you are specifying the keybinding in +@code{current-global-map}. + +Specific modes, such as C mode or Text mode, have their own keymaps; +the mode-specific keymaps override the global map that is shared by +all buffers. + +The @code{global-set-key} function binds, or rebinds, the global +keymap. For example, the following binds the key @kbd{C-x C-b} to the +function @code{buffer-menu}: + +@smallexample +(global-set-key "\C-x\C-b" 'buffer-menu) +@end smallexample + +Mode-specific keymaps are bound using the @code{define-key} function, +which takes a specific keymap as an argument, as well as the key and +the command. For example, my @file{.emacs} file contains the +following expression to bind the @code{texinfo-insert-@@group} command +to @kbd{C-c C-c g}: + +@smallexample +@group +(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) +@end group +@end smallexample + +@noindent +The @code{texinfo-insert-@@group} function itself is a little extension +to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I +use this command all the time and prefer to type the three strokes +@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. +(@samp{@@group} and its matching @samp{@@end group} are commands that +keep all enclosed text together on one page; many multi-line examples +in this book are surrounded by @samp{@@group @dots{} @@end group}.) + +@need 1250 +Here is the @code{texinfo-insert-@@group} function definition: + +@smallexample +@group +(defun texinfo-insert-@@group () + "Insert the string @@group in a Texinfo buffer." + (interactive) + (beginning-of-line) + (insert "@@group\n")) +@end group +@end smallexample + +(Of course, I could have used Abbrev mode to save typing, rather than +write a function to insert a word; but I prefer key strokes consistent +with other Texinfo mode key bindings.) + +You will see numerous @code{define-key} expressions in +@file{loaddefs.el} as well as in the various mode libraries, such as +@file{cc-mode.el} and @file{lisp-mode.el}. + +@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs +Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp +Reference Manual}, for more information about keymaps. + +@node Loading Files, Autoload, Keymaps, Emacs Initialization +@section Loading Files +@cindex Loading files +@c findex load + +Many people in the GNU Emacs community have written extensions to +Emacs. As time goes by, these extensions are often included in new +releases. For example, the Calendar and Diary packages are now part +of the standard GNU Emacs, as is Calc. + +You can use a @code{load} command to evaluate a complete file and +thereby install all the functions and variables in the file into Emacs. +For example: + +@c (auto-compression-mode t) + +@smallexample +(load "~/emacs/slowsplit") +@end smallexample + +This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it +exists, the faster, byte compiled @file{slowsplit.elc} file from the +@file{emacs} sub-directory of your home directory. The file contains +the function @code{split-window-quietly}, which John Robinson wrote in +1989. + +The @code{split-window-quietly} function splits a window with the +minimum of redisplay. I installed it in 1989 because it worked well +with the slow 1200 baud terminals I was then using. Nowadays, I only +occasionally come across such a slow connection, but I continue to use +the function because I like the way it leaves the bottom half of a +buffer in the lower of the new windows and the top half in the upper +window. + +@need 1250 +To replace the key binding for the default +@code{split-window-vertically}, you must also unset that key and bind +the keys to @code{split-window-quietly}, like this: + +@smallexample +@group +(global-unset-key "\C-x2") +(global-set-key "\C-x2" 'split-window-quietly) +@end group +@end smallexample + +@vindex load-path +If you load many extensions, as I do, then instead of specifying the +exact location of the extension file, as shown above, you can specify +that directory as part of Emacs' @code{load-path}. Then, when Emacs +loads a file, it will search that directory as well as its default +list of directories. (The default list is specified in @file{paths.h} +when Emacs is built.) + +@need 1250 +The following command adds your @file{~/emacs} directory to the +existing load path: + +@smallexample +@group +;;; Emacs Load Path +(setq load-path (cons "~/emacs" load-path)) +@end group +@end smallexample + +Incidentally, @code{load-library} is an interactive interface to the +@code{load} function. The complete function looks like this: + +@findex load-library +@smallexample +@group +(defun load-library (library) + "Load the library named LIBRARY. +This is an interface to the function `load'." + (interactive + (list (completing-read "Load library: " + 'locate-file-completion + (cons load-path (get-load-suffixes))))) + (load library)) +@end group +@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 +@code{load-library} command is in the @file{files.el} library. + +Another interactive command that does a slightly different job is +@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for +Emacs, emacs, The GNU Emacs Manual}, for information on the +distinction between @code{load-library} and this command. + +@node Autoload, Simple Extension, Loading Files, Emacs Initialization +@section Autoloading +@findex autoload + +Instead of installing a function by loading the file that contains it, +or by evaluating the function definition, you can make the function +available but not actually install it until it is first called. This +is called @dfn{autoloading}. + +When you execute an autoloaded function, Emacs automatically evaluates +the file that contains the definition, and then calls the function. + +Emacs starts quicker with autoloaded functions, since their libraries +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 +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. +@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp +Reference Manual}, and the @file{INSTALL} file for more about +dumping.) + +You may also want to include autoloaded expressions in your @file{.emacs} +file. @code{autoload} is a built-in function that takes up to five +arguments, the final three of which are optional. The first argument +is the name of the function to be autoloaded; the second is the name +of the file to be loaded. The third argument is documentation for the +function, and the fourth tells whether the function can be called +interactively. The fifth argument tells what type of +object---@code{autoload} can handle a keymap or macro as well as a +function (the default is a function). + +@need 800 +Here is a typical example: + +@smallexample +@group +(autoload 'html-helper-mode + "html-helper-mode" "Edit HTML documents" t) +@end group +@end smallexample + +@noindent +(@code{html-helper-mode} is an older alternative to @code{html-mode}, +which is a standard part of the distribution.) + +@noindent +This expression autoloads the @code{html-helper-mode} function. It +takes it from the @file{html-helper-mode.el} file (or from the byte +compiled file @file{html-helper-mode.elc}, if it exists.) The file +must be located in a directory specified by @code{load-path}. The +documentation says that this is a mode to help you edit documents +written in the HyperText Markup Language. You can call this mode +interactively by typing @kbd{M-x html-helper-mode}. (You need to +duplicate the function's regular documentation in the autoload +expression because the regular function is not yet loaded, so its +documentation is not available.) + +@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference +Manual}, for more information. + +@node Simple Extension, X11 Colors, Autoload, Emacs Initialization +@section A Simple Extension: @code{line-to-top-of-window} +@findex line-to-top-of-window +@cindex Simple extension in @file{.emacs} file + +Here is a simple extension to Emacs that moves the line point is on to +the top of the window. I use this all the time, to make text easier +to read. + +You can put the following code into a separate file and then load it +from your @file{.emacs} file, or you can include it within your +@file{.emacs} file. + +@need 1250 +Here is the definition: + +@smallexample +@group +;;; Line to top of window; +;;; replace three keystroke sequence C-u 0 C-l +(defun line-to-top-of-window () + "Move the line point is on to top of window." + (interactive) + (recenter 0)) +@end group +@end smallexample + +@need 1250 +Now for the keybinding. + +Nowadays, function keys as well as mouse button events and +non-@sc{ascii} characters are written within square brackets, without +quotation marks. (In Emacs version 18 and before, you had to write +different function key bindings for each different make of terminal.) + +I bind @code{line-to-top-of-window} to my @key{F6} function key like +this: + +@smallexample +(global-set-key [f6] 'line-to-top-of-window) +@end smallexample + +For more information, see @ref{Init Rebinding, , Rebinding Keys in +Your Init File, emacs, The GNU Emacs Manual}. + +@cindex Conditional 'twixt two versions of Emacs +@cindex Version of Emacs, choosing +@cindex Emacs version, choosing +If you run two versions of GNU Emacs, such as versions 21 and 22, and +use one @file{.emacs} file, you can select which code to evaluate with +the following conditional: + +@smallexample +@group +(cond + (= 21 emacs-major-version) + ;; evaluate version 21 code + ( @dots{} )) + (= 22 emacs-major-version) + ;; evaluate version 22 code + ( @dots{} ))) +@end group +@end smallexample + +For example, in contrast to version 20, more recent versions blink +their cursors by default. I hate such blinking, as well as other +features, so I placed the following in my @file{.emacs} +file@footnote{When I start instances of Emacs that do not load my +@file{.emacs} file or any site file, I also turn off blinking: + +@smallexample +emacs -q --no-site-file -eval '(blink-cursor-mode nil)' + +@exdent Or nowadays, using an even more sophisticated set of options, + +emacs -Q - D +@end smallexample +}: + +@smallexample +@group +(when (or (= 21 emacs-major-version) + (= 22 emacs-major-version)) + (blink-cursor-mode 0) + ;; Insert newline when you press `C-n' (next-line) + ;; at the end of the buffer + (setq next-line-add-newlines t) +@end group +@group + ;; Turn on image viewing + (auto-image-file-mode t) +@end group +@group + ;; Turn on menu bar (this bar has text) + ;; (Use numeric argument to turn on) + (menu-bar-mode 1) +@end group +@group + ;; Turn off tool bar (this bar has icons) + ;; (Use numeric argument to turn on) + (tool-bar-mode nil) +@end group +@group + ;; Turn off tooltip mode for tool bar + ;; (This mode causes icon explanations to pop up) + ;; (Use numeric argument to turn on) + (tooltip-mode nil) + ;; If tooltips turned on, make tips appear promptly + (setq tooltip-delay 0.1) ; default is 0.7 second + ) +@end group +@end smallexample + +@need 1250 +Alternatively, since @code{blink-cursor-mode} has existed since Emacs +version 21 and is likely to continue, you could write + +@smallexample +@group +(when (>= emacs-major-version 21) + (blink-cursor-mode 0) +@end group +@end smallexample + +@noindent +and add other expressions, too. + + +@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization +@section X11 Colors + +You can specify colors when you use Emacs with the MIT X Windowing +system. + +I dislike the default colors and specify my own. + +@need 1250 +Here are the expressions in my @file{.emacs} +file that set values: + +@smallexample +@group +;; Set cursor color +(set-cursor-color "white") + +;; Set mouse color +(set-mouse-color "white") + +;; Set foreground and background +(set-foreground-color "white") +(set-background-color "darkblue") +@end group + +@group +;;; Set highlighting colors for isearch and drag +(set-face-foreground 'highlight "white") +(set-face-background 'highlight "blue") +@end group + +@group +(set-face-foreground 'region "cyan") +(set-face-background 'region "blue") +@end group + +@group +(set-face-foreground 'secondary-selection "skyblue") +(set-face-background 'secondary-selection "darkblue") +@end group + +@group +;; Set calendar highlighting colors +(setq calendar-load-hook + '(lambda () + (set-face-foreground 'diary-face "skyblue") + (set-face-background 'holiday-face "slate blue") + (set-face-foreground 'holiday-face "white"))) +@end group +@end smallexample + +The various shades of blue soothe my eye and prevent me from seeing +the screen flicker. + +Alternatively, I could have set my specifications in various X +initialization files. For example, I could set the foreground, +background, cursor, and pointer (i.e., mouse) colors in my +@file{~/.Xresources} file like this: + +@smallexample +@group +Emacs*foreground: white +Emacs*background: darkblue +Emacs*cursorColor: white +Emacs*pointerColor: white +@end group +@end smallexample + +In any event, since it is not part of Emacs, I set the root color of +my X window in my @file{~/.xinitrc} file, like this@footnote{I also +run more modern window managers, such as Enlightenment, Gnome, or KDE; +in those cases, I often specify an image rather than a plain color.}: + +@smallexample +xsetroot -solid Navy -fg white & +@end smallexample + +@need 1700 +@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization +@section Miscellaneous Settings for a @file{.emacs} File + +@need 1250 +Here are a few miscellaneous settings: +@sp 1 + +@itemize @minus +@item +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. +@end group + +@group +(let ((mpointer (x-get-resource "*mpointer" + "*emacs*mpointer"))) + ;; If you have not set your mouse pointer + ;; then set it, otherwise leave as is: + (if (eq mpointer nil) + (setq mpointer "132")) ; top_left_arrow +@end group +@group + (setq x-pointer-shape (string-to-int mpointer)) + (set-mouse-color "white")) +@end group +@end smallexample + +@item +Or you can set the values of a variety of features in an alist, like +this: + +@smallexample +@group +(setq-default + default-frame-alist + '((cursor-color . "white") + (mouse-color . "white") + (foreground-color . "white") + (background-color . "DodgerBlue4") + ;; (cursor-type . bar) + (cursor-type . box) +@end group +@group + (tool-bar-lines . 0) + (menu-bar-lines . 1) + (width . 80) + (height . 58) + (font . + "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") + )) +@end group +@end smallexample + +@item +Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} +into @kbd{@key{CTRL}-h}.@* +(Some older keyboards needed this, although I have not seen the +problem recently.) + +@smallexample +@group +;; Translate `C-h' to <DEL>. +; (keyboard-translate ?\C-h ?\C-?) + +;; Translate <DEL> to `C-h'. +(keyboard-translate ?\C-? ?\C-h) +@end group +@end smallexample + +@item Turn off a blinking cursor! + +@smallexample +@group +(if (fboundp 'blink-cursor-mode) + (blink-cursor-mode -1)) +@end group +@end smallexample + +@noindent +or start GNU Emacs with the command @code{emacs -nbc}. + +@need 1250 +@item When using `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.@* +@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} + +@smallexample +(setq grep-command "grep -i -nH -e ") +@end smallexample + +@ignore +@c Evidently, no longer needed in GNU Emacs 22 + +item Automatically uncompress compressed files when visiting them + +smallexample +(load "uncompress") +end smallexample + +@end ignore + +@item Find an existing buffer, even if it has a different name@* +This avoids problems with symbolic links. + +@smallexample +(setq find-file-existing-other-name t) +@end smallexample + +@item Set your language environment and default input method + +@smallexample +@group +(set-language-environment "latin-1") +;; Remember you can enable or disable multilingual text input +;; with the @code{toggle-input-method'} (@kbd{C-\}) command +(setq default-input-method "latin-1-prefix") +@end group +@end smallexample + +If you want to write with Chinese `GB' characters, set this instead: + +@smallexample +@group +(set-language-environment "Chinese-GB") +(setq default-input-method "chinese-tonepy") +@end group +@end smallexample +@end itemize + +@subsubheading Fixing Unpleasant Key Bindings +@cindex Key bindings, fixing +@cindex Bindings, key, fixing unpleasant + +Some systems bind keys unpleasantly. Sometimes, for example, the +@key{CTRL} key appears in an awkward spot rather than at the far left +of the home row. + +Usually, when people fix these sorts of keybindings, they do not +change their @file{~/.emacs} file. Instead, they bind the proper keys +on their consoles with the @code{loadkeys} or @code{install-keymap} +commands in their boot script and then include @code{xmodmap} commands +in their @file{.xinitrc} or @file{.Xsession} file for X Windows. + +@need 1250 +@noindent +For a boot script: + +@smallexample +@group +loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz +@exdent or +install-keymap emacs2 +@end group +@end smallexample + +@need 1250 +@noindent +For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps +Lock} key is at the far left of the home row: + +@smallexample +@group +# Bind the key labeled `Caps Lock' to `Control' +# (Such a broken user interface suggests that keyboard manufacturers +# think that computers are typewriters from 1885.) + +xmodmap -e "clear Lock" +xmodmap -e "add Control = Caps_Lock" +@end group +@end smallexample + +@need 1250 +@noindent +In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} +key to a @key{META} key: + +@smallexample +@group +# Some ill designed keyboards have a key labeled ALT and no Meta +xmodmap -e "keysym Alt_L = Meta_L Alt_L" +@end group +@end smallexample + +@need 1700 +@node Mode Line, , Miscellaneous, Emacs Initialization +@section A Modified Mode Line +@vindex default-mode-line-format +@cindex Mode line format + +Finally, a feature I really like: a modified mode line. + +When I work over a network, I forget which machine I am using. Also, +I tend to I lose track of where I am, and which line point is on. + +So I reset my mode line to look like this: + +@smallexample +-:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top +@end smallexample + +I am visiting a file called @file{foo.texi}, on my machine +@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in +Texinfo mode, and am at the top of the buffer. + +@need 1200 +My @file{.emacs} file has a section that looks like this: + +@smallexample +@group +;; Set a Mode Line that tells me which machine, which directory, +;; and which line I am on, plus the other customary information. +(setq default-mode-line-format + (quote + (#("-" 0 1 + (help-echo + "mouse-1: select window, mouse-2: delete others ...")) + mode-line-mule-info + mode-line-modified + mode-line-frame-identification + " " +@end group +@group + mode-line-buffer-identification + " " + (:eval (substring + (system-name) 0 (string-match "\\..+" (system-name)))) + ":" + default-directory + #(" " 0 1 + (help-echo + "mouse-1: select window, mouse-2: delete others ...")) + (line-number-mode " Line %l ") + global-mode-string +@end group +@group + #(" %[(" 0 6 + (help-echo + "mouse-1: select window, mouse-2: delete others ...")) + (:eval (mode-line-mode-name)) + mode-line-process + minor-mode-alist + #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) + ")%] " + (-3 . "%P") + ;; "-%-" + ))) +@end group +@end smallexample + +@noindent +Here, I redefine the default mode line. Most of the parts are from +the original; but I make a few changes. I set the @emph{default} mode +line format so as to permit various modes, such as Info, to override +it. + +Many elements in the list are self-explanatory: +@code{mode-line-modified} is a variable that tells whether the buffer +has been modified, @code{mode-name} tells the name of the mode, and so +on. However, the format looks complicated because of two features we +have not discussed. + +@cindex Properties, in mode line example +The first string in the mode line is a dash or hyphen, @samp{-}. In +the old days, it would have been specified simply as @code{"-"}. But +nowadays, Emacs can add properties to a string, such as highlighting +or, as in this case, a help feature. If you place your mouse cursor +over the hyphen, some help information appears (By default, you must +wait seven-tenths of a second before the information appears. You can +change that timing by changing the value of @code{tooltip-delay}.) + +@need 1000 +The new string format has a special syntax: + +@smallexample +#("-" 0 1 (help-echo "mouse-1: select window, ...")) +@end smallexample + +@noindent +The @code{#(} begins a list. The first element of the list is the +string itself, just one @samp{-}. The second and third +elements specify the range over which the fourth element applies. A +range starts @emph{after} a character, so a zero means the range +starts just before the first character; a 1 means that the range ends +just after the first character. The third element is the property for +the range. It consists of a property list, a +property name, in this case, @samp{help-echo}, followed by a value, in this +case, a string. The second, third, and fourth elements of this new +string format can be repeated. + +@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp +Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, +elisp, The GNU Emacs Lisp Reference Manual}, for more information. + +@code{mode-line-buffer-identification} +displays the current buffer name. It is a list +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' +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 +characters; this length works well in a typical 80 column wide +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 +tell me the length of the first component. The substring from the +zeroth character to that length is the name of the machine. + +@need 1250 +This is the expression: + +@smallexample +@group +(:eval (substring + (system-name) 0 (string-match "\\..+" (system-name)))) +@end group +@end smallexample + +@samp{%[} and @samp{%]} cause a pair of square brackets +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 +@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 +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' +Emacs, with no customization, type: + +@smallexample +emacs -q +@end smallexample + +@noindent +This will start an Emacs that does @emph{not} load your +@file{~/.emacs} initialization file. A plain, default Emacs. Nothing +more. + +@node Debugging, Conclusion, Emacs Initialization, Top +@chapter Debugging +@cindex debugging + +GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The +first is built into the internals of Emacs and is always with you; +the second requires that you instrument a function before you can use it. + +Both debuggers are described extensively in @ref{Debugging, , +Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. +In this chapter, I will walk through a short example of each. + +@menu +* debug:: How to use the built-in debugger. +* debug-on-entry:: Start debugging when you call a function. +* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. +* edebug:: How to use Edebug, a source level debugger. +* Debugging Exercises:: +@end menu + +@node debug, debug-on-entry, Debugging, Debugging +@section @code{debug} +@findex debug + +Suppose you have written a function definition that is intended to +return the sum of the numbers 1 through a given number. (This is the +@code{triangle} function discussed earlier. @xref{Decrementing +Example, , Example with Decrementing Counter}, for a discussion.) +@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) + +However, your function definition has a bug. You have mistyped +@samp{1=} for @samp{1-}. Here is the broken definition: + +@findex triangle-bugged +@smallexample +@group +(defun triangle-bugged (number) + "Return sum of numbers 1 through NUMBER inclusive." + (let ((total 0)) + (while (> number 0) + (setq total (+ total number)) + (setq number (1= number))) ; @r{Error here.} + total)) +@end group +@end smallexample + +If you are reading this in Info, you can evaluate this definition in +the normal fashion. You will see @code{triangle-bugged} appear in the +echo area. + +@need 1250 +Now evaluate the @code{triangle-bugged} function with an +argument of 4: + +@smallexample +(triangle-bugged 4) +@end smallexample + +@noindent +In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} +buffer that says: + +@noindent +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: (void-function 1=) + (1= number) + (setq number (1= number)) + (while (> number 0) (setq total (+ total number)) + (setq number (1= number))) + (let ((total 0)) (while (> number 0) (setq total ...) + (setq number ...)) total) + triangle-bugged(4) +@end group +@group + eval((triangle-bugged 4)) + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@noindent +(I have reformatted this example slightly; the debugger does not fold +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 +tell you what you need to know to correct the definition. The +function @code{1=} is `void'. + +@ignore +@need 800 +In GNU Emacs 20 and before, you will see: + +@smallexample +Symbol's function definition is void:@: 1= +@end smallexample + +@noindent +which has the same meaning as the @file{*Backtrace*} buffer line in +version 21. +@end ignore + +However, suppose you are not quite certain what is going on? +You can read the complete backtrace. + +In this case, you need to run a recent GNU Emacs, which automatically +starts the debugger that puts you in the @file{*Backtrace*} buffer; or +else, you need to start the debugger manually as described below. + +Read the @file{*Backtrace*} buffer from the bottom up; it tells you +what Emacs did that led to the error. Emacs made an interactive call +to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation +of the @code{triangle-bugged} expression. Each line above tells you +what the Lisp interpreter evaluated next. + +@need 1250 +The third line from the top of the buffer is + +@smallexample +(setq number (1= number)) +@end smallexample + +@noindent +Emacs tried to evaluate this expression; in order to do so, it tried +to evaluate the inner expression shown on the second line from the +top: + +@smallexample +(1= number) +@end smallexample + +@need 1250 +@noindent +This is where the error occurred; as the top line says: + +@smallexample +Debugger entered--Lisp error: (void-function 1=) +@end smallexample + +@noindent +You can correct the mistake, re-evaluate the function definition, and +then run your test again. + +@node debug-on-entry, debug-on-quit, debug, Debugging +@section @code{debug-on-entry} +@findex debug-on-entry + +A recent GNU Emacs starts the debugger automatically when your +function has an error. + +@ignore +GNU Emacs version 20 and before did not; it simply +presented you with an error message. You had to start the debugger +manually. +@end ignore + +Incidentally, you can start the debugger manually for all versions of +Emacs; the advantage is that the debugger runs even if you do not have +a bug in your code. Sometimes your code will be free of bugs! + +You can enter the debugger when you call the function by calling +@code{debug-on-entry}. + +@need 1250 +@noindent +Type: + +@smallexample +M-x debug-on-entry RET triangle-bugged RET +@end smallexample + +@need 1250 +@noindent +Now, evaluate the following: + +@smallexample +(triangle-bugged 5) +@end smallexample + +@noindent +All versions of Emacs will create a @file{*Backtrace*} buffer and tell +you that it is beginning to evaluate the @code{triangle-bugged} +function: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--entering a function: +* triangle-bugged(5) + eval((triangle-bugged 5)) +@end group +@group + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate +the first expression in @code{triangle-bugged}; the buffer will look +like this: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--beginning evaluation of function call form: +* (let ((total 0)) (while (> number 0) (setq total ...) + (setq number ...)) total) +* triangle-bugged(5) + eval((triangle-bugged 5)) +@end group +@group + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@noindent +Now, type @kbd{d} again, eight times, slowly. Each time you type +@kbd{d}, Emacs will evaluate another expression in the function +definition. + +@need 1750 +Eventually, the buffer will look like this: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--beginning evaluation of function call form: +* (setq number (1= number)) +* (while (> number 0) (setq total (+ total number)) + (setq number (1= number))) +@group +@end group +* (let ((total 0)) (while (> number 0) (setq total ...) + (setq number ...)) total) +* triangle-bugged(5) + eval((triangle-bugged 5)) +@group +@end group + eval-last-sexp-1(nil) + eval-last-sexp(nil) + call-interactively(eval-last-sexp) +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +@need 1500 +@noindent +Finally, after you type @kbd{d} two more times, Emacs will reach the +error, and the top two lines of the @file{*Backtrace*} buffer will look +like this: + +@smallexample +@group +---------- Buffer: *Backtrace* ---------- +Debugger entered--Lisp error: (void-function 1=) +* (1= number) +@dots{} +---------- Buffer: *Backtrace* ---------- +@end group +@end smallexample + +By typing @kbd{d}, you were able to step through the function. + +You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this +quits the trace, but does not cancel @code{debug-on-entry}. + +@findex cancel-debug-on-entry +To cancel the effect of @code{debug-on-entry}, call +@code{cancel-debug-on-entry} and the name of the function, like this: + +@smallexample +M-x cancel-debug-on-entry RET triangle-bugged RET +@end smallexample + +@noindent +(If you are reading this in Info, cancel @code{debug-on-entry} now.) + +@node debug-on-quit, edebug, debug-on-entry, Debugging +@section @code{debug-on-quit} and @code{(debug)} + +In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, +there are two other ways to start @code{debug}. + +@findex debug-on-quit +You can start @code{debug} whenever you type @kbd{C-g} +(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to +@code{t}. This is useful for debugging infinite loops. + +@need 1500 +@cindex @code{(debug)} in code +Or, you can insert a line that says @code{(debug)} into your code +where you want the debugger to start, like this: + +@smallexample +@group +(defun triangle-bugged (number) + "Return sum of numbers 1 through NUMBER inclusive." + (let ((total 0)) + (while (> number 0) + (setq total (+ total number)) + (debug) ; @r{Start debugger.} + (setq number (1= number))) ; @r{Error here.} + total)) +@end group +@end smallexample + +The @code{debug} function is described in detail in @ref{Debugger, , +The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. + +@node edebug, Debugging Exercises, debug-on-quit, Debugging +@section The @code{edebug} Source Level Debugger +@cindex Source level debugger +@findex edebug + +Edebug is a source level debugger. Edebug normally displays the +source of the code you are debugging, with an arrow at the left that +shows which line you are currently executing. + +You can walk through the execution of a function, line by line, or run +quickly until reaching a @dfn{breakpoint} where execution stops. + +Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs +Lisp Reference Manual}. + +@need 1250 +Here is a bugged function definition for @code{triangle-recursively}. +@xref{Recursive triangle function, , Recursion in place of a counter}, +for a review of it. + +@smallexample +@group +(defun triangle-recursively-bugged (number) + "Return sum of numbers 1 through NUMBER inclusive. +Uses recursion." + (if (= number 1) + 1 + (+ number + (triangle-recursively-bugged + (1= number))))) ; @r{Error here.} +@end group +@end smallexample + +@noindent +Normally, you would install this definition by positioning your cursor +after the function's closing parenthesis and typing @kbd{C-x C-e} +(@code{eval-last-sexp}) or else by positioning your cursor within the +definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, +the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp +Interactive mode.) + +@need 1500 +However, to prepare this function definition for Edebug, you must +first @dfn{instrument} the code using a different command. You can do +this by positioning your cursor within or just after the definition +and typing + +@smallexample +M-x edebug-defun RET +@end smallexample + +@noindent +This will cause Emacs to load Edebug automatically if it is not +already loaded, and properly instrument the function. + +After instrumenting the function, place your cursor after the +following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): + +@smallexample +(triangle-recursively-bugged 3) +@end smallexample + +@noindent +You will be jumped back to the source for +@code{triangle-recursively-bugged} and the cursor positioned at the +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'.) + +@smallexample +=>@point{}(if (= number 1) +@end smallexample + +@noindent +@iftex +In the example, the location of point is displayed with a star, +@samp{@point{}} (in Info, it is displayed as @samp{-!-}). +@end iftex +@ifnottex +In the example, the location of point is displayed as @samp{@point{}} +(in a printed book, it is displayed with a five pointed star). +@end ifnottex + +If you now press @key{SPC}, point will move to the next expression to +be executed; the line will look like this: + +@smallexample +=>(if @point{}(= number 1) +@end smallexample + +@noindent +As you continue to press @key{SPC}, point will move from expression to +expression. At the same time, whenever an expression returns a value, +that value will be displayed in the echo area. For example, after you +move point past @code{number}, you will see the following: + +@smallexample +Result: 3 (#o3, #x3, ?\C-c) +@end smallexample + +@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 +alphabet, in case you need to know this information). + +You can continue moving through the code until you reach the line with +the error. Before evaluation, that line looks like this: + +@smallexample +=> @point{}(1= number))))) ; @r{Error here.} +@end smallexample + +@need 1250 +@noindent +When you press @key{SPC} once again, you will produce an error message +that says: + +@smallexample +Symbol's function definition is void:@: 1= +@end smallexample + +@noindent +This is the bug. + +Press @kbd{q} to quit Edebug. + +To remove instrumentation from a function definition, simply +re-evaluate it with a command that does not instrument it. +For example, you could place your cursor after the definition's +closing parenthesis and type @kbd{C-x C-e}. + +Edebug does a great deal more than walk with you through a function. +You can set it so it races through on its own, stopping only at an +error or at specified stopping points; you can cause it to display the +changing values of various expressions; you can find out how many +times a function is called, and more. + +Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs +Lisp Reference Manual}. + +@need 1500 +@node Debugging Exercises, , edebug, Debugging +@section Debugging Exercises + +@itemize @bullet +@item +Install the @code{count-words-region} 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 +the command finishes? (For information on hooks, see @ref{Command +Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference +Manual}.) + +@item +Copy @code{count-words-region} into the @file{*scratch*} buffer, +instrument the function for Edebug, and walk through its execution. +The function does not need to have a bug, although you can introduce +one if you wish. If the function lacks a bug, the walk-through +completes without problems. + +@item +While running Edebug, type @kbd{?} to see a list of all the Edebug commands. +(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: +@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix +for commands made outside of the Edebug debugging buffer.) + +@item +In the Edebug debugging buffer, use the @kbd{p} +(@code{edebug-bounce-point}) command to see where in the region the +@code{count-words-region} is working. + +@item +Move point to some spot further down the function and then type the +@kbd{h} (@code{edebug-goto-here}) command to jump to that location. + +@item +Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to +walk through the function on its own; use an upper case @kbd{T} for +@code{edebug-Trace-fast-mode}. + +@item +Set a breakpoint, then run Edebug in Trace mode until it reaches the +stopping point. +@end itemize + +@node Conclusion, the-the, Debugging, Top +@chapter Conclusion + +We have now reached the end of this Introduction. You have now +learned enough about programming in Emacs Lisp to set values, to write +simple @file{.emacs} files for yourself and your friends, and write +simple customizations and extensions to Emacs. + +This is a place to stop. Or, if you wish, you can now go onward, and +teach yourself. + +You have learned some of the basic nuts and bolts of programming. But +only some. There are a great many more brackets and hinges that are +easy to use that we have not touched. + +A path you can follow right now lies among the sources to GNU Emacs +and in +@ifnotinfo +@cite{The GNU Emacs Lisp Reference Manual}. +@end ifnotinfo +@ifinfo +@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU +Emacs Lisp Reference Manual}. +@end ifinfo + +The Emacs Lisp sources are an adventure. When you read the sources and +come across a function or expression that is unfamiliar, you need to +figure out or find out what it does. + +Go to the Reference Manual. It is a thorough, complete, and fairly +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.) + +Go to the other on-line help that is part of GNU Emacs: the on-line +documentation for all functions and variables, and @code{find-tags}, +the program that takes you to sources. + +Here is an example of how I explore the sources. Because of its name, +@file{simple.el} is the file I looked at first, a long time ago. As +it happens some of the functions in @file{simple.el} are complicated, +or at least look complicated at first sight. The @code{open-line} +function, for example, looks complicated. + +You may want to walk through this function slowly, as we did with the +@code{forward-sentence} function. (@xref{forward-sentence, The +@code{forward-sentence} function}.) Or you may want to skip that +function and look at another, such as @code{split-line}. You don't +need to read all the functions. According to +@code{count-words-in-defun}, the @code{split-line} function contains +102 words and symbols. + +Even though it is short, @code{split-line} contains expressions +we have not studied: @code{skip-chars-forward}, @code{indent-to}, +@code{current-column} and @code{insert-and-inherit}. + +Consider the @code{skip-chars-forward} function. (It is part of the +function definition for @code{back-to-indentation}, which is shown in +@ref{Review, , Review}.) + +In GNU Emacs, you can find out more about @code{skip-chars-forward} by +typing @kbd{C-h f} (@code{describe-function}) and the name of the +function. This gives you the function documentation. + +You may be able to guess what is done by a well named function such as +@code{indent-to}; or you can look it up, too. Incidentally, the +@code{describe-function} function itself is in @file{help.el}; it is +one of those long, but decipherable functions. You can look up +@code{describe-function} using the @kbd{C-h f} command! + +In this instance, since the code is Lisp, the @file{*Help*} buffer +contains the name of the library containing the function's source. +You can put point over the name of the library and press the RET key, +which in this situation is bound to @code{help-follow}, and be taken +directly to the source, in the same way as @kbd{M-.} +(@code{find-tag}). + +The definition for @code{describe-function} illustrates how to +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 +source as does @code{find-tag}, when properly set up.) + +You can look at a function's source using @code{find-tag}, which is +bound to @kbd{M-.} Finally, you can find out what the Reference +Manual has to say by visiting the manual in Info, and typing @kbd{i} +(@code{Info-index}) and the name of the function, or by looking up the +function in the index to a printed copy of the manual. + +Similarly, you can find out what is meant by +@code{insert-and-inherit}. + +Other interesting source files include @file{paragraphs.el}, +@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} +file includes short, easily understood functions as well as longer +ones. The @file{loaddefs.el} file contains the many standard +autoloads and many keymaps. I have never looked at it all; only at +parts. @file{loadup.el} is the file that loads the standard parts of +Emacs; it tells you a great deal about how Emacs is built. +(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp +Reference Manual}, for more about building.) + +As I said, you have learned some nuts and bolts; however, and very +importantly, we have hardly touched major aspects of programming; I +have said nothing about how to sort information, except to use the +predefined @code{sort} function; I have said nothing about how to store +information, except to use variables and lists; I have said nothing +about how to write programs that write programs. These are topics for +another, and different kind of book, a different kind of learning. + +What you have done is learn enough for much practical work with GNU +Emacs. What you have done is get started. This is the end of a +beginning. + +@c ================ Appendix ================ + +@node the-the, Kill Ring, Conclusion, Top +@appendix The @code{the-the} Function +@findex the-the +@cindex Duplicated words function +@cindex Words, duplicated + +Sometimes when you you write text, you duplicate words---as with ``you +you'' near the beginning of this sentence. I find that most +frequently, I duplicate ``the''; hence, I call the function for +detecting duplicated words, @code{the-the}. + +@need 1250 +As a first step, you could use the following regular expression to +search for duplicates: + +@smallexample +\\(\\w+[ \t\n]+\\)\\1 +@end smallexample + +@noindent +This regexp matches one or more word-constituent characters followed +by one or more spaces, tabs, or newlines. However, it does not detect +duplicated words on different lines, since the ending of the first +word, the end of the line, is different from the ending of the second +word, a space. (For more information about regular expressions, see +@ref{Regexp Search, , Regular Expression Searches}, as well as +@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs +Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, +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'. + +Another possible regexp searches for word-constituent characters +followed by non-word-constituent characters, reduplicated. Here, +@w{@samp{\\w+}} matches one or more word-constituent characters and +@w{@samp{\\W*}} matches zero or more non-word-constituent characters. + +@smallexample +\\(\\(\\w+\\)\\W*\\)\\1 +@end smallexample + +@noindent +Again, not useful. + +Here is the pattern that I use. It is not perfect, but good enough. +@w{@samp{\\b}} matches the empty string, provided it is at the beginning +or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of +any characters that are @emph{not} an @@-sign, space, newline, or tab. + +@smallexample +\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b +@end smallexample + +One can write more complicated expressions, but I found that this +expression is good enough, so I use it. + +Here is the @code{the-the} function, as I include it in my +@file{.emacs} file, along with a handy global key binding: + +@smallexample +@group +(defun the-the () + "Search forward for for a duplicated word." + (interactive) + (message "Searching for for duplicated words ...") + (push-mark) +@end group +@group + ;; This regexp is not perfect + ;; but is fairly good over all: + (if (re-search-forward + "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) + (message "Found duplicated word.") + (message "End of buffer"))) +@end group + +@group +;; Bind `the-the' to C-c \ +(global-set-key "\C-c\\" 'the-the) +@end group +@end smallexample + +@sp 1 +Here is test text: + +@smallexample +@group +one two two three four five +five six seven +@end group +@end smallexample + +You can substitute the other regular expressions shown above in the +function definition and try each of them on this list. + +@node Kill Ring, Full Graph, the-the, Top +@appendix Handling the Kill Ring +@cindex Kill ring handling +@cindex Handling the kill ring +@cindex Ring, making a list like a + +The kill ring is a list that is transformed into a ring by the +workings of the @code{current-kill} function. The @code{yank} and +@code{yank-pop} commands use the @code{current-kill} function. + +This appendix describes the @code{current-kill} function as well as +both the @code{yank} and the @code{yank-pop} commands, but first, +consider the workings of the kill ring. + +@menu +* What the Kill Ring Does:: +* current-kill:: +* yank:: Paste a copy of a clipped element. +* yank-pop:: Insert element pointed to. +* ring file:: +@end menu + +@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring +@ifnottex +@unnumberedsec What the Kill Ring Does +@end ifnottex + +@need 1250 +The kill ring has a default maximum length of sixty items; this number +is too large for an explanation. Instead, set it to four. Please +evaluate the following: + +@smallexample +@group +(setq old-kill-ring-max kill-ring-max) +(setq kill-ring-max 4) +@end group +@end smallexample + +@noindent +Then, please copy each line of the following indented example into the +kill ring. You may kill each line with @kbd{C-k} or mark it and copy +it with @kbd{M-w}. + +@noindent +(In a read-only buffer, such as the @file{*info*} buffer, the kill +command, @kbd{C-k} (@code{kill-line}), will not remove the text, +merely copy it to the kill ring. However, your machine may beep at +you. Alternatively, for silence, you may copy the region of each line +with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark +each line for this command to succeed, but it does not matter at which +end you put point or mark.) + +@need 1250 +@noindent +Please invoke the calls in order, so that five elements attempt to +fill the kill ring: + +@smallexample +@group +first some text +second piece of text +third line +fourth line of text +fifth bit of text +@end group +@end smallexample + +@need 1250 +@noindent +Then find the value of @code{kill-ring} by evaluating + +@smallexample +kill-ring +@end smallexample + +@need 800 +@noindent +It is: + +@smallexample +@group +("fifth bit of text" "fourth line of text" +"third line" "second piece of text") +@end group +@end smallexample + +@noindent +The first element, @samp{first some text}, was dropped. + +@need 1250 +To return to the old value for the length of the kill ring, evaluate: + +@smallexample +(setq kill-ring-max old-kill-ring-max) +@end smallexample + +@node current-kill, yank, What the Kill Ring Does, Kill Ring +@comment node-name, next, previous, up +@appendixsec The @code{current-kill} Function +@findex current-kill + +The @code{current-kill} function changes the element in the kill ring +to which @code{kill-ring-yank-pointer} points. (Also, the +@code{kill-new} function sets @code{kill-ring-yank-pointer} to point +to the latest element of the the kill ring. The @code{kill-new} +function is used directly or indirectly by @code{kill-append}, +@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, +and @code{kill-region}.) + +@menu +* Code for current-kill:: +* Understanding current-kill:: +@end menu + +@node Code for current-kill, Understanding current-kill, current-kill, current-kill +@ifnottex +@unnumberedsubsec The code for @code{current-kill} +@end ifnottex + + +@need 1500 +The @code{current-kill} function is used by @code{yank} and by +@code{yank-pop}. Here is the code for @code{current-kill}: + +@smallexample +@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. +@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)))) +@end group +@group + (if interprogram-paste + (progn + ;; Disable the interprogram cut function when we add the new + ;; 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) +@end group +@group + (or kill-ring (error "Kill ring is empty")) + (let ((ARGth-kill-element + (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)) + (car ARGth-kill-element))))) +@end group +@end smallexample + +Remember also that the @code{kill-new} function sets +@code{kill-ring-yank-pointer} to the latest element of the the kill +ring, which means that all the functions that call it set the value +indirectly: @code{kill-append}, @code{copy-region-as-kill}, +@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. + +@need 1500 +Here is the line in @code{kill-new}, which is explained in +@ref{kill-new function, , The @code{kill-new} function}. + +@smallexample +(setq kill-ring-yank-pointer kill-ring) +@end smallexample + +@node Understanding current-kill, , Code for current-kill, current-kill +@ifnottex +@unnumberedsubsec @code{current-kill} in Outline +@end ifnottex + +The @code{current-kill} function looks complex, but as usual, it can +be understood by taking it apart piece by piece. First look at it in +skeletal form: + +@smallexample +@group +(defun current-kill (n &optional do-not-move) + "Rotate the yanking point by N places, and then return that kill." + (let @var{varlist} + @var{body}@dots{}) +@end group +@end smallexample + +This function takes two arguments, one of which is optional. It has a +documentation string. It is @emph{not} interactive. + +@menu +* Body of current-kill:: +* Digression concerning error:: How to mislead humans, but not computers. +* Determining the Element:: +@end menu + +@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill +@ifnottex +@unnumberedsubsubsec The Body of @code{current-kill} +@end ifnottex + +The body of the function definition is a @code{let} expression, which +itself has a body as well as a @var{varlist}. + +The @code{let} expression declares a variable that will be only usable +within the bounds of this function. This variable is called +@code{interprogram-paste} and is for copying to another program. It +is not for copying within this instance of GNU Emacs. Most window +systems provide a facility for interprogram pasting. Sadly, that +facility usually provides only for the last element. Most windowing +systems have not adopted a ring of many possibilities, even though +Emacs has provided it for decades. + +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} +function. (The then-part uses the the @code{kill-new} function, which +we have already described. @xref{kill-new function, , The +@code{kill-new} function}.) + +@smallexample +@group +(or kill-ring (error "Kill ring is empty")) +(let ((ARGth-kill-element + (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)) + (car ARGth-kill-element)) +@end group +@end smallexample + +@noindent +The code first checks whether the kill ring has content; otherwise it +signals an error. + +@need 1000 +Note that the @code{or} expression is very similar to testing length +with an @code{if}: + +@findex zerop +@findex error +@smallexample +@group +(if (zerop (length kill-ring)) ; @r{if-part} + (error "Kill ring is empty")) ; @r{then-part} + ;; No else-part +@end group +@end smallexample + +@noindent +If there is not anything in the kill ring, its length must be zero and +an error message sent to the user: @samp{Kill ring is empty}. The +@code{current-kill} function uses an @code{or} expression which is +simpler. But an @code{if} expression reminds us what goes on. + +This @code{if} expression uses the function @code{zerop} which returns +true if the value it is testing is zero. When @code{zerop} tests +true, the then-part of the @code{if} is evaluated. The then-part is a +list starting with the function @code{error}, which is a function that +is similar to the @code{message} function +(@pxref{message, , The @code{message} Function}) in that +it prints a one-line message in the echo area. However, in addition +to printing a message, @code{error} also stops evaluation of the +function within which it is embedded. This means that the rest of the +function will not be evaluated if the length of the kill ring is zero. + +Then the @code{current-kill} function selects the element to return. +The selection depends on the number of places that @code{current-kill} +rotates and on where @code{kill-ring-yank-pointer} points. + +Next, either the optional @code{do-not-move} argument is true or the +current value of @code{kill-ring-yank-pointer} is set to point to the +list. Finally, another expression returns the first element of the +list even if the @code{do-not-move} argument is true. + +@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill +@ifnottex +@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 +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. +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. + +From the human point of view, the act of exploration and discovery is +not necessarily an error, and therefore should not be labelled 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. + +@node Determining the Element, , Digression concerning error, Understanding current-kill +@ifnottex +@unnumberedsubsubsec Determining the Element +@end ifnottex + +Among other actions, the else-part of the @code{if} expression sets +the value of @code{kill-ring-yank-pointer} to +@code{ARGth-kill-element} when the kill ring has something in it and +the value of @code{do-not-move} is @code{nil}. + +@need 800 +The code looks like this: + +@smallexample +@group +(nthcdr (mod (- n (length kill-ring-yank-pointer)) + (length kill-ring)) + kill-ring))) +@end group +@end smallexample + +This needs some examination. Unless it is not supposed to move the +pointer, the @code{current-kill} function changes where +@code{kill-ring-yank-pointer} points. +That is what the +@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} +expression does. Also, clearly, @code{ARGth-kill-element} is being +set to be equal to some @sc{cdr} of the kill ring, using the +@code{nthcdr} function that is described in an earlier section. +(@xref{copy-region-as-kill}.) How does it do this? + +As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function +works by repeatedly taking the @sc{cdr} of a list---it takes the +@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} + +@need 800 +The two following expressions produce the same result: + +@smallexample +@group +(setq kill-ring-yank-pointer (cdr kill-ring)) + +(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) +@end group +@end smallexample + +However, the @code{nthcdr} expression is more complicated. It uses +the @code{mod} function to determine which @sc{cdr} to select. + +(You will remember to look at inner functions first; indeed, we will +have to go inside the @code{mod}.) + +The @code{mod} function returns the value of its first argument modulo +the second; that is to say, it returns the remainder after dividing +the first argument by the second. The value returned has the same +sign as the second argument. + +@need 800 +Thus, + +@smallexample +@group +(mod 12 4) + @result{} 0 ;; @r{because there is no remainder} +(mod 13 4) + @result{} 1 +@end group +@end smallexample + +@need 1250 +In this case, the first argument is often smaller than the second. +That is fine. + +@smallexample +@group +(mod 0 4) + @result{} 0 +(mod 1 4) + @result{} 1 +@end group +@end smallexample + +We can guess what the @code{-} function does. It is like @code{+} but +subtracts instead of adds; the @code{-} function subtracts its second +argument from its first. Also, we already know what the @code{length} +function does (@pxref{length}). It returns the length of a list. + +And @code{n} is the name of the required argument to the +@code{current-kill} function. + +@need 1250 +So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} +expression returns the whole list, as you can see by evaluating the +following: + +@smallexample +@group +;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} +;; @r{and} (mod (- 0 4) 4) @result{} 0 +(nthcdr (mod (- 0 4) 4) + '("fourth line of text" + "third line" + "second piece of text" + "first some text")) +@end group +@end smallexample + +@need 1250 +When the first argument to the @code{current-kill} function is one, +the @code{nthcdr} expression returns the list without its first +element. + +@smallexample +@group +(nthcdr (mod (- 1 4) 4) + '("fourth line of text" + "third line" + "second piece of text" + "first some text")) +@end group +@end smallexample + +@cindex @samp{global variable} defined +@cindex @samp{variable, global}, defined +Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} +are @dfn{global variables}. That means that any expression in Emacs +Lisp can access them. They are not like the local variables set by +@code{let} or like the symbols in an argument list. +Local variables can only be accessed +within the @code{let} that defines them or the function that specifies +them in an argument list (and within expressions called by them). + +@ignore +@c texi2dvi fails when the name of the section is within ifnottex ... +(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and +@ref{defun, , The @code{defun} Special Form}.) +@end ignore + +@node yank, yank-pop, current-kill, Kill Ring +@comment node-name, next, previous, up +@appendixsec @code{yank} +@findex yank + +After learning about @code{current-kill}, the code for the +@code{yank} function is almost easy. + +The @code{yank} function does not use the +@code{kill-ring-yank-pointer} variable directly. It calls +@code{insert-for-yank} which calls @code{current-kill} which sets the +@code{kill-ring-yank-pointer} variable. + +@need 1250 +The code looks like this: + +@c in GNU Emacs 22 +@smallexample +@group +(defun yank (&optional arg) + "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. + +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]." +@end group +@group + (interactive "*P") + (setq yank-window-start (window-start)) + ;; If we don't get all the way thru, make last-command indicate that + ;; for the following command. + (setq this-command t) + (push-mark (point)) +@end group +@group + (insert-for-yank (current-kill (cond + ((listp arg) 0) + ((eq arg '-) -2) + (t (1- arg))))) + (if (consp arg) + ;; 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) + (set-marker (mark-marker) (point) (current-buffer))))) +@end group +@group + ;; If we do get all the way thru, make this-command indicate that. + (if (eq this-command t) + (setq this-command 'yank)) + nil) +@end group +@end smallexample + +The key expression is @code{insert-for-yank}, which inserts the string +returned by @code{current-kill}, but removes some text properties from +it. + +However, before getting to that expression, the function sets the value +of @code{yank-window-start} to the position returned by the +@code{(window-start)} expression, the position at which the display +currently starts. The @code{yank} function also sets +@code{this-command} and pushes the mark. + +After it yanks the appropriate element, if the optional argument is a +@sc{cons} rather than a number or nothing, it puts point at beginning +of the yanked text and mark at its end. + +(The @code{prog1} function is like @code{progn} but returns the value +of its first argument rather than the value of its last argument. Its +first argument is forced to return the buffer's mark as an integer. +You can see the documentation for these functions by placing point +over them in this buffer and then typing @kbd{C-h f} +(@code{describe-function}) followed by a @kbd{RET}; the default is the +function.) + +The last part of the function tells what to do when it succeeds. + +@node yank-pop, ring file, yank, Kill Ring +@comment node-name, next, previous, up +@appendixsec @code{yank-pop} +@findex yank-pop + +After understanding @code{yank} and @code{current-kill}, you know how +to approach the @code{yank-pop} function. Leaving out the +documentation to save space, it looks like this: + +@c GNU Emacs 22 +@smallexample +@group +(defun yank-pop (&optional arg) + "@dots{}" + (interactive "*p") + (if (not (eq last-command 'yank)) + (error "Previous command was not a yank")) +@end group +@group + (setq this-command 'yank) + (unless arg (setq arg 1)) + (let ((inhibit-read-only t) + (before (< (point) (mark t)))) +@end group +@group + (if before + (funcall (or yank-undo-function 'delete-region) (point) (mark t)) + (funcall (or yank-undo-function 'delete-region) (mark t) (point))) + (setq yank-undo-function nil) +@end group +@group + (set-marker (mark-marker) (point) (current-buffer)) + (insert-for-yank (current-kill arg)) + ;; Set the window start back where it was in the yank command, + ;; if possible. + (set-window-start (selected-window) yank-window-start t) +@end group +@group + (if before + ;; 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) + (set-marker (mark-marker) + (point) + (current-buffer)))))) + nil) +@end group +@end smallexample + +The function is interactive with a small @samp{p} so the prefix +argument is processed and passed to the function. The command can +only be used after a previous yank; otherwise an error message is +sent. This check uses the variable @code{last-command} which is set +by @code{yank} and is discussed elsewhere. +(@xref{copy-region-as-kill}.) + +The @code{let} clause sets the variable @code{before} to true or false +depending whether point is before or after mark and then the region +between point and mark is deleted. This is the region that was just +inserted by the previous yank and it is this text that will be +replaced. + +@code{funcall} calls its first argument as a function, passing +remaining arguments to it. The first argument is whatever the +@code{or} expression returns. The two remaining arguments are the +positions of point and mark set by the preceding @code{yank} command. + +There is more, but that is the hardest part. + +@node ring file, , yank-pop, Kill Ring +@comment node-name, next, previous, up +@appendixsec The @file{ring.el} File +@cindex @file{ring.el} file + +Interestingly, GNU Emacs posses a file called @file{ring.el} that +provides many of the features we just discussed. But functions such +as @code{kill-ring-yank-pointer} do not use this library, possibly +because they were written earlier. + +@node Full Graph, Free Software and Free Manuals, Kill Ring, Top +@appendix A Graph with Labelled Axes + +Printed axes help you understand a graph. They convey scale. In an +earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we +wrote the code to print the body of a graph. Here we write the code +for printing and labelling vertical and horizontal axes, along with the +body itself. + +@menu +* Labelled Example:: +* print-graph Varlist:: @code{let} expression in @code{print-graph}. +* print-Y-axis:: Print a label for the vertical axis. +* print-X-axis:: Print a horizontal label. +* Print Whole Graph:: The function to print a complete graph. +@end menu + +@node Labelled Example, print-graph Varlist, Full Graph, Full Graph +@ifnottex +@unnumberedsec Labelled Example Graph +@end ifnottex + +Since insertions fill a buffer to the right and below point, the new +graph printing function should first print the Y or vertical axis, +then the body of the graph, and finally the X or horizontal axis. +This sequence lays out for us the contents of the function: + +@enumerate +@item +Set up code. + +@item +Print Y axis. + +@item +Print body of graph. + +@item +Print X axis. +@end enumerate + +@need 800 +Here is an example of how a finished graph should look: + +@smallexample +@group + 10 - + * + * * + * ** + * *** + 5 - * ******* + * *** ******* + ************* + *************** + 1 - **************** + | | | | + 1 5 10 15 +@end group +@end smallexample + +@noindent +In this graph, both the vertical and the horizontal axes are labelled +with numbers. However, in some graphs, the horizontal axis is time +and would be better labelled with months, like this: + +@smallexample +@group + 5 - * + * ** * + ******* + ********** ** + 1 - ************** + | ^ | + Jan June Jan +@end group +@end smallexample + +Indeed, with a little thought, we can easily come up with a variety of +vertical and horizontal labelling schemes. Our task could become +complicated. But complications breed confusion. Rather than permit +this, it is better choose a simple labelling scheme for our first +effort, and to modify or replace it later. + +@need 1200 +These considerations suggest the following outline for the +@code{print-graph} function: + +@smallexample +@group +(defun print-graph (numbers-list) + "@var{documentation}@dots{}" + (let ((height @dots{} + @dots{})) +@end group +@group + (print-Y-axis height @dots{} ) + (graph-body-print numbers-list) + (print-X-axis @dots{} ))) +@end group +@end smallexample + +We can work on each part of the @code{print-graph} function definition +in turn. + +@node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph +@comment node-name, next, previous, up +@appendixsec The @code{print-graph} Varlist +@cindex @code{print-graph} varlist + +In writing the @code{print-graph} function, the first task is to write +the varlist in the @code{let} expression. (We will leave aside for the +moment any thoughts about making the function interactive or about the +contents of its documentation string.) + +The varlist should set several values. Clearly, the top of the label +for the vertical axis must be at least the height of the graph, which +means that we must obtain this information here. Note that the +@code{print-graph-body} function also requires this information. There +is no reason to calculate the height of the graph in two different +places, so we should change @code{print-graph-body} from the way we +defined it earlier to take advantage of the calculation. + +Similarly, both the function for printing the X axis labels and the +@code{print-graph-body} function need to learn the value of the width of +each symbol. We can perform the calculation here and change the +definition for @code{print-graph-body} from the way we defined it in the +previous chapter. + +The length of the label for the horizontal axis must be at least as long +as the graph. However, this information is used only in the function +that prints the horizontal axis, so it does not need to be calculated here. + +These thoughts lead us directly to the following form for the varlist +in the @code{let} for @code{print-graph}: + +@smallexample +@group +(let ((height (apply 'max numbers-list)) ; @r{First version.} + (symbol-width (length graph-blank))) +@end group +@end smallexample + +@noindent +As we shall see, this expression is not quite right. + +@need 2000 +@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph +@comment node-name, next, previous, up +@appendixsec The @code{print-Y-axis} Function +@cindex Axis, print vertical +@cindex Y axis printing +@cindex Vertical axis printing +@cindex Print vertical axis + +The job of the @code{print-Y-axis} function is to print a label for +the vertical axis that looks like this: + +@smallexample +@group + 10 - + + + + + 5 - + + + + 1 - +@end group +@end smallexample + +@noindent +The function should be passed the height of the graph, and then should +construct and insert the appropriate numbers and marks. + +@menu +* print-Y-axis in Detail:: +* Height of label:: What height for the Y axis? +* Compute a Remainder:: How to compute the remainder of a division. +* Y Axis Element:: Construct a line for the Y axis. +* Y-axis-column:: Generate a list of Y axis labels. +* print-Y-axis Penultimate:: A not quite final version. +@end menu + +@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis +@ifnottex +@unnumberedsubsec The @code{print-Y-axis} Function in Detail +@end ifnottex + +It is easy enough to see in the figure what the Y axis label should +look like; but to say in words, and then to write a function +definition to do the job is another matter. It is not quite true to +say that we want a number and a tic every five lines: there are only +three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), +but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, +and 9). It is better to say that we want a number and a tic mark on +the base line (number 1) and then that we want a number and a tic on +the fifth line from the bottom and on every line that is a multiple of +five. + +@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis +@ifnottex +@unnumberedsubsec What height should the label be? +@end ifnottex + +The next issue is what height the label should be? Suppose the maximum +height of tallest column of the graph is seven. Should the highest +label on the Y axis be @samp{5 -}, and should the graph stick up above +the label? Or should the highest label be @samp{7 -}, and mark the peak +of the graph? Or should the highest label be @code{10 -}, which is a +multiple of five, and be higher than the topmost value of the graph? + +The latter form is preferred. Most graphs are drawn within rectangles +whose sides are an integral number of steps long---5, 10, 15, and so +on for a step distance of five. But as soon as we decide to use a +step height for the vertical axis, we discover that the simple +expression in the varlist for computing the height is wrong. The +expression is @code{(apply 'max numbers-list)}. This returns the +precise height, not the maximum height plus whatever is necessary to +round up to the nearest multiple of five. A more complex expression +is required. + +As usual in cases like this, a complex problem becomes simpler if it is +divided into several smaller problems. + +First, consider the case when the highest value of the graph is an +integral multiple of five---when it is 5, 10, 15, or some higher +multiple of five. We can use this value as the Y axis height. + +A fairly simply way to determine whether a number is a multiple of +five is to divide it by five and see if the division results in a +remainder. If there is no remainder, the number is a multiple of +five. Thus, seven divided by five has a remainder of two, and seven +is not an integral multiple of five. Put in slightly different +language, more reminiscent of the classroom, five goes into seven +once, with a remainder of two. However, five goes into ten twice, +with no remainder: ten is an integral multiple of five. + +@node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis +@appendixsubsec Side Trip: Compute a Remainder + +@findex % @r{(remainder function)} +@cindex Remainder function, @code{%} +In Lisp, the function for computing a remainder is @code{%}. The +function returns the remainder of its first argument divided by its +second argument. As it happens, @code{%} is a function in Emacs Lisp +that you cannot discover using @code{apropos}: you find nothing if you +type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to +learn of the existence of @code{%} is to read about it in a book such +as this or in the Emacs Lisp sources. + +You can try the @code{%} function by evaluating the following two +expressions: + +@smallexample +@group +(% 7 5) + +(% 10 5) +@end group +@end smallexample + +@noindent +The first expression returns 2 and the second expression returns 0. + +To test whether the returned value is zero or some other number, we +can use the @code{zerop} function. This function returns @code{t} if +its argument, which must be a number, is zero. + +@smallexample +@group +(zerop (% 7 5)) + @result{} nil + +(zerop (% 10 5)) + @result{} t +@end group +@end smallexample + +Thus, the following expression will return @code{t} if the height +of the graph is evenly divisible by five: + +@smallexample +(zerop (% height 5)) +@end smallexample + +@noindent +(The value of @code{height}, of course, can be found from @code{(apply +'max numbers-list)}.) + +On the other hand, if the value of @code{height} is not a multiple of +five, we want to reset the value to the next higher multiple of five. +This is straightforward arithmetic using functions with which we are +already familiar. First, we divide the value of @code{height} by five +to determine how many times five goes into the number. Thus, five +goes into twelve twice. If we add one to this quotient and multiply by +five, we will obtain the value of the next multiple of five that is +larger than the height. Five goes into twelve twice. Add one to two, +and multiply by five; the result is fifteen, which is the next multiple +of five that is higher than twelve. The Lisp expression for this is: + +@smallexample +(* (1+ (/ height 5)) 5) +@end smallexample + +@noindent +For example, if you evaluate the following, the result is 15: + +@smallexample +(* (1+ (/ 12 5)) 5) +@end smallexample + +All through this discussion, we have been using `five' 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 +which we can assign a value. The best name I can think of for this +variable is @code{Y-axis-label-spacing}. + +@need 1250 +Using this term, and an @code{if} expression, we produce the +following: + +@smallexample +@group +(if (zerop (% height Y-axis-label-spacing)) + height + ;; @r{else} + (* (1+ (/ height Y-axis-label-spacing)) + Y-axis-label-spacing)) +@end group +@end smallexample + +@noindent +This expression returns the value of @code{height} itself if the height +is an even multiple of the value of the @code{Y-axis-label-spacing} or +else it computes and returns a value of @code{height} that is equal to +the next higher multiple of the value of the @code{Y-axis-label-spacing}. + +We can now include this expression in the @code{let} expression of the +@code{print-graph} function (after first setting the value of +@code{Y-axis-label-spacing}): +@vindex Y-axis-label-spacing + +@smallexample +@group +(defvar Y-axis-label-spacing 5 + "Number of lines from one Y axis label to next.") +@end group + +@group +@dots{} +(let* ((height (apply 'max numbers-list)) + (height-of-top-line + (if (zerop (% height Y-axis-label-spacing)) + height +@end group +@group + ;; @r{else} + (* (1+ (/ height Y-axis-label-spacing)) + Y-axis-label-spacing))) + (symbol-width (length graph-blank)))) +@dots{} +@end group +@end smallexample + +@noindent +(Note use of the @code{let*} function: the initial value of height is +computed once by the @code{(apply 'max numbers-list)} expression and +then the resulting value of @code{height} is used to compute its +final value. @xref{fwd-para let, , The @code{let*} expression}, for +more about @code{let*}.) + +@node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis +@appendixsubsec Construct a Y Axis Element + +When we print the vertical axis, we want to insert strings such as +@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. +Moreover, we want the numbers and dashes to line up, so shorter +numbers must be padded with leading spaces. If some of the strings +use two digit numbers, the strings with single digit numbers must +include a leading blank space before the number. + +@findex number-to-string +To figure out the length of the number, the @code{length} function is +used. But the @code{length} function works only with a string, not with +a number. So the number has to be converted from being a number to +being a string. This is done with the @code{number-to-string} function. +For example, + +@smallexample +@group +(length (number-to-string 35)) + @result{} 2 + +(length (number-to-string 100)) + @result{} 3 +@end group +@end smallexample + +@noindent +(@code{number-to-string} is also called @code{int-to-string}; you will +see this alternative name in various sources.) + +In addition, in each label, each number is followed by a string such +as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. +This variable is defined with @code{defvar}: + +@vindex Y-axis-tic +@smallexample +@group +(defvar Y-axis-tic " - " + "String that follows number in a Y axis label.") +@end group +@end smallexample + +The length of the Y label is the sum of the length of the Y axis tic +mark and the length of the number of the top of the graph. + +@smallexample +(length (concat (number-to-string height) Y-axis-tic))) +@end smallexample + +This value will be calculated by the @code{print-graph} function in +its varlist as @code{full-Y-label-width} and passed on. (Note that we +did not think to include this in the varlist when we first proposed it.) + +To make a complete vertical axis label, a tic mark is concatenated +with a number; and the two together may be preceded by one or more +spaces depending on how long the number is. The label consists of +three parts: the (optional) leading spaces, the number, and the tic +mark. The function is passed the value of the number for the specific +row, and the value of the width of the top line, which is calculated +(just once) by @code{print-graph}. + +@smallexample +@group +(defun Y-axis-element (number full-Y-label-width) + "Construct a NUMBERed label element. +A numbered element looks like this ` 5 - ', +and is padded as needed so all line up with +the element for the largest number." +@end group +@group + (let* ((leading-spaces + (- full-Y-label-width + (length + (concat (number-to-string number) + Y-axis-tic))))) +@end group +@group + (concat + (make-string leading-spaces ? ) + (number-to-string number) + Y-axis-tic))) +@end group +@end smallexample + +The @code{Y-axis-element} function concatenates together the leading +spaces, if any; the number, as a string; and the tic mark. + +To figure out how many leading spaces the label will need, the +function subtracts the actual length of the label---the length of the +number plus the length of the tic mark---from the desired label width. + +@findex make-string +Blank spaces are inserted using the @code{make-string} function. This +function takes two arguments: the first tells it how long the string +will be and the second is a symbol for the character to insert, in a +special format. The format is a question mark followed by a blank +space, like this, @samp{? }. @xref{Character Type, , Character Type, +elisp, The GNU Emacs Lisp Reference Manual}, for a description of the +syntax for characters. (Of course, you might want to replace the +blank space by some other character @dots{} You know what to do.) + +The @code{number-to-string} function is used in the concatenation +expression, to convert the number to a string that is concatenated +with the leading spaces and the tic mark. + +@node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis +@appendixsubsec Create a Y Axis Column + +The preceding functions provide all the tools needed to construct a +function that generates a list of numbered and blank strings to insert +as the label for the vertical axis: + +@findex Y-axis-column +@smallexample +@group +(defun Y-axis-column (height width-of-label) + "Construct list of Y axis labels and blank strings. +For HEIGHT of line above base and WIDTH-OF-LABEL." + (let (Y-axis) +@group +@end group + (while (> height 1) + (if (zerop (% height Y-axis-label-spacing)) + ;; @r{Insert label.} + (setq Y-axis + (cons + (Y-axis-element height width-of-label) + Y-axis)) +@group +@end group + ;; @r{Else, insert blanks.} + (setq Y-axis + (cons + (make-string width-of-label ? ) + Y-axis))) + (setq height (1- height))) + ;; @r{Insert base line.} + (setq Y-axis + (cons (Y-axis-element 1 width-of-label) Y-axis)) + (nreverse Y-axis))) +@end group +@end smallexample + +In this function, we start with the value of @code{height} and +repetitively subtract one from its value. After each subtraction, we +test to see whether the value is an integral multiple of the +@code{Y-axis-label-spacing}. If it is, we construct a numbered label +using the @code{Y-axis-element} function; if not, we construct a +blank label using the @code{make-string} function. The base line +consists of the number one followed by a tic mark. + +@need 2000 +@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis +@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} + +The list constructed by the @code{Y-axis-column} function is passed to +the @code{print-Y-axis} function, which inserts the list as a column. + +@findex print-Y-axis +@smallexample +@group +(defun print-Y-axis (height full-Y-label-width) + "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. +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'. +@end group +@group + (let ((start (point))) + (insert-rectangle + (Y-axis-column height full-Y-label-width)) + ;; @r{Place point ready for inserting graph.} + (goto-char start) + ;; @r{Move point forward by value of} full-Y-label-width + (forward-char full-Y-label-width))) +@end group +@end smallexample + +The @code{print-Y-axis} uses the @code{insert-rectangle} function to +insert the Y axis labels created by the @code{Y-axis-column} function. +In addition, it places point at the correct position for printing the body of +the graph. + +You can test @code{print-Y-axis}: + +@enumerate +@item +Install + +@smallexample +@group +Y-axis-label-spacing +Y-axis-tic +Y-axis-element +Y-axis-column +print-Y-axis +@end group +@end smallexample + +@item +Copy the following expression: + +@smallexample +(print-Y-axis 12 5) +@end smallexample + +@item +Switch to the @file{*scratch*} buffer and place the cursor where you +want the axis labels to start. + +@item +Type @kbd{M-:} (@code{eval-expression}). + +@item +Yank the @code{graph-body-print} expression into the minibuffer +with @kbd{C-y} (@code{yank)}. + +@item +Press @key{RET} to evaluate the expression. +@end enumerate + +Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ +}}}. (The @code{print-graph} function will pass the value of +@code{height-of-top-line}, which in this case will end up as 15, +thereby getting rid of what might appear as a bug.) + +@need 2000 +@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph +@appendixsec The @code{print-X-axis} Function +@cindex Axis, print horizontal +@cindex X axis printing +@cindex Print horizontal axis +@cindex Horizontal axis printing + +X axis labels are much like Y axis labels, except that the ticks are on a +line above the numbers. Labels should look like this: + +@smallexample +@group + | | | | + 1 5 10 15 +@end group +@end smallexample + +The first tic is under the first column of the graph and is preceded by +several blank spaces. These spaces provide room in rows above for the Y +axis labels. The second, third, fourth, and subsequent ticks are all +spaced equally, according to the value of @code{X-axis-label-spacing}. + +The second row of the X axis consists of numbers, preceded by several +blank spaces and also separated according to the value of the variable +@code{X-axis-label-spacing}. + +The value of the variable @code{X-axis-label-spacing} should itself be +measured in units of @code{symbol-width}, since you may want to change +the width of the symbols that you are using to print the body of the +graph without changing the ways the graph is labelled. + +@menu +* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. +* X Axis Tic Marks:: Create tic marks for the horizontal axis. +@end menu + +@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis +@ifnottex +@unnumberedsubsec Similarities and differences +@end ifnottex + +The @code{print-X-axis} function is constructed in more or less the +same fashion as the @code{print-Y-axis} function except that it has +two lines: the line of tic marks and the numbers. We will write a +separate function to print each line and then combine them within the +@code{print-X-axis} function. + +This is a three step process: + +@enumerate +@item +Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. + +@item +Write a function to print the X numbers, @code{print-X-axis-numbered-line}. + +@item +Write a function to print both lines, the @code{print-X-axis} function, +using @code{print-X-axis-tic-line} and +@code{print-X-axis-numbered-line}. +@end enumerate + +@node X Axis Tic Marks, , Similarities differences, print-X-axis +@appendixsubsec X Axis Tic Marks + +The first function should print the X axis tic marks. We must specify +the tic marks themselves and their spacing: + +@smallexample +@group +(defvar X-axis-label-spacing + (if (boundp 'graph-blank) + (* 5 (length graph-blank)) 5) + "Number of units from one X axis label to next.") +@end group +@end smallexample + +@noindent +(Note that the value of @code{graph-blank} is set by another +@code{defvar}. The @code{boundp} predicate checks whether it has +already been set; @code{boundp} returns @code{nil} if it has not. If +@code{graph-blank} were unbound and we did not use this conditional +construction, in a recent GNU Emacs, we would enter the debugger and +see an error message saying @samp{@w{Debugger entered--Lisp error:} +@w{(void-variable graph-blank)}}.) + +@need 1200 +Here is the @code{defvar} for @code{X-axis-tic-symbol}: + +@smallexample +@group +(defvar X-axis-tic-symbol "|" + "String to insert to point to a column in X axis.") +@end group +@end smallexample + +@need 1250 +The goal is to make a line that looks like this: + +@smallexample + | | | | +@end smallexample + +The first tic is indented so that it is under the first column, which is +indented to provide space for the Y axis labels. + +A tic element consists of the blank spaces that stretch from one tic to +the next plus a tic symbol. The number of blanks is determined by the +width of the tic symbol and the @code{X-axis-label-spacing}. + +@need 1250 +The code looks like this: + +@smallexample +@group +;;; X-axis-tic-element +@dots{} +(concat + (make-string + ;; @r{Make a string of blanks.} + (- (* symbol-width X-axis-label-spacing) + (length X-axis-tic-symbol)) + ? ) + ;; @r{Concatenate blanks with tic symbol.} + X-axis-tic-symbol) +@dots{} +@end group +@end smallexample + +Next, we determine how many blanks are needed to indent the first tic +mark to the first column of the graph. This uses the value of +@code{full-Y-label-width} passed it by the @code{print-graph} function. + +@need 1250 +The code to make @code{X-axis-leading-spaces} +looks like this: + +@smallexample +@group +;; X-axis-leading-spaces +@dots{} +(make-string full-Y-label-width ? ) +@dots{} +@end group +@end smallexample + +We also need to determine the length of the horizontal axis, which is +the length of the numbers list, and the number of ticks in the horizontal +axis: + +@smallexample +@group +;; X-length +@dots{} +(length numbers-list) +@end group + +@group +;; tic-width +@dots{} +(* symbol-width X-axis-label-spacing) +@end group + +@group +;; number-of-X-ticks +(if (zerop (% (X-length tic-width))) + (/ (X-length tic-width)) + (1+ (/ (X-length tic-width)))) +@end group +@end smallexample + +@need 1250 +All this leads us directly to the function for printing the X axis tic line: + +@findex print-X-axis-tic-line +@smallexample +@group +(defun print-X-axis-tic-line + (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) + "Print ticks for X axis." + (insert X-axis-leading-spaces) + (insert X-axis-tic-symbol) ; @r{Under first column.} +@end group +@group + ;; @r{Insert second tic in the right spot.} + (insert (concat + (make-string + (- (* symbol-width X-axis-label-spacing) + ;; @r{Insert white space up to second tic symbol.} + (* 2 (length X-axis-tic-symbol))) + ? ) + X-axis-tic-symbol)) +@end group +@group + ;; @r{Insert remaining ticks.} + (while (> number-of-X-tics 1) + (insert X-axis-tic-element) + (setq number-of-X-tics (1- number-of-X-tics)))) +@end group +@end smallexample + +The line of numbers is equally straightforward: + +@need 1250 +First, we create a numbered element with blank spaces before each number: + +@findex X-axis-element +@smallexample +@group +(defun X-axis-element (number) + "Construct a numbered X axis element." + (let ((leading-spaces + (- (* symbol-width X-axis-label-spacing) + (length (number-to-string number))))) + (concat (make-string leading-spaces ? ) + (number-to-string number)))) +@end group +@end smallexample + +Next, we create the function to print the numbered line, starting with +the number ``1'' under the first column: + +@findex print-X-axis-numbered-line +@smallexample +@group +(defun print-X-axis-numbered-line + (number-of-X-tics X-axis-leading-spaces) + "Print line of X-axis numbers" + (let ((number X-axis-label-spacing)) + (insert X-axis-leading-spaces) + (insert "1") +@end group +@group + (insert (concat + (make-string + ;; @r{Insert white space up to next number.} + (- (* symbol-width X-axis-label-spacing) 2) + ? ) + (number-to-string number))) +@end group +@group + ;; @r{Insert remaining numbers.} + (setq number (+ number X-axis-label-spacing)) + (while (> number-of-X-tics 1) + (insert (X-axis-element number)) + (setq number (+ number X-axis-label-spacing)) + (setq number-of-X-tics (1- number-of-X-tics))))) +@end group +@end smallexample + +Finally, we need to write the @code{print-X-axis} that uses +@code{print-X-axis-tic-line} and +@code{print-X-axis-numbered-line}. + +The function must determine the local values of the variables used by both +@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and +then it must call them. Also, it must print the carriage return that +separates the two lines. + +The function consists of a varlist that specifies five local variables, +and calls to each of the two line printing functions: + +@findex print-X-axis +@smallexample +@group +(defun print-X-axis (numbers-list) + "Print X axis labels to length of NUMBERS-LIST." + (let* ((leading-spaces + (make-string full-Y-label-width ? )) +@end group +@group + ;; symbol-width @r{is provided by} graph-body-print + (tic-width (* symbol-width X-axis-label-spacing)) + (X-length (length numbers-list)) +@end group +@group + (X-tic + (concat + (make-string +@end group +@group + ;; @r{Make a string of blanks.} + (- (* symbol-width X-axis-label-spacing) + (length X-axis-tic-symbol)) + ? ) +@end group +@group + ;; @r{Concatenate blanks with tic symbol.} + X-axis-tic-symbol)) +@end group +@group + (tic-number + (if (zerop (% X-length tic-width)) + (/ X-length tic-width) + (1+ (/ X-length tic-width))))) +@end group +@group + (print-X-axis-tic-line tic-number leading-spaces X-tic) + (insert "\n") + (print-X-axis-numbered-line tic-number leading-spaces))) +@end group +@end smallexample + +@need 1250 +You can test @code{print-X-axis}: + +@enumerate +@item +Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, +@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, +@code{print-X-axis-numbered-line}, and @code{print-X-axis}. + +@item +Copy the following expression: + +@smallexample +@group +(progn + (let ((full-Y-label-width 5) + (symbol-width 1)) + (print-X-axis + '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) +@end group +@end smallexample + +@item +Switch to the @file{*scratch*} buffer and place the cursor where you +want the axis labels to start. + +@item +Type @kbd{M-:} (@code{eval-expression}). + +@item +Yank the test expression into the minibuffer +with @kbd{C-y} (@code{yank)}. + +@item +Press @key{RET} to evaluate the expression. +@end enumerate + +@need 1250 +Emacs will print the horizontal axis like this: +@sp 1 + +@smallexample +@group + | | | | | + 1 5 10 15 20 +@end group +@end smallexample + +@node Print Whole Graph, , print-X-axis, Full Graph +@appendixsec Printing the Whole Graph +@cindex Printing the whole graph +@cindex Whole graph printing +@cindex Graph, printing all + +Now we are nearly ready to print the whole graph. + +The function to print the graph with the proper labels follows the +outline we created earlier (@pxref{Full Graph, , A Graph with Labelled +Axes}), but with additions. + +@need 1250 +Here is the outline: + +@smallexample +@group +(defun print-graph (numbers-list) + "@var{documentation}@dots{}" + (let ((height @dots{} + @dots{})) +@end group +@group + (print-Y-axis height @dots{} ) + (graph-body-print numbers-list) + (print-X-axis @dots{} ))) +@end group +@end smallexample + +@menu +* The final version:: A few changes. +* Test print-graph:: Run a short test. +* Graphing words in defuns:: Executing the final code. +* lambda:: How to write an anonymous function. +* mapcar:: Apply a function to elements of a list. +* Another Bug:: Yet another bug @dots{} most insidious. +* Final printed graph:: The graph itself! +@end menu + +@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph +@ifnottex +@unnumberedsubsec Changes for the Final Version +@end ifnottex + +The final version is different from what we planned in two ways: +first, it contains additional values calculated once in the varlist; +second, it carries an option to specify the labels' increment per row. +This latter feature turns out to be essential; otherwise, a graph may +have more rows than fit on a display or on a sheet of paper. + +@need 1500 +This new feature requires a change to the @code{Y-axis-column} +function, to add @code{vertical-step} to it. The function looks like +this: + +@findex Y-axis-column @r{Final version.} +@smallexample +@group +;;; @r{Final version.} +(defun Y-axis-column + (height width-of-label &optional vertical-step) + "Construct list of labels for Y axis. +HEIGHT is maximum height of graph. +WIDTH-OF-LABEL is maximum width of label. +VERTICAL-STEP, an option, is a positive integer +that specifies how much a Y axis label increments +for each line. For example, a step of 5 means +that each line is five units of the graph." +@end group +@group + (let (Y-axis + (number-per-line (or vertical-step 1))) + (while (> height 1) + (if (zerop (% height Y-axis-label-spacing)) +@end group +@group + ;; @r{Insert label.} + (setq Y-axis + (cons + (Y-axis-element + (* height number-per-line) + width-of-label) + Y-axis)) +@end group +@group + ;; @r{Else, insert blanks.} + (setq Y-axis + (cons + (make-string width-of-label ? ) + Y-axis))) + (setq height (1- height))) +@end group +@group + ;; @r{Insert base line.} + (setq Y-axis (cons (Y-axis-element + (or vertical-step 1) + width-of-label) + Y-axis)) + (nreverse Y-axis))) +@end group +@end smallexample + +The values for the maximum height of graph and the width of a symbol +are computed by @code{print-graph} in its @code{let} expression; so +@code{graph-body-print} must be changed to accept them. + +@findex graph-body-print @r{Final version.} +@smallexample +@group +;;; @r{Final version.} +(defun graph-body-print (numbers-list height symbol-width) + "Print a bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values. +HEIGHT is maximum height of graph. +SYMBOL-WIDTH is number of each column." +@end group +@group + (let (from-position) + (while numbers-list + (setq from-position (point)) + (insert-rectangle + (column-of-graph height (car numbers-list))) + (goto-char from-position) + (forward-char symbol-width) +@end group +@group + ;; @r{Draw graph column by column.} + (sit-for 0) + (setq numbers-list (cdr numbers-list))) + ;; @r{Place point for X axis labels.} + (forward-line height) + (insert "\n"))) +@end group +@end smallexample + +@need 1250 +Finally, the code for the @code{print-graph} function: + +@findex print-graph @r{Final version.} +@smallexample +@group +;;; @r{Final version.} +(defun print-graph + (numbers-list &optional vertical-step) + "Print labelled bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values. +@end group + +@group +Optionally, VERTICAL-STEP, a positive integer, +specifies how much a Y axis label increments for +each line. For example, a step of 5 means that +each row is five units." +@end group +@group + (let* ((symbol-width (length graph-blank)) + ;; @code{height} @r{is both the largest number} + ;; @r{and the number with the most digits.} + (height (apply 'max numbers-list)) +@end group +@group + (height-of-top-line + (if (zerop (% height Y-axis-label-spacing)) + height + ;; @r{else} + (* (1+ (/ height Y-axis-label-spacing)) + Y-axis-label-spacing))) +@end group +@group + (vertical-step (or vertical-step 1)) + (full-Y-label-width + (length +@end group +@group + (concat + (number-to-string + (* height-of-top-line vertical-step)) + Y-axis-tic)))) +@end group + +@group + (print-Y-axis + height-of-top-line full-Y-label-width vertical-step) +@end group +@group + (graph-body-print + numbers-list height-of-top-line symbol-width) + (print-X-axis numbers-list))) +@end group +@end smallexample + +@node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph +@appendixsubsec Testing @code{print-graph} + +@need 1250 +We can test the @code{print-graph} function with a short list of numbers: + +@enumerate +@item +Install the final versions of @code{Y-axis-column}, +@code{graph-body-print}, and @code{print-graph} (in addition to the +rest of the code.) + +@item +Copy the following expression: + +@smallexample +(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) +@end smallexample + +@item +Switch to the @file{*scratch*} buffer and place the cursor where you +want the axis labels to start. + +@item +Type @kbd{M-:} (@code{eval-expression}). + +@item +Yank the test expression into the minibuffer +with @kbd{C-y} (@code{yank)}. + +@item +Press @key{RET} to evaluate the expression. +@end enumerate + +@need 1250 +Emacs will print a graph that looks like this: + +@smallexample +@group +10 - + + + * + ** * + 5 - **** * + **** *** + * ********* + ************ + 1 - ************* + + | | | | + 1 5 10 15 +@end group +@end smallexample + +@need 1200 +On the other hand, if you pass @code{print-graph} a +@code{vertical-step} value of 2, by evaluating this expression: + +@smallexample +(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) +@end smallexample + +@need 1250 +@noindent +The graph looks like this: + +@smallexample +@group +20 - + + + * + ** * +10 - **** * + **** *** + * ********* + ************ + 2 - ************* + + | | | | + 1 5 10 15 +@end group +@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.) + +@node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph +@appendixsubsec Graphing Numbers of Words and Symbols + +Now for the graph for which all this code was written: a graph that +shows how many function definitions contain fewer than 10 words and +symbols, how many contain between 10 and 19 words and symbols, how +many contain between 20 and 29 words and symbols, and so on. + +This is a multi-step process. First make sure you have loaded all the +requisite code. + +@need 1500 +It is a good idea to reset the value of @code{top-of-ranges} in case +you have set it to some different value. You can evaluate the +following: + +@smallexample +@group +(setq top-of-ranges + '(10 20 30 40 50 + 60 70 80 90 100 + 110 120 130 140 150 + 160 170 180 190 200 + 210 220 230 240 250 + 260 270 280 290 300) +@end group +@end smallexample + +@noindent +Next create a list of the number of words and symbols in each range. + +@need 1500 +@noindent +Evaluate the following: + +@smallexample +@group +(setq list-for-graph + (defuns-per-range + (sort + (recursive-lengths-list-many-files + (directory-files "/usr/local/emacs/lisp" + t ".+el$")) + '<) + top-of-ranges)) +@end group +@end smallexample + +@noindent +On my old machine, this took about an hour. It looked though 303 Lisp +files in my copy of Emacs version 19.23. After all that computing, +the @code{list-for-graph} had this value: + +@smallexample +@group +(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 +90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) +@end group +@end smallexample + +@noindent +This means that my copy of Emacs had 537 function definitions with +fewer than 10 words or symbols in them, 1,027 function definitions +with 10 to 19 words or symbols in them, 955 function definitions with +20 to 29 words or symbols in them, and so on. + +Clearly, just by looking at this list we can see that most function +definitions contain ten to thirty words and symbols. + +Now for printing. We do @emph{not} want to print a graph that is +1,030 lines high @dots{} Instead, we should print a graph that is +fewer than twenty-five lines high. A graph that height can be +displayed on almost any monitor, and easily printed on a sheet of paper. + +This means that each value in @code{list-for-graph} must be reduced to +one-fiftieth its present value. + +Here is a short function to do just that, using two functions we have +not yet seen, @code{mapcar} and @code{lambda}. + +@smallexample +@group +(defun one-fiftieth (full-range) + "Return list, each number one-fiftieth of previous." + (mapcar '(lambda (arg) (/ arg 50)) full-range)) +@end group +@end smallexample + +@node lambda, mapcar, Graphing words in defuns, Print Whole Graph +@appendixsubsec A @code{lambda} Expression: Useful Anonymity +@cindex Anonymous function +@findex lambda + +@code{lambda} is the symbol for an anonymous function, a function +without a name. Every time you use an anonymous function, you need to +include its whole body. + +@need 1250 +@noindent +Thus, + +@smallexample +(lambda (arg) (/ arg 50)) +@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'. + +@need 1200 +Earlier, for example, we had a function @code{multiply-by-seven}; it +multiplied its argument by 7. This function is similar, except it +divides its argument by 50; and, it has no name. The anonymous +equivalent of @code{multiply-by-seven} is: + +@smallexample +(lambda (number) (* 7 number)) +@end smallexample + +@noindent +(@xref{defun, , The @code{defun} Special Form}.) + +@need 1250 +@noindent +If we want to multiply 3 by 7, we can write: + +@c !!! Clear print-postscript-figures if the computer formatting this +@c document is too small and cannot handle all the diagrams and figures. +@c clear print-postscript-figures +@c set print-postscript-figures +@c lambda example diagram #1 +@ifnottex +@smallexample +@group +(multiply-by-seven 3) + \_______________/ ^ + | | + function argument +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{lambda-1} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +(multiply-by-seven 3) + \_______________/ ^ + | | + function argument +@end group +@end smallexample +@end iftex +@end ifclear + +@noindent +This expression returns 21. + +@need 1250 +@noindent +Similarly, we can write: + +@c lambda example diagram #2 +@ifnottex +@smallexample +@group +((lambda (number) (* 7 number)) 3) + \____________________________/ ^ + | | + anonymous function argument +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{lambda-2} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +((lambda (number) (* 7 number)) 3) + \____________________________/ ^ + | | + anonymous function argument +@end group +@end smallexample +@end iftex +@end ifclear + +@need 1250 +@noindent +If we want to divide 100 by 50, we can write: + +@c lambda example diagram #3 +@ifnottex +@smallexample +@group +((lambda (arg) (/ arg 50)) 100) + \______________________/ \_/ + | | + anonymous function argument +@end group +@end smallexample +@end ifnottex +@ifset print-postscript-figures +@sp 1 +@tex +@center @image{lambda-3} +%%%% old method of including an image +% \input /usr/local/lib/tex/inputs/psfig.tex +% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} +% \catcode`\@=0 % +@end tex +@sp 1 +@end ifset +@ifclear print-postscript-figures +@iftex +@smallexample +@group +((lambda (arg) (/ arg 50)) 100) + \______________________/ \_/ + | | + anonymous function argument +@end group +@end smallexample +@end iftex +@end ifclear + +@noindent +This expression returns 2. The 100 is passed to the function, which +divides that number by 50. + +@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs +Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda +expressions derive from the Lambda Calculus. + +@node mapcar, Another Bug, lambda, Print Whole Graph +@appendixsubsec The @code{mapcar} Function +@findex mapcar + +@code{mapcar} is a function that calls its first argument with each +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 +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 +first of a list. + +@need 1250 +@noindent +For example, + +@smallexample +@group +(mapcar '1+ '(2 4 6)) + @result{} (3 5 7) +@end group +@end smallexample + +@noindent +The function @code{1+} which adds one to its argument, is executed on +@emph{each} element of the list, and a new list is returned. + +Contrast this with @code{apply}, which applies its first argument to +all the remaining. +(@xref{Readying a Graph, , Readying a Graph}, for a explanation of +@code{apply}.) + +@need 1250 +In the definition of @code{one-fiftieth}, the first argument is the +anonymous function: + +@smallexample +(lambda (arg) (/ arg 50)) +@end smallexample + +@noindent +and the second argument is @code{full-range}, which will be bound to +@code{list-for-graph}. + +@need 1250 +The whole expression looks like this: + +@smallexample +(mapcar '(lambda (arg) (/ arg 50)) full-range)) +@end smallexample + +@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs +Lisp Reference Manual}, for more about @code{mapcar}. + +Using the @code{one-fiftieth} function, we can generate a list in +which each element is one-fiftieth the size of the corresponding +element in @code{list-for-graph}. + +@smallexample +@group +(setq fiftieth-list-for-graph + (one-fiftieth list-for-graph)) +@end group +@end smallexample + +@need 1250 +The resulting list looks like this: + +@smallexample +@group +(10 20 19 15 11 9 6 5 4 3 3 2 2 +1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) +@end group +@end smallexample + +@noindent +This, we are almost ready to print! (We also notice the loss of +information: many of the higher ranges are 0, meaning that fewer than +50 defuns had that many words or symbols---but not necessarily meaning +that none had that many words or symbols.) + +@node Another Bug, Final printed graph, mapcar, Print Whole Graph +@appendixsubsec Another Bug @dots{} Most Insidious +@cindex Bug, most insidious type +@cindex Insidious type of bug + +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 +@code{print-graph} function will print only by ones. + +This is a classic example of what some consider the most insidious +type of bug, the bug of omission. This is not the kind of bug you can +find by studying the code, for it is not in the code; it is an omitted +feature. Your best actions are to try your program early and often; +and try to arrange, as much as you can, to write code that is easy to +understand and easy to change. Try to be aware, whenever you can, +that whatever you have written, @emph{will} be rewritten, if not soon, +eventually. A hard maxim to follow. + +It is the @code{print-X-axis-numbered-line} function that needs the +work; and then the @code{print-X-axis} and the @code{print-graph} +functions need to be adapted. Not much needs to be done; there is one +nicety: the numbers ought to line up under the tic marks. This takes +a little thought. + +@need 1250 +Here is the corrected @code{print-X-axis-numbered-line}: + +@smallexample +@group +(defun print-X-axis-numbered-line + (number-of-X-tics X-axis-leading-spaces + &optional horizontal-step) + "Print line of X-axis numbers" + (let ((number X-axis-label-spacing) + (horizontal-step (or horizontal-step 1))) +@end group +@group + (insert X-axis-leading-spaces) + ;; @r{Delete extra leading spaces.} + (delete-char + (- (1- + (length (number-to-string horizontal-step))))) + (insert (concat + (make-string +@end group +@group + ;; @r{Insert white space.} + (- (* symbol-width + X-axis-label-spacing) + (1- + (length + (number-to-string horizontal-step))) + 2) + ? ) + (number-to-string + (* number horizontal-step)))) +@end group +@group + ;; @r{Insert remaining numbers.} + (setq number (+ number X-axis-label-spacing)) + (while (> number-of-X-tics 1) + (insert (X-axis-element + (* number horizontal-step))) + (setq number (+ number X-axis-label-spacing)) + (setq number-of-X-tics (1- number-of-X-tics))))) +@end group +@end smallexample + +@need 1500 +If you are reading this in Info, you can see the new versions of +@code{print-X-axis} @code{print-graph} and evaluate them. If you are +reading this in a printed book, you can see the changed lines here +(the full text is too much to print). + +@iftex +@smallexample +@group +(defun print-X-axis (numbers-list horizontal-step) + @dots{} + (print-X-axis-numbered-line + tic-number leading-spaces horizontal-step)) +@end group +@end smallexample + +@smallexample +@group +(defun print-graph + (numbers-list + &optional vertical-step horizontal-step) + @dots{} + (print-X-axis numbers-list horizontal-step)) +@end group +@end smallexample +@end iftex + +@ifnottex +@smallexample +@group +(defun print-X-axis (numbers-list horizontal-step) + "Print X axis labels to length of NUMBERS-LIST. +Optionally, HORIZONTAL-STEP, a positive integer, +specifies how much an X axis label increments for +each column." +@end group +@group +;; Value of symbol-width and full-Y-label-width +;; are passed by `print-graph'. + (let* ((leading-spaces + (make-string full-Y-label-width ? )) + ;; symbol-width @r{is provided by} graph-body-print + (tic-width (* symbol-width X-axis-label-spacing)) + (X-length (length numbers-list)) +@end group +@group + (X-tic + (concat + (make-string + ;; @r{Make a string of blanks.} + (- (* symbol-width X-axis-label-spacing) + (length X-axis-tic-symbol)) + ? ) +@end group +@group + ;; @r{Concatenate blanks with tic symbol.} + X-axis-tic-symbol)) + (tic-number + (if (zerop (% X-length tic-width)) + (/ X-length tic-width) + (1+ (/ X-length tic-width))))) +@end group + +@group + (print-X-axis-tic-line + tic-number leading-spaces X-tic) + (insert "\n") + (print-X-axis-numbered-line + tic-number leading-spaces horizontal-step))) +@end group +@end smallexample + +@smallexample +@group +(defun print-graph + (numbers-list &optional vertical-step horizontal-step) + "Print labelled bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values. +@end group + +@group +Optionally, VERTICAL-STEP, a positive integer, +specifies how much a Y axis label increments for +each line. For example, a step of 5 means that +each row is five units. +@end group + +@group +Optionally, HORIZONTAL-STEP, a positive integer, +specifies how much an X axis label increments for +each column." + (let* ((symbol-width (length graph-blank)) + ;; @code{height} @r{is both the largest number} + ;; @r{and the number with the most digits.} + (height (apply 'max numbers-list)) +@end group +@group + (height-of-top-line + (if (zerop (% height Y-axis-label-spacing)) + height + ;; @r{else} + (* (1+ (/ height Y-axis-label-spacing)) + Y-axis-label-spacing))) +@end group +@group + (vertical-step (or vertical-step 1)) + (full-Y-label-width + (length + (concat + (number-to-string + (* height-of-top-line vertical-step)) + Y-axis-tic)))) +@end group +@group + (print-Y-axis + height-of-top-line full-Y-label-width vertical-step) + (graph-body-print + numbers-list height-of-top-line symbol-width) + (print-X-axis numbers-list horizontal-step))) +@end group +@end smallexample +@end ifnottex + +@c qqq +@ignore +Graphing Definitions Re-listed + +@need 1250 +Here are all the graphing definitions in their final form: + +@smallexample +@group +(defvar top-of-ranges + '(10 20 30 40 50 + 60 70 80 90 100 + 110 120 130 140 150 + 160 170 180 190 200 + 210 220 230 240 250) + "List specifying ranges for `defuns-per-range'.") +@end group + +@group +(defvar graph-symbol "*" + "String used as symbol in graph, usually an asterisk.") +@end group + +@group +(defvar graph-blank " " + "String used as blank in graph, usually a blank space. +graph-blank must be the same number of columns wide +as graph-symbol.") +@end group + +@group +(defvar Y-axis-tic " - " + "String that follows number in a Y axis label.") +@end group + +@group +(defvar Y-axis-label-spacing 5 + "Number of lines from one Y axis label to next.") +@end group + +@group +(defvar X-axis-tic-symbol "|" + "String to insert to point to a column in X axis.") +@end group + +@group +(defvar X-axis-label-spacing + (if (boundp 'graph-blank) + (* 5 (length graph-blank)) 5) + "Number of units from one X axis label to next.") +@end group +@end smallexample + +@smallexample +@group +(defun count-words-in-defun () + "Return the number of words and symbols in a defun." + (beginning-of-defun) + (let ((count 0) + (end (save-excursion (end-of-defun) (point)))) +@end group + +@group + (while + (and (< (point) end) + (re-search-forward + "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" + end t)) + (setq count (1+ count))) + count)) +@end group +@end smallexample + +@smallexample +@group +(defun lengths-list-file (filename) + "Return list of definitions' lengths within FILE. +The returned list is a list of numbers. +Each number is the number of words or +symbols in one function definition." +@end group + +@group + (message "Working on `%s' ... " filename) + (save-excursion + (let ((buffer (find-file-noselect filename)) + (lengths-list)) + (set-buffer buffer) + (setq buffer-read-only t) + (widen) + (goto-char (point-min)) +@end group + +@group + (while (re-search-forward "^(defun" nil t) + (setq lengths-list + (cons (count-words-in-defun) lengths-list))) + (kill-buffer buffer) + lengths-list))) +@end group +@end smallexample + +@smallexample +@group +(defun lengths-list-many-files (list-of-files) + "Return list of lengths of defuns in LIST-OF-FILES." + (let (lengths-list) +;;; @r{true-or-false-test} + (while list-of-files + (setq lengths-list + (append + lengths-list +@end group +@group +;;; @r{Generate a lengths' list.} + (lengths-list-file + (expand-file-name (car list-of-files))))) +;;; @r{Make files' list shorter.} + (setq list-of-files (cdr list-of-files))) +;;; @r{Return final value of lengths' list.} + lengths-list)) +@end group +@end smallexample + +@smallexample +@group +(defun defuns-per-range (sorted-lengths top-of-ranges) + "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." + (let ((top-of-range (car top-of-ranges)) + (number-within-range 0) + defuns-per-range-list) +@end group + +@group + ;; @r{Outer loop.} + (while top-of-ranges + + ;; @r{Inner loop.} + (while (and + ;; @r{Need number for numeric test.} + (car sorted-lengths) + (< (car sorted-lengths) top-of-range)) + + ;; @r{Count number of definitions within current range.} + (setq number-within-range (1+ number-within-range)) + (setq sorted-lengths (cdr sorted-lengths))) +@end group + +@group + ;; @r{Exit inner loop but remain within outer loop.} + + (setq defuns-per-range-list + (cons number-within-range defuns-per-range-list)) + (setq number-within-range 0) ; @r{Reset count to zero.} + + ;; @r{Move to next range.} + (setq top-of-ranges (cdr top-of-ranges)) + ;; @r{Specify next top of range value.} + (setq top-of-range (car top-of-ranges))) +@end group + +@group + ;; @r{Exit outer loop and count the number of defuns larger than} + ;; @r{ the largest top-of-range value.} + (setq defuns-per-range-list + (cons + (length sorted-lengths) + defuns-per-range-list)) + + ;; @r{Return a list of the number of definitions within each range,} + ;; @r{ smallest to largest.} + (nreverse defuns-per-range-list))) +@end group +@end smallexample + +@smallexample +@group +(defun column-of-graph (max-graph-height actual-height) + "Return list of MAX-GRAPH-HEIGHT strings; +ACTUAL-HEIGHT are graph-symbols. +The graph-symbols are contiguous entries at the end +of the list. +The list will be inserted as one column of a graph. +The strings are either graph-blank or graph-symbol." +@end group + +@group + (let ((insert-list nil) + (number-of-top-blanks + (- max-graph-height actual-height))) + + ;; @r{Fill in @code{graph-symbols}.} + (while (> actual-height 0) + (setq insert-list (cons graph-symbol insert-list)) + (setq actual-height (1- actual-height))) +@end group + +@group + ;; @r{Fill in @code{graph-blanks}.} + (while (> number-of-top-blanks 0) + (setq insert-list (cons graph-blank insert-list)) + (setq number-of-top-blanks + (1- number-of-top-blanks))) + + ;; @r{Return whole list.} + insert-list)) +@end group +@end smallexample + +@smallexample +@group +(defun Y-axis-element (number full-Y-label-width) + "Construct a NUMBERed label element. +A numbered element looks like this ` 5 - ', +and is padded as needed so all line up with +the element for the largest number." +@end group +@group + (let* ((leading-spaces + (- full-Y-label-width + (length + (concat (number-to-string number) + Y-axis-tic))))) +@end group +@group + (concat + (make-string leading-spaces ? ) + (number-to-string number) + Y-axis-tic))) +@end group +@end smallexample + +@smallexample +@group +(defun print-Y-axis + (height full-Y-label-width &optional vertical-step) + "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. +Height must be the maximum height of the graph. +Full width is the width of the highest label element. +Optionally, print according to VERTICAL-STEP." +@end group +@group +;; Value of height and full-Y-label-width +;; are passed by `print-graph'. + (let ((start (point))) + (insert-rectangle + (Y-axis-column height full-Y-label-width vertical-step)) +@end group +@group + ;; @r{Place point ready for inserting graph.} + (goto-char start) + ;; @r{Move point forward by value of} full-Y-label-width + (forward-char full-Y-label-width))) +@end group +@end smallexample + +@smallexample +@group +(defun print-X-axis-tic-line + (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) + "Print ticks for X axis." + (insert X-axis-leading-spaces) + (insert X-axis-tic-symbol) ; @r{Under first column.} +@end group +@group + ;; @r{Insert second tic in the right spot.} + (insert (concat + (make-string + (- (* symbol-width X-axis-label-spacing) + ;; @r{Insert white space up to second tic symbol.} + (* 2 (length X-axis-tic-symbol))) + ? ) + X-axis-tic-symbol)) +@end group +@group + ;; @r{Insert remaining ticks.} + (while (> number-of-X-tics 1) + (insert X-axis-tic-element) + (setq number-of-X-tics (1- number-of-X-tics)))) +@end group +@end smallexample + +@smallexample +@group +(defun X-axis-element (number) + "Construct a numbered X axis element." + (let ((leading-spaces + (- (* symbol-width X-axis-label-spacing) + (length (number-to-string number))))) + (concat (make-string leading-spaces ? ) + (number-to-string number)))) +@end group +@end smallexample + +@smallexample +@group +(defun graph-body-print (numbers-list height symbol-width) + "Print a bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values. +HEIGHT is maximum height of graph. +SYMBOL-WIDTH is number of each column." +@end group +@group + (let (from-position) + (while numbers-list + (setq from-position (point)) + (insert-rectangle + (column-of-graph height (car numbers-list))) + (goto-char from-position) + (forward-char symbol-width) +@end group +@group + ;; @r{Draw graph column by column.} + (sit-for 0) + (setq numbers-list (cdr numbers-list))) + ;; @r{Place point for X axis labels.} + (forward-line height) + (insert "\n"))) +@end group +@end smallexample + +@smallexample +@group +(defun Y-axis-column + (height width-of-label &optional vertical-step) + "Construct list of labels for Y axis. +HEIGHT is maximum height of graph. +WIDTH-OF-LABEL is maximum width of label. +@end group +@group +VERTICAL-STEP, an option, is a positive integer +that specifies how much a Y axis label increments +for each line. For example, a step of 5 means +that each line is five units of the graph." + (let (Y-axis + (number-per-line (or vertical-step 1))) +@end group +@group + (while (> height 1) + (if (zerop (% height Y-axis-label-spacing)) + ;; @r{Insert label.} + (setq Y-axis + (cons + (Y-axis-element + (* height number-per-line) + width-of-label) + Y-axis)) +@end group +@group + ;; @r{Else, insert blanks.} + (setq Y-axis + (cons + (make-string width-of-label ? ) + Y-axis))) + (setq height (1- height))) +@end group +@group + ;; @r{Insert base line.} + (setq Y-axis (cons (Y-axis-element + (or vertical-step 1) + width-of-label) + Y-axis)) + (nreverse Y-axis))) +@end group +@end smallexample + +@smallexample +@group +(defun print-X-axis-numbered-line + (number-of-X-tics X-axis-leading-spaces + &optional horizontal-step) + "Print line of X-axis numbers" + (let ((number X-axis-label-spacing) + (horizontal-step (or horizontal-step 1))) +@end group +@group + (insert X-axis-leading-spaces) + ;; line up number + (delete-char (- (1- (length (number-to-string horizontal-step))))) + (insert (concat + (make-string + ;; @r{Insert white space up to next number.} + (- (* symbol-width X-axis-label-spacing) + (1- (length (number-to-string horizontal-step))) + 2) + ? ) + (number-to-string (* number horizontal-step)))) +@end group +@group + ;; @r{Insert remaining numbers.} + (setq number (+ number X-axis-label-spacing)) + (while (> number-of-X-tics 1) + (insert (X-axis-element (* number horizontal-step))) + (setq number (+ number X-axis-label-spacing)) + (setq number-of-X-tics (1- number-of-X-tics))))) +@end group +@end smallexample + +@smallexample +@group +(defun print-X-axis (numbers-list horizontal-step) + "Print X axis labels to length of NUMBERS-LIST. +Optionally, HORIZONTAL-STEP, a positive integer, +specifies how much an X axis label increments for +each column." +@end group +@group +;; Value of symbol-width and full-Y-label-width +;; are passed by `print-graph'. + (let* ((leading-spaces + (make-string full-Y-label-width ? )) + ;; symbol-width @r{is provided by} graph-body-print + (tic-width (* symbol-width X-axis-label-spacing)) + (X-length (length numbers-list)) +@end group +@group + (X-tic + (concat + (make-string + ;; @r{Make a string of blanks.} + (- (* symbol-width X-axis-label-spacing) + (length X-axis-tic-symbol)) + ? ) +@end group +@group + ;; @r{Concatenate blanks with tic symbol.} + X-axis-tic-symbol)) + (tic-number + (if (zerop (% X-length tic-width)) + (/ X-length tic-width) + (1+ (/ X-length tic-width))))) +@end group + +@group + (print-X-axis-tic-line + tic-number leading-spaces X-tic) + (insert "\n") + (print-X-axis-numbered-line + tic-number leading-spaces horizontal-step))) +@end group +@end smallexample + +@smallexample +@group +(defun one-fiftieth (full-range) + "Return list, each number of which is 1/50th previous." + (mapcar '(lambda (arg) (/ arg 50)) full-range)) +@end group +@end smallexample + +@smallexample +@group +(defun print-graph + (numbers-list &optional vertical-step horizontal-step) + "Print labelled bar graph of the NUMBERS-LIST. +The numbers-list consists of the Y-axis values. +@end group + +@group +Optionally, VERTICAL-STEP, a positive integer, +specifies how much a Y axis label increments for +each line. For example, a step of 5 means that +each row is five units. +@end group + +@group +Optionally, HORIZONTAL-STEP, a positive integer, +specifies how much an X axis label increments for +each column." + (let* ((symbol-width (length graph-blank)) + ;; @code{height} @r{is both the largest number} + ;; @r{and the number with the most digits.} + (height (apply 'max numbers-list)) +@end group +@group + (height-of-top-line + (if (zerop (% height Y-axis-label-spacing)) + height + ;; @r{else} + (* (1+ (/ height Y-axis-label-spacing)) + Y-axis-label-spacing))) +@end group +@group + (vertical-step (or vertical-step 1)) + (full-Y-label-width + (length + (concat + (number-to-string + (* height-of-top-line vertical-step)) + Y-axis-tic)))) +@end group +@group + + (print-Y-axis + height-of-top-line full-Y-label-width vertical-step) + (graph-body-print + numbers-list height-of-top-line symbol-width) + (print-X-axis numbers-list horizontal-step))) +@end group +@end smallexample +@c qqq +@end ignore + +@page +@node Final printed graph, , Another Bug, Print Whole Graph +@appendixsubsec The Printed Graph + +When made and installed, you can call the @code{print-graph} command +like this: +@sp 1 + +@smallexample +@group +(print-graph fiftieth-list-for-graph 50 10) +@end group +@end smallexample +@sp 1 + +@noindent +Here is the graph: +@sp 2 + +@smallexample +@group +1000 - * + ** + ** + ** + ** + 750 - *** + *** + *** + *** + **** + 500 - ***** + ****** + ****** + ****** + ******* + 250 - ******** + ********* * + *********** * + ************* * + 50 - ***************** * * + | | | | | | | | + 10 50 100 150 200 250 300 350 +@end group +@end smallexample + +@sp 2 + +@noindent +The largest group of functions contain 10 -- 19 words and symbols each. + +@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top +@appendix Free Software and Free Manuals + +@strong{by Richard M. Stallman} +@sp 1 + +The biggest deficiency in free operating systems is not in the +software---it is the lack of good free manuals that we can include in +these systems. Many of our most important programs do not come with +full manuals. Documentation is an essential part of any software +package; when an important free software package does not come with a +free manual, that is a major gap. We have many such gaps today. + +Once upon a time, many years ago, I thought I would learn Perl. I got +a copy of a free manual, but I found it hard to read. When I asked +Perl users about alternatives, they told me that there were better +introductory manuals---but those were not free. + +Why was this? The authors of the good manuals had written them for +O'Reilly Associates, which published them with restrictive terms---no +copying, no modification, source files not available---which exclude +them from the free software community. + +That wasn't the first time this sort of thing has happened, and (to +our community's great loss) it was far from the last. Proprietary +manual publishers have enticed a great many authors to restrict their +manuals since then. Many times I have heard a GNU user eagerly tell me +about a manual that he is writing, with which he expects to help the +GNU project---and then had my hopes dashed, as he proceeded to explain +that he had signed a contract with a publisher that would restrict it +so that we cannot use it. + +Given that writing good English is a rare skill among programmers, we +can ill afford to lose manuals this way. + +@c (texinfo)uref +(The Free Software Foundation +@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , +sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, +GNU manuals}, too.) + +Free documentation, like free software, is a matter of freedom, not +price. The problem with these manuals was not that O'Reilly Associates +charged a price for printed copies---that in itself is fine. (The Free +Software Foundation sells printed copies of free GNU manuals, too.) +But GNU manuals are available in source code form, while these manuals +are available only on paper. GNU manuals come with permission to copy +and modify; the Perl manuals do not. These restrictions are the +problems. + +The criterion for a free manual is pretty much the same as for free +software: it is a matter of giving all users certain +freedoms. Redistribution (including commercial redistribution) must be +permitted, so that the manual can accompany every copy of the program, +on-line or on paper. Permission for modification is crucial too. + +As a general rule, I don't believe that it is essential for people to +have permission to modify all sorts of articles and books. The issues +for writings are not necessarily the same as those for software. For +example, I don't think you or I are obliged to give permission to +modify articles like this one, which describe our actions and our +views. + +But there is a particular reason why the freedom to modify is crucial +for documentation for free software. When people exercise their right +to modify the software, and add or change its features, if they are +conscientious they will change the manual too---so they can provide +accurate and usable documentation with the modified program. A manual +which forbids programmers to be conscientious and finish the job, or +more precisely requires them to write a new manual from scratch if +they change the program, does not fill our community's needs. + +While a blanket prohibition on modification is unacceptable, some +kinds of limits on the method of modification pose no problem. For +example, requirements to preserve the original author's copyright +notice, the distribution terms, or the list of authors, are ok. It is +also no problem to require modified versions to include notice that +they were modified, even to have entire sections that may not be +deleted or changed, as long as these sections deal with nontechnical +topics. (Some GNU manuals have them.) + +These kinds of restrictions are not a problem because, as a practical +matter, they don't stop the conscientious programmer from adapting the +manual to fit the modified program. In other words, they don't block +the free software community from making full use of the manual. + +However, it must be possible to modify all the technical content of +the manual, and then distribute the result in all the usual media, +through all the usual channels; otherwise, the restrictions do block +the community, the manual is not free, and so we need another manual. + +Unfortunately, it is often hard to find someone to write another +manual when a proprietary manual exists. The obstacle is that many +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 +not considered the issue. I hope this article will do something to +change that. + +Other users consider proprietary manuals acceptable for the same +reason so many people consider proprietary software acceptable: they +judge in purely practical terms, not using freedom as a +criterion. These people are entitled to their opinions, but since +those opinions spring from values which do not include freedom, they +are no guide for those of us who do value freedom. + +Please spread the word about this issue. We continue to lose manuals +to proprietary publishing. If we spread the word that proprietary +manuals are not sufficient, perhaps the next person who wants to help +GNU by writing documentation will realize, before it is too late, that +he must above all make it free. + +We can also encourage commercial publishers to sell free, copylefted +manuals instead of proprietary ones. One way you can help this is to +check the distribution terms of a manual before you buy it, and prefer +copylefted manuals to non-copylefted ones. + +@sp 2 +@noindent +Note: The Free Software Foundation maintains a page on its Web site +that lists free books available from other publishers:@* +@uref{http://www.gnu.org/doc/other-free-books.html} + +@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@appendixsubsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group +Copyright (C) @var{year} @var{your name}. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group +with the Invariant Sections being @var{list their titles}, with +the Front-Cover Texts being @var{list}, and with the Back-Cover Texts +being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@node Index, About the Author, GNU Free Documentation License, Top +@comment node-name, next, previous, up +@unnumbered Index + +@ignore +MENU ENTRY: NODE NAME. +@end ignore + +@printindex cp + +@iftex +@c Place biographical information on right-hand (verso) page + +@tex +\ifodd\pageno + \par\vfill\supereject + \global\evenheadline={\hfil} \global\evenfootline={\hfil} + \global\oddheadline={\hfil} \global\oddfootline={\hfil} + \page\hbox{}\page +\else + \par\vfill\supereject + \par\vfill\supereject + \global\evenheadline={\hfil} \global\evenfootline={\hfil} + \global\oddheadline={\hfil} \global\oddfootline={\hfil} + \page\hbox{}\page + \page\hbox{}\page +\fi +@end tex + +@page +@w{ } + +@c ================ Biographical information ================ + +@w{ } +@sp 8 +@center About the Author +@sp 1 +@end iftex + +@ifnottex +@node About the Author, , Index, Top +@unnumbered About the Author +@end ifnottex + +@quotation +Robert J. Chassell has worked with GNU Emacs since 1985. He writes +and edits, teaches Emacs and Emacs Lisp, and speaks throughout the +world on software freedom. Chassell was a founding Director and +Treasurer of the Free Software Foundation, Inc. He is co-author of +the @cite{Texinfo} manual, and has edited more than a dozen other +books. He graduated from Cambridge University, in England. He has an +abiding interest in social and economic history and flies his own +airplane. +@end quotation + +@page +@w{ } + +@c Prevent page number on blank verso, so eject it first. +@tex +\par\vfill\supereject +@end tex + +@iftex +@headings off +@evenheading @thispage @| @| @thistitle +@oddheading @| @| @thispage +@end iftex + +@bye + +@ignore + arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf +@end ignore
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/install-sh Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,250 @@ +#!/bin/sh +# +# install - install a program, script, or datafile +# This comes from X11R5 (mit/util/scripts/install.sh). +# +# Copyright 1991 by the Massachusetts Institute of Technology +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation, and that the name of M.I.T. not be used in advertising or +# publicity pertaining to distribution of the software without specific, +# written prior permission. M.I.T. makes no representations about the +# suitability of this software for any purpose. It is provided "as is" +# without express or implied warranty. +# +# Calling this script install-sh is preferred over install.sh, to prevent +# `make' implicit rules from creating a file called install from it +# when there is no Makefile. +# +# This script is compatible with the BSD install script, but was written +# from scratch. It can only install one file at a time, a restriction +# shared with many OS's install programs. + + +# set DOITPROG to echo to test this script + +# Don't use :- since 4.3BSD and earlier shells don't like it. +doit="${DOITPROG-}" + + +# put in absolute paths if you don't have them in your path; or use env. vars. + +mvprog="${MVPROG-mv}" +cpprog="${CPPROG-cp}" +chmodprog="${CHMODPROG-chmod}" +chownprog="${CHOWNPROG-chown}" +chgrpprog="${CHGRPPROG-chgrp}" +stripprog="${STRIPPROG-strip}" +rmprog="${RMPROG-rm}" +mkdirprog="${MKDIRPROG-mkdir}" + +transformbasename="" +transform_arg="" +instcmd="$mvprog" +chmodcmd="$chmodprog 0755" +chowncmd="" +chgrpcmd="" +stripcmd="" +rmcmd="$rmprog -f" +mvcmd="$mvprog" +src="" +dst="" +dir_arg="" + +while [ x"$1" != x ]; do + case $1 in + -c) instcmd="$cpprog" + shift + continue;; + + -d) dir_arg=true + shift + continue;; + + -m) chmodcmd="$chmodprog $2" + shift + shift + continue;; + + -o) chowncmd="$chownprog $2" + shift + shift + continue;; + + -g) chgrpcmd="$chgrpprog $2" + shift + shift + continue;; + + -s) stripcmd="$stripprog" + shift + continue;; + + -t=*) transformarg=`echo $1 | sed 's/-t=//'` + shift + continue;; + + -b=*) transformbasename=`echo $1 | sed 's/-b=//'` + shift + continue;; + + *) if [ x"$src" = x ] + then + src=$1 + else + # this colon is to work around a 386BSD /bin/sh bug + : + dst=$1 + fi + shift + continue;; + esac +done + +if [ x"$src" = x ] +then + echo "install: no input file specified" + exit 1 +else + true +fi + +if [ x"$dir_arg" != x ]; then + dst=$src + src="" + + if [ -d $dst ]; then + instcmd=: + else + instcmd=mkdir + fi +else + +# Waiting for this to be detected by the "$instcmd $src $dsttmp" command +# might cause directories to be created, which would be especially bad +# if $src (and thus $dsttmp) contains '*'. + + if [ -f $src -o -d $src ] + then + true + else + echo "install: $src does not exist" + exit 1 + fi + + if [ x"$dst" = x ] + then + echo "install: no destination specified" + exit 1 + else + true + fi + +# If destination is a directory, append the input filename; if your system +# does not like double slashes in filenames, you may need to add some logic + + if [ -d $dst ] + then + dst="$dst"/`basename $src` + else + true + fi +fi + +## this sed command emulates the dirname command +dstdir=`echo $dst | sed -e 's,[^/]*$,,;s,/$,,;s,^$,.,'` + +# Make sure that the destination directory exists. +# this part is taken from Noah Friedman's mkinstalldirs script + +# Skip lots of stat calls in the usual case. +if [ ! -d "$dstdir" ]; then +defaultIFS=' +' +IFS="${IFS-${defaultIFS}}" + +oIFS="${IFS}" +# Some sh's can't handle IFS=/ for some reason. +IFS='%' +set - `echo ${dstdir} | sed -e 's@/@%@g' -e 's@^%@/@'` +IFS="${oIFS}" + +pathcomp='' + +while [ $# -ne 0 ] ; do + pathcomp="${pathcomp}${1}" + shift + + if [ ! -d "${pathcomp}" ] ; + then + $mkdirprog "${pathcomp}" + else + true + fi + + pathcomp="${pathcomp}/" +done +fi + +if [ x"$dir_arg" != x ] +then + $doit $instcmd $dst && + + if [ x"$chowncmd" != x ]; then $doit $chowncmd $dst; else true ; fi && + if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dst; else true ; fi && + if [ x"$stripcmd" != x ]; then $doit $stripcmd $dst; else true ; fi && + if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dst; else true ; fi +else + +# If we're going to rename the final executable, determine the name now. + + if [ x"$transformarg" = x ] + then + dstfile=`basename $dst` + else + dstfile=`basename $dst $transformbasename | + sed $transformarg`$transformbasename + fi + +# don't allow the sed command to completely eliminate the filename + + if [ x"$dstfile" = x ] + then + dstfile=`basename $dst` + else + true + fi + +# Make a temp file name in the proper directory. + + dsttmp=$dstdir/#inst.$$# + +# Move or copy the file name to the temp name + + $doit $instcmd $src $dsttmp && + + trap "rm -f ${dsttmp}" 0 && + +# and set any options; do chmod last to preserve setuid bits + +# If any of these fail, we abort the whole thing. If we want to +# ignore errors from any of these, just make sure not to ignore +# errors from the above "$doit $instcmd $src $dsttmp" command. + + if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; else true;fi && + if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; else true;fi && + if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; else true;fi && + if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; else true;fi && + +# Now rename the file to the real destination. + + $doit $rmcmd -f $dstdir/$dstfile && + $doit $mvcmd $dsttmp $dstdir/$dstfile + +fi && + + +exit 0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/lambda-1.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,471 @@ +%! +%%BoundingBox: 33 710 173 759 +%%Title: lambda-diagram1 +%%CreationDate: Wed Mar 8 14:31:53 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 33 710 173 759 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 63 75 moveto (\(multiply-by-seven 3\)) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 80 80 moveto + 96 96 lineto + 224 96 lineto + 240 80 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 264 119 moveto + -22 0 atan dup cos 8 mul 264 exch sub + exch sin 8 mul 97 exch sub lineto + stroke +grestore +gsave + newpath + 264 97 8 3 0 -22 tgifarrowtip + closepath fill +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 160 103 moveto + 160 119 lineto + stroke +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 112 139 moveto (function) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 224 139 moveto (argument) show + grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:31:53 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/lambda-2.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,471 @@ +%! +%%BoundingBox: 33 730 240 777 +%%Title: lambda-diagram2 +%%CreationDate: Wed Mar 8 14:33:09 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 33 730 240 777 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 63 43 moveto (\(\(lambda \(number\) \(* 7 number\)\) 3\)) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 80 48 moveto + 96 64 lineto + 336 64 lineto + 353 49 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 395 85 moveto + -21 0 atan dup cos 8 mul 395 exch sub + exch sin 8 mul 64 exch sub lineto + stroke +grestore +gsave + newpath + 395 64 8 3 0 -21 tgifarrowtip + closepath fill +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 208 69 moveto + 208 85 lineto + stroke +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 112 102 moveto (anonymous function) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 344 102 moveto (argument) show + grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:33:09 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/lambda-3.eps Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,471 @@ +%! +%%BoundingBox: 33 728 211 777 +%%Title: lambda-diagram3 +%%CreationDate: Wed Mar 8 14:33:49 1995 +%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) +% +% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 +% + +% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +% 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, 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; see the file COPYING. If not, write to +% the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +% Boston, MA 02110-1301, USA. + +/tgifdict 132 dict def +tgifdict begin + +% +% Using a zero value radius for an ellipse or an arc would result +% in a non-invertible CTM matrix which causes problem when this +% when this PostScript is wrapped inside other routines, such as +% the multi.ps package from +% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such +% error by uncommenting the sole line of the procedure below: +% +/tgif_min_radius + { +% dup 0.01 lt { pop 0.01 } if + } bind def + +/tgifellipsedict 6 dict def +tgifellipsedict /mtrx matrix put + +/tgifellipse + { tgifellipsedict begin + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 0 360 arc + savematrix setmatrix + end + } def + +/tgifarrowtipdict 8 dict def +tgifarrowtipdict /mtrx matrix put + +/tgifarrowtip + { tgifarrowtipdict begin + /dy exch def + /dx exch def + /h exch def + /w exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + dy dx atan rotate + 0 0 moveto + w neg h lineto + w neg h neg lineto + savematrix setmatrix + end + } def + +/tgifarcdict 8 dict def +tgifarcdict /mtrx matrix put + +/tgifarcn + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arc + savematrix setmatrix + end + } def + +/tgifarc + { tgifarcdict begin + /endangle exch def + /startangle exch def + /yrad exch def + /xrad exch def + /y exch def + /x exch def + /savematrix mtrx currentmatrix def + x y translate + xrad yrad scale + 0 0 1 startangle endangle arcn + savematrix setmatrix + end + } def + +/tgifsetuserscreendict 22 dict def +tgifsetuserscreendict begin + /tempctm matrix def + /temprot matrix def + /tempscale matrix def + + /concatprocs + { /proc2 exch cvlit def + /proc1 exch cvlit def + /newproc proc1 length proc2 length add array def + newproc 0 proc1 putinterval + newproc proc1 length proc2 putinterval + newproc cvx + } def + /resmatrix matrix def + /findresolution + { 72 0 resmatrix defaultmatrix dtransform + /yres exch def /xres exch def + xres dup mul yres dup mul add sqrt + } def +end + +/tgifsetuserscreen + { tgifsetuserscreendict begin + /spotfunction exch def + /screenangle exch def + /cellsize exch def + + /m tempctm currentmatrix def + /rm screenangle temprot rotate def + /sm cellsize dup tempscale scale def + + sm rm m m concatmatrix m concatmatrix pop + + 1 0 m dtransform /y1 exch def /x1 exch def + + /veclength x1 dup mul y1 dup mul add sqrt def + /frequency findresolution veclength div def + + /newscreenangle y1 x1 atan def + + m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt + + {{neg} /spotfunction load concatprocs + /spotfunction exch def + } if + + frequency newscreenangle /spotfunction load setscreen + end + } def + +/tgifsetpatterndict 18 dict def +tgifsetpatterndict begin + /bitison + { /ybit exch def /xbit exch def + /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def + + /mask 1 7 xbit 8 mod sub bitshift def + bytevalue mask and 0 ne + } def +end + +/tgifbitpatternspotfunction + { tgifsetpatterndict begin + /y exch def /x exch def + + /xindex x 1 add 2 div bpside mul cvi def + /yindex y 1 add 2 div bpside mul cvi def + + xindex yindex bitison + { /onbits onbits 1 add def 1 } + { /offbits offbits 1 add def 0 } + ifelse + end + } def + +/tgifsetpattern + { tgifsetpatterndict begin + /cellsz exch def + /angle exch def + /bwidth exch def + /bpside exch def + /bstring exch def + + /onbits 0 def /offbits 0 def + cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen + {} settransfer + offbits offbits onbits add div setgray + end + } def + +/tgifxpmdict 4 dict def +/tgifbwpicstr 1 string def +/tgifcolorpicstr 3 string def + +/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def + +/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def + +/tgifbwspot + { tgifxpmdict begin + /index exch def + tgifbwpicstr 0 + pixels index 3 mul 3 getinterval aload pop + 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add + cvi put + tgifbwpicstr + end + } def + +/tgifcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop + 255 mul cvi tgifcolorpicstr 2 3 -1 roll put + 255 mul cvi tgifcolorpicstr 1 3 -1 roll put + 255 mul cvi tgifcolorpicstr 0 3 -1 roll put + tgifcolorpicstr + end + } def + +/tgifnewcolorspot + { tgifxpmdict begin + /index exch def + pixels index 3 mul 3 getinterval aload pop setrgbcolor + end + } def + +/tgifcolordict 4 dict def + +/colorimage where + { pop } + { /colorimage + { tgifcolordict begin + pop pop pop pop pop + /ih exch def + /iw exch def + /x 0 def + /y 0 def + 1 1 ih + { pop 1 1 iw + { pop currentfile + tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot + x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto + closepath fill + /x x 1 add def + } for + /y y 1 add def + /x 0 def + } for + end + } def + } ifelse + +/tgifpatdict 10 dict def + +/tgifpatbyte + { currentdict /retstr get exch + pat i cellsz mod get put + } def + +/tgifpatproc + { 0 1 widthlim {tgifpatbyte} for retstr + /i i 1 add def + } def + +/tgifpatfill + { tgifpatdict begin + /h exch def + /w exch def + /lty exch def + /ltx exch def + /cellsz exch def + /pat exch def + + /widthlim w cellsz div cvi 1 sub def + /retstr widthlim 1 add string def + /i 0 def + + ltx lty translate + w h true [1 0 0 1 0 0] {tgifpatproc} imagemask + ltx neg lty neg translate + end + } def + +/pat1 <ffffffffffffffff> def +/pat2 <0000000000000000> def +/pat3 <8000000008000000> def +/pat4 <8800000022000000> def +/pat5 <8800220088002200> def +/pat6 <8822882288228822> def +/pat7 <aa55aa55aa55aa55> def +/pat8 <77dd77dd77dd77dd> def +/pat9 <77ffddff77ffddff> def +/pat10 <77ffffff77ffffff> def +/pat11 <7fffffff7fffffff> def +/pat12 <8040200002040800> def +/pat13 <40a00000040a0000> def +/pat14 <ff888888ff888888> def +/pat15 <ff808080ff080808> def +/pat16 <f87422478f172271> def +/pat17 <038448300c020101> def +/pat18 <081c22c180010204> def +/pat19 <8080413e080814e3> def +/pat20 <8040201008040201> def +/pat21 <8844221188442211> def +/pat22 <77bbddee77bbddee> def +/pat23 <c1e070381c0e0783> def +/pat24 <7fbfdfeff7fbfdfe> def +/pat25 <3e1f8fc7e3f1f87c> def +/pat26 <0102040810204080> def +/pat27 <1122448811224488> def +/pat28 <eeddbb77eeddbb77> def +/pat29 <83070e1c3870e0c1> def +/pat30 <fefdfbf7efdfbf7f> def +/pat31 <7cf8f1e3c78f1f3e> def + +/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def + +/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def + +/tgifreencsmalldict 12 dict def +/tgifReEncodeSmall + { tgifreencsmalldict begin + /newcodesandnames exch def + /newfontname exch def + /basefontname exch def + + /basefontdict basefontname findfont def + /newfont basefontdict maxlength dict def + + basefontdict + { exch dup /FID ne + { dup /Encoding eq + { exch dup length array copy newfont 3 1 roll put } + { exch newfont 3 1 roll put } + ifelse + } + { pop pop } + ifelse + } + forall + + newfont /FontName newfontname put + newcodesandnames aload pop + + newcodesandnames length 2 idiv + { newfont /Encoding get 3 1 roll put} + repeat + + newfontname newfont definefont pop + end + } def + +/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def + +/tgifboxdict 6 dict def +/tgifboxstroke + { tgifboxdict begin + /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + 1.415 setmiterlimit + w 1 eq { w setlinewidth } if + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + w 1 eq { 1 setlinewidth } if + 1 setmiterlimit + end + } def +/tgifboxfill + { tgifboxdict begin + /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def + pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if + newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath + pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse + pat pat1 ne pat pat2 ne and { grestore } if + end + } def + +end + +%%PageBoundingBox: 33 728 211 777 +tgifdict begin +/tgifsavedpage save def + +1 setmiterlimit +1 setlinewidth + +0 setgray + +72 0 mul 72 11.00 mul translate +72 128 div 100 mul 100 div dup neg scale + +gsave + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 63 43 moveto (\(\(lambda \(arg\) \(/ arg 50\)\) 100\)) show + grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 80 48 moveto + 96 64 lineto + 284 64 lineto + 299 48 lineto + stroke +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 354 86 moveto + -25 0 atan dup cos 8 mul 354 exch sub + exch sin 8 mul 61 exch sub lineto + stroke +grestore +gsave + newpath + 354 61 8 3 0 -25 tgifarrowtip + closepath fill +grestore + +% POLY/OPEN-SPLINE +gsave + newpath + 199 70 moveto + 199 86 lineto + stroke +grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 101 106 moveto (anonymous function) show + grestore + +% TEXT +0 setgray +/Courier findfont [17 0 0 -17 0 0] makefont setfont + gsave + 293 106 moveto (argument) show + grestore + +grestore +tgifsavedpage restore +end +%MatchingCreationDate: Wed Mar 8 14:33:49 1995
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/makefile.w32-in Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,73 @@ +#### -*- Makefile -*- for the Emacs Lisp Introduction manual. + +# Copyright (C) 2003, 2004, 2005, 2006, 2007 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, 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; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +srcdir = . + +infodir = $(srcdir)/../../info + +INFO_SOURCES = $(srcdir)/emacs-lisp-intro.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 +DVI_TARGETS = emacs-lisp-intro.dvi + +MAKEINFO = makeinfo +INSTALL_INFO = install-info +TEXI2DVI = texi2dvi +DVIPS = dvips +ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ + "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C + +.SUFFIXES: .dvi .ps .texi + +info: $(INFO_TARGETS) + +$(infodir)/dir: + $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) + +dvi: $(DVI_TARGETS) + +$(infodir)/eintr: $(INFO_SOURCES) + $(MAKEINFO) -o $@ $(srcdir)/emacs-lisp-intro.texi + +emacs-lisp-intro.dvi: $(INFO_SOURCES) + $(ENVADD) $(TEXI2DVI) $(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* + +distclean: clean + +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:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/missing Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,135 @@ +#! /bin/sh +# Common stub for a few missing GNU programs while installing. +# Copyright (C) 1996, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +# Free Software Foundation, Inc. +# Franc,ois Pinard <pinard@iro.umontreal.ca>, 1996. + +# This program 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 2, or (at your option) +# any later version. + +# This program 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 this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, +# MA 02110-1301, USA. + +if test $# -eq 0; then + echo 1>&2 "Try \`$0 --help' for more information" + exit 1 +fi + +case "$1" in + + -h|--h|--he|--hel|--help) + echo "\ +$0 [OPTION]... PROGRAM [ARGUMENT]... + +Handle \`PROGRAM [ARGUMENT]...' for when PROGRAM is missing, or return an +error status if there is no known handling for PROGRAM. + +Options: + -h, --help display this help and exit + -v, --version output version information and exit + +Supported PROGRAM values: + aclocal touch file \`aclocal.m4' + autoconf touch file \`configure' + autoheader touch file \`config.h.in' + automake touch all \`Makefile.in' files + bison touch file \`y.tab.c' + makeinfo touch the output file + yacc touch file \`y.tab.c'" + ;; + + -v|--v|--ve|--ver|--vers|--versi|--versio|--version) + echo "missing - GNU libit 0.0" + ;; + + -*) + echo 1>&2 "$0: Unknown \`$1' option" + echo 1>&2 "Try \`$0 --help' for more information" + exit 1 + ;; + + aclocal) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified \`acinclude.m4' or \`configure.in'. You might want + to install the \`Automake' and \`Perl' packages. Grab them from + any GNU archive site." + touch aclocal.m4 + ;; + + autoconf) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified \`configure.in'. You might want to install the + \`Autoconf' and \`GNU m4' packages. Grab them from any GNU + archive site." + touch configure + ;; + + autoheader) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified \`acconfig.h' or \`configure.in'. You might want + to install the \`Autoconf' and \`GNU m4' packages. Grab them + from any GNU archive site." + touch config.h.in + ;; + + automake) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified \`Makefile.am', \`acinclude.m4' or \`configure.in'. + You might want to install the \`Automake' and \`Perl' packages. + Grab them from any GNU archive site." + find . -type f -name Makefile.am -print \ + | sed 's/^\(.*\).am$/touch \1.in/' \ + | sh + ;; + + bison|yacc) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified a \`.y' file. You may need the \`Bison' package + in order for those modifications to take effect. You can get + \`Bison' from any GNU archive site." + touch y.tab.c + ;; + + makeinfo) + echo 1>&2 "\ +WARNING: \`$1' is missing on your system. You should only need it if + you modified a \`.texi' or \`.texinfo' file, or any other file + indirectly affecting the aspect of the manual. The spurious + call might also be the consequence of using a buggy \`make' (AIX, + DU, IRIX). You might want to install the \`Texinfo' package or + the \`GNU make' package. Grab either from any GNU archive site." + file=`echo "$*" | sed -n 's/.*-o \([^ ]*\).*/\1/p'` + if test -z "$file"; then + file=`echo "$*" | sed 's/.* \([^ ]*\) *$/\1/'` + file=`sed -n '/^@setfilename/ { s/.* \([^ ]*\) *$/\1/; p; q; }' $file` + fi + touch $file + ;; + + *) + echo 1>&2 "\ +WARNING: \`$1' is needed, and you do not seem to have it handy on your + system. You might have modified some files without having the + proper tools for further handling them. Check the \`README' file, + it often tells you about the needed prerequirements for installing + this package. You may also peek at any GNU archive site, in case + some other package would contain this missing \`$1' program." + exit 1 + ;; +esac + +exit 0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispintro/mkinstalldirs Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,38 @@ +#! /bin/sh +# mkinstalldirs --- make directory hierarchy +# Author: Noah Friedman <friedman@prep.ai.mit.edu> +# Created: 1993-05-16 +# Public domain + +errstatus=0 + +for file +do + set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` + shift + + pathcomp= + for d + do + pathcomp="$pathcomp$d" + case "$pathcomp" in + -* ) pathcomp=./$pathcomp ;; + esac + + if test ! -d "$pathcomp"; then + echo "mkdir $pathcomp" 1>&2 + + mkdir "$pathcomp" || lasterr=$? + + if test ! -d "$pathcomp"; then + errstatus=$lasterr + fi + fi + + pathcomp="$pathcomp/" + done +done + +exit $errstatus + +# mkinstalldirs ends here
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/mkinstalldirs Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,38 @@ +#! /bin/sh +# mkinstalldirs --- make directory hierarchy +# Author: Noah Friedman <friedman@prep.ai.mit.edu> +# Created: 1993-05-16 +# Public domain + +errstatus=0 + +for file +do + set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` + shift + + pathcomp= + for d + do + pathcomp="$pathcomp$d" + case "$pathcomp" in + -* ) pathcomp=./$pathcomp ;; + esac + + if test ! -d "$pathcomp"; then + echo "mkdir $pathcomp" 1>&2 + + mkdir "$pathcomp" || lasterr=$? + + if test ! -d "$pathcomp"; then + errstatus=$lasterr + fi + fi + + pathcomp="$pathcomp/" + done +done + +exit $errstatus + +# mkinstalldirs ends here
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/ChangeLog Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,31 @@ +2007-09-06 Glenn Morris <rgm@gnu.org> + + * ctags.1, emacs.1, emacsclient.1, etags.1: Move from etc/ to + doc/man/. + +;; Local Variables: +;; coding: iso-2022-7bit +;; fill-column: 79 +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 2007 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, 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; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +;; arch-tag: 2bd1112e-157f-4884-b0ca-0fb1057972d7
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/etc/AUTHORS Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,2766 @@ +Many people have contributed code included in the Free Software +Foundation's distribution of GNU Emacs. To show our appreciation for +their public spirit, we list here in alphabetical order a condensed +list of their contributions. + +Aaron Larson: changed bibtex.el + +Aaron S. Hawley: changed files.texi files.el isearch.el misc.texi + +Abraham Nahum: changed configure.in dgux4.h sysdep.c + +Abramo Bagnara: changed term.c + +Adrian Aichner: changed erc-log.el erc.el erc-autojoin.el erc-backend.el + erc-dcc.el erc-members.el erc-nets.el erc-sound.el etags.c + gnus-score.el + +Adrian Colley: changed aix3-2.h + +Adrian Lanz: changed mail-source.el spam.el + +Agust,Am(Bn Mart,Am(Bn: changed flyspell.el ispell.el + +Aidan Kehoe: changed lread.c mm-util.el erc.el objects.texi + +Ake Stenhoff: wrote imenu.el +and changed cc-mode.el perl-mode.el + +Aki Vehtari: changed bibtex.el gnus-art.el gnus-score.el gnus-sum.el + nnmail.el tar-mode.el + +Alakazam Petrofsky: changed hanoi.el + +Alan Mackenzie: wrote cc-awk.el +and changed cc-cmds.el cc-mode.el cc-engine.el cc-defs.el cc-vars.el + cc-langs.el cc-mode.texi cc-styles.el cc-align.el cc-fonts.el lread.c + programs.texi cc-subword.el isearch.el lisp.el search.texi startup.el + subr.el text.texi buffers.texi cc-fix.el and 18 other files + +Alan Shutko: changed diary-lib.el calendar.el bindings.el cal-hebrew.el + easy-mmode.el gnus-sum.el ibuf-ext.el ibuffer.el lunar.el macros.el + solar.el + +Alastair Burt: changed gnus-art.el smiley.el + +Albert L. Ting: changed gnus-group.el mail-hist.el + +Alex Coventry: changed files.el + +Alex Ott: changed TUTORIAL.ru ru-refcard.tex ispell.el ru-refcard.ps + +Alex Rezinsky: wrote which-func.el + +Alex Schroeder: wrote ansi-color.el cus-theme.el erc-compat.el + erc-hecomplete.el erc-join.el erc-lang.el erc-ring.el master.el + spam-stat.el sql.el +and changed erc.el erc-track.el erc-button.el erc-stamp.el erc-match.el + erc-autoaway.el erc-nickserv.el Makefile erc-autojoin.el erc-fill.el + erc-pcomplete.el erc-complete.el erc-ibuffer.el erc-members.el + rcirc.texi comint.el custom.el erc-bbdb.el erc-chess.el erc-ezbounce.el + erc-imenu.el and 26 other files + +Alexander Klimov: changed man.el + +Alexander Kreuzer: changed nnrss.el + +Alexander L. Belikoff: wrote erc.el + +Alexander Pohoyda: changed rmailsum.el man.el rmail.el sendmail.el + +Alexander Shopov: changed code-pages.el + +Alexander Zhuckov: changed ebrowse.c + +Alexandre Oliva: wrote gnus-mlspl.el +and changed unexelf.c format.el iris4d.h iris5d.h unexsgi.c + +Alexandre Veyrenc: changed fr-refcard.tex + +Alfred Correira: changed generic-x.el + +Alfred M. Szmidt: changed compile.el html2text.el openbsd.h + +Alfredo Finelli: changed TUTORIAL.it + +Alin C. Soare: changed lisp-mode.el hexl.el + +Ami Fischman: changed calendar.el diary-lib.el + +Anders Holst: wrote hippie-exp.el + +Anders Lindgren: wrote autorevert.el cwarn.el follow.el +and changed font-lock.el etags.c compile.el + +Andre Spiegel: changed vc.el vc-hooks.el vc-cvs.el vc-rcs.el vc-sccs.el + files.el dired.el files.texi cperl-mode.el ediff-util.el log-view.el + parse-time.el startup.el tramp-vc.el vc-arch.el vc-mcvs.el vc-svn.el + vcdiff viper-util.el + +Andre Srinivasan: changed gnus-group.el gnus-sum.el gnus.texi message.el + mm-decode.el mml.el nnmail.el + +Andrea Russo: changed erc-dcc.el info-look.el + +Andreas B,A|(Bsching: changed emacsclient.c + +Andreas Fuchs: wrote erc-ezbounce.el erc-fill.el erc-match.el + erc-replace.el erc-truncate.el +and changed erc.el erc-bbdb.el erc-button.el erc-log.el erc-stamp.el + erc-autoaway.el erc-autojoin.el erc-dcc.el erc-imenu.el erc-list.el + erc-members.el erc-menu.el erc-netsplit.el erc-notify.el erc-ring.el + erc-speedbar.el erc-track.el erc-xdcc.el gnus-registry.el mml-sec.el + mml2015.el + +Andreas Jaeger: changed gnus-msg.el gnus-start.el gnus-xmas.el + nnfolder.el nnml.el + +Andreas Leue: changed artist.el + +Andreas Luik: changed xfns.c xterm.c + +Andreas Schwab: changed Makefile.in files.el lisp.h xdisp.c configure.in + alloc.c fns.c print.c coding.c editfns.c dired.el info.el eval.c + fileio.c simple.el buffer.c minibuf.c process.c xterm.c emacs.c + keyboard.c and 449 other files + +Andreas Seltenreich: changed nnweb.el gnus.texi nnslashdot.el + gnus-util.el mm-uu.el url-http.el battery.el comint.el easy-mmode.el + gmm-utils.el gnus-art.el gnus-ml.el gnus-msg.el gnus-srvr.el + gnus-start.el gnus-sum.el gnus.el message.el mm-url.el url-cookie.el + xterm.c + +Andrew Choi: wrote mac-win.el +and changed macterm.c mac.c macfns.c INSTALL macmenu.c darwin.h macterm.h + sysdep.c emacs.c fontset.c frame.c keyboard.c macgui.h xfaces.c Emacs.r + README cw5-mcp.xml cw6-mcp.xml dispextern.h make-package makefile.MPW + and 61 other files + +Andrew Cohen: changed dns.el + +Andrew Csillag: wrote m4-mode.el + +Andrew Hall: changed paren.el + +Andrew Innes: changed makefile.w32-in w32fns.c w32term.c w32.c w32proc.c + fileio.c gmake.defs dos-w32.el ms-w32.h nmake.defs w32-fns.el w32term.h + unexw32.c w32menu.c w32xfns.c addpm.c cmdproxy.c emacs.c w32-win.el + w32inevt.c configure.bat and 135 other files + +Andrew Oram: changed man/calendar.texi + miscellaneous changes to files in man/ + +Andrey Slusar: changed gnus.el + +Andrey Zhdanov: changed gud.el + +Andy Norman: wrote ange-ftp.el + +Andy Petrusenco: changed w32term.c + +Anna M. Bigatti: wrote cal-html.el + +Ari Roponen: changed atimer.c startup.el + +Arisawa Akihiro: changed mm-decode.el mm-view.el ps-print.el time.el + utf-8.el + +Arne Georg Gleditsch: changed gnus-sum.el + +Arne J,Ax(Brgensen: wrote latexenc.el +and changed smime.el gnus-art.el gnus-sieve.el ldap.el message.el + mm-decode.el mule-conf.el nnimap.el nnrss.el wid-edit.el + +Artem Chuprina: changed message.el + +Ashwin Ram: wrote refer.el + +Aubrey Jaffer: changed info.el unexelf.c + +Axel Boldt: changed ehelp.el electric.el + +B. Anyos: changed w32term.c + +Barry A. Warsaw: wrote assoc.el elp.el man.el regi.el reporter.el + supercite.el +and changed cc-mode.el cc-cmds.el cc-engine.el cc-langs.el cc-styles.el + cc-vars.el c++-mode.el cc-menus.el cc-align.el cc-defs.el cplus-md1.el + syntax.c syntax.h + +Barry Fishman: changed gnu-linux.h + +Ben A. Mesander: wrote erc-dcc.el + +Ben Harris: changed configure.in + +Ben Key: changed w32.c w32fns.c w32menu.c makefile.w32-in w32.h w32term.c + emacs.c gmake.defs ms-w32.h nmake.defs sound.c + +Ben North: changed outline.el fill.el isearch.el lisp-mode.el paren.el + w32term.c xfaces.c + +Benjamin Drieu: wrote pong.el + +Benjamin Riefenstahl: changed emacs.c mac-win.el macterm.c ms-w32.h + mule-cmds.el runemacs.c tcl.el w32.c w32.h w32select.c + +Benjamin Rutt: changed vc.el gnus-msg.el message.el diff-mode.el ffap.el + gnus-dired.el nnimap.el nnmbox.el simple.el vc-cvs.el + +Bill Atkins: changed wdired.el + +Bill Burton: changed ptx.h sequent-ptx.h + +Bill Carpenter: wrote feedmail.el (public domain) + +Bill Mann: changed configure.in unexaix.c ibmrs6000.h usg5-4-3.h + +Bill Pringlemeir: changed messcompat.el + +Bill Richter: changed fill.el quail.el ccl.el encoded-kb.el fontset.el + kinsoku.el kkc.el mule-cmds.el mule-conf.el mule-util.el mule.el + +Bill Rosenblatt: wrote float.el + +Bill Rozas: wrote scheme.el +and changed xscheme.el + +Bill White: changed gnus-start.el + +Bill Wohler: wrote mh-buffers.el mh-comp.el mh-compat.el mh-e.el + mh-folder.el mh-funcs.el mh-letter.el mh-loaddefs.el mh-mime.el + mh-scan.el mh-seq.el mh-show.el mh-utils.el mh-xface.el +and changed mh-customize.el mh-index.el MH-E-NEWS mh-alias.el Makefile + mh-identity.el mh-pick.el README mh-speed.el mh-init.el mh-junk.el + mh-e.texi mh-acros.el mh-gnus.el mh-search.el mh-unit.el mh-inc.el + mh-xemacs-compat.el mh-print.el Makefile.in image.el and 88 other files + +Bjorn Solberg: changed nnimap.el + +Bj,Av(Brn Lindstr,Av(Bm: changed rcirc.texi + +Bj,Av(Brn Torkelsson: changed gnus-art.el gnus-group.el gnus-srvr.el + gnus-sum.el gnus-mlspl.el gnus-msg.el message.el dgnushack.el + gnus-agent.el gnus-cus.el gnus-gl.el gnus-nocem.el gnus-score.el + gnus-topic.el gnus.el mail-source.el nnmail.el + +Bj,Ax(Brn Mork: changed gnus-agent.el message.el mml2015.el + +Blitz Product Development Corporation: wrote ispell.el + +Boaz Ben-Zvi: wrote profile.el + +Bob Glickstein: wrote sregex.el +and changed isearch.el sendmail.el + +Bob Halley: changed esh-io.el + +Bob Rogers: changed ffap.el thingatpt.el + +Bob Weiner: changed info.el quail.el + +Boris Goldowsky: wrote avoid.el descr-text.el enriched.el facemenu.el + format.el shadowfile.el +and changed fill.el simple.el indent.el paragraphs.el cmds.c intervals.c + intervals.h add-log.el cc-mode.el enriched.doc fileio.c make-mode.el + text-mode.el textprop.c ada.el allout.el awk-mode.el bibtex.el buffer.c + buffer.h c-mode.el and 38 other files + +Boris Samorodov: changed imap.el + +Boyd Lynn Gerber: changed configure.in + +Brad Howes: changed gnus-demon.el + +Brad Miller: wrote gnus-gl.el + +Brendan Kehoe: changed hpux9.h + +Brian D. Carlstrom: changed gud.el smtpmail.el + +Brian Fox: changed Makefile.in configure.in minibuf.c dired.el files.el + rmail.el search.c simple.el sysdep.c Makefile compile.el forms.texi + frame.c info.texi keyboard.c make-dist subr.el systty.h xterm.c INSTALL + alloc.c and 44 other files + +Brian Marick: wrote hideif.el + +Brian P Templeton: changed erc.el erc-compat.el erc-fill.el + erc-nickserv.el erc-pcomplete.el erc-stamp.el erc-track.el + +Brian Palmer: changed erc.el erc-list.el + +Brian Preble: changed abbrev.el apropos.el asm-mode.el doctex.el + abbrevlist.el ada.el add-log.el appt.el array.el autoload.el + awk-mode.el bg-mouse.el bib-mode.el blackbox.el buff-menu.el + bug-screen.el bytecomp.el c++-mode.el c-comment.el c-fill.el c-mode.el + and 92 other files + +Bruno Haible: changed INSTALL emacs.1 epaths.in info.el paths.el + +Bryan D. O'connor: changed make-package + +Bryan Henderson: changed Makefile term.el + +Bryan O'sullivan: changed ange-ftp.el + +Caleb Deupree: changed winnt.el + +Carl D. Roth: changed gnus-nocem.el + +Carsten Bormann: changed ibmrs6000.h + +Carsten Dominik: wrote idlw-complete-structtag.el idlw-toolbar.el org.el + reftex-auc.el reftex-cite.el reftex-dcr.el reftex-global.el + reftex-index.el reftex-parse.el reftex-ref.el reftex-sel.el + reftex-toc.el reftex-vars.el reftex.el +and changed org.texi orgcard.tex idlw-shell.el idlwave.el idlw-rinfo.el + reftex.texi reftex-vcr.el diary-lib.el bibtex.el bookmark.el files.el + idlwave-rinfo.el idlwave-shell.el idlwave-toolbar.el + +Caveh Jalali: changed configure.in intel386.h sol2-4.h + +Changwoo Ryu: changed files.el + +Chao-Hong Liu: changed TUTORIAL.cn TUTORIAL.zh + +Charles Hannum: changed aix3-1.h aix3-2.h configure ibmrs6000.h + keyboard.c netbsd.h pop.c sysdep.c systime.h systty.h xrdb.c + +Charlie Martin: wrote autoinsert.el + +Cheng Gao: changed MORE.STUFF flymake.el tips.texi url-dired.el + url-file.el url-handlers.el url-http.el url-nfs.el + +Chong Yidong: changed cus-edit.el simple.el files.el custom.el + display.texi xdisp.c longlines.el files.texi info.el keyboard.c + compile.el custom.texi text.texi xterm.c frames.texi image-mode.el + mouse.el misc.texi startup.el wid-edit.el cus-theme.el + and 297 other files + +Chris Hanson: changed xscheme.el scheme.el xterm.c hpux.h x11term.c + hp9000s300.h keyboard.c process.c texinfmt.el emacsclient.c sort.el + syntax.c texnfo-upd.el x11fns.c xfns.c dired.el fileio.c hp9000s800.h + indent.c info.el man.el and 17 other files + +Chris Moore: changed dired.el hexl.el replace.el Makefile.in gnus-sum.el + isearch.el jka-cmpr-hook.el pgg-gpg.el pgg-pgp.el pgg-pgp5.el + tutorial.el wdired.el + +Chris Prince: changed w32term.c + +Chris Smith: wrote icon.el +and changed icon-mode.el + +Christian Limpach: changed configure.in + +Christian Lynbech: changed appt.el emacsserver.c + +Christian Neukirchen: changed mm-util.el + +Christian Plaunt: wrote soundex.el + +Christian Von Roques: changed gnus-start.el + +Christoph Bauer: changed configure.in + +Christoph Conrad: changed gnus-agent.el gnus-score.el makefile.w32-in + qp.el + +Christoph Wedler: wrote antlr-mode.el +and changed format.el gnus-art.el gnus-picon.el message.el register.el + smiley.el texinfmt.el + +Christopher Allan Webber: changed gamegrid.el tetris.el + +Christopher J. Madsen: wrote decipher.el +and changed files.el ispell.el replace.el time.el + +Chunyu Wang: changed gnus-art.el pcl-cvs.texi + +Claudio Fontana: changed Makefile.in + +Colin Marquardt: changed gnus.el message.el + +Colin Rafferty: changed message.el + +Colin Walters: wrote ibuf-ext.el ibuf-macs.el ibuffer.el +and changed calc.el replace.el update-game-score.c calc-ext.el + calc-misc.el Makefile.in calc-macs.el calc-mode.el calc-graph.el + gamegrid.el calc-aent.el calc-bin.el calc-embed.el calc-keypd.el + calc-math.el calc-prog.el calc-units.el calcalg2.el font-core.el + info.el calc-alg.el and 78 other files + +Craig Mcdaniel: changed sheap.c + +Daiki Ueno: wrote pgg-def.el pgg-gpg.el pgg-parse.el pgg-pgp.el + pgg-pgp5.el pgg.el starttls.el +and changed gnus-sum.el mml2015.el gnus-agent.el gnus-srvr.el + message.texi mml1991.el pgg.texi + +Dale Gulledge: changed TUTORIAL.eo + +Dale Hagglund: changed unexelf.c + +Dale R. Worley: wrote emerge.el (public domain) +and changed mail-extr.el + +Damien Elmes: changed erc.el erc-dcc.el erc-track.el erc-log.el + erc-pcomplete.el README erc-button.el erc-nets.el erc-ring.el Makefile + erc-fill.el erc-match.el erc-members.el erc-nickserv.el + +Damon Anton Permezel: wrote hanoi.el (public domain) + +Dan Christensen: changed gnus-sum.el nnfolder.el gnus-art.el + gnus-group.el gnus-registry.el gnus-score.el nndoc.el nnmail.el + +Dan Nicolaescu: wrote iris-ansi.el romanian.el +and changed term.el xterm.el hideshow.el isearch.el icon.el lisp.h + cus-edit.el faces.el font-lock.el grep.el sh-script.el eterm-color.ti + ibuffer.el rxvt.el vhdl-mode.el xterm.c bindings.el compile.el + dabbrev.el imenu.el outline.el and 166 other files + +Daniel Brockman: changed cus-start.el format-spec.el ibuffer.el rcirc.el + +Daniel Laliberte: wrote cl-specs.el cust-print.el edebug.el hideif.el + isearch.el +and changed mlconvert.el eval-region.el + +Daniel M Coffman: changed arc-mode.el + +Daniel N,Ai(Bri: changed message.el + +Daniel Ortmann: changed paragraphs.el + +Daniel Pfeiffer: wrote conf-mode.el copyright.el executable.el + sh-script.el skeleton.el two-column.el wyse50.el +and changed compile.el files.el make-mode.el apropos.el buff-menu.el + font-lock.el grep.el mpuz.el sgml-mode.el autoinsert.el cperl-mode.el + facemenu.el gomoku.el help.el imenu.el autoload.el autorevert.el + bindings.el button.el cc-fonts.el cc-mode.el and 12 other files + +Daniel Pittman: wrote tramp-vc.el +and changed gnus-spec.el gnus-sum.el nnimap.el + +Daniel Quinlan: changed dired.el info.el + +Danny Roozendaal: wrote handwrite.el + +Danny Siu: changed gnus-picon.el gnus-sum.el nndoc.el nnimap.el smiley.el + +Darren Stalder: changed gnus-util.el + +Darrin B. Jewell: changed etags.c lisp.h + +Dave Lambert: changed sol2-5.h xfns.c xterm.c xterm.h + +Dave Love: wrote autoarg.el autoconf.el benchmark.el cfengine.el + code-pages.el elide-head.el georgian.el hl-line.el latin-8.el + latin-9.el latin1-disp.el python.el refill.el rfc1345.el sgml-input.el + smiley.el subst-big5.el subst-gb2312.el subst-jis.el subst-ksc.el + tool-bar.el ucs-tables.el uni-input.el utf-16.el utf-7.el utf-8-lang.el + welsh.el +and changed configure.in Makefile.in help.el fortran.el browse-url.el + mule-cmds.el simple.el xterm.c cus-edit.el files.el info.el mule.el + wid-edit.el fns.c vc.el rfc2047.el bindings.el cus-start.el buffer.c + byte-opt.el bytecomp.el and 727 other files + +Dave Pearson: wrote 5x5.el quickurl.el + +David A. Capello: changed etags.c + +David Abrahams: changed coding.c + +David Bakhash: wrote strokes.el + +David Byers: changed minibuf.c + +David Casperson: changed menu-bar.el tex-mode.el + +David Edmondson: changed message.el gnus-cite.el imap.el mm-view.el + nnfolder.el nnml.el + +David Gillespie: wrote calc-aent.el calc-alg.el calc-arith.el calc-bin.el + calc-comb.el calc-cplx.el calc-embed.el calc-ext.el calc-fin.el + calc-forms.el calc-frac.el calc-funcs.el calc-graph.el calc-help.el + calc-incom.el calc-keypd.el calc-lang.el calc-macs.el calc-map.el + calc-math.el calc-misc.el calc-mode.el calc-mtx.el calc-poly.el + calc-prog.el calc-rewr.el calc-rules.el calc-sel.el calc-stat.el + calc-store.el calc-stuff.el calc-trail.el calc-undo.el calc-units.el + calc-vec.el calc-yank.el calc.el calcalg2.el calcalg3.el calccomp.el + calcsel2.el cl-compat.el cl-extra.el cl-macs.el cl-seq.el cl.el + cl.texinfo complete.el edmacro.el +and changed info.el bytecomp.el + +David Hansen: changed nnrss.el cc-cmds.el lisp.el pcomplete.el tempo.el + +David Hedbor: changed gnus-art.el mm-decode.el mm-view.el gnus-agent.el + gnus-cite.el gnus-cus.el gnus-eform.el gnus-group.el gnus-msg.el + gnus-score.el gnus-spec.el gnus-util.el gnus.el mail-source.el + message.el mm-encode.el mm-util.el nndoc.el nnmail.el score-mode.el + webmail.el + +David Hunter: changed config.nt flymake.el ms-w32.h process.c + +David J. Mackenzie: changed configure.in etags.c fakemail.c movemail.c + wakeup.c Makefile cvtmail.c qsort.c termcap.c yow.c Makefile.in + avoid.el b2m.c digest-doc.c emacsclient.c emacsserver.c emacstool.c + etags-vmslib.c fortran.el hexl.c isearch.el and 12 other files + +David Kastrup: changed greek.el replace.el faq.texi search.c ange-ftp.el + help.el mouse.el Makefile.in calc.el desktop.el keymaps.texi + meta-mode.el process.c search.texi subr.el woman.el DEBUG DEVEL.HUMOR + MAILINGLISTS autoload.el browse-url.el and 37 other files + +David K,Ae(Bgedal: wrote tempo.el +and changed sendmail.el xmenu.c + +David Lawrence: changed loaddefs.el comint.el simple.el files.el + c++-mode.el compile.el inf-lisp.el shell.el tex-mode.el MACHINES + Makefile c-mode.el cl.el dired.el emacs.1 emacsserver.c emerge.el + gnus.el history.el lisp-mode.el lisp.el and 78 other files + +David M. Brown: wrote array.el + +David M. Koppelman: changed hi-lock.el display.texi + +David M. Koppelman, Koppel@Ece.Lsu.Edu: wrote hi-lock.el + +David M. Smith: wrote ielm.el +and changed imenu.el + +David Mccabe: changed lisp-mode.el + +David Megginson: wrote derived.el +and changed mode-clone.el + +David Moore: wrote nnvirtual.el +and changed gnus-xmas.el + +David Mosberger-Tang: changed alpha.h unexelf.c cm.h config.in + configure.in cvtmail.c data.c dispnew.c emacsserver.c etags.c + fakemail.c keyboard.c mem-limits.h process.c profile.c sorted-doc.c + sysdep.c terminfo.c unexelf1.c yow.c + +David Ponce: wrote recentf.el ruler-mode.el tree-widget.el +and changed w32menu.c w32term.c close.png close.xpm empty.png empty.xpm + end-guide.png end-guide.xpm files.el guide.png guide.xpm handle.png + handle.xpm keyboard.c leaf.png leaf.xpm no-guide.png no-guide.xpm + no-handle.png no-handle.xpm open.png and 21 other files + +David Reitter: wrote mailclient.el +and changed commands.h cus-edit.el easy-mmode.el emacsbug.el + emacsclient.c keymap.c macterm.c menu-bar.el minibuf.c python.el + sendmail.el url-http.el + +David Robinson: changed menu-bar.el x-win.el + +David S. Goldberg: changed gnus-art.el message.el + +David Vazquez: changed m4-mode.el + +David Z. Maze: changed nnml.el nnrss.el + +Davis Herring: changed timeclock.el + +Deanna Phillips: changed configure.in + +Decklin Foster: changed nngateway.el + +Deepak Goel: changed README ada-mode.el ada-xref.el appt.el apropos.el + artist.el bibtex.el bookmark.el calc-forms.el calc-mode.el + calc-units.el calc.el cmacexp.el decipher.el desktop.el diary-lib.el + dired-aux.el dnd.el doctor.el ebnf2ps.el echistory.el + and 50 other files + +Denis Bueno: changed autorevert.el + +Denis Howe: wrote browse-url.el + +Denis St,A|(Bnkel: changed ibuf-ext.el + +Derek Atkins: changed imap.el pgg-pgp.el + +Derek L. Davies: changed gud.el + +Detlev Zundel: wrote re-builder.el + +Dhruva Krishnamurthy: changed makefile.w32-in + +Diane Murray: changed erc.el erc-menu.el erc-backend.el erc-button.el + erc-track.el erc-match.el erc-nets.el erc-list.el erc-autoaway.el + erc-capab.el erc-nickserv.el erc-stamp.el erc-compat.el erc-fill.el + erc-goodies.el erc-ibuffer.el erc-log.el Makefile erc-dcc.el + erc-networks.el erc-nicklist.el and 32 other files + +Dick King: wrote uniquify.el + +Didier Verna: wrote gnus-diary.el nndiary.el +and changed nntp.el gnus-art.el gnus-msg.el gnus-group.el gnus-start.el + gnus-sum.el gnus-xmas.el gnus-picon.el gnus-salt.el cus-edit.el rect.el + dgnushack.el gnus-agent.el gnus-ems.el gnus-fun.el gnus-topic.el + gnus.texi message.el nnmail.el nnmbox.el smiley.el + +Dirk Herrmann: changed bibtex.el + +Dmitry Antipov: changed keyboard.c + +Dominique De Waleffe: changed pcvs-info.el + +Don Morrison: wrote dabbrev.el + +Don Woods: changed replace.el + +Doug Cutting: wrote disass.el + +Doug Maxey: changed mouse.el + +Drew Adams: changed speedbar.el + +E. Jay Berkenbilt: changed flyspell.el ispell.el window.h + +Ed L. Cashin: changed gnus-sum.el imap.el + +Ed Swarthout: changed hexl.el + +Eduardo Mu,Aq(Boz: changed dired.el ls-lisp.el + +Edward M. Reingold: wrote cal-china.el cal-coptic.el cal-french.el + cal-islam.el cal-iso.el cal-julian.el cal-menu.el cal-move.el + cal-persia.el calendar.el diary-lib.el holidays.el lunar.el solar.el +and changed diary.el tex-mode.el cal-tex.el cal-mayan.el holiday.el + cal-x.el cal-hebrew.el cal-chinese.el cal-dst.el diary-ins.el + diary-insert.el cal-persian.el cal-islamic.el calendar.texi + list-holidays.el + +Edward O'connor: changed erc.el erc-viper.el erc-log.el erc-track.el + viper.el erc-backend.el erc-chess.el erc-dcc.el erc-ezbounce.el + erc-goodies.el erc-list.el erc-macs.el erc-match.el erc-ring.el + erc-stamp.el goto-addr.el python.el + +Edwin Steiner: changed gnus-nocem.el + +Ehud Karni: changed rmail.el aviion-intel.h compile.el complete.el + configure.in frame.el rmailsum.el sort.el xdisp.c + +Eirik Fuller: changed ralloc.c xterm.c + +Eli Barzilay: wrote calculator.el + +Eli Tziperman: wrote rmail-spam-filter.el + +Eli Zaretskii: wrote codepage.el rxvt.el tty-colors.el +and changed msdos.c Makefile.in makefile.w32-in files.el info.el fileio.c + startup.el mainmake.v2 config.bat rmail.el menu-bar.el pc-win.el + simple.el msdos.h internal.el xfaces.c emacs.c frame.c INSTALL dosfns.c + faces.el and 532 other files + +Emanuele Giaquinta: changed rxvt.el configure.in etags.c frame.el + sh-script.el text.texi + +Emilio C. Lopes: changed woman.el cmuscheme.el help.el vc.el advice.el + animate.el apropos.el artist.el bookmark.el cal-menu.el calc-prog.el + calc-store.el calcalg3.el calendar.el calendar.texi checkdoc.el + code-pages.el codepage.el compile.el completion.el cus-edit.el + and 53 other files + +Emmanuel Briot: wrote ada-prj.el xml.el +and changed ada-mode.el ada-stmt.el ada-xref.el + +Enami Tsugutomo: changed frame.c keyboard.c dispnew.c fileio.c process.c + xdisp.c add-log.el bytecomp.el configure.in editfns.c emacs.c frame.h + gnus-group.el perl-mode.el rmailsum.el simple.el sysdep.c vc.el + window.c window.el + +Era Eriksson: changed dired.el shell.el + +Eric Decker: changed hp9000s800.h hpux.h sysdep.c + +Eric Ding: wrote goto-addr.el +and changed mh-utils.el mh-e.el mh-comp.el mh-mime.el + +Eric Eide: changed gnus-xmas.el + +Eric Hanchrow: changed TUTORIAL.es abbrev.el autorevert.el cperl-mode.el + delphi.el dired.el emacsclient.c erc.el ispell.el make-dist + +,AI(Bric Jacoboni: changed fr-refcard.tex + +Eric Knauel: changed gnus.el spam-report.el spam.el + +Eric M. Ludlam: wrote checkdoc.el dframe.el ezimage.el sb-image.el + speedbar.el +and changed info.el rmail.el speedbspec.el gud.el Makefile.in comint.el + dir lisp-mnt.el rmailout.el sb-*.xpm sb-dir+.xpm sb-dir-.xpm + sb-dir-minus.xpm sb-dir-plus.xpm sb-dir.xpm sb-file+.xpm sb-file-.xpm + sb-file.xpm sb-mail.xpm sb-pg-minus.xpm sb-pg-plus.xpm + and 10 other files + +Eric Marsden: changed gnus-cache.el url-util.el + +Eric S. Raymond: wrote AT386.el asm-mode.el cookie1.el finder.el gud.el + keyswap.el lisp-mnt.el loadhist.el +and changed vc.el Makefile.in files.el comint.el loaddefs.el simple.el + vc-hooks.el cust-print.el dired.el emacsbug.el help.el isearch.el + makefile.el tex-mode.el x-win.el bibtex.el buff-menu.el bytecomp.el + c-mode.el cmulisp.el cmuscheme.el and 217 other files + +Eric Youngdale: changed etags-vmslib.c + +Erik Naggum: wrote disp-table.el latin-4.el latin-5.el mailheader.el + parse-time.el +and changed simple.el emacs.c files.el lread.c rmail.el alloc.c editfns.c + keyboard.c apropos.el configure.in dispnew.c filelock.c fns.c keymap.c + lisp.h print.c process.c add-log.el buffer.c casetab.c cl-macs.el + and 112 other files + +Erik Toubro Nielsen: changed gnus-sum.el gnus-topic.el + +Espen Skoglund: wrote pascal.el + +Ethan Bradford: changed ispell.el ange-ftp.el gnus.el gnuspost.el lpr.el + mailalias.el vt-control.el + +Eugene Exarevsky: changed sql.el + +Evgeni Dobrev: changed man.el + +Evgeny Roubinchtein: changed mail-source.el pc-select.el + +F. Thomas May: wrote blackbox.el + +Fabrice Bauzac: changed dired-aux.el + +Fabrice Popineau: changed etags.c gnus-cache.el + +Faried Nawaz: changed message.el + +Felix Lee: changed flyspell.el outline.el compile.el data.c gud.el + nntp.el process.c vc.el xdisp.c + +Ferenc Wagner: changed nnweb.el + +Flemming Hoejstrup Hansen: changed forms.el + +Florian Weimer: changed message.el gnus.el coding.c gnus.texi mm-util.el + +Francesc Rocher: changed cus-start.el macterm.c w32term.c xdisp.c xterm.c + +Francesco Potort,Al(B: wrote cmacexp.el +and changed etags.c man.el delta.h undigest.el etags.1 comint.el + configure.in uniquify.el latin-post.el maintaining.texi rmail.el + Makefile.in etags.el latin-alt.el sgml-mode.el data.c european.el + filelock.c files.el generic-x.el gud.el and 43 other files + +Francis J. Wright: wrote woman.el +and changed dired.el comint.el files.el + +Francis Litterio: changed erc.el erc-list.el erc-dcc.el erc-notify.el + erc-button.el erc-goodies.el erc-nets.el erc-ring.el Makefile + erc-pcomplete.el erc-backend.el erc-ibuffer.el erc-match.el + erc-nickserv.el erc-page.el erc-speedbar.el gnus-util.el keymaps.texi + message.el os.texi saveplace.el and 4 other files + +Francois Felix Ingrand: changed gnus-salt.el + +Frank Bennett: changed nnmail.el + +Frank Bresz: wrote diff.el + +Frank Schmitt: changed gnus-sum.el gnus-util.el + +Frank Weinberg: changed gnus-art.el + +Fran,Ag(Bois Pinard: changed nndoc.el allout.el bytecomp.el gnus-sum.el + gnus-util.el gnus-uu.el make-mode.el nnmail.el rmailsum.el timezone.el + +Fran,Ag(Bois-David Collin: changed message.el mm-decode.el + +Fred Fish: changed linux.h unexec.c + +Fred Oberhauser: changed nnmail.el + +Frederic Han: changed iso-cvt.el + +Frederic Lepied: wrote expand.el +and changed gnus.el + +Frederic Pierresteguy: wrote widget.c +and changed xmenu.c xterm.c xfns.c dpx2.h lwlib.c rmailsum.el rmail.el + xlwmenu.c xterm.h lwlib-Xaw.c lwlib-Xlw.c Makefile.in configure.in + lwlib-Xaw.h lwlib-int.h xdisp.c compile.el editfns.c fns.c frame.h + hilit19.el and 9 other files + +Frederik Fouvry: changed sendmail.el TUTORIAL.nl emacs.bash faces.el + filecache.el mailalias.el rmail.el thumbs.el + +Fritz Knabe: changed mh-mime.el + +Fr,Ai(Bd,Ai(Bric Bothamy: changed TUTORIAL.fr + +G Dinesh Dutt: changed etags.el + +Gareth Jones: changed fns.c gnus-score.el + +Garrett Wollman: changed sendmail.el + +Gary Byers: changed xenix.h + +Gary D. Foster: wrote crisp.el scroll-all.el +and changed gnus-group.el gnus-topic.el + +Gary Delp: wrote mailpost.el (public domain) + +Gary Howell: changed server.el + +Gary Oberbrunner: changed gud.el + +Gary Wong: changed termcap.c tparam.c + +Gaute B Strokkenes: changed imap.el gnus-fun.el mail-source.el process.c + +Geoff Greene: changed message.el + +Geoff Voelker: wrote lisp/makefile.nt nt.c nt.h ntheap.c ntheap.h + ntinevt.c ntproc.c ntterm.c src/makefile.nt w32-fns.el windowsnt.h + winnt.el +and changed w32.c w32fns.c fileio.c w32heap.c w32term.c w32inevt.c + callproc.c s/ms-w32.h w32proc.c unexw32.c w32term.h dos-w32.el + emacs.bat loadup.el w32-win.el emacs.c keyboard.c process.c + w32console.c addpm.c cmdproxy.c and 106 other files + +Georg C. F. Greve: changed pgg-gpg.el + +George V. Reilly: changed emacs.ico + +Georges Brun-Cottan: wrote easy-mmode.el + +Gerd M,Av(Bllmann: wrote authors.el ebrowse.el jit-lock.el rx.el tooltip.el +and changed xdisp.c xterm.c dispnew.c dispextern.h xfns.c xfaces.c + window.c keyboard.c lisp.h Makefile.in faces.el alloc.c buffer.c + startup.el xterm.h fns.c simple.el term.c configure.in frame.c xmenu.c + and 620 other files + +Gergely Nagy: changed erc.el + +Germano Caronni: changed ralloc.c + +Gernot Heiser: changed refer.el + +Giorgos Keramidas: changed configure.in MACHINES amdx86-64.h apropos.el + display.texi fringe.c fringe.el lisp.h windows.texi xmenu.c + +Giuseppe Scrivano: changed buffer.c configure.in sysdep.c xsmfns.c + +Glenn Morris: changed f90.el diary-lib.el calendar.el fortran.el + calendar.texi appt.el sh-script.el Makefile.in timeclock.el cal-menu.el + files.el complete.el configure.in programs.texi startup.el MACHINES + abbrevs.texi cal-hebrew.el cal-islam.el emacs.texi faq.texi + and 151 other files + +Glynn Clements: wrote gamegrid.el snake.el tetris.el + +Gordon Matzigkeit: changed gnus-uu.el + +Greg Hill: changed bytecomp.el + +Greg Hudson: changed configure.in indent.c + +Greg Klanderman: changed messagexmas.el + +Greg Mcgary: changed tar-mode.el + +Greg Stark: changed gnus-ems.el timezone.el + +Gregor Schmid: wrote tcl-mode.el +and changed intervals.c intervals.h textprop.c dispnew.c indent.c xdisp.c + +Gregorio Gervasio, Jr.: changed gnus-sum.el + +Gregory Chernov: changed nnslashdot.el + +Gregory Neil Shapiro: changed mailabbrev.el + +Guanpeng Xu: changed add-log.el TUTORIAL.cn display.texi mouse.el + type-break.el + +Guillermo J. Rozas: wrote fakemail.c + +Gunnar Horrigmo: changed gnus-sum.el + +Gustav H,Ae(Bllberg: changed compile.el rect.el + +Guy Geens: changed gnus-score.el + +G,Av(Bran Uddeborg: changed isc4-1.h + +Hallvard B. Furuseth: changed gnus-util.el editfns.c gnus-cache.el + gnus-sum.el lread.c messcompat.el nntp.el print.c process.c search.c + +Han Boetes: changed netbsd.h + +Han-Wen Nienhuys: changed emacsclient.c server.el + +Hans Chalupsky: wrote advice.el trace.el +and changed bytecomp.el + +Hans De Graaff: changed mml.el + +Hans Henrik Eriksen: wrote simula.el + +Harald Maier: changed w32heap.c + +Harald Meland: changed gnus-art.el gnus-salt.el gnus-score.el + gnus-util.el gnus-win.el + +Heiko Muenkel: changed b2m.c + +Helmut Waitzmann: changed gnus-sum.el gnus.texi + +Henrik Enberg: changed gnus-art.el gnus-msg.el lread.c rmailout.el + xfaces.c + +Henry Guillaume: wrote find-file.el + +Henry Kautz: wrote bib-mode.el refbib.el + +Hewlett-Packard: changed emacsclient.c emacsserver.c keyboard.c server.el + +Hideki Iwamoto: changed etags.c + +Hiroshi Fujishima: changed faq.texi mail-source.el spam-stat.el + +Hiroshi Nakano: changed ralloc.c unexelf.c + +Hoan Ton-That: changed erc-log.el + +Holger Schauer: wrote fortune.el +and changed message-utils.el + +Hovav Shacham: wrote windmove.el + +Howard Gayle: wrote case-table.el casetab.c disp-table.el iso-ascii.el + iso-insert.el iso-swed.el iso-syntax.el iso-transl.el latin-1.el + rot13.el swedish.el vt100-led.el + +Howard Melman: changed imenu.el picture.el + +Howie Kaye: wrote sort.el + +Hrvoje Nik,B9(Bi,Bf(B: wrote croatian.el savehist.el +and changed gnus-xmas.el message.el nnmail.el fileio.c fns.c gnus-art.el + gnus-salt.el gnus-spec.el mm-decode.el add-log.el appt.el arc-mode.el + avoid.el bookmark.el cal-china.el cal-tex.el calendar.el cl-indent.el + cmacexp.el comint.el compile.el and 83 other files + +H,Ae(Bkan Granath: changed dired.el + +H,Ae(Bkon Malmedal: changed calendar.el holidays.el + +Ian Lance Taylor: changed sco4.h + +Ian T Zimmerman: wrote gametree.el +and changed ange-ftp.el desktop.el tex-mode.el + +Ilja Weis: wrote gnus-topic.el + +Ilya N. Golubev: changed mm-util.el shell.el + +Ilya Zakharevich: wrote tmm.el +and changed cperl-mode.el syntax.c syntax.h textprop.c dired.c + font-lock.el interval.c intervals.c intervals.h regex.c regex.h + search.c + +Ilya Zakharevich And Bob Olson: wrote cperl-mode.el + +Indiana University Foundation: changed buffer.c buffer.h indent.c + region-cache.c region-cache.h search.c xdisp.c + +Inge Frick: changed easymenu.el keyboard.c view.el compile.el + dired-aux.el arc-mode.el dired.el files.el gnus-sum.el keyboard.h + keymap.c tar-mode.el window.el xmenu.c + +Inoue Seiichiro: changed xterm.c xfns.c xterm.h + +International Business Machines: changed emacs.c fileio.c ibmrt-aix.h + ibmrt.h process.c sysdep.c unexec.c + +Ishikawa Chiaki: changed aviion.h dgux.h + +Istvan Marko: changed gnus-agent.el xfns.c + +Ivan Boldyrev: changed mml1991.el + +Ivan Zakharyaschev: changed codepage.el lread.c + +Ivar Rummelhoff: wrote winner.el + +Iwamuro Motonori: changed gnus-kill.el + +J.D. Smith: changed idlwave.el idlw-shell.el idlw-help.el idlw-rinfo.el + idlw-toolbar.el comint.el idlwave.texi vc.el bibtex.el files.texi + hideshow.el idlw-complete-structtag.el misc.texi mouse.el + +Jaap-Henk Hoepman: changed mm-decode.el + +Jack Repenning: changed unexelfsgi.c + +Jack Twilley: changed message.el + +Jacob Morzinski: changed mh-comp.el + +Jacques Duthen: changed ps-print.el + +Jaeyoun Chung: changed hangul3.el hanja3.el gnus-mule.el hangul.el + +James Clark: wrote sgml-mode.el +and changed fns.c window.c xselect.c + +James Cloos: changed url-history.el + +James R. Larus: wrote mh-e.el + +James R. Van Zandt: changed sh-script.el + +James Troup: changed gnus-sum.el + +James Van Artsdalen: changed unexec.c usg5-4.h + +Jamie Zawinski: wrote byte-opt.el byte-run.el bytecomp.el disass.el + mailabbrev.el tar-mode.el +and changed bytecode.c mail-extr.el subr.el + +Jan Dj,Ad(Brv: wrote dnd.el x-dnd.el +and changed gtkutil.c xterm.c xfns.c xmenu.c xterm.h configure.in + gtkutil.h x-win.el Makefile.in keyboard.c frames.texi config.in + xselect.c emacs.c alloc.c xlwmenu.c xresources.texi frame.c startup.el + xdisp.c cus-start.el and 176 other files + +Jan Nieuwenhuizen: changed info.el TUTORIAL.nl emacs.c emacsclient.c + gnus-start.el gud.el nnmh.el server.el startup.el + +Jan Rychter: changed gnus-msg.el + +Jan Schormann: wrote solitaire.el + +Jan Vroonhof: changed gnus-cite.el gnus-msg.el nntp.el + +Jan-Hein Buhrman: changed ange-ftp.el env.el + +Jari Aalto: changed add-log.el filecache.el gnus-art.el lisp-mnt.el + nnmail.el apropos.el autorevert.el compile.el cperl-mode.el debug.el + executable.el files.el finder.el font-lock.el gnus.el gnus.texi grep.el + ls-lisp.el man.el sendmail.el terminal.el + +Jason Merrill: changed gnus-sum.el gnus-salt.el imap.el nnfolder.el + +Jason Rumney: wrote w32-vars.el +and changed w32fns.c w32term.c w32menu.c w32-win.el w32term.h + makefile.w32-in w32.c w32bdf.c w32-fns.el w32select.c w32console.c + w32gui.h w32proc.c keyboard.c mule-cmds.el emacs.c fileio.c w32bdf.h + w32inevt.c config.nt configure.bat and 84 other files + +Jay Belanger: changed calc.texi calc.el calc-ext.el calc-embed.el + calc-aent.el calc-prog.el calc-arith.el calc-help.el calc-lang.el + calcalg2.el COPYING calc-graph.el calc-store.el calc-units.el + calc-misc.el calc-yank.el calc-alg.el calc-poly.el calccomp.el + calc-mode.el calc-forms.el and 35 other files + +Jay K. Adams: wrote jka-cmpr-hook.el jka-compr.el + +Jay Sachs: changed gnus-score.el gnus-win.el + +Jean-Philippe Theberge: wrote thumbs.el + +Jeff Dwork: changed ehelp.el facemenu.el + +Jeff Miller: changed appt.el + +Jeff Morgenthaler: changed flow-ctrl.el vt200.el vt201.el vt220.el + vt240.el + +Jeff Norden: wrote kermit.el + +Jeff Peck: wrote sun-curs.el sun-fns.el sun-mouse.el sun.el + +Jeffrey C Honig: wrote mh-print.el +and changed mh-comp.el mh-e.el mh-utils.el mh-customize.el mh-funcs.el + mh-mime.el mh-seq.el Makefile bsdos4.h mh-alias.el mh-junk.el + mh-loaddefs.el + +Jens Krinke: changed smime.el + +Jens Lautenbacher: changed gnus.el + +Jens Petersen: wrote find-func.el +and changed ffap.el mule-cmds.el + +Jens Toivo Berger Thielemann: changed word-help.el + +Jens-Ulrik Holger Petersen: changed cus-edit.el find-func.el gnus.el + +Jeramey Crawford: changed amdx86-64.h configure.in + +Jeremy Bertram Maitin-Shepard: changed erc.el erc-backend.el + erc-button.el mml.el + +Jerry Frain: changed systime.h usg5-4.h + +Jerry James: changed format.el dns.el gnus-util.el gnus-xmas.el + +Jesper Harder: wrote yenc.el +and changed gnus-art.el gnus-sum.el message.el gnus-msg.el gnus.el + gnus-group.el mm-bodies.el gnus-util.el mm-util.el mm-decode.el mml.el + rfc2047.el mailcap.el mm-uu.el mml1991.el pgg-gpg.el smtpmail.el + gnus-srvr.el info.el nnmail.el pgg.el and 178 other files + +Jhair Tocancipa Triana: changed gnus-audio.el + +Jim Blandy: wrote tvi970.el +and changed keyboard.c xterm.c xfns.c Makefile.in window.c process.c + dispnew.c xdisp.c sysdep.c configure.in lisp.h keymap.c configure + make-dist buffer.c frame.c screen.c x-win.el simple.el alloc.c emacs.c + and 389 other files + +Jim Kingdon: changed MACHINES SERVICE emacsclient.c emacs.tex hp300bsd.h + rmail.el + +Jim Meyering: changed Makefile.in grep-changelog + +Jim Radford: changed gnus-start.el + +Jim Salem: wrote completion.el + +Jim Thompson: wrote ps-print.el + +Jim Wilson: changed Makefile.in alloca.c + +Jindrich Makovicka: changed eval.c fns.c + +Jirka Kosek: changed mule.el + +Joakim Hove: wrote html2text.el + +Joakim Verona: changed nnrss.el + +Joanna Pluta: changed TUTORIAL.pl + +Jochen Hein: changed gnus-art.el + +Jochen K,A|(Bpper: changed calc-units.el gnus.texi + +Joe Buehler: changed Makefile.in configure.in cygwin.h MACHINES + browse-url.el comint.el configure dired-aux.el dired.el dirtrack.el + dos-w32.el fast-lock.el filecache.el fileio.c files.el gmalloc.c + gnus-util.el hippie-exp.el keyboard.c lastfile.c loadup.el + and 12 other files + +Joe Casadonte: changed gnus-srvr.el + +Joe Corneli: changed subr.el + +Joe Edmonds: changed lisp-mode.el + +Joe Kelsey: changed skeleton.el + +Joe Ramey: changed filelock.c rmailsum.el + +Joe Reiss: changed gnus-art.el + +Joe Wells: wrote apropos.el mail-extr.el resume.el +and changed arc-mode.el + +Joel N. Weber Ii: changed comint.el make-dist + +Joel Ray Holveck: changed gnus-sum.el info.el + +Joev Dubach: changed nntp.el + +Johan Bockg,Ae(Brd: changed erc.el erc-backend.el cl-macs.el erc-match.el + custom.el erc-nickserv.el erc-ring.el erc-speak.el erc-track.el + simple.el align.el bytecomp.el calendar.el cl.texi dired-aux.el + dired-x.el display.texi erc-bbdb.el erc-button.el erc-compat.el + erc-dcc.el and 16 other files + +Johan Vromans: wrote forms-d2.el forms.el iso-acc.el +and changed complete.el + +John Basrai: changed man.el + +John F. Carr: changed dired.c + +John F. Whitehead: changed mule-cmds.el mule-diag.el + +John Fremlin: changed gnus-msg.el message.el + +John Grabowski: changed xfaces.c xfns.c + +John H. Palmieri: changed gnus-fun.el + +John Heidemann: wrote mouse-copy.el mouse-drag.el + +John Hughes: changed term.c + +John J Foerch: changed erc-stamp.el + +John Mongan: changed f90.el + +John Paul Wallington: changed ibuffer.el ibuf-ext.el subr.el files.el + help-fns.el rmail.el thumbs.el fns.c bindings.el bytecomp.el + cus-theme.el info.el re-builder.el simple.el startup.el xfns.c + apropos.el arc-mode.el browse-url.el comint.el cus-start.el + and 117 other files + +John Robinson: wrote bg-mouse.el + +John Sullivan: changed window.c + +John Tobey: changed gud.el + +John W. Eaton: wrote octave-hlp.el octave-inf.el octave-mod.el + +John Wiegley: wrote align.el cal-bahai.el em-alias.el em-banner.el + em-basic.el em-cmpl.el em-dirs.el em-glob.el em-hist.el em-ls.el + em-pred.el em-prompt.el em-rebind.el em-script.el em-smart.el + em-term.el em-unix.el em-xtra.el erc-identd.el esh-arg.el esh-cmd.el + esh-ext.el esh-io.el esh-maint.el esh-mode.el esh-module.el esh-opt.el + esh-proc.el esh-test.el esh-util.el esh-var.el eshell.el eudcb-mab.el + isearchb.el pcmpl-cvs.el pcomplete.el timeclock.el +and changed erc-chess.el erc.el iswitchb.el Makefile.in allout.el + cal-menu.el calendar.el compile.el desktop.el diary-lib.el erc-bbdb.el + erc-button.el erc-complete.el erc-fill.el erc-ibuffer.el erc-list.el + erc-match.el erc-menu.el erc-nets.el erc-replace.el erc-speak.el + and 11 other files + +John Williams: changed etags.el + +Jon Ericson: changed gnus.el spam-report.el + +Jon K Hellan: wrote utf7.el + +Jonathan I. Kamens: changed pop.c movemail.c rmail.el configure.in + Makefile.in b2m.pl config.in files.el pop.h terminal.el vc.el + gnus-sum.el jka-compr.el rmailout.el rnewspost.el sendmail.el simple.el + timezone.el vc-hooks.el + +Jonathan Stigelman: wrote hilit19.el + +Jonathan Vail: changed vc.el + +Jonathan Yavner: wrote ses.el tcover-ses.el tcover-unsafep.el + testcover.el unsafep.el +and changed ses.texi Makefile.in edebug.el editfns.c files.el + functions.texi ses-example.ses subr.el variables.texi + +Jorgen Schaefer: wrote erc-autoaway.el erc-goodies.el erc-spelling.el +and changed erc.el erc-track.el erc-backend.el erc-match.el erc-stamp.el + erc-button.el erc-fill.el erc-truncate.el erc-compat.el erc-members.el + Makefile erc-dcc.el erc-ibuffer.el erc-page.el erc-pcomplete.el + erc-sound.el erc-bbdb.el erc-imenu.el erc-lang.el erc-list.el + erc-macs.el and 9 other files + +Jose E. Marchesi: changed smtpmail.el + +Joseph Arceneaux: wrote xrdb.c +and changed xterm.c xfns.c keyboard.c screen.c dispnew.c xdisp.c window.c + x-win.el fileio.c buffer.c xterm.h minibuf.c editfns.c lread.c + process.c alloc.c buffer.h screen.el files.el insdel.c emacs.c + and 105 other files + +Joseph M. Kelsey: changed dir.h fileio.c uaf.h vms-pwd.h vmsfns.c + +Josh Huber: changed mml-sec.el gnus-msg.el message.el mml.el mml2015.el + nnmail.el ChangeLog ChangeLog.1 gnus-cite.el gnus-delay.el gnus-spec.el + mml1991.el nnultimate.el nnwfm.el gnus-cus.el gnus-smiley.el + gnus-start.el gnus-topic.el gnus.el nnbabyl.el nndiary.el + and 8 other files + +Joshua Varner: changed intro.texi + +Jouni K. Sepp,Ad(Bnen: changed gnus.texi nnimap.el mm-url.el + +Juan Le,As(Bn Lahoz Garc,Am(Ba: wrote wdired.el +and changed files.el perl-mode.el + +Juanma Barranquero: changed makefile.w32-in subr.el faces.el help-fns.el + files.el simple.el buffer.c w32fns.c emacsclient.c replace.el + vhdl-mode.el bs.el cperl-mode.el eval.c org.el process.c xdisp.c + idlwave.el sh-script.el window.c ada-mode.el and 629 other files + +Juergen Hoetzel: changed url-handlers.el + +Juergen Nickelsen: wrote ws-mode.el + +Julien Avarre: changed gnus-fun.el + +Julien Gilles: wrote gnus-ml.el + +Junio Hamano: changed window.el + +Jure Cuhalev: changed ispell.el + +Juri Linkov: changed info.el simple.el replace.el isearch.el compile.el + faces.el display.texi grep.el descr-text.el cus-edit.el dired.el + dired-aux.el edebug.el compare-w.el files.el lisp-mode.el lisp.el + modes.texi mule.el desktop.el files.texi and 221 other files + +Justin Sheehy: changed gnus-sum.el nntp.el + +J,Ai(Br,At(Bme Marant: changed Makefile.in make-dist bindings.el configure.in + emacsclient.c misc.texi + +K. Shane Hartman: wrote chistory.el echistory.el electric.el emacsbug.el + helper.el picture.el view.el +and changed rmail.el loaddefs.el ebuff-menu.el dired.el simple.el + add-log.el lisp-mode.el shell.el buff-menu.el buffer.c c-mode.el + mail-utils.el mim-mode.el more-mode.el aton.el c++-mode.el cmds.c + compile.el files.el gud.el indent.el and 14 other files + +Kahlil Hodgson: changed timeclock.el + +Kai Gro,A_(Bjohann: wrote gnus-delay.el tramp-util.el tramp-uu.el tramp.el + trampver.el +and changed gnus-agent.el message.el gnus-sum.el files.el nnmail.el + tramp.texi gnus.el simple.el ange-ftp.el Makefile.in dired.el + paragraphs.el bindings.el files.texi gnus-art.el gnus-group.el man.el + nntp.el INSTALL crisp.el fileio.c and 44 other files + +Kailash C. Chowksey: changed HELLO Makefile.in ind-util.el kannada.el + knd-util.el loadup.el makefile.w32-in + +Kanematsu Daiji: changed nnimap.el + +Karl Berry: changed emacs.texi info.texi elisp.texi anti.texi + display.texi emacs-xtra.texi filelock.c gnu.texi mule.texi texinfo.tex + text.texi building.texi cmdargs.texi control.texi copyright.el + custom.texi customize.texi dired.c dired.texi faq.texi frames.texi + and 72 other files + +Karl Chen: changed files.el align.el cc-vars.el gnus-art.el help-mode.el + jka-cmpr-hook.el make-mode.el perl-mode.el python.el tex-mode.el + vc-svn.el + +Karl Eichwalder: changed Makefile.in add-log.el bookmark.el dired-aux.el + dired.el info.el menu-bar.el midnight.el po.el + +Karl Fogel: wrote bookmark.el mail-hist.el saveplace.el +and changed isearch.el menu-bar.el simple.el autogen.sh editfns.c + nnmail.el vc-svn.el window.c + +Karl Heuer: changed keyboard.c lisp.h xdisp.c buffer.c xfns.c xterm.c + alloc.c files.el frame.c configure.in window.c data.c minibuf.c + editfns.c fns.c process.c fileio.c simple.el keymap.c indent.c sysdep.c + and 444 other files + +Karl Kleinpaste: changed gnus-sum.el gnus-art.el gnus-picon.el + gnus-score.el gnus-uu.el gnus-xmas.el gnus.el mm-uu.el mml.el nnmail.el + smiley.el + +Karl M. Hegbloom: changed gnus.el + +Karl Pfl,Ad(Bsterer: changed gnus-art.el gnus-score.el spam-stat.el + +Katsuhiro Hermit Endo: changed gnus-group.el gnus-spec.el + +Katsumi Yamaoka: wrote canlock.el +and changed gnus-art.el message.el gnus-sum.el gnus.texi mm-decode.el + mm-view.el gnus-util.el gnus-msg.el mm-util.el gnus.el lpath.el + gnus-group.el gnus-start.el rfc2047.el dgnushack.el mm-uu.el nntp.el + gnus-agent.el mml.el nnrss.el message.texi and 72 other files + +Kaveh R. Ghazi: changed delta88k.h xterm.c + +Kawabata, Taichi: wrote indian.el +and changed devanagari.el ind-util.el Makefile.in devan-util.el + characters.el fontset.el malayalam.el mlm-util.el mule-conf.el tamil.el + tml-util.el + +Kayvan Sylvan: changed sc.el + +Kazushi Marukawa: changed filelock.c hexl.c profile.c unexalpha.c + +Keiichi Suzuki: changed nntp.el + +Keisuke Nishida: changed print.c alloc.c bytecomp.el data.c keymap.c + +Keith Gabryelski: wrote hexl.c hexl.el + +Ken Brush: changed emacsclient.c + +Ken Laprade: changed simple.el + +Ken Manheimer: wrote allout.el icomplete.el +and changed pgg-gpg.el pgg.el pgg-pgp.el pgg-pgp5.el edebug.el pgg.texi + tips.texi + +Ken Raeburn: changed lisp.h buffer.c alloc.c keyboard.c lread.c minibuf.c + coding.c Makefile.in editfns.c fileio.c fns.c keymap.c undo.c xdisp.c + xfns.c xterm.c charset.h fontset.c search.c window.c charset.c + and 84 other files + +Ken Stevens: wrote ispell.el + +Kenichi Handa: wrote cyrillic.el isearch-x.el py-punct.el pypunct-b5.el + quail.el thai-word.el +and changed coding.c mule-cmds.el mule.el charset.c fileio.c xterm.c + fns.c ccl.c Makefile.in mule-conf.el fontset.c charset.h coding.h + fontset.el mule-diag.el xdisp.c editfns.c process.c insdel.c + japanese.el characters.el and 286 other files + +Kenneth Stailey: changed alpha.h configure.in ns32000.h openbsd.h pmax.h + sparc.h unexalpha.c unexelf.c + +Kevin Blake: changed font-lock.el ring.el + +Kevin Broadey: wrote foldout.el + +Kevin Christian: changed gnus-score.el + +Kevin Gallagher: wrote edt-lk201.el edt-mapper.el edt-pc.el edt-vt100.el + edt.el flow-ctrl.el +and changed edt-user.doc + +Kevin Gallo: wrote w32-win.el +and changed dispnew.c addpm.c config.nt dispextern.h emacs.c facemenu.el + faces.el fns.c frame.c frame.h keyboard.c mouse.el ntterm.c process.c + s/ms-w32.h scroll.c startup.el sysdep.c term.c unexw32.c w32.c + and 16 other files + +Kevin Greiner: wrote legacy-gnus-agent.el +and changed gnus-agent.el gnus-start.el gnus-sum.el gnus-int.el gnus.el + nntp.el gnus-util.el gnus-group.el gnus-cus.el gnus-range.el + gnus-art.el gnus-cache.el gnus-srvr.el nnagent.el nnheader.el + dgnushack.el gnus-async.el gnus-draft.el gnus-registry.el gnus-salt.el + gnus-uu.el and 3 other files + +Kevin Layer: changed w32proc.c + +Kevin Rodgers: changed compile.el mailabbrev.el dired-x.el files.el + ange-ftp.el byte-opt.el desktop.el diff-mode.el dired-x.texi ffap.el + files.texi flyspell.el isearch.el killing.texi lisp.el loadhist.el + mailalias.el menu-bar.el print.c replace.el sendmail.el + and 5 other files + +Kevin Ryde: wrote info-xref.el +and changed info-look.el info.el arc-mode.el cl.texi gnus-art.el + gnus-sum.el mailcap.el mule.el os.texi text.texi MORE.STUFF cal-dst.el + calendar.texi cc-align.el cmdargs.texi compile.texi display.texi + em-alias.el em-dirs.el em-hist.el em-unix.el and 19 other files + +Kim F. Storm: wrote bindat.el cua-base.el cua-gmrk.el cua-rect.el ido.el + keypad.el kmacro.el +and changed xdisp.c dispextern.h process.c simple.el window.c keyboard.c + xterm.c subr.el w32term.c dispnew.c lisp.h fringe.c macterm.c + display.texi fns.c alloc.c xfaces.c keymap.c xfns.c xterm.h .gdbinit + and 255 other files + +Kim-Minh Kaplan: changed gnus-picon.el gnus-sum.el gnus-start.el + gnus-win.el gnus-xmas.el gnus.texi message.el nndraft.el nnml.el + +Kishore Kumar: changed terminal.el + +Klaus Straubinger: changed url-http.el url-history.el url-cookie.el + url.el + +Klaus Zeitler: changed configure.in files.el sh-script.el vcursor.el + +Koaunghi Un: wrote hanja3.el +and changed hanja.el hangul.el hangul3.el hanja-jis.el symbol-ksc.el + +Kobayashi Yasuhiro: changed w32fns.c configure.bat indent.c info.el + w32term.c w32term.h window.c xfns.c + +Kohtala Marko: changed info.el + +Koseki Yoshinori: wrote iimage.el +and changed nnmail.el + +Kurt B. Kaiser: changed message.el + +Kurt Hornik: wrote octave-hlp.el octave-inf.el octave-mod.el +and changed battery.el ielm.el term.el + +Kurt Swanson: changed gnus-art.el gnus-salt.el gnus-sum.el gnus-ems.el + gnus-group.el gnus-msg.el gnus-score.el gnus-util.el nnmail.el window.c + +Kyle Jones: wrote life.el mldrag.el +and changed saveconf.el buffer.c mail-utils.el sendmail.el + +Kyotaro Horiguchi: changed coding.c indent.c + +K,Aa(Broly L$,1 q(Brentey: changed xfns.c bindings.el keyboard.c HELLO authors.el + buff-menu.el buffer.c buffers.texi cmds.c coding.c editfns.c frame.el + menu-bar.el print.c simple.el xdisp.c xterm.c xterm.h + +Larry Kolodney: wrote cvtmail.c + +Lars Balker Rasmussen: changed gnus-art.el gnus-agent.el message.el + +Lars Brinkhoff: changed building.texi config.in configure.in editfns.c + fns.c os.texi + +Lars Hansen: changed desktop.el tramp.el info.el mh-e.el dired-x.el + dired-x.texi dired.el ls-lisp.el rmail.el dired.c files.texi grp.h + hilit-chg.el misc.texi url-auth.el url-cache.el url-dired.el url-ftp.el + url-irc.el url-misc.el url-news.el and 39 other files + +Lars Lindberg: wrote imenu.el msb.el +and changed dabbrev.el + +Lars Magne Ingebrigtsen: wrote compface.el dns.el format-spec.el + gnus-agent.el gnus-art.el gnus-async.el gnus-bcklg.el gnus-cache.el + gnus-demon.el gnus-draft.el gnus-dup.el gnus-eform.el gnus-ems.el + gnus-fun.el gnus-group.el gnus-int.el gnus-logic.el gnus-move.el + gnus-nocem.el gnus-picon.el gnus-range.el gnus-salt.el gnus-spec.el + gnus-srvr.el gnus-start.el gnus-sum.el gnus-undo.el gnus-util.el + gnus-uu.el gnus-win.el ietf-drums.el mail-parse.el mail-prsvr.el + mail-source.el message.el messcompat.el mm-bodies.el mm-decode.el + mm-encode.el mm-util.el mm-view.el mml.el netrc.el nnagent.el + nnbabyl.el nndir.el nndoc.el nndraft.el nneething.el nngateway.el + nnkiboze.el nnlistserv.el nnmail.el nnmbox.el nnmh.el nnoo.el + nnslashdot.el nnsoup.el nntp.el nnultimate.el nnweb.el nnwfm.el qp.el + rfc2045.el rfc2047.el rfc2231.el score-mode.el spam.el time-date.el +and changed gnus.el gnus-msg.el gnus-score.el gnus-topic.el gnus-xmas.el + nnfolder.el gnus-cite.el nnheader.el nnml.el lpath.el nnvirtual.el + dgnushack.el gnus-cus.el smiley-ems.el editfns.c gnus-mh.el + gnus-soup.el gnus.texi nnrss.el pop3.el fns.c and 46 other files + +Lasse Rasinen: changed gnus-start.el + +Laurent Martelli: changed mm-decode.el + +Lawrence Mitchell: wrote erc-backend.el erc-log.el erc-nicklist.el +and changed erc.el erc-match.el erc-nets.el erc-nickserv.el erc-button.el + erc-compat.el erc-dcc.el erc-fill.el erc-list.el erc-track.el Makefile + erc-autoaway.el erc-autojoin.el erc-bbdb.el erc-ezbounce.el erc-menu.el + erc-netsplit.el erc-notify.el erc-sound.el subr.el tempo.el + +Lawrence R. Dodd: wrote dired-x.el +and changed fortran.el ispell.el sendmail.el cmuscheme.el comint.el + compile.el dired.el find-dired.el gnus.el gud.el inf-lisp.el info.el + lisp.el loaddefs.el man.el minibuf.c rcs2log rmail.el simple.el + terminal.el text-mode.el and 4 other files + +Leigh Stoller: changed emacsclient.c emacsserver.c server.el + +Lennart Borgman: changed tutorial.el window.el ada-xref.el emacsclient.c + filesets.el flymake.el help-fns.el isearch.el mouse.el recentf.el + replace.el shell.el texinfmt.el w32term.c w32term.h + +Lennart Staflin: changed dired.el diary-ins.el diary-lib.el tq.el xdisp.c + +Leonard H. Tower Jr.: changed rnews.el rnewspost.el emacsbug.el + rmailout.el + +Levin Du: changed parse-time.el + +Liam Healy: changed outline.el + +Lloyd Zusman: changed mml.el pgg-gpg.el + +Luc Teirlinck: wrote help-at-pt.el +and changed files.el autorevert.el cus-edit.el subr.el simple.el + frames.texi startup.el display.texi files.texi Makefile.in dired.el + comint.el custom.texi emacs.texi fns.c frame.el ielm.el minibuf.texi + modes.texi variables.texi buffers.texi and 215 other files + +Lucid, Inc.: changed byte-opt.el byte-run.el bytecode.c bytecomp.el + delsel.el disass.el faces.el font-lock.el lmenu.el lselect.el + mailabbrev.el select.el xfaces.c xselect.c + +$,1 a(Bukasz Demianiuk: changed erc.el + +Lute Kamstra: changed modes.texi generic.el debug.el generic-x.el + font-lock.el subr.el Makefile.in debugging.texi easy-mmode.el + elisp.texi hl-line.el simple.el battery.el bindings.el calc.el + cmdargs.texi edebug.texi emacs.texi info.el make-tarball.txt + octave-inf.el and 216 other files + +Lynn Slater: wrote help-macro.el + +L,Bu(Brentey K,Ba(Broly: changed spam.el gnus-sum.el + +MCC: wrote xmenu.c +and changed emacsclient.c emacsserver.c etags.c lisp.h movemail.c + rmail.el rmailedit.el rmailkwd.el rmailmsc.el rmailout.el rmailsum.el + scribe.el server.el sysdep.c unexec.c + +Maciek Pasternacki: changed nnrss.el + +Magnus Henoch: changed url-http.el ispell.el url.el url-gw.el + url-parse.el url-proxy.el autoinsert.el rcirc.el url-https.el + +Manuel Serrano: wrote flyspell.el + +Marc Fleischeuers: changed files.el + +Marc Girod: changed informat.el rmail.el rmailsum.el sendmail.el + +Marc Lefranc: changed gnus-art.el + +Marc Shapiro: changed bibtex.el + +Marcelo Toledo: changed TUTORIAL.pt_BR TUTORIAL.cn TUTORIAL.cs + TUTORIAL.de TUTORIAL.es TUTORIAL.fr TUTORIAL.it TUTORIAL.ja TUTORIAL.ko + TUTORIAL.pl TUTORIAL.ro TUTORIAL.ru TUTORIAL.sk TUTORIAL.sl TUTORIAL.th + TUTORIAL.translators TUTORIAL.zh add-log.el european.el + +Marco Melgazzi: changed term.el + +Marco Walther: changed mips-siemens.h unexelfsni.c unexsni.c + +Marcus G. Daniels: changed xterm.c configure.in lwlib-Xm.c lwlib.c + Makefile.in xdisp.c xfns.c xmenu.c alloc.c config.in dispnew.c + editfns.c emacs.c irix5-0.h linux.h lwlib-Xm.h lwlib.h ptx4.h + sequent-ptx.h unexelf.c + +Marek Martin: changed nnfolder.el + +Marien Zwart: changed python.el + +Mario Lang: wrote erc-button.el erc-ibuffer.el erc-imenu.el erc-menu.el + erc-netsplit.el erc-networks.el erc-notify.el erc-speedbar.el + erc-stamp.el erc-track.el erc-xdcc.el +and changed erc.el erc-dcc.el erc-speak.el Makefile erc-bbdb.el + erc-complete.el erc-pcomplete.el erc-chess.el erc-fill.el erc-list.el + battery.el erc-match.el erc-autojoin.el erc-nets.el erc-nickserv.el + erc-ring.el diff.el erc-ezbounce.el erc-identd.el erc-lang.el + erc-log.el and 6 other files + +Mark A. Hershberger: changed xml.el nnrss.el mm-url.el cperl-mode.el + esh-mode.el gnus-group.el + +Mark D. Baushke: changed mh-e.el mh-utils.el mh-mime.el mh-comp.el + mh-customize.el mh-index.el mh-loaddefs.el Makefile mh-identity.el + mh-seq.el mh-speed.el mh-funcs.el mh-alias.el MH-E-NEWS etags.c + mh-junk.el mh-pick.el mh-tool-bar.el mh-xemacs-compat.el + +Mark Davies: changed Makefile.in amdx86-64.h configure configure.in + hp800.h netbsd.h ralloc.c sh3el.h sort.el + +Mark Diekhans: changed compile.el + +Mark H. Weaver: changed comint.el + +Mark Hood: changed gnus-uu.el + +Mark Lambert: changed process.c process.h + +Mark Mitchell: changed font-lock.el + +Mark Neale: changed fortran.el + +Mark Osbourne: changed hexl-mode.el + +Mark Plaksin: changed nnrss.el term.el + +Mark Thomas: changed flow-fill.el gnus-sum.el gnus-util.el nnmail.el + +Mark W Maimone: changed mpuz.el + +Mark W. Eichin: changed keyboard.c xterm.c + +Marko Kohtala: changed info.el + +Marko Rahamaa: wrote latin-3.el + +Markus Armbruster: changed avoid.el + +Markus Heritsch: wrote ada-xref.el + +Markus Holmberg: changed thingatpt.el + +Markus Rost: wrote cus-test.el +and changed cus-edit.el Makefile.in files.el compile.el rmail.el + tex-mode.el find-func.el rmailsum.el simple.el cus-dep.el dired.el + mule-cmds.el rmailout.el checkdoc.el configure.in custom.el emacsbug.el + gnus.el help-fns.el ls-lisp.el mwheel.el and 122 other files + +Markus Triska: changed byte-opt.el bytecomp.el doctor.el expand.el + flymake.el flymake.texi handwrite.el internals.texi speedbar.el subr.el + tumme.el widget.texi + +Marshall T. Vandegrift: changed gnus-fun.el + +Martin Boyer: changed bibtex.el menu-bar.el + +Martin Buchholz: changed etags.c + +Martin J. Reed: changed ldap.el + +Martin Kretzschmar: changed gnus-spec.el gnus-sum.el + +Martin Larose: changed message.el + +Martin Lorentzon: changed vc.el vc-cvs.el vc-hooks.el vc-rcs.el + vc-sccs.el + +Martin Neitzel: changed sc.el + +Martin Rudalics: changed cus-edit.el wid-edit.el cus-start.el files.el + flyspell.el font-lock.el complete.el insdel.c ispell.el macmenu.c + syntax.c table.el w32menu.c wdired.el whitespace.el window.el xdisp.c + xmenu.c backups.texi buffer.c buffer.h and 36 other files + +Martin Stjernholm: wrote cc-bytecomp.el +and changed cc-engine.el cc-cmds.el cc-langs.el cc-defs.el cc-mode.el + cc-vars.el cc-fonts.el cc-align.el cc-styles.el cc-menus.el cc-fix.el + cc-mode.texi Makefile.in cc-guess.el cc-mode-19.el ack.texi awk-mode.el + cc-awk.el cc-lobotomy.el cc-make.el cc-style.el and 5 other files + +Martin Thornquist: changed gnus-group.el gnus-topic.el + +Masahiko Sato: wrote vip.el + +Masanobu Umeda: wrote gnus-kill.el gnus-mh.el gnus-msg.el gnus.el + metamail.el nndb.el nnheader.el nnspool.el prolog.el rmailsort.el + timezone.el +and changed gnuspost.el + +Masatake Yamato: wrote cc-subword.el ld-script.el +and changed etags.el asm-mode.el hexl.el xdisp.c bindings.el man.el + simple.el wid-edit.el add-log.el compile.el faces.el pcvs.el + register.el ruler-mode.el buffer.c cus-face.el dired-x.el display.texi + etags.c font-lock.el gdb-ui.el and 59 other files + +Masayuki Ataka: changed texinfmt.el texinfo.el characters.el cmuscheme.el + make-mode.el + +Masayuki Fujii: changed dnd.el w32-win.el + +Mathias Dahl: wrote image-dired.el +and changed tumme.el dired.el dired.texi + +Mathias Megyei: changed Makefile.in + +Mats Lidell: changed TUTORIAL.sv european.el gnus-art.el + +Matt Hodges: changed table.el faces.el iswitchb.el simple.el tmm.el + cal-menu.el calendar.el calendar.texi diary-lib.el easymenu.el + edebug.texi eldoc.el em-hist.el em-pred.el fixit.texi icon.el ido.el + locate.el paragraphs.el pcomplete.el repeat.el and 3 other files + +Matt Pharr: changed message.el + +Matt Simmons: changed message.el + +Matt Swift: changed compile.el dired.el editfns.c lisp-mode.el + mm-decode.el outline.el rx.el simple.el startup.el + +Matthew Mundell: changed calendar.texi diary-lib.el files.texi + type-break.el debugging.texi display.texi edebug.texi editfns.c eval.c + fileio.c frames.texi help.texi internals.texi modes.texi nonascii.texi + objects.texi os.texi positions.texi searching.texi subr.el text.texi + tips.texi + +Matthias F,Av(Brste: changed files.el + +Matthias Wiehl: changed gnus.el + +Matthieu Devin: wrote delsel.el + +Matthieu Moy: changed gnus-msg.el message.el + +Max Froumentin: changed gnus-art.el mml.el + +Michael Albinus: wrote tramp-ftp.el tramp-smb.el +and changed tramp.el tramp.texi tramp-vc.el ange-ftp.el files.el + tramp-util.el files.texi nnml.el tramp-uu.el vc.el dired-x.el dired.el + faq.texi find-dired.el locate.el mini.texi rcompile.el tramp*.el + trampver.el trampver.texi woman.el + +Michael Ben-Gershon: changed acorn.h configure.in riscix1-1.h riscix1-2.h + unexec.c + +Michael Cook: changed gnus-sum.el + +Michael D. Ernst: wrote reposition.el +and changed dired-x.el uniquify.el ispell.el bibtex.el rmail.el dired.el + simple.el dired-aux.el gud.el rmailsum.el bytecomp.el compare-w.el + complete.el fill.el shadow.el texnfo-upd.el vc.el allout.el comint.el + cust-print.el edebug.el and 29 other files + +Michael D. Prange: wrote fortran.el +and changed tex-mode.el + +Michael Downes: changed gnus-sum.el + +Michael Gschwind: wrote iso-cvt.el latin-2.el + +Michael Hotchin: changed compile.el + +Michael I. Bushnell: changed rmail.el simple.el callproc.c gnu.h gnus.el + lread.c process.c screen.el search.c sendmail.el startup.el timer.c + +Michael K. Johnson: changed configure.in emacs.c intel386.h linux.h + mem-limits.h process.c sysdep.c syssignal.h systty.h template.h + unexec.c ymakefile + +Michael Kifer: wrote cal-x.el ediff-diff.el ediff-help.el ediff-hook.el + ediff-init.el ediff-merg.el ediff-mult.el ediff-ptch.el ediff-util.el + ediff-vers.el ediff-wind.el ediff.el viper-cmd.el viper-ex.el + viper-init.el viper-keym.el viper-macs.el viper-mous.el viper-util.el + viper.el +and changed ediff-merge.el ediff*.el viper*.el ediff-hooks.el menu-bar.el + viper-utils.el appt.el desktop.el ediff-meta.el ediff-nult.el + ediff.texi viper-mouse.el viper.texi + +Michael Olson: changed erc.el erc-backend.el erc.texi Makefile + erc-autoaway.el erc-log.el erc-stamp.el erc-identd.el erc-list.el + erc-track.el erc-match.el erc-bbdb.el erc-dcc.el erc-notify.el + erc-ibuffer.el erc-pcomplete.el erc-spelling.el erc-compat.el + erc-goodies.el erc-nicklist.el ERC-NEWS and 44 other files + +Michael Piotrowski: changed gnus-sum.el ps-print.el + +Michael R. Cook: changed gnus-topic.el gnus-art.el gnus-sum.el + +Michael R. Mauger: changed sql.el emacsclient.c cua-base.el custom.el + facemenu.el recentf.el replace.el tramp.el w32fns.c + +Michael R. Wolf: changed ange-ftp.el + +Michael Schierl: changed pgg-pgp.el + +Michael Schmidt: wrote modula2.el (public domain) + +Michael Shields: changed spam.el gnus-art.el gnus-sum.el gnus-cite.el + gnus-group.el gnus.el intel386.h nndraft.el pgg-def.el + +Michael Sperber [Mr. Preprocessor]: changed aix3-1.h aix4-2.h + +Michael Staats: wrote pc-select.el + +Michael Welsh Duggan: changed lisp.h sh-script.el w32term.c buffer.c + gnus-spec.el keyboard.c nnmail.el termhooks.h url-http.el w32-win.el + w32fns.c w32menu.c w32term.h xdisp.c xterm.c + +Michal Jankowski: changed insdel.c keyboard.c + +Michal Nazarewicz: changed ispell.el + +Micha,Ak(Bl Cadilhac: changed ido.el fill.el ispell.el Makefile anti.texi + battery.el blackbox.el bs.el cmuscheme.el complete.el cus-edit.el + dispnew.c faq.texi flyspell.el footnote.el fr-refcard.ps fr-refcard.tex + glasses.el info.el life.el lpr.el and 12 other files + +Michelangelo Grigni: wrote ffap.el +and changed gnus-score.el + +Mikael Djurfeldt: changed xdisp.c + +Mike Haertel: changed 7300.h + +Mike Kupfer: changed mh-e.el mh-utils.el + +Mike Long: changed b2m.c make-dist make-mode.el netbsd.h view.el vms.h + +Mike Mcewan: changed gnus-agent.el gnus-sum.el gnus-score.el + +Mike Newton: changed bibtex.el + +Mike Rowan: changed process.c alloc.c dispnew.c keyboard.c process.h + sysdep.c xdisp.c + +Mike Williams: wrote mouse-sel.el thingatpt.el +and changed sgml-mode.el xml-lite.el + +Mike Woolley: changed gnus-sum.el + +Mikio Nakajima: changed ring.el viper-util.el + +Milan Zamazal: wrote czech.el glasses.el tildify.el +and changed slovak.el abbrev.el compile.el filecache.el files.el + +Miles Bader: wrote button.el image-file.el macroexp.el minibuf-eldef.el + rfn-eshadow.el +and changed comint.el faces.el simple.el editfns.c xfaces.c info.el + xdisp.c minibuf.c wid-edit.el xterm.c subr.el window.el cus-edit.el + diff-mode.el dispextern.h quick-install-emacs xfns.c help.el lisp.h + textprop.c bytecomp.el and 242 other files + +Miyashita Hisashi: changed ccl.c coding.c coding.h mule-cmds.el + mule-conf.el mule.el pop3.el + +Miyoshi Masanori: changed mouse.el smtpmail.el xdisp.c + +Morioka Tomohiko: changed rmail.el rmailout.el rmailsum.el fns.c + message.el nnheader.el nnmail.el rmailkwd.el smiley.el + +Morten Welinder: wrote [many MSDOS files] arc-mode.el desktop.el dosfns.c + internal.el msdos.h pc-win.el s-region.el +and changed msdos.c config.bat keyboard.c sed1.inp sed2.inp fileio.c + sed3.inp dos-fns.el callproc.c add-log.el alpha.h data.c editfns.c + emacs.c etags.c files.el info.el lread.c mainmake osf1.h tar-mode.el + and 73 other files + +Mosur Mohan: changed etags.c + +Motorola: changed buff-menu.el + +Mukesh Prasad: wrote vmsproc.el + +Murata Shuuichirou: changed coding.c + +N. Raghavendra: changed timezone.el + +Nachum Dershowitz: wrote cal-hebrew.el + +Nagy Andras: wrote gnus-sieve.el +and changed imap.el gnus.el + +Nakaji Hiroyuki: changed amdx86-64.h configure.in mm-util.el + +Nakamura Toshikazu: changed w32fns.c + +NeXT, Inc.: wrote unexnext.c + +Neal Ziring: wrote vi.el (public domain) + +Neil Mager: wrote appt.el + +Neil W. Van Dyke: wrote webjump.el + +Nelson H. F. Beebe: changed configure.in + +Nelson Jose Dos Santos Ferreira: changed nnsoup.el + +Nevin Kapur: changed nnmail.el gnus-sum.el nnimap.el gnus-group.el + gnus.el nnbabyl.el nnfolder.el nnmbox.el nnmh.el nnml.el + +Niall Mansfield: changed etags.c + +Nick Roberts: wrote gdb-ui.el +and changed gud.el building.texi tooltip.el speedbar.el bindings.el + thumbs.el xt-mouse.el .gdbinit DEBUG cc-mode.el t-mouse.el frames.texi + subr.el comint.el display.texi help-mode.el compile.el descr-text.el + dired.el gud-display.pbm speedbar.texi and 116 other files + +Nico Francois: changed w32fns.c w32inevt.c w32menu.c + +Niimi Satoshi: changed pp.el search.c + +Niklas Morberg: changed nnweb.el gnus-art.el nnimap.el spam.el + +Nikolaj Schumacher: changed compile.el rx.el + +Noah Friedman: wrote eldoc.el rlogin.el rsz-mini.el type-break.el +and changed comint.el emacs-buffer.gdb files.el mailabbrev.el sendmail.el + subr.el timer.el yow.el battery.el complete.el config.in configure.in + copyright.h fns.c gnu-linux.h hpux7.h irix3-3.h lisp-mnt.el loaddefs.el + mailalias.el menu-bar.el and 14 other files + +Nobuyuki Hikichi: changed news-risc.h + +Noel Cragg: changed mh-junk.el + +Norbert Koch: changed gnus-score.el + +Nozomu Ando: changed unexmacosx.c alloc.c buffer.c mips.h pmax.h + smtpmail.el sysselect.h unexelf.c + +Nuutti Kotivuori: changed gnus-sum.el flow-fill.el gnus-cache.el + +Odd Gripenstam: wrote dcl-mode.el + +Ognyan Kulev: changed TUTORIAL.bg cyrillic.el + +Olaf Sylvester: wrote bs.el + +Ole Aamot: changed compile.el + +Oleg S. Tihonov: changed cyrillic.el ispell.el map-ynp.el subr.el + +Olin Shivers: wrote cmuscheme.el comint.el inf-lisp.el shell.el + +Olive Lin: changed tex-mode.el + +Oliver Scholz: changed gamegrid.el nonascii.texi rx.el startup.el + update-game-score.c + +Oliver Seidel: wrote todo-mode.el + +Olivier Laurens: changed forms.el + +Olivier Lecarme: changed make-mode.el ange-ftp.el apropos.el bibtex.el + cpp.el facemenu.el forms.el hscroll.el indent.el nroff-mode.el + paragraphs.el server.el sort.el + +Olli Savia: changed etags.c syssignal.h + +Osamu Yamane: changed smtpmail.el + +Oscar Figueiredo: wrote eudc-bob.el eudc-export.el eudc-hotlist.el + eudc-vars.el eudc.el eudcb-bbdb.el eudcb-ldap.el eudcb-ph.el ldap.el +and changed ph.el + +,bS(Bscar Fuentes: changed emacsclient.c + +Oystein Viggen: changed dgnushack.el + +P. E. Jareth Hein: changed gnus-util.el + +Pace Willisson: wrote ispell.el + +Pascal Dupuis: changed octave-inf.el + +Pascal Rigaux: changed rfc2231.el + +Paul Curry: changed cc-subword.el + +Paul D. Smith: wrote snmp-mode.el +and changed imenu.el make-mode.el + +Paul Eggert: wrote cal-dst.el rcs2log vcdiff +and changed editfns.c vc.el Makefile.in configure.in vc-hooks.el data.c + emacs.c gnus.el calendar.el config.in floatfns.c process.c sysdep.c + dired.el xterm.c callproc.c fileio.c filelock.c lread.c print.c + rmail.el and 290 other files + +Paul Fisher: changed fns.c + +Paul Franklin: changed nnmail.el message.el + +Paul Hilfinger: changed fill.el + +Paul Jarc: wrote nnmaildir.el nnnil.el +and changed message.el gnus-util.el gnus-int.el gnus.el gnus-agent.el + gnus-start.el gnus-sum.el lpath.el nnmail.el + +Paul Pogonyshev: changed subr.el align.el dabbrev.el display.texi + etags.el info.el ses.el tar-mode.el url-http.el which-func.el window.el + +Paul Reilly: wrote dgux5-4r3.h gux5-4r2.h +and changed dgux.h lwlib-Xm.c lwlib.c xlwmenu.c configure.in process.c + xfns.c Makefile.in dgux5-4R2.h dgux5-4R3.h files.el keyboard.c + lwlib-Xaw.c lwlib-Xm.h lwlib-int.h lwlib.h widget.c widget.h xlwmenu.h + xmenu.c xterm.c + +Paul Rubin: changed config.h sun2.h texinfmt.el window.c + +Paul Stevenson: changed nnvirtual.el + +Paul Stodghill: changed gnus-agent.el + +Pavel Jan,Bm(Bk: changed COPYING keyboard.c xterm.c xdisp.c Makefile.in + process.c emacs.c lisp.h menu-bar.el ldap.el make-dist xfns.c buffer.c + coding.c eval.c fileio.c flyspell.el fns.c indent.c callint.c + cus-start.el and 703 other files + +Pavel Kobiakov: changed flymake.el flymake.texi + +Pavel Kobyakov: wrote flymake.el + +Per Abrahamsen: wrote cpp.el cus-dep.el cus-edit.el cus-face.el + cus-start.el custom.el double.el gnus-cite.el gnus-cus.el gnus-score.el + gnus-soup.el wid-browse.el wid-edit.el widget.el xt-mouse.el +and changed message.el menu-bar.el gnus.el gnus-art.el gnus-msg.el + gnus-group.el frame.el gnus-draft.el gnus-sum.el tool-bar.el + widget.texi apropos.el easymenu.el facemenu.el faces.el gnus-srvr.el + gnus-uu.el ispell.el lisp-mode.el makefile.el mouse.el + and 27 other files + +Per Bothner: wrote term.el +and changed iso-acc.el process.c sysdep.c + +Per Cederqvist: wrote ewoc.el +and changed vc.el vc-hooks.el diff-mode.el etags.c etags.el forms.el + hexl.el process.c + +Per Persson: wrote gnus-vm.el + +Per Starback: changed ispell.el gnus-start.el apropos.el bytecomp.el + characters.el charset.h coding.c dired.el doctor.el emacs.c european.el + iso-transl.el replace.el startup.el vc.el xdisp.c + +Pete Kazmier: changed gnus-art.el + +Pete Ware: wrote auto-show.el (public domain) +and changed message.el + +Pete-Temp: changed gnus-art.el + +Peter Breton: wrote dirtrack.el filecache.el find-lisp.el generic-x.el + generic.el locate.el net-utils.el + +Peter Doornbosch: changed vc-svn.el + +Peter Heslin: changed flyspell.el outline.el + +Peter Kleiweg: wrote ps-mode.el + +Peter Liljenberg: wrote elint.el + +Peter Runestig: changed makefile.w32-in configure.bat dos-w32.el emacs.rc + envadd.bat gmake.defs multi-install-info.bat nmake.defs w32fns.c + zone-mode.el + +Peter S. Galbraith: wrote mh-alias.el mh-identity.el mh-inc.el + mh-limit.el +and changed mh-comp.el mh-e.el mh-utils.el mh-mime.el mh-customize.el + mh-seq.el Makefile mh-init.el mh-loaddefs.el mh-pick.el + mh-xemacs-compat.el mh-xemacs-toolbar.el README info-look.el + mh-compat.el mh-funcs.el .cvsignore MH-E-NEWS alias.pbm alias.xpm + cabinet.xpm and 14 other files + +Peter Seibel: changed cl-indent.el lisp-mode.el + +Peter Stephenson: wrote vcursor.el + +Peter Von Der Ahe: changed gnus-ems.el + +Peter Whaite: changed data.c + +Petri Kaurinkoski: changed configure.in iris4d.h irix6-0.h irix6-5.h + usg5-4.h + +Philippe Schnoebelen: wrote gomoku.el mpuz.el + +Philippe Waroquiers: changed etags.el + +Piet Van Oostrum: changed data.c fileio.c flyspell.el make-package + smtpmail.el + +Pieter E.J. Pareit: wrote mixal-mode.el + +Pinku Surana: changed sql.el + +Pmr-Sav: changed mail-utils.el rmail.el + +Primoz Peterlin: changed TUTORIAL.sl + +R. Bernstein: changed gud.el + +Rafael Sep,Az(Blveda: changed TUTORIAL.es + +Rainer Schoepf: wrote alpha.h unexalpha.c +and changed osf1.h alloc.c buffer.c callint.c data.c dispextern.h doc.c + editfns.c floatfns.c frame.h lisp.h lread.c marker.c mem-limits.h + print.c puresize.h window.h xdisp.c xterm.h + +Raja R Harinath: changed nnml.el + +Raja R. Harinath: changed gnus-salt.el + +Rajappa Iyer: changed gnus-salt.el + +Rajesh Vaidheeswarran: wrote whitespace.el +and changed ffap.el + +Ralf Angeli: wrote scroll-lock.el +and changed w32fns.c tex-mode.el comint.el flow-fill.el frame.el + gnus-art.el killing.texi mm-view.el pcl-cvs.texi reftex-auc.el + reftex-cite.el reftex-dcr.el reftex-global.el reftex-index.el + reftex-parse.el reftex-ref.el reftex-sel.el reftex-toc.el + reftex-vars.el reftex.el reftex.texi and 4 other files + +Ralf Fassel: changed dabbrev.el files.el fill.el iso-acc.el tar-mode.el + +Ralph Schleicher: wrote battery.el info-look.el +and changed libc.el fileio.c mm-decode.el nnultimate.el + +Ramakrishnan M: changed mlm-util.el + +Randal Schwartz: wrote pp.el + +Randall Smith: changed dired.el + +Raul Acevedo: changed info.el options.el + +Ray Blaak: wrote delphi.el + +Raymond Scholz: wrote deuglify.el +and changed gnus-art.el gnus-msg.el gnus.texi message.el nnmail.el + pgg-gpg.el + +Reiner Steib: wrote gmm-utils.el +and changed gnus-art.el gnus.texi message.el gnus-sum.el gnus.el + gnus-group.el gnus-faq.texi gnus-util.el mml.el gnus-score.el + gnus-start.el message.texi mm-util.el gnus-agent.el gnus-msg.el spam.el + files.el spam-report.el mm-decode.el nnmail.el nnweb.el + and 166 other files + +Remek Trzaska: changed gnus-ems.el + +Remi Letot: changed nnmaildir.el + +Renaud Rioboo: changed nnmail.el + +Ren,Ai(B Kyllingstad: changed pcomplete.el + +Reto Zimmermann: changed vhdl-mode.el + +Richard Bielawski: changed modes.texi + +Richard Dawe: changed Makefile.in config.in + +Richard G Bielawski: changed paren.el + +Richard Hoskins: changed message.el + +Richard King: wrote backquote.el filelock.c userlock.el + +Richard L. Pieri: wrote pop3.el + +Richard M. Heiberger: changed tex-mode.el + +Richard M. Stallman: wrote [The original GNU Emacs and numerous files] + easymenu.el font-lock.el image-mode.el menu-bar.el paren.el +and changed keyboard.c files.el simple.el xterm.c xdisp.c rmail.el + fileio.c process.c sysdep.c xfns.c buffer.c Makefile.in window.c + configure.in subr.el startup.el emacs.c editfns.c sendmail.el info.el + dispnew.c and 1334 other files + +Richard Mlynarik: wrote cl-indent.el ebuff-menu.el ehelp.el env.c + rfc822.el terminal.el yow.el +and changed files.el sysdep.c rmail.el info.el keyboard.c fileio.c + loaddefs.el simple.el process.c window.c editfns.c startup.el unexec.c + xfns.c bytecomp.el keymap.c minibuf.c sendmail.el buffer.c dispnew.c + emacs.c and 123 other files + +Richard Sharman: wrote hilit-chg.el +and changed sh-script.el ediff-init.el regexp-opt.el simple.el + +Rick Farnbach: wrote morse.el + +Rick Sladkey: wrote backquote.el +and changed gud.el intervals.c intervals.h simple.el + +Rob Browning: changed configure.in + +Rob Kaut: changed vhdl-mode.el + +Rob Riepel: wrote tpu-edt.el tpu-extras.el tpu-mapper.el vt-control.el +and changed tpu-doc.el + +Robert Bihlmeyer: changed gnus-score.el gnus-util.el message.el + +Robert Fenk: changed desktop.el + +Robert J. Chassell: wrote makeinfo.el texinfo.el texnfo-upd.el +and changed texinfmt.el emacs-lisp-intro.texi page-ext.el emacs.tex + info.el loaddefs.el texinfo-update.el texinfo.tex INSTALL case-table.el + cl.texinfo history.el informat.el latin-1.el latin-2.el latin-3.el + latin-4.el page.el tex-mode.el texinfo.texinfo vip.texinfo + +Robert Thorpe: changed cus-start.el indent.el + +Roberto Rodr,Am(Bguez: changed ada-mode.texi glossary.texi widget.texi + +Roderick Schertler: changed dgux.h dgux4.h gud.el sysdep.c + +Rodrigo Real: changed pt-br-refcard.tex pt-br-refcard.ps + +Roger Breitenstein: changed smtpmail.el + +Roland B. Roberts: wrote logout.com mailemacs.com vms-pmail.el +and changed buffer.h build.com callproc.c compile.com dired.c files.el + gnus-group.el gnus-sum.el kepteditor.com precomp.com process.c sort.el + sysdep.c systty.h vmspaths.h vmsproc.el + +Roland Mcgrath: wrote autoload.el etags.el find-dired.el grep.el + map-ynp.el +and changed compile.el add-log.el configure.in files.el vc.el Makefile.in + simple.el mailabbrev.el buffer.c comint.el upd-copyr.el etags.c + menu-bar.el loaddefs.el mem-limits.h ralloc.c fileio.c data.c process.c + rlogin.el rmail.el and 137 other files + +Roland Winkler: changed bibtex.el appt.el artist.el conf-mode.el + flyspell.el ispell.el make-mode.el sgml-mode.el sh-script.el + skeleton.el + +Rolf Ebert: wrote ada-mode.el +and changed files.el find-file.el + +Romain Francoise: changed faq.texi dired-x.el ibuf-ext.el Makefile.in + comint.el compile.el message.el puresize.h replace.el subr.el + files.texi gnus-fun.el gnus.texi help-fns.el make-dist rcirc.el + antlr-mode.el bookmark.el buffer.c diary-lib.el dired.el + and 130 other files + +Roman Belenov: changed which-func.el + +Ron Schnell: wrote dunnet.el + +Ronan Waide: changed smtpmail.el + +Rui-Tao Dong: changed nnweb.el + +Rune Kleveland: changed xfns.c + +Russ Allbery: changed message.el + +Ryan Yeske: wrote rcirc.el +and changed ffap.el ispell.el rmailsum.el simple.el testcover.el + +Ryszard Kubiak: changed ogonek.el + +Sacha Chua: wrote erc-pcomplete.el +and changed erc.el erc-button.el + +Saito Takuya: changed compile.el mule.el + +Sam Dooley: changed keyboard.c + +Sam Falkner: changed nntp.el + +Sam Kendall: changed etags.c etags.el + +Sam Steingold: wrote gulp.el midnight.el +and changed cl-indent.el font-lock.el ange-ftp.el mouse.el tex-mode.el + vc-cvs.el add-log.el bindings.el bookmark.el debug.el diary-lib.el + dired.el pcvs.el sgml-mode.el simple.el browse-url.el buff-menu.el + bytecomp.el cc-mode.el compile.el etags.el and 96 other files + +Samuel Tardieu: changed smime.el + +Sanghyuk Suh: changed mac-win.el macterm.c + +Sascha L,A|(Bdecke: wrote mml1991.el +and changed gnus-win.el + +Sascha Wilde: changed pgg-gpg.el pgg.el pgg.texi configure.in + +Satyaki Das: wrote mh-acros.el mh-gnus.el mh-junk.el mh-search.el + mh-speed.el mh-thread.el mh-tool-bar.el +and changed mh-e.el mh-utils.el mh-seq.el mh-index.el mh-comp.el + mh-mime.el mh-customize.el mh-loaddefs.el mh-funcs.el Makefile + mh-alias.el mh-pick.el mh-unit.el mh-init.el mh-identity.el mh-make.el + mh-xemacs-toolbar.el mh-xemacs-compat.el pgg-gpg.el mh-inc.el + highlight.xpm and 7 other files + +Schlumberger Technology Corporation: changed gud.el + +Scott A Crosby: changed gnus-logic.el + +Scott Byer: changed gnus-sum.el + +Scott Draves: wrote tq.el + +Scott M. Meyers: changed cmacexp.el + +Sean Neakums: changed gnus-msg.el gnus-uu.el + +Sean O'rourke: changed ibuf-ext.el + +Sebastian Kremer: wrote dired-aux.el dired-x.el dired.el ls-lisp.el +and changed add-log.el + +Sebastian Tennant: changed desktop.el + +Sebastien Kirche: changed mail-extr.el + +Sen Nagata: wrote crm.el rfc2368.el + +Seokchan Lee: changed message.el + +Sergey Poznyakoff: changed rmail.el mh-mime.el rmail.texi smtpmail.el + +Sergio Pokrovskij: changed TUTORIAL.eo + +Shawn M. Carey: wrote freebsd.h + +Shenghuo Zhu: wrote binhex.el mm-extern.el mm-partial.el mm-url.el + mm-uu.el mml2015.el nnrss.el nnwarchive.el rfc1843.el uudecode.el + webmail.el +and changed gnus-art.el message.el gnus-sum.el gnus-msg.el gnus.el + gnus-agent.el mm-decode.el mm-util.el gnus-group.el mml.el + gnus-start.el gnus-util.el nnfolder.el mm-view.el nnslashdot.el + nnmail.el nntp.el gnus-topic.el gnus-xmas.el rfc2047.el dgnushack.el + and 101 other files + +Shinichirou Sugou: changed etags.c + +Shuhei Kobayashi: wrote hex-util.el sha1.el +and changed gnus-group.el message.el nnmail.el + +Shun-Ichi Goto: changed url-http.el + +Sidney Markowitz: changed doctor.el + +Sigbjorn Finne: changed gnus-srvr.el + +Simon Josefsson: wrote dig.el dns-mode.el flow-fill.el fringe.el imap.el + mml-sec.el mml-smime.el nnfolder.el nnimap.el nnml.el rfc2104.el + sieve-manage.el sieve-mode.el sieve.el smime.el starttls.el tls.el + url-imap.el +and changed message.el gnus-sum.el gnus-art.el smtpmail.el pgg.el + mml2015.el pgg-gpg.el gnus-agent.el mml.el mm-decode.el mml1991.el + gnus-group.el gnus-msg.el pgg-pgp5.el gnus-sieve.el browse-url.el + gnus-int.el gnus.el pgg-parse.el gnus-cache.el mail-source.el + and 89 other files + +Simon Leinen: changed smtpmail.el Makefile Makefile.in cm.c cm.h hpux9.h + indent.c process.c sc.texinfo sgml-mode.el term.c xfns.c xmenu.c + xterm.c + +Simon Marshall: wrote fast-lock.el lazy-lock.el regexp-opt.el +and changed comint.el font-lock.el shell.el rmail.el fortran.el + sendmail.el subr.el dired.el sh-script.el texinfo.el add-log.el + compile.el outline.el help.el menu-bar.el perl-mode.el ps-print.el + rmailsum.el bytecomp.el cc-fonts.el data.c and 57 other files + +Skip Collins: changed w32fns.c w32term.c w32term.h + +Slawomir Nowaczyk: changed emacs.py python.el TUTORIAL.pl flyspell.el + ls-lisp.el w32proc.c + +Spencer Thomas: changed dabbrev.el emacsclient.c emacsserver.c gnus.texi + server.el tcp.c unexec.c + +Sriram Karra: changed message.el + +Stanislav Shalunov: wrote uce.el + +Stefan Monnier: wrote bibtex.el cvs-status.el diff-mode.el log-edit.el + log-view.el pcvs-defs.el pcvs-info.el pcvs-parse.el pcvs-util.el + reveal.el smerge-mode.el +and changed vc.el font-lock.el pcvs.el newcomment.el subr.el lisp.h + keyboard.c fill.el keymap.c tex-mode.el alloc.c compile.el files.el + regex.c simple.el easy-mmode.el syntax.c vc-hooks.el info.el xdisp.c + sh-script.el and 519 other files + +Steinar Bang: changed imap.el + +Stephan Stahl: changed which-func.el buff-menu.el buffer.c dired-x.texi + ediff-mult.el + +Stephen A. Wood: changed fortran.el + +Stephen Berman: changed allout.el find-dired.el recentf.el + +Stephen C. Gilardi: changed configure.in + +Stephen Compall: changed saveplace.el texinfo.el + +Stephen Eglen: wrote iswitchb.el mspools.el +and changed diary-lib.el locate.el octave-inf.el replace.el hexl.el + info-look.el sendmail.el spell.el uce.el MORE.STUFF add-log.el + advice.el allout.el autoinsert.el avoid.el backquote.el battery.el + bib-mode.el bruce.el c-mode.el ccl.el and 71 other files + +Stephen Gildea: wrote mh-funcs.el mh-pick.el refcard.tex +and changed time-stamp.el mh-e.el mh-comp.el mh-utils.el mh-customize.el + mh-junk.el fileio.c files.el fortran.el mh-e.texi mh-mime.el mwheel.el + tex-mode.el + +Stephen J. Turnbull: changed ediff-init.el strings.texi subr.el + +Stephen Leake: changed ada-mode.el ada-xref.el ada-stmt.el ada-mode.texi + ada-prj.el align.el + +Steve Fisk: wrote cal-tex.el + +Steve Nygard: changed unexnext.c + +Steve Strassman: wrote spook.el + +Steve Youngs: changed mh-utils.el mh-xemacs-compat.el dgnushack.el + mh-customize.el mh-e.el mh-comp.el mh-mime.el Makefile Makefile.in + browse-url.el gnus-art.el gnus-sum.el gnus-xmas.el lpath.el mh-seq.el + .cvsignore dns.el em-unix.el gnus-async.el gnus-util.el mail-source.el + and 15 other files + +Steven E. Harris: changed nnheader.el + +Steven Huwig: changed emacs.py python.el + +Steven L. Baur: wrote earcon.el footnote.el gnus-audio.el gnus-setup.el +and changed gnus-xmas.el gnus-msg.el add-log.el dgnushack.el edebug.el + gnus-ems.el gnus-start.el gnus-topic.el message.el nnbabyl.el nntp.el + webjump.el + +Steven Suhr: changed dispnew.c scroll.c term.c termchar.h + +Steven Tamm: changed macterm.c make-package mac.c macfns.c configure.in + unexmacosx.c INSTALL mac-win.el Makefile.in README darwin.h editfns.c + lread.c macmenu.c scroll-bar.el MACHINES config.h config.in dispnew.c + eval.c fileio.c and 7 other files + +Stewart M. Clamen: wrote cal-mayan.el + +Stuart D. Herring: changed keymap.c minibuf.c widget.texi + +Stuart Herring: changed files.el isearch.el align.el allout.el comint.el + edebug.el find-lisp.el sregex.el + +Sudish Joseph: changed mac-win.el + +Sun Microsystems, Inc: wrote emacs.icon emacstool.1 emacstool.c + sun-curs.el sun-fns.el sun-mouse.el sun.el sunfns.c +and changed emacsclient.c emacsserver.c server.el + +Sun Yijiang: changed TUTORIAL.cn + +Sundar Narasimhan: changed rnews.el rnewspost.el + +Sven Joachim: changed arc-mode.el de-refcard.tex files.el files.texi + help.el mule.texi sed3v2.inp sh-script.el simple.el + +Svend Tollak Munkejord: changed deuglify.el + +Takaaki Ota: wrote table.el +and changed appt.el compile.el dired.c etags.c ldap.el makefile.w32-in + recentf.el subr.el w32bdf.c + +Takahashi Kaoru: changed texinfmt.el + +Takahashi Naoto: wrote cyrillic.el ethio-util.el ethiopic.el latin-alt.el + latin-ltx.el latin-post.el utf-8.el +and changed fontset.el mule-conf.el quail.el + +Takai Kousuke: changed ccl.el + +Takeshi Yamada: changed fns.c + +Taro Kawagishi: changed arc-mode.el + +Tatsuya Ichikawa: changed gnus-agent.el gnus-cache.el + +Ted Lemon: changed emacs.c lastfile.c puresize.h + +Ted Phelps: changed mh-search.el mh-tool-bar.el + +Teodor Zlatanov: wrote gnus-registry.el spam-report.el +and changed spam.el gnus.el gnus-sum.el nnmail.el gnus-start.el + spam-stat.el gnus.texi lpath.el nnbabyl.el nnfolder.el nnimap.el + nnmbox.el nnmh.el nnml.el replace.el simple.el basic.texi building.texi + commands.texi compile.el dig.el and 12 other files + +Terje Rosten: changed xfns.c version.el xterm.c xterm.h + +Terrence Brannon: wrote landmark.el + +Terry Jones: wrote shadow.el + +Tetsurou Okazaki: changed log-edit.el xterm.c + +Theodore Jump: changed w32-win.el w32faces.c + +Thien-Thi Nguyen: wrote hideshow.el make-mms-derivative.el +and changed ewoc.el info.el processes.texi zone.el Makefile.in vc.el + fileio.c lisp-mode.el scheme.el text.texi TUTORIAL.it bindat.el + dcl-mode.el display.texi files.el gnus.texi pcvs.el startup.el sysdep.c + vc-rcs.el MORE.STUFF and 129 other files + +Thierry Emery: changed kinsoku.el timezone.el url-http.el wid-edit.el + +Thomas Deweese: changed x-win.el + +Thomas Dorner: changed ange-ftp.el + +Thomas Horsley: wrote cxux.h cxux7.h +and changed cxux-crt0.s emacs.c nh3000.h nh4000.h sysdep.c xterm.c + +Thomas Link: wrote filesets.el + +Thomas Morgan: changed forms.el + +Thomas Neumann: wrote make-mode.el +and changed makefile.el + +Thomas W Murphy: changed outline.el + +Thomas Wurgler: changed emacs-lock.el + +Thor Kristoffersen: changed nntp.el + +Thorsten Ohl: changed lread.c next.h + +Tijs Van Bakel: changed erc.el + +Tim Fleehart: wrote makefile.nt + +Tim Van Holder: changed emacsclient.c Makefile.in compile.el configure.in + which-func.el + +Tobias C. Rittweiler: changed font-lock.el + +Toby Allsopp: changed ldap.el eudc.el + +Toby Speight: changed window.el + +Tom Breton: changed autoinsert.el gnus-agent.el lread.c + +Tom Hageman: changed etags.c + +Tom Houlder: wrote mantemp.el + +Tom Tromey: wrote tcl.el +and changed makefile.el buffer.c make-mode.el add-log.el blackbox.el + buff-menu.el doc.c emacsclient.c info.el man.el replace.el xfns.c + xterm.c xterm.h + +Tom Wurgler: wrote emacs-lock.el +and changed subr.el + +Tomas Abrahamsson: wrote artist.el + +Tommi Vainikainen: changed gnus-sum.el message.el + +Tomohiko Morioka: changed gnus-sum.el nnfolder.el nnmail.el nnmh.el + nnml.el coding.c gnus-art.el gnus-ems.el gnus-mule.el nnheader.el + nnspool.el nntp.el + +Tomoji Kagatani: wrote smtpmail.el + +Torbj,Av(Brn Axelsson: changed options.el + +Torbj,Av(Brn Einarsson: wrote f90.el + +Torsten Bronger: changed latin-ltx.el + +Toru Tomabechi: wrote tibet-util.el tibetan.el + +Toshiaki Nomura: changed uxpds.h + +Trent Buck: changed rcirc.el + +Trey Jackson: changed spam-stat.el + +Triet Hoai Lai: changed vntelex.el viet-util.el vietnamese.el + +Trung Tran-Duc: changed nntp.el + +Tsuchiya Masatoshi: changed gnus-art.el gnus-sum.el nneething.el + mm-view.el gnus-group.el nnheader.el nnml.el gnus-agent.el + gnus-cache.el gnus-msg.el lpath.el nndiary.el nnfolder.el nnimap.el + nnmaildir.el pgg.el rfc2047.el + +Tsugutomo Enami: changed nnheader.el regex.c regex.h simple.el + +Tsuyoshi Akiho: changed gnus-sum.el nnrss.el + +Tudor Hulubei: changed iso-acc.el latin-pre.el + +Ulf Jasper: wrote icalendar.el newsticker.el +and changed calendar.texi newsticker.texi Makefile.in + +Ulrich Leodolter: changed w32proc.c + +Ulrich Mueller: changed gud.el Makefile.in XMakeAssoc.c case-table.el + fortran.el iso-acc.el sysdep.c + +Ulrik Vieth: wrote meta-mode.el +and changed files.el + +Vadim Nasardinov: changed allout.el + +Vagn Johansen: changed gnus-cache.el + +Valery Alexeev: changed cyril-util.el cyrillic.el + +Vasily Korytov: changed cperl-mode.el gnus-art.el gnus-dired.el + gnus-msg.el gnus-util.el mail-source.el message.el smiley.el + +Victor Zandy: wrote zone.el + +Viktor Dukhovni: wrote unexsunos4.c + +Ville Skytt,Ad(B: changed mh-comp.el pgg.el tcl.el + +Vincent Del Vecchio: changed info.el mh-utils.el + +Vinicius Jose Latorre: wrote delim-col.el ebnf-abn.el ebnf-bnf.el + ebnf-dtd.el ebnf-ebx.el ebnf-iso.el ebnf-otz.el ebnf-yac.el ebnf2ps.el + printing.el ps-mule.el +and changed ps-print.el ps-prin1.ps ps-bdf.el ps-prin0.ps ps-prin3.ps + ps-prin2.ps lpr.el ps-print.ps subr.el TUTORIAL.pt_BR easymenu.el + loading.texi ps-print-def.el ps-print0.ps ps-vars.el + +Vivek Dasmohapatra: changed emacs.c erc-backend.el erc.el sh-script.el + xterm.c xterm.h + +Vladimir Alexiev: changed arc-mode.el nnvirtual.el tmm.el + +Vladimir Volovich: changed smime.el + +Walter C. Pelissero: changed browse-url.el url-methods.el + +Wayne Mesard: wrote hscroll.el + +Werner Benger: changed keyboard.c + +Werner Lemberg: wrote sisheng.el vntelex.el +and changed TUTORIAL.de Makefile.in calc.texi chinese.el czech.el + european.el idlwave.el reftex-vars.el reftex.el reftex.texi slovak.el + supercite.el .cvsignore advice.el calc-forms.el calc-sel.el calendar.el + china-util.el cl-macs.el cl.texi complete.el and 44 other files + +Wes Hardaker: changed gnus-score.el gnus-art.el gnus-sum.el gnus-win.el + +Will Mengarini: wrote repeat.el + +William F. Mann: wrote perl-mode.el + +William F. Schelter: wrote telnet.el + +William M. Perry: wrote mailcap.el url-dav.el url-gw.el url-http.el + url-util.el url.el vc-dav.el +and changed url-handlers.el url-file.el url-methods.el url-vars.el + url-https.el aclocal.m4 mule-sysdp.el url-imap.el url-news.el + url-nfs.el configure.in image.el mwheel.el url-about.el url-auth.el + url-cid.el url-dired.el url-expand.el url-ftp.el url-history.el + url-irc.el and 6 other files + +William Smith: changed strftime.c + +William Sommerfeld: wrote emacsclient.c emacsserver.c scribe.el server.el + +Wilson H. Tien: changed unexelf.c + +Wim Nieuwenhuizen: changed TUTORIAL.nl + +Wlodzimierz Bzyl: wrote ogonek.el +and changed latin-pre.el pl-refcard.ps pl-refcard.tex refcard-pl.ps + refcard-pl.tex survival.tex + +Wolfgang Glas: changed unexsgi.c + +Wolfgang Jenkner: changed conf-mode.el gnus-sum.el pcvs.el + +Wolfgang Rupprecht: wrote float-sup.el floatfns.c sup-mouse.el +and changed process.c alloc.c callint.c config.h.in config.in + configure.in crt0.c data.c fns.c lisp-mode.el lisp.h loadup.el lread.c + net-utils.el nntp.el print.c sort.el sun3.h ymakefile + +Wolfgang Scherer: changed vc-cvs.el + +Wolfram Fenske: changed nnimap.el + +Wolfram Gloger: changed emacs.c + +Xavier Maillard: changed gnus-faq.texi gnus-score.el spam.el + +Yagi Tatsuya: changed gnus-art.el gnus-start.el + +Yamamoto Mitsuharu: changed macterm.c macfns.c mac-win.el mac.c macterm.h + macmenu.c macgui.h image.c macselect.c keyboard.c xdisp.c makefile.MPW + config.h emacs.c INSTALL Makefile.in macos.texi darwin.h xfaces.c + dispnew.c alloc.c and 77 other files + +Yann Dirson: changed imenu.el + +Yavor Doganov: changed emacs.1 etags.1 + +Yoichi Nakayama: changed browse-url.el finder.el man.el rfc2368.el + +Yoni Rabkin Katzenell: changed faces.el whitespace.el + +Yoshiki Hayashi: changed texinfmt.el nnheader.el + +Yoshinori Koseki: changed fontset.el + +Yutaka Niibe: changed indent.c xdisp.c configure.in Makefile.in dispnew.c + sysdep.c config.in dired.el emacs.c fill.el fns.c gmalloc.c gnu-linux.h + indent.h process.c simple.el term.c window.c + +Zhang Wei: changed xfns.c erc.el x-win.el + +Zoltan Kemenczy: changed gud.el + +Zoran Milojevic: changed avoid.el + +Local Variables: +coding: iso-2022-7bit +End:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/etc/CONTRIBUTE Thu Oct 11 16:24:58 2007 +0000 @@ -0,0 +1,207 @@ +Copyright (C) 2006, 2007 Free Software Foundation, Inc. +See end for license conditions. + + + Contributing to Emacs + +Emacs is a collaborative project and we encourage contributions from +anyone and everyone. If you want to contribute in the way that will +help us most, we recommend (1) fixing reported bugs and (2) +implementing the feature ideas in etc/TODO. However, if you think of +new features to add, please suggest them too -- we might like your +idea. Porting to new platforms is also useful, when there is a new +platform, but that is not common nowadays. + +For documentation on how to develop Emacs changes, refer to the Emacs +Manual and the Emacs Lisp Reference Manual (both included in the Emacs +distribution). The web pages in http://www.gnu.org/software/emacs +contain additional information. + +You may also want to submit your change so that can be considered for +inclusion in a future version of Emacs (see below). + +If you don't feel up to hacking Emacs, there are many other ways to +help. You can answer questions on the mailing lists, write +documentation, find and report bugs, contribute to the Emacs web +pages, or develop a package that works with Emacs. + +Here are some style and legal conventions for contributors to Emacs: + + +* Coding Standards + +Contributed code should follow the GNU Coding Standard. + +If it doesn't, we'll need to find someone to fix the code before we +can use it. + +Emacs has certain additional style and coding conventions. + +Ref: http://www.gnu.org/prep/standards_toc.html +Ref: GNU Coding Standards Info Manual +Ref: The "Tips" Appendix in the Emacs Lisp Reference. + + +* Copyright Assignment + +We can accept small changes without legal papers, and for medium-size +changes a copyright disclaimer is ok too. To accept substantial +contributions from you, we need a copyright assignment form filled out +and filed with the FSF. + +Contact us at emacs-devel@gnu.org to obtain the relevant forms. + + +* Getting the Source Code + +The latest version of Emacs can be downloaded using CVS or Arch from +the Savannah web site. It is important to write your patch based on +this version; if you start from an older version, your patch may be +outdated when you write it, and maintainers will have a hard time +applying it. + +After you have downloaded the CVS source, you should read the file +INSTALL.CVS for build instructions (they differ to some extent from a +normal build). + +Ref: http://savannah.gnu.org/projects/emacs + + +* Submitting Patches + +Every patch must have several pieces of information before we +can properly evaluate it. + +When you have all these pieces, bundle them up in a mail message and +send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org. + +All subsequent discussion should also be sent to the mailing list. + +** Description + +For bug fixes, a description of the bug and how your patch fixes this +bug. + +For new features, a description of the feature and your implementation. + +** ChangeLog + +A ChangeLog entry as plaintext (separate from the patch). + +See the various ChangeLog files for format and content. Note that, +unlike some other projects, we do require ChangeLogs also for +documentation, i.e. Texinfo files. + +Ref: "Change Log Concepts" node of the GNU Coding Standards Info +Manual, for how to write good log entries. + +** The patch itself. + +Please use "Context Diff" format. + +If you are accessing the CVS repository use + cvs update; cvs diff -cp +else, use + diff -cp OLD NEW + +If your version of diff does not support these options, then get the +latest version of GNU Diff. + +** Mail format. + +We prefer to get the patches as inline plain text. + +Please be aware of line wrapping which will make the patch unreadable +and useless for us. To avoid that, you can use MIME attachments or, +as a last resort, uuencoded gzipped text. + +** Please reread your patch before submitting it. + +** Do not mix changes. + +If you send several unrelated changes together, we will ask you to +separate them so we can consider each of the changes by itself. + + +* Coding style and conventions. + +** Mandatory reading: + +The "Tips and Conventions" Appendix of the Emacs Lisp Reference. + +** Avoid using `defadvice' or `eval-after-load' for Lisp code to be +included in Emacs. + +** Remove all trailing whitespace in all source and text files. + +** Use ?\s instead of ? in Lisp code for a space character. + + +* Supplemental information for Emacs Developers. + +** Write access to Emacs' CVS repository. + +Once you become a frequent contributor to Emacs, we can consider +giving you write access to the CVS repository. + + +** Emacs Mailing lists. + +Discussion about Emacs development takes place on emacs-devel@gnu.org. + +Bug reports for released versions are sent to bug-gnu-emacs@gnu.org. + +Bug reports for development versions are sent to emacs-pretest-bug@gnu.org. + +You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs. + +You can find the mailing lists archives at lists.gnu.org or gmane.org. + + +** Document your changes. + +Think carefully about whether your change requires updating the +documentation. If it does, you can either do this yourself or add an +item to the NEWS file. + +If you document your change in NEWS, please mark the NEWS entry with +the documentation status of the change: if you submit the changes for +the manuals, mark it with "+++"; if it doesn't need to be documented, +mark it with "---"; if it needs to be documented, but you didn't +submit documentation changes, leave the NEWS entry unmarked. (These +marks are checked by the Emacs maintainers to make sure every change +was reflected in the manuals.) + + +** Understanding Emacs Internals. + +The best way to understand Emacs Internals is to read the code, +but the nodes "Tips" and "GNU Emacs Internals" in the Appendix +of the Emacs Lisp Reference Manual may also help. + +The file etc/DEBUG describes how to debug Emacs bugs. + + + +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, 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; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, USA. + +Local variables: +mode: outline +paragraph-separate: "[ ]*$" +end: +
--- a/lispref/mkinstalldirs Thu Oct 11 16:22:07 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -#! /bin/sh -# mkinstalldirs --- make directory hierarchy -# Author: Noah Friedman <friedman@prep.ai.mit.edu> -# Created: 1993-05-16 -# Public domain - -errstatus=0 - -for file -do - set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` - shift - - pathcomp= - for d - do - pathcomp="$pathcomp$d" - case "$pathcomp" in - -* ) pathcomp=./$pathcomp ;; - esac - - if test ! -d "$pathcomp"; then - echo "mkdir $pathcomp" 1>&2 - - mkdir "$pathcomp" || lasterr=$? - - if test ! -d "$pathcomp"; then - errstatus=$lasterr - fi - fi - - pathcomp="$pathcomp/" - done -done - -exit $errstatus - -# mkinstalldirs ends here