changeset 83932:b9810e4e9906

Move to ../doc/lispintro
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 03:58:07 +0000
parents 92cfbaf16dd9
children 909c429adf41
files lispintro/emacs-lisp-intro.texi
diffstat 1 files changed, 0 insertions(+), 22721 deletions(-) [+]
line wrap: on
line diff
--- a/lispintro/emacs-lisp-intro.texi	Thu Sep 06 03:58:01 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,22721 +0,0 @@
-\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.07
-@set update-date 9 November 2006
-
-@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
-@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