info/eintr-1: Updated Info file to Third Edition for

       `Introduction to Programming in Emacs Lisp'

1 files changed, 7313 insertions, 0 deletions

diff --git a/info/eintr-1 b/info/eintr-1
new file mode 100644
index 00000000000..391572a9ad4
--- /dev/null
+++ b/info/eintr-1
@@ -0,0 +1,7313 @@
+This is ../info/eintr, produced by makeinfo version 4.8 from
+emacs-lisp-intro.texi.
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Emacs Lisp Intro: (eintr).
+  			A simple introduction to Emacs Lisp programming.
+END-INFO-DIR-ENTRY
+
+This is an `Introduction to Programming in Emacs Lisp', for people who
+are not programmers.
+
+Edition 3.00, 2006 Oct 31
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,    2002,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
+Published by the:
+
+     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
+
+
+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."
+
+
+File: eintr,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
+
+An Introduction to Programming in Emacs Lisp
+********************************************
+
+This is an `Introduction to Programming in Emacs Lisp', for people who
+are not programmers.
+
+Edition 3.00, 2006 Oct 31
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,    2002,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
+Published by the:
+
+     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
+
+
+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."
+
+This master menu first lists each chapter and index; then it lists
+every node in every chapter.
+
+* 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 `defun'.
+* Readying a Graph::            A prototype graph printing function.
+* Emacs Initialization::        How to write a `.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::
+
+ --- 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
+
+* 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 `setq' to count.
+
+Practicing Evaluation
+
+* How to Evaluate::            Typing editing commands or 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 `defun' special form.
+* Install::                      Install a function definition.
+* Interactive::                  Making a function interactive.
+* Interactive Options::          Different options for `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.
+
+`let'
+
+* Prevent confusion::
+* Parts of let Expression::
+* Sample let Expression::
+* Uninitialized let Variables::
+
+The `if' Special Form
+
+* if in more detail::
+* type-of-animal in detail::    An example of an `if' expression.
+
+Truth and Falsehood in Emacs Lisp
+
+* nil explained::               `nil' has two meanings.
+
+`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 `goto-char',
+                                `point-min', and `push-mark'.
+* mark-whole-buffer::           Almost the same as `beginning-of-buffer'.
+* append-to-buffer::            Uses `save-excursion' and
+                                `insert-buffer-substring'.
+* Buffer Related Review::       Review.
+* Buffer Exercises::
+
+The Definition of `mark-whole-buffer'
+
+* mark-whole-buffer overview::
+* Body of mark-whole-buffer::   Only three lines of code.
+
+The Definition of `append-to-buffer'
+
+* append-to-buffer overview::
+* append interactive::          A two part interactive expression.
+* append-to-buffer body::       Incorporates a `let' expression.
+* append save-excursion::       How the `save-excursion' works.
+
+A Few More Complex Functions
+
+* copy-to-buffer::              With `set-buffer', `get-buffer-create'.
+* insert-buffer::               Read-only, and with `or'.
+* beginning-of-buffer::         Shows `goto-char',
+                                `point-min', and `push-mark'.
+* Second Buffer Related Review::
+* optional Exercise::
+
+The Definition of `insert-buffer'
+
+* insert-buffer code::
+* insert-buffer interactive::   When you can read, but not write.
+* insert-buffer body::          The body has an `or' and a `let'.
+* if & or::                     Using an `if' instead of an `or'.
+* Insert or::                   How the `or' expression works.
+* Insert let::                  Two `save-excursion' expressions.
+* New insert-buffer::
+
+The Interactive Expression in `insert-buffer'
+
+* Read-only buffer::            When a buffer cannot be modified.
+* b for interactive::           An existing buffer or else its name.
+
+Complete Definition of `beginning-of-buffer'
+
+* Optional Arguments::
+* beginning-of-buffer opt arg::  Example with optional argument.
+* beginning-of-buffer complete::
+
+`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 `save-restriction' special form.
+* what-line::                   The number of the line that point is on.
+* narrow Exercise::
+
+`car', `cdr', `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 `cdr' repeatedly.
+* nth::
+* setcar::                      Changing the first element of a list.
+* setcdr::                      Changing the rest of a list.
+* cons Exercise::
+
+`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::
+
+`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 `progn' special form.
+* Summing up zap-to-char::      Using `point' and `search-forward'.
+
+`kill-region'
+
+* Complete kill-region::        The function definition.
+* condition-case::              Dealing with a problem.
+* Lisp macro::
+
+`copy-region-as-kill'
+
+* Complete copy-region-as-kill::  The complete function definition.
+* copy-region-as-kill body::    The body of `copy-region-as-kill'.
+
+The Body of `copy-region-as-kill'
+
+* last-command & this-command::
+* kill-append function::
+* kill-new function::
+
+Initializing a Variable with `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 `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::
+
+`while'
+
+* Looping with while::          Repeat so long as test returns true.
+* Loop Example::                A `while' loop that uses a list.
+* print-elements-of-list::      Uses `while', `car', `cdr'.
+* Incrementing Loop::           A loop with an incrementing counter.
+* Decrementing Loop::           A loop with a decrementing counter.
+
+A Loop with an Incrementing Counter
+
+* 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: `dolist' and `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 `sentence-end'.
+* re-search-forward::           Very similar to `search-forward'.
+* forward-sentence::            A straightforward example of regexp search.
+* forward-paragraph::           A somewhat complex example.
+* etags::                       How to create your own `TAGS' table.
+* Regexp Review::
+* re-search Exercises::
+
+`forward-sentence'
+
+* Complete forward-sentence::
+* fwd-sentence while loops::    Two `while' loops.
+* fwd-sentence re-search::      A regular expression search.
+
+`forward-paragraph': a Goldmine of Functions
+
+* forward-paragraph in brief::  Key parts of the function definition.
+* fwd-para let::                The `let*' expression.
+* fwd-para while::              The forward motion `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 `count-words-region' Function
+
+* Design count-words-region::   The definition using a `while' loop.
+* Whitespace Bug::              The Whitespace Bug in `count-words-region'.
+
+Counting Words in a `defun'
+
+* Divide and Conquer::
+* Words and Symbols::           What to count?
+* Syntax::                      What constitutes a word or symbol?
+* count-words-in-defun::        Very like `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 `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
+
+* 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 `.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 `.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 version 19 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 C-g.
+* edebug::                      How to use Edebug, a source level debugger.
+* Debugging Exercises::
+
+Handling the Kill Ring
+
+* current-kill::
+* yank::                        Paste a copy of a clipped element.
+* yank-pop::                    Insert element pointed to.
+* ring file::
+
+The `current-kill' Function
+
+* Understanding current-kill::
+
+`current-kill' in Outline
+
+* Digression concerning error::  How to mislead humans, but not computers.
+* Determining the Element::
+
+A Graph with Labelled Axes
+
+* Labelled Example::
+* print-graph Varlist::         `let' expression in `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 `print-Y-axis' Function
+
+* 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 `print-X-axis' Function
+
+* Similarities differences::    Much like `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 ... most insidious.
+* Final printed graph::         The graph itself!
+
+
+File: eintr,  Node: Preface,  Next: List Processing,  Prev: Top,  Up: Top
+
+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::
+* On Reading this Text::
+* Who You Are::
+* Lisp History::
+* Note for Novices::
+* Thank You::
+
+
+File: eintr,  Node: Why,  Next: On Reading this Text,  Prev: Preface,  Up: Preface
+
+Why Study Emacs Lisp?
+=====================
+
+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.
+
+
+File: eintr,  Node: On Reading this Text,  Next: Who You Are,  Prev: Why,  Up: Preface
+
+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 `M-.' (the key which
+invokes the `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.
+
+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.
+
+
+File: eintr,  Node: Who You Are,  Next: Lisp History,  Prev: On Reading this Text,  Up: Preface
+
+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:
+
+     I prefer to learn from reference manuals.  I "dive into" each
+     paragraph, and "come up for air" between paragraphs.
+
+     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.
+
+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 `Programming in Emacs Lisp' has a companion
+document, *Note The GNU Emacs Lisp Reference Manual: (elisp)Top.  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 `Introduction',
+you will find the `Reference Manual' useful when you are writing your
+own programs.
+
+
+File: eintr,  Node: Lisp History,  Next: Note for Novices,  Prev: Who You Are,  Up: Preface
+
+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.
+
+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, `cl.el', that adds many Common Lisp features to Emacs Lisp.)
+
+
+File: eintr,  Node: Note for Novices,  Next: Thank You,  Prev: Lisp History,  Up: Preface
+
+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 `C-h t'.  (This means
+you press and release the <CTRL> key and the `h' at the same time, and
+then press and release `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: `M-C-\' (`indent-region').  What
+this means is that the `indent-region' command is customarily invoked
+by typing `M-C-\'.  (You can, if you wish, change the keys that are
+typed to invoke the command; this is called "rebinding".  *Note
+Keymaps: Keymaps.)  The abbreviation `M-C-\' means that you type your
+<META> key, <CTRL> key and <\> key all at the same time.  (On many
+modern keyboards the <META> key is labelled <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
+<META> key, the <ESC> key prefix is used in place of it.  In this case,
+`M-C-\' means that you press and release your <ESC> key and then type
+the <CTRL> key and the <\> key at the same time.  But usually `M-C-\'
+means press the <CTRL> key along with the key that is labelled <ALT>
+and, at the same time, press the <\> key.
+
+In addition to typing a lone keychord, you can prefix what you type
+with `C-u', which is called the `universal argument'.  The `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
+`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.)  *Note Numeric Arguments: (emacs)Arguments.
+
+If you are reading this in Info using GNU Emacs, you can read through
+this whole document just by pressing the space bar, <SPC>.  (To learn
+about Info, type `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.
+
+
+File: eintr,  Node: Thank You,  Prev: Note for Novices,  Up: Preface
+
+Thank You
+=========
+
+My thanks to all who helped me with this book.  My especial thanks to
+Jim Blandy, Noah Friedman, Jim Kingdon, Roland McGrath, Frank Ritter,
+Randy Smith, Richard M. Stallman, and Melissa Weisshaus.  My thanks
+also go to both Philip Johnson and David Stampe for their patient
+encouragement.  My mistakes are my own.
+
+                                                     Robert J. Chassell
+
+
+File: eintr,  Node: List Processing,  Next: Practicing Evaluation,  Prev: Preface,  Up: Top
+
+1 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 _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,
+`''(1)  Lists are the basis of Lisp.
+
+* Menu:
+
+* Lisp Lists::
+* Run a Program::
+* Making Errors::
+* Names & Definitions::
+* Lisp Interpreter::
+* Evaluation::
+* Variables::
+* Arguments::
+* set & setq::
+* Summary::
+* Error Message Exercises::
+
+---------- Footnotes ----------
+
+(1) The single apostrophe or quotation mark is an abbreviation for the
+function `quote'; you need not think about functions now; functions are
+defined in *Note Generate an Error Message: Making Errors.
+
+
+File: eintr,  Node: Lisp Lists,  Next: Run a Program,  Prev: List Processing,  Up: List Processing
+
+1.1 Lisp Lists
+==============
+
+In Lisp, a list looks like this: `'(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:
+
+     '(rose
+       violet
+       daisy
+       buttercup)
+
+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.  
+
+* Menu:
+
+* Numbers Lists::
+* Lisp Atoms::
+* Whitespace in Lists::
+* Typing Lists::
+
+
+File: eintr,  Node: Numbers Lists,  Next: Lisp Atoms,  Prev: Lisp Lists,  Up: Lisp Lists
+
+Numbers, Lists inside of Lists
+------------------------------
+
+Lists can also have numbers in them, as in this list: `(+ 2 2)'.  This
+list has a plus-sign, `+', followed by two `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 _not_ Lisp lists, because they contain `;' and `.' as
+punctuation marks.)
+
+Here is another list, this time with a list inside of it:
+
+     '(this list has (a list inside of it))
+
+The components of this list are the words `this', `list', `has', and
+the list `(a list inside of it)'.  The interior list is made up of the
+words `a', `list', `inside', `of', `it'.
+
+
+File: eintr,  Node: Lisp Atoms,  Next: Whitespace in Lists,  Prev: Numbers Lists,  Up: Lisp Lists
+
+1.1.1 Lisp Atoms
+----------------
+
+In Lisp, what we have been calling words are called "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 `+'.  On the other hand, unlike an
+ancient atom, a list can be split into parts.  (*Note `car' `cdr' &
+`cons' Fundamental Functions: car cdr & cons.)
+
+In a list, atoms are separated from each other by whitespace.  They can
+be right next to a parenthesis.
+
+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:
+`()', and is called the "empty list".  Unlike anything else, an empty
+list is considered both an atom and a list at the same time.
+
+The printed representation of both atoms and lists are called "symbolic
+expressions" or, more concisely, "s-expressions".  The word
+"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 "expression" indiscriminately.  (Also, in
+many texts, the word "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 `ai', is completely
+different from the two words, `a', and `i'.
+
+There are many kinds of atom in nature but only a few in Lisp: for
+example, "numbers", such as 37, 511, or 1729, and "symbols", such as
+`+', `foo', or `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.)
+
+In addition, text between double quotation marks--even sentences or
+paragraphs--is an atom.  Here is an example: 
+
+     '(this list includes "text between quotation marks.")
+
+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 "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.
+
+
+File: eintr,  Node: Whitespace in Lists,  Next: Typing Lists,  Prev: Lisp Atoms,  Up: Lisp Lists
+
+1.1.2 Whitespace in Lists
+-------------------------
+
+The amount of whitespace in a list does not matter.  From the point of
+view of the Lisp language,
+
+     '(this list
+        looks like this)
+
+is exactly the same as this:
+
+     '(this list looks like this)
+
+Both examples show what to Lisp is the same list, the list made up of
+the symbols `this', `list', `looks', `like', and `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.)
+
+
+File: eintr,  Node: Typing Lists,  Prev: Whitespace in Lists,  Up: Lisp Lists
+
+1.1.3 GNU Emacs Helps You Type Lists
+------------------------------------
+
+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 <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 `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.
+(*Note Major Modes: (emacs)Major Modes, for more information about
+Emacs' modes.)
+
+
+File: eintr,  Node: Run a Program,  Next: Making Errors,  Prev: Lisp Lists,  Up: List Processing
+
+1.2 Run a Program
+=================
+
+A list in Lisp--any list--is a program ready to run.  If you run it
+(for which the Lisp jargon is "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!)
+
+The single apostrophe, `'', that I put in front of some of the example
+lists in preceding sections is called a "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 _functions_.)  The list `(+ 2 2)'
+shown above did not have a quote in front of it, so Lisp understands
+that the `+' is an instruction to do something with the rest of the
+list: add the numbers that follow.
+
+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 `C-x C-e':
+
+     (+ 2 2)
+
+You will see the number `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 `C-x C-e':
+
+     '(this is a quoted list)
+
+You will see `(this is a quoted list)' appear in the echo area.
+
+In both cases, what you are doing is giving a command to the program
+inside of GNU Emacs called the "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 (*note Variables::), we will discuss what the
+Lisp interpreter does when you make an error.
+
+
+File: eintr,  Node: Making Errors,  Next: Names & Definitions,  Prev: Run a Program,  Up: List Processing
+
+1.3 Generate an Error Message
+=============================
+
+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 `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 `C-x C-e':
+
+     (this is an unquoted list)
+
+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.
+
+In GNU Emacs version 22, a `*Backtrace*' window will open up and you
+will see the following in it:
+
+     ---------- 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* ----------
+
+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:
+
+     q
+
+Please type `q' right now, so you become confident that you can get out
+of the debugger.  Then, type `C-x C-e' again to re-enter it.
+
+Based on what we already know, we can almost read this error message.
+
+You read the `*Backtrace*' buffer from the bottom up; it tells you what
+Emacs did.  When you typed `C-x C-e', you made an interactive call to
+the command `eval-last-sexp'.  `eval' is an abbreviation for `evaluate'
+and `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
+`*Backtrace*' buffer because it enables you to track Emacs backwards.
+
+At the top of the `*Backtrace*' buffer, you see the line:
+
+     Debugger entered--Lisp error: (void-function this)
+
+The Lisp interpreter tried to evaluate the first atom of the list, the
+word `this'.  It is this action that generated the error message
+`void-function this'.
+
+The message contains the words `void-function' and `this'.
+
+The word `function' was mentioned once before.  It is a very important
+word.  For our purposes, we can define it by saying that a "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: `void-function this'.
+The function (that is, the word `this') does not have a definition of
+any set of instructions for the computer to carry out.
+
+The slightly odd word, `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 `(+ 2 2)', we can infer that the symbol `+' must have a set
+of instructions for the computer to obey and those instructions must be
+to add the numbers that follow the `+'.
+
+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:
+
+     Symbol's function definition is void: this
+
+(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 `Symbol'.  It refers to the first atom
+of the list, the word `this'.  The word `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: `Symbol's function definition is
+void: this'.  The symbol (that is, the word `this') lacks instructions
+for the computer to carry out.
+
+
+File: eintr,  Node: Names & Definitions,  Next: Lisp Interpreter,  Prev: Making Errors,  Up: List Processing
+
+1.4 Symbol Names and Function Definitions
+=========================================
+
+We can articulate another characteristic of Lisp based on what we have
+discussed so far--an important characteristic: a symbol, like `+', 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 `Bob'; however, I am not the letters `B',
+`o', `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 `plus' as well as to the symbol `+' (and are in some
+dialects of Lisp).  Among humans, I can be referred to as `Robert' as
+well as `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 `Bob'.  However, the function
+definition to which the name refers can be changed readily.  (*Note
+Install a Function Definition: Install.)
+
+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
+`texinfo-' and those for functions that deal with reading mail start
+with `rmail-'.
+
+
+File: eintr,  Node: Lisp Interpreter,  Next: Evaluation,  Prev: Names & Definitions,  Up: List Processing
+
+1.5 The Lisp Interpreter
+========================
+
+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::
+* Byte Compiling::
+
+
+File: eintr,  Node: Complications,  Next: Byte Compiling,  Prev: Lisp Interpreter,  Up: Lisp Interpreter
+
+Complications
+-------------
+
+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 "variable".  This situation is described in the
+section on variables.  (*Note Variables::.)
+
+The second complication occurs because some functions are unusual and do
+not work in the usual manner.  Those that don't are called "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.
+
+
+File: eintr,  Node: Byte Compiling,  Prev: Complications,  Up: Lisp Interpreter
+
+1.5.1 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 "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 `byte-compile-file'.  Byte
+compiled code is usually stored in a file that ends with a `.elc'
+extension rather than a `.el' extension.  You will see both kinds of
+file in the `emacs/lisp' directory; the files to read are those with
+`.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.  *Note Byte Compilation: (elisp)Byte Compilation, for a
+full description of byte compilation.
+
+
+File: eintr,  Node: Evaluation,  Next: Variables,  Prev: Lisp Interpreter,  Up: List Processing
+
+1.6 Evaluation
+==============
+
+When the Lisp interpreter works on an expression, the term for the
+activity is called "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 `Webster's New
+Collegiate Dictionary'.
+
+After evaluating an expression, the Lisp interpreter will most likely
+"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.
+
+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 "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.
+
+* Menu:
+
+* Evaluating Inner Lists::
+
+
+File: eintr,  Node: Evaluating Inner Lists,  Prev: Evaluation,  Up: Evaluation
+
+1.6.1 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.
+
+We can investigate this process by evaluating another addition example.
+Place your cursor after the following expression and type `C-x C-e':
+
+     (+ 2 (+ 3 3))
+
+The number 8 will appear in the echo area.
+
+What happens is that the Lisp interpreter first evaluates the inner
+expression, `(+ 3 3)', for which the value 6 is returned; then it
+evaluates the outer expression as if it were written `(+ 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 `C-x C-e': the name is `eval-last-sexp'.  The letters `sexp'
+are an abbreviation for `symbolic expression', and `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.
+
+Here is another copy of the expression:
+
+     (+ 2 (+ 3 3))
+
+If you place the cursor at the beginning of the blank line that
+immediately follows the expression and type `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 `(+ 3 3)'.
+
+Now put the cursor immediately after a number.  Type `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 `+', 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.
+
+
+File: eintr,  Node: Variables,  Next: Arguments,  Prev: Evaluation,  Up: List Processing
+
+1.7 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
+"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".
+
+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::
+* Void Variable::
+
+
+File: eintr,  Node: fill-column Example,  Next: Void Function,  Prev: Variables,  Up: Variables
+
+`fill-column', an Example Variable
+----------------------------------
+
+The variable `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 `C-x C-e':
+
+     fill-column
+
+After I typed `C-x C-e', Emacs printed the number 72 in my echo area.
+This is the value for which `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
+"bind" the variable to a value: to a number, such as 72; to a string,
+`"such as this"'; to a list, such as `(spruce pine oak)'; we can even
+bind a variable to a function definition.
+
+A symbol can be bound to a value in several ways.  *Note Setting the
+Value of a Variable: set & setq, for information about one way to do
+this.
+
+
+File: eintr,  Node: Void Function,  Next: Void Variable,  Prev: fill-column Example,  Up: Variables
+
+1.7.1 Error Message for a Symbol Without a Function
+---------------------------------------------------
+
+When we evaluated `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 `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 `fill-column' has no function definition.  Try evaluating this:
+
+     (fill-column)
+
+In GNU Emacs version 22, you will create a `*Backtrace*' buffer that
+says:
+
+     ---------- 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* ----------
+
+(Remember, to quit the debugger and make the debugger window go away,
+type `q' in the `*Backtrace*' buffer.)
+
+
+File: eintr,  Node: Void Variable,  Prev: Void Function,  Up: Variables
+
+1.7.2 Error Message for a Symbol Without a 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 `+', before the first number 2, type
+`C-x C-e':
+
+     (+ 2 2)
+
+In GNU Emacs 22, you will create a `*Backtrace*' buffer that says:
+
+     ---------- 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* ----------
+
+(As with the other times we entered the debugger, you can quit by
+typing `q' in the `*Backtrace*' buffer.)
+
+This backtrace is different from the very first error message we saw,
+which said, `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 `+', what we did was cause the Lisp
+interpreter to evaluate the `+' 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 `+' by
+itself.
+
+Since `+' 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.
+
+
+File: eintr,  Node: Arguments,  Next: set & setq,  Prev: Variables,  Up: List Processing
+
+1.8 Arguments
+=============
+
+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:
+
+     (+ 2 2)
+
+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 `+'.
+
+The numbers added by `+' are called the "arguments" of the function
+`+'.  These numbers are the information that is given to or "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 `+'.
+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.(1)
+
+* Menu:
+
+* Data types::
+* Args as Variable or List::
+* Variable Number of Arguments::
+* Wrong Type of Argument::
+* message::
+
+---------- Footnotes ----------
+
+(1) 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 `Oxford English Dictionary', the
+word derives from the Latin for `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.)
+
+
+File: eintr,  Node: Data types,  Next: Args as Variable or List,  Prev: Arguments,  Up: Arguments
+
+1.8.1 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 `+'
+must have values that are numbers, since `+' adds numbers.  Other
+functions use different kinds of data for their arguments.
+
+For example, the `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 `abc', `def' produces the
+single string `abcdef'.  This can be seen by evaluating the following:
+
+     (concat "abc" "def")
+
+The value produced by evaluating this expression is `"abcdef"'.
+
+A function such as `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.
+
+For example, if you evaluate the following:
+
+     (substring "The quick brown fox jumped." 16 19)
+
+you will see `"fox"' appear in the echo area.  The arguments are the
+string and the two numbers.
+
+Note that the string passed to `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 `substring' function as a
+kind of `atom smasher' since it takes an otherwise indivisible atom and
+extracts a part.  However, `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.
+
+
+File: eintr,  Node: Args as Variable or List,  Next: Variable Number of Arguments,  Prev: Data types,  Up: Arguments
+
+1.8.2 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 `fill-column' by itself is evaluated, it
+returns a number.  This number can be used in an addition.
+
+Position the cursor after the following expression and type `C-x C-e':
+
+     (+ 2 fill-column)
+
+The value will be a number two more than what you get by evaluating
+`fill-column' alone.  For me, this is 74, because my value of
+`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 `concat' are the strings `"The "' and
+`" red foxes."' and the list `(number-to-string (+ 2 fill-column))'.
+
+     (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
+
+If you evaluate this expression--and if, as with my Emacs,
+`fill-column' evaluates to 72--`"The 74 red foxes."' will appear in the
+echo area.  (Note that you must put spaces after the word `The' and
+before the word `red' so they will appear in the final string.  The
+function `number-to-string' converts the integer that the addition
+function returns to a string.  `number-to-string' is also known as
+`int-to-string'.)
+
+
+File: eintr,  Node: Variable Number of Arguments,  Next: Wrong Type of Argument,  Prev: Args as Variable or List,  Up: Arguments
+
+1.8.3 Variable Number of Arguments
+----------------------------------
+
+Some functions, such as `concat', `+' or `*', take any number of
+arguments.  (The `*' 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 `=>',
+which you may read as `evaluates to'.
+
+In the first set, the functions have no arguments:
+
+     (+)       => 0
+
+     (*)       => 1
+
+In this set, the functions have one argument each:
+
+     (+ 3)     => 3
+
+     (* 3)     => 3
+
+In this set, the functions have three arguments each:
+
+     (+ 3 4 5) => 12
+
+     (* 3 4 5) => 60
+
+
+File: eintr,  Node: Wrong Type of Argument,  Next: message,  Prev: Variable Number of Arguments,  Up: Arguments
+
+1.8.4 Using the Wrong Type Object as an Argument
+------------------------------------------------
+
+When a function is passed an argument of the wrong type, the Lisp
+interpreter produces an error message.  For example, the `+' function
+expects the values of its arguments to be numbers.  As an experiment we
+can pass it the quoted symbol `hello' instead of a number.  Position
+the cursor after the following expression and type `C-x C-e':
+
+     (+ 2 'hello)
+
+When you do this you will generate an error message.  What has happened
+is that `+' has tried to add the 2 to the value returned by `'hello',
+but the value returned by `'hello' is the symbol `hello', not a number.
+Only numbers can be added.  So `+' could not carry out its addition.
+
+In GNU Emacs version 22, you will create and enter a `*Backtrace*'
+buffer that says:
+
+
+     ---------- 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* ----------
+
+As usual, the error message tries to be helpful and makes sense after
+you learn how to read it.(1)
+
+The first part of the error message is straightforward; it says `wrong
+type argument'.  Next comes the mysterious jargon word
+`number-or-marker-p'.  This word is trying to tell you what kind of
+argument the `+' expected.
+
+The symbol `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 `+' 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 `C-@' or `C-<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, `+' can be used to add the numeric value of marker positions as
+numbers.
+
+The `p' of `number-or-marker-p' is the embodiment of a practice started
+in the early days of Lisp programming.  The `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 `p' tells us that `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 `p' include
+`zerop', a function that tests whether its argument has the value of
+zero, and `listp', a function that tests whether its argument is a list.
+
+Finally, the last part of the error message is the symbol `hello'.
+This is the value of the argument that was passed to `+'.  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
+`hello'.  But then you would not have got the error message.
+
+---------- Footnotes ----------
+
+(1) `(quote hello)' is an expansion of the abbreviation `'hello'.
+
+
+File: eintr,  Node: message,  Prev: Wrong Type of Argument,  Up: Arguments
+
+1.8.5 The `message' Function
+----------------------------
+
+Like `+', the `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.
+
+A message is printed in the echo area.  For example, you can print a
+message in your echo area by evaluating the following list:
+
+     (message "This message appears in the echo area!")
+
+The whole string between double quotation marks is a single argument
+and is printed 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 `message' function.  In most uses of
+`message' in programs that you write, the text will be printed in the
+echo area as a side-effect, without the quotes.  *Note
+`multiply-by-seven' in detail: multiply-by-seven in detail, for an
+example of this.)
+
+However, if there is a `%s' in the quoted string of characters, the
+`message' function does not print the `%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 `%s' is.
+
+You can see this by positioning the cursor after the following
+expression and typing `C-x C-e':
+
+     (message "The name of this buffer is: %s." (buffer-name))
+
+In Info, `"The name of this buffer is: *info*."' will appear in the
+echo area.  The function `buffer-name' returns the name of the buffer
+as a string, which the `message' function inserts in place of `%s'.
+
+To print a value as an integer, use `%d' in the same way as `%s'.  For
+example, to print a message in the echo area that states the value of
+the `fill-column', evaluate the following:
+
+     (message "The value of fill-column is %d." fill-column)
+
+On my system, when I evaluate this list, `"The value of fill-column is
+72."' appears in my echo area(1).
+
+If there is more than one `%s' in the quoted string, the value of the
+first argument following the quoted string is printed at the location
+of the first `%s' and the value of the second argument is printed at
+the location of the second `%s', and so on.
+
+For example, if you evaluate the following,
+
+     (message "There are %d %s in the office!"
+              (- fill-column 14) "pink elephants")
+
+a rather whimsical message will appear in your echo area.  On my system
+it says, `"There are 58 pink elephants in the office!"'.
+
+The expression `(- fill-column 14)' is evaluated and the resulting
+number is inserted in place of the `%d'; and the string in double
+quotes, `"pink elephants"', is treated as a single argument and
+inserted in place of the `%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 `%s':
+
+     (message "He saw %d %s"
+              (- fill-column 32)
+              (concat "red "
+                      (substring
+                       "The quick brown foxes jumped." 16 21)
+                      " leaping."))
+
+In this example, `message' has three arguments: the string, `"He saw %d
+%s"', the expression, `(- fill-column 32)', and the expression
+beginning with the function `concat'.  The value resulting from the
+evaluation of `(- fill-column 32)' is inserted in place of the `%d';
+and the value returned by the expression beginning with `concat' is
+inserted in place of the `%s'.
+
+When your fill column is 70 and you evaluate the expression, the
+message `"He saw 38 red foxes leaping."' appears in your echo area.
+
+---------- Footnotes ----------
+
+(1) Actually, you can use `%s' to print a number.  It is non-specific.
+`%d' prints only the part of a number left of a decimal point, and not
+anything that is not a number.
+
+
+File: eintr,  Node: set & setq,  Next: Summary,  Prev: Arguments,  Up: List Processing
+
+1.9 Setting the Value of a Variable
+===================================
+
+There are several ways by which a variable can be given a value.  One of
+the ways is to use either the function `set' or the function `setq'.
+Another way is to use `let' (*note let::).  (The jargon for this
+process is to "bind" a variable to a value.)
+
+The following sections not only describe how `set' and `setq' work but
+also illustrate how arguments are passed.
+
+* Menu:
+
+* Using set::
+* Using setq::
+* Counting::
+
+
+File: eintr,  Node: Using set,  Next: Using setq,  Prev: set & setq,  Up: set & setq
+
+1.9.1 Using `set'
+-----------------
+
+To set the value of the symbol `flowers' to the list `'(rose violet
+daisy buttercup)', evaluate the following expression by positioning the
+cursor after the expression and typing `C-x C-e'.
+
+     (set 'flowers '(rose violet daisy buttercup))
+
+The list `(rose violet daisy buttercup)' will appear in the echo area.
+This is what is _returned_ by the `set' function.  As a side effect,
+the symbol `flowers' is bound to the list; that is, the symbol
+`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 `set' expression, you can evaluate the symbol
+`flowers' and it will return the value you just set.  Here is the
+symbol.  Place your cursor after it and type `C-x C-e'.
+
+     flowers
+
+When you evaluate `flowers', the list `(rose violet daisy buttercup)'
+appears in the echo area.
+
+Incidentally, if you evaluate `'flowers', the variable with a quote in
+front of it, what you will see in the echo area is the symbol itself,
+`flowers'.  Here is the quoted symbol, so you can try this:
+
+     'flowers
+
+Note also, that when you use `set', you need to quote both arguments to
+`set', unless you want them evaluated.  Since we do not want either
+argument evaluated, neither the variable `flowers' nor the list `(rose
+violet daisy buttercup)', both are quoted.  (When you use `set' without
+quoting its first argument, the first argument is evaluated before
+anything else is done.  If you did this and `flowers' did not have a
+value already, you would get an error message that the `Symbol's value
+as variable is void'; on the other hand, if `flowers' did return a
+value after it was evaluated, the `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.)
+
+
+File: eintr,  Node: Using setq,  Next: Counting,  Prev: Using set,  Up: set & setq
+
+1.9.2 Using `setq'
+------------------
+
+As a practical matter, you almost always quote the first argument to
+`set'.  The combination of `set' and a quoted first argument is so
+common that it has its own name: the special form `setq'.  This special
+form is just like `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, `setq' permits you to set several
+different variables to different values, all in one expression.
+
+To set the value of the variable `carnivores' to the list `'(lion tiger
+leopard)' using `setq', the following expression is used:
+
+     (setq carnivores '(lion tiger leopard))
+
+This is exactly the same as using `set' except the first argument is
+automatically quoted by `setq'.  (The `q' in `setq' means `quote'.)
+
+With `set', the expression would look like this:
+
+     (set 'carnivores '(lion tiger leopard))
+
+Also, `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 `trees' and a list of herbivores
+to the symbol `herbivores':
+
+     (setq trees '(pine fir oak maple)
+           herbivores '(gazelle antelope zebra))
+
+(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 `set' and `setq'; and that is to say
+that `set' and `setq' make the symbol _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.
+
+
+File: eintr,  Node: Counting,  Prev: Using setq,  Up: set & setq
+
+1.9.3 Counting
+--------------
+
+Here is an example that shows how to use `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 `setq' expression
+that sets the counter variable to zero; and a second `setq' expression
+that increments the counter each time it is evaluated.
+
+     (setq counter 0)                ; Let's call this the initializer.
+
+     (setq counter (+ counter 1))    ; This is the incrementer.
+
+     counter                         ; This is the counter.
+
+(The text following the `;' are comments.  *Note Change a Function
+Definition: Change a defun.)
+
+If you evaluate the first of these expressions, the initializer, `(setq
+counter 0)', and then evaluate the third expression, `counter', the
+number `0' will appear in the echo area.  If you then evaluate the
+second expression, the incrementer, `(setq counter (+ counter 1))', the
+counter will get the value 1.  So if you again evaluate `counter', the
+number `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, `(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
+`counter' and the number `1'.  When it evaluates the variable
+`counter', it receives its current value.  It passes this value and the
+number `1' to the `+' which adds them together.  The sum is then
+returned as the value of the inner list and passed to the `setq' which
+sets the variable `counter' to this new value.  Thus, the value of the
+variable, `counter', is changed.
+
+
+File: eintr,  Node: Summary,  Next: Error Message Exercises,  Prev: set & setq,  Up: List Processing
+
+1.10 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.
+
+In summary,
+
+   * Lisp programs are made up of expressions, which are lists or
+     single atoms.
+
+   * Lists are made up of zero or more atoms or inner lists, separated
+     by whitespace and surrounded by parentheses.  A list can be empty.
+
+   * Atoms are multi-character symbols, like `forward-paragraph', single
+     character symbols like `+', strings of characters between double
+     quotation marks, or numbers.
+
+   * A number evaluates to itself.
+
+   * A string between double quotes also evaluates to itself.
+
+   * When you evaluate a symbol by itself, its value is returned.
+
+   * 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.
+
+   * A single quotation mark, ' , 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.
+
+   * 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.
+
+   * 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.
+
+
+File: eintr,  Node: Error Message Exercises,  Prev: Summary,  Up: List Processing
+
+1.11 Exercises
+==============
+
+A few simple exercises:
+
+   * Generate an error message by evaluating an appropriate symbol that
+     is not within parentheses.
+
+   * Generate an error message by evaluating an appropriate symbol that
+     is between parentheses.
+
+   * Create a counter that increments by two rather than one.
+
+   * Write an expression that prints a message in the echo area when
+     evaluated.
+
+
+File: eintr,  Node: Practicing Evaluation,  Next: Writing Defuns,  Prev: List Processing,  Up: Top
+
+2 Practicing Evaluation
+***********************
+
+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::
+* Buffer Names::
+* Getting Buffers::
+* Switching Buffers::
+* Buffer Size & Locations::
+* Evaluation Exercise::
+
+
+File: eintr,  Node: How to Evaluate,  Next: Buffer Names,  Prev: Practicing Evaluation,  Up: Practicing Evaluation
+
+How to Evaluate
+===============
+
+Whenever you give an editing command to Emacs Lisp, such as the command
+to move the cursor or to scroll the screen, you are evaluating an
+expression, the first element of which is a function.  This is how
+Emacs works.
+
+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
+`self-insert-command', which simply inserts the character you typed.
+The functions you evaluate by typing keystrokes are called
+"interactive" functions, or "commands"; how you make a function
+interactive will be illustrated in the chapter on how to write function
+definitions.  *Note Making a Function Interactive: 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 `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.
+
+
+File: eintr,  Node: Buffer Names,  Next: Getting Buffers,  Prev: How to Evaluate,  Up: Practicing Evaluation
+
+2.1 Buffer Names
+================
+
+The two functions, `buffer-name' and `buffer-file-name', show the
+difference between a file and a buffer.  When you evaluate the
+following expression, `(buffer-name)', the name of the buffer appears
+in the echo area.  When you evaluate `(buffer-file-name)', the name of
+the file to which the buffer refers appears in the echo area.  Usually,
+the name returned by `(buffer-name)' is the same as the name of the
+file to which it refers, and the name returned by `(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 "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.
+
+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 `C-x C-e'.
+
+     (buffer-name)
+
+     (buffer-file-name)
+
+When I do this in Info, the value returned by evaluating
+`(buffer-name)' is `"*info*"', and the value returned by evaluating
+`(buffer-file-name)' is `nil'.
+
+On the other hand, while I am writing this Introduction, the value
+returned by evaluating `(buffer-name)' is `"introduction.texinfo"', and
+the value returned by evaluating `(buffer-file-name)' is
+`"/gnu/work/intro/introduction.texinfo"'.
+
+The former is the name of the buffer and the latter is the name of the
+file.  In Info, the buffer name is `"*info*"'.  Info does not point to
+any file, so the result of evaluating `(buffer-file-name)' is `nil'.
+The symbol `nil' is from the Latin word for `nothing'; in this case, it
+means that the buffer is not associated with any file.  (In Lisp, `nil'
+is also used to mean `false' and is a synonym for the empty list, `()'.)
+
+When I am writing, the name of my buffer is `"introduction.texinfo"'.
+The name of the file to which it points is
+`"/gnu/work/intro/introduction.texinfo"'.
+
+(In the expressions, the parentheses tell the Lisp interpreter to treat
+`buffer-name' and `buffer-file-name' as functions; without the
+parentheses, the interpreter would attempt to evaluate the symbols as
+variables.  *Note 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.
+
+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 `*scratch*'
+buffer does not visit any file.  Similarly, a `*Help*' buffer is not
+associated with any file.
+
+In the old days, when you lacked a `~/.emacs' file and started an Emacs
+session by typing the command `emacs' alone, without naming any files,
+Emacs started with the `*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
+`*scratch*' buffer.
+
+If you switch to the `*scratch*' buffer, type `(buffer-name)', position
+the cursor after it, and then type `C-x C-e' to evaluate the
+expression.  The name `"*scratch*"' will be returned and will appear in
+the echo area.  `"*scratch*"' is the name of the buffer.  When you type
+`(buffer-file-name)' in the `*scratch*' buffer and evaluate that, `nil'
+will appear in the echo area, just as it does when you evaluate
+`(buffer-file-name)' in Info.
+
+Incidentally, if you are in the `*scratch*' buffer and want the value
+returned by an expression to appear in the `*scratch*' buffer itself
+rather than in the echo area, type `C-u C-x C-e' instead of `C-x C-e'.
+This causes the value returned to appear after the expression.  The
+buffer will look like this:
+
+     (buffer-name)"*scratch*"
+
+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.
+
+
+File: eintr,  Node: Getting Buffers,  Next: Switching Buffers,  Prev: Buffer Names,  Up: Practicing Evaluation
+
+2.2 Getting Buffers
+===================
+
+The `buffer-name' function returns the _name_ of the buffer; to get the
+buffer _itself_, a different function is needed: the `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 `G', `e', `o', `r', `g', and `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 `*scratch*', but
+the name is not the buffer.  To get a buffer itself, you need to use a
+function such as `current-buffer'.
+
+However, there is a slight complication: if you evaluate
+`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.
+
+Here is an expression containing the function:
+
+     (current-buffer)
+
+If you evaluate this expression in Info in Emacs in the usual way,
+`#<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 `current-buffer'.
+
+A related function is `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 `*scratch*' buffer, `other-buffer' will return that
+buffer.
+
+You can see this by evaluating the expression:
+
+     (other-buffer)
+
+You should see `#<buffer *scratch*>' appear in the echo area, or the
+name of whatever other buffer you switched back from most recently(1).
+
+---------- Footnotes ----------
+
+(1) Actually, by default, if the buffer from which you just switched is
+visible to you in another window, `other-buffer' will choose the most
+recent buffer that you cannot see; this is a subtlety that I often
+forget.
+
+
+File: eintr,  Node: Switching Buffers,  Next: Buffer Size & Locations,  Prev: Getting Buffers,  Up: Practicing Evaluation
+
+2.3 Switching Buffers
+=====================
+
+The `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 `other-buffer' and `switch-to-buffer' to switch to a different
+buffer.
+
+But first, a brief introduction to the `switch-to-buffer' function.
+When you switched back and forth from Info to the `*scratch*' buffer to
+evaluate `(buffer-name)', you most likely typed `C-x b' and then typed
+`*scratch*'(1) when prompted in the minibuffer for the name of the
+buffer to which you wanted to switch.  The keystrokes, `C-x b', cause
+the Lisp interpreter to evaluate the interactive function
+`switch-to-buffer'.  As we said before, this is how Emacs works:
+different keystrokes call or run different functions.  For example,
+`C-f' calls `forward-char', `M-e' calls `forward-sentence', and so on.
+
+By writing `switch-to-buffer' in an expression, and giving it a buffer
+to switch to, we can switch buffers just the way `C-x b' does.
+
+Here is the Lisp expression:
+
+     (switch-to-buffer (other-buffer))
+
+The symbol `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 `other-buffer' is inside parentheses and
+work on that symbol first.  `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 `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 `C-x
+b <RET>'.)(2)
+
+In the programming examples in later sections of this document, you will
+see the function `set-buffer' more often than `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.
+
+`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.
+`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).
+
+Also, we have just introduced another jargon term, the word "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.
+
+---------- Footnotes ----------
+
+(1) Or rather, to save typing, you probably only typed `RET' if the
+default buffer was `*scratch*', or if it was different, then you typed
+just part of the name, such as `*sc', pressed your `TAB' key to cause
+it to expand to the full name, and then typed your `RET' key.
+
+(2) 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:
+
+     (switch-to-buffer (other-buffer (current-buffer) t))
+
+In this case, the first argument to `other-buffer' tells it which
+buffer to skip--the current one--and the second argument tells
+`other-buffer' it is OK to switch to a visible buffer.  In regular use,
+`switch-to-buffer' takes you to an invisible window since you would
+most likely use `C-x o' (`other-window') to go to another visible
+buffer.
+
+
+File: eintr,  Node: Buffer Size & Locations,  Next: Evaluation Exercise,  Prev: Switching Buffers,  Up: Practicing Evaluation
+
+2.4 Buffer Size and the Location of Point
+=========================================
+
+Finally, let's look at several rather simple functions, `buffer-size',
+`point', `point-min', and `point-max'.  These give information about
+the size of a buffer and the location of point within it.
+
+The function `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.
+
+     (buffer-size)
+
+You can evaluate this in the usual way, by positioning the cursor after
+the expression and typing `C-x C-e'.
+
+In Emacs, the current  position of the cursor is called "point".  The
+expression `(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.
+
+You can see the character count for point in this buffer by evaluating
+the following expression in the usual way:
+
+     (point)
+
+As I write this, the value of `point' is 65724.  The `point' function
+is frequently used in some of the examples later in this book.
+
+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:
+
+     (point)
+
+For me, the value of point in this location is 66043, which means that
+there are 319 characters (including spaces) between the two expressions.
+
+The function `point-min' is somewhat similar to `point', but it returns
+the value of the minimum permissible value of point in the current
+buffer.  This is the number 1 unless "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.  *Note Narrowing and
+Widening: Narrowing & Widening.)  Likewise, the function `point-max'
+returns the value of the maximum permissible value of point in the
+current buffer.
+
+
+File: eintr,  Node: Evaluation Exercise,  Prev: Buffer Size & Locations,  Up: Practicing Evaluation
+
+2.5 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.
+
+
+File: eintr,  Node: Writing Defuns,  Next: Buffer Walk Through,  Prev: Practicing Evaluation,  Up: Top
+
+3 How To Write Function Definitions
+***********************************
+
+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::
+* Install::
+* Interactive::
+* Interactive Options::
+* Permanent Installation::
+* let::
+* if::
+* else::
+* Truth & Falsehood::
+* save-excursion::
+* Review::
+* defun Exercises::
+
+
+File: eintr,  Node: Primitive Functions,  Next: defun,  Prev: Writing Defuns,  Up: Writing Defuns
+
+An Aside about Primitive Functions
+==================================
+
+All functions are defined in terms of other functions, except for a few
+"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.
+
+
+File: eintr,  Node: defun,  Next: Install,  Prev: Primitive Functions,  Up: Writing Defuns
+
+3.1 The `defun' Special Form
+============================
+
+In Lisp, a symbol such as `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 "function definition" and is created by evaluating a
+Lisp expression that starts with the symbol `defun' (which is an
+abbreviation for _define function_).  Because `defun' does not evaluate
+its arguments in the usual way, it is called a "special form".
+
+In subsequent sections, we will look at function definitions from the
+Emacs source code, such as `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 `defun':
+
+  1. The name of the symbol to which the function definition should be
+     attached.
+
+  2. 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,
+     `()'.
+
+  3. Documentation describing the function.  (Technically optional, but
+     strongly recommended.)
+
+  4. Optionally, an expression to make the function interactive so you
+     can use it by typing `M-x' and then the name of the function; or by
+     typing an appropriate key or keychord.
+
+  5. The code that instructs the computer what to do: the "body" of the
+     function definition.
+
+It is helpful to think of the five parts of a function definition as
+being organized in a template, with slots for each part:
+
+     (defun FUNCTION-NAME (ARGUMENTS...)
+       "OPTIONAL-DOCUMENTATION..."
+       (interactive ARGUMENT-PASSING-INFO)     ; optional
+       BODY...)
+
+As an example, here is the code for a function that multiplies its
+argument by 7.  (This example is not interactive.  *Note Making a
+Function Interactive: Interactive, for that information.)
+
+     (defun multiply-by-seven (number)
+       "Multiply NUMBER by seven."
+       (* 7 number))
+
+This definition begins with a parenthesis and the symbol `defun',
+followed by the name of the function.
+
+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
+"argument list".  In this example, the list has only one element, the
+symbol, `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 `number' for the name of the argument, I
+could have picked any other name.  For example, I could have chosen the
+word `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 `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 `let' expression.  (*Note `let': let.)
+
+The argument list is followed by the documentation string that
+describes the function.  This is what you see when you type `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 `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 `C-h f' (`describe-function').  The
+documentation string is optional, but it is so useful, it should be
+included in almost every function you write.
+
+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, `(* 7 number)', which
+says to multiply the value of NUMBER by 7.  (In Emacs Lisp, `*' is the
+function for multiplication, just as `+' is the function for addition.)
+
+When you use the `multiply-by-seven' function, the argument `number'
+evaluates to the actual number you want used.  Here is an example that
+shows how `multiply-by-seven' is used; but don't try to evaluate this
+yet!
+
+     (multiply-by-seven 3)
+
+The symbol `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 `number' was inside parentheses in the
+function definition, the argument passed to the `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.
+
+
+File: eintr,  Node: Install,  Next: Interactive,  Prev: defun,  Up: Writing Defuns
+
+3.2 Install a Function Definition
+=================================
+
+If you are reading this inside of Info in Emacs, you can try out the
+`multiply-by-seven' function by first evaluating the function
+definition and then evaluating `(multiply-by-seven 3)'.  A copy of the
+function definition follows.  Place the cursor after the last
+parenthesis of the function definition and type `C-x C-e'.  When you do
+this, `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.
+
+     (defun multiply-by-seven (number)
+       "Multiply NUMBER by seven."
+       (* 7 number))
+
+By evaluating this `defun', you have just installed `multiply-by-seven'
+in Emacs.  The function is now just as much a part of Emacs as
+`forward-word' or any other editing function you use.
+(`multiply-by-seven' will stay installed until you quit Emacs.  To
+reload code automatically whenever you start Emacs, see *Note
+Installing Code Permanently: Permanent Installation.)
+
+* Menu:
+
+* Effect of installation::
+* Change a defun::
+
+
+File: eintr,  Node: Effect of installation,  Next: Change a defun,  Prev: Install,  Up: Install
+
+The effect of installation
+--------------------------
+
+You can see the effect of installing `multiply-by-seven' by evaluating
+the following sample.  Place the cursor after the following expression
+and type `C-x C-e'.  The number 21 will appear in the echo area.
+
+     (multiply-by-seven 3)
+
+If you wish, you can read the documentation for the function by typing
+`C-h f' (`describe-function') and then the name of the function,
+`multiply-by-seven'.  When you do this, a `*Help*' window will appear
+on your screen that says:
+
+     multiply-by-seven is a Lisp function.
+     (multiply-by-seven NUMBER)
+
+     Multiply NUMBER by seven.
+
+(To return to a single window on your screen, type `C-x 1'.)
+
+
+File: eintr,  Node: Change a defun,  Prev: Effect of installation,  Up: Install
+
+3.2.1 Change a Function Definition
+----------------------------------
+
+If you want to change the code in `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 `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".
+
+     (defun multiply-by-seven (number)       ; Second version.
+       "Multiply NUMBER by seven."
+       (+ number number number number number number number))
+
+The comment follows a semicolon, `;'.  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.
+
+*Note Beginning a `.emacs' File: Beginning a .emacs File, and *Note
+Comments: (elisp)Comments, for more about comments.
+
+You can install this version of the `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 `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.
+
+
+File: eintr,  Node: Interactive,  Next: Interactive Options,  Prev: Install,  Up: Writing Defuns
+
+3.3 Make a Function Interactive
+===============================
+
+You make a function interactive by placing a list that begins with the
+special form `interactive' immediately after the documentation.  A user
+can invoke an interactive function by typing `M-x' and then the name of
+the function; or by typing the keys to which it is bound, for example,
+by typing `C-n' for `next-line' or `C-x h' for `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::
+* multiply-by-seven in detail::
+
+
+File: eintr,  Node: Interactive multiply-by-seven,  Next: multiply-by-seven in detail,  Prev: Interactive,  Up: Interactive
+
+An Interactive `multiply-by-seven', An Overview
+-----------------------------------------------
+
+Both the use of the special form `interactive' and one way to display a
+value in the echo area can be illustrated by creating an interactive
+version of `multiply-by-seven'.
+
+Here is the code:
+
+     (defun multiply-by-seven (number)       ; Interactive version.
+       "Multiply NUMBER by seven."
+       (interactive "p")
+       (message "The result is %d" (* 7 number)))
+
+You can install this code by placing your cursor after it and typing
+`C-x C-e'.  The name of the function will appear in your echo area.
+Then, you can use this code by typing `C-u' and a number and then
+typing `M-x multiply-by-seven' and pressing <RET>.  The phrase `The
+result is ...' followed by the product will appear in the echo area.
+
+Speaking more generally, you invoke a function like this in either of
+two ways:
+
+  1. By typing a prefix argument that contains the number to be passed,
+     and then typing `M-x' and the name of the function, as with `C-u 3
+     M-x forward-sentence'; or,
+
+  2. By typing whatever key or keychord the function is bound to, as
+     with `C-u 3 M-e'.
+
+Both the examples just mentioned work identically to move point forward
+three sentences.  (Since `multiply-by-seven' is not bound to a key, it
+could not be used as an example of key binding.)
+
+(*Note Some Keybindings: Keybindings, to learn how to bind a command to
+a key.)
+
+A prefix argument is passed to an interactive function by typing the
+<META> key followed by a number, for example, `M-3 M-e', or by typing
+`C-u' and then a number, for example, `C-u 3 M-e' (if you type `C-u'
+without a number, it defaults to 4).
+
+
+File: eintr,  Node: multiply-by-seven in detail,  Prev: Interactive multiply-by-seven,  Up: Interactive
+
+3.3.1 An Interactive `multiply-by-seven'
+----------------------------------------
+
+Let's look at the use of the special form `interactive' and then at the
+function `message' in the interactive version of `multiply-by-seven'.
+You will recall that the function definition looks like this:
+
+     (defun multiply-by-seven (number)       ; Interactive version.
+       "Multiply NUMBER by seven."
+       (interactive "p")
+       (message "The result is %d" (* 7 number)))
+
+In this function, the expression, `(interactive "p")', is a list of two
+elements.  The `"p"' tells Emacs to pass the prefix argument to the
+function and use its value for the argument of the function.
+
+The argument will be a number.  This means that the symbol `number'
+will be bound to a number in the line:
+
+     (message "The result is %d" (* 7 number))
+
+For example, if your prefix argument is 5, the Lisp interpreter will
+evaluate the line as if it were:
+
+     (message "The result is %d" (* 7 5))
+
+(If you are reading this in GNU Emacs, you can evaluate this expression
+yourself.)  First, the interpreter will evaluate the inner list, which
+is `(* 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 `message'.
+
+As we have seen, `message' is an Emacs Lisp function especially
+designed for sending a one line message to a user.  (*Note The
+`message' function: message.)  In summary, the `message' function
+prints its first argument in the echo area as is, except for
+occurrences of `%d' or `%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 `multiply-by-seven' function, the control string is
+`%d', which requires a number, and the value returned by evaluating `(*
+7 5)' is the number 35.  Consequently, the number 35 is printed in
+place of the `%d' and the message is `The result is 35'.
+
+(Note that when you call the function `multiply-by-seven', the message
+is printed without quotes, but when you call `message', the text is
+printed in double quotes.  This is because the value returned by
+`message' is what appears in the echo area when you evaluate an
+expression whose first element is `message'; but when embedded in a
+function, `message' prints the text as a side effect without quotes.)
+
+
+File: eintr,  Node: Interactive Options,  Next: Permanent Installation,  Prev: Interactive,  Up: Writing Defuns
+
+3.4 Different Options for `interactive'
+=======================================
+
+In the example, `multiply-by-seven' used `"p"' as the argument to
+`interactive'.  This argument told Emacs to interpret your typing
+either `C-u' followed by a number or <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 `interactive'.  In
+almost every case, one of these options will enable you to pass the
+right information interactively to a function.  (*Note Code Characters
+for `interactive': (elisp)Interactive Codes.)
+
+Consider the function `zap-to-char'.  Its interactive expression is
+
+     (interactive "p\ncZap to char: ")
+
+The first part of the argument to `interactive' is `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 `C-u' followed by a number or by typing <META>
+followed by a number.  The prefix is the number of specified
+characters.  Thus, if your prefix is three and the specified character
+is `x', then you will delete all the text up to and including the third
+next `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 `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 `interactive'.  When you do this, the information is passed to
+each argument in the same order it is specified in the `interactive'
+list.  In the string, each part is separated from the next part by a
+`\n', which is a newline.  For example, you can follow `p' with a `\n'
+and an `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
+`arg' and `char' are the symbols to which `interactive' binds the
+prefix argument and the specified character:
+
+     (defun NAME-OF-FUNCTION (arg char)
+       "DOCUMENTATION..."
+       (interactive "p\ncZap to char: ")
+       BODY-OF-FUNCTION...)
+
+(The space after the colon in the prompt makes it look better when you
+are prompted.  *Note The Definition of `copy-to-buffer':
+copy-to-buffer, for an example.)
+
+When a function does not take arguments, `interactive' does not require
+any.  Such a function contains the simple expression `(interactive)'.
+The `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 `interactive' as a list.
+
+*Note The Definition of `append-to-buffer': append-to-buffer, for an
+example.  *Note Using `Interactive': (elisp)Using Interactive, for a
+more complete explanation about this technique.
+
+
+File: eintr,  Node: Permanent Installation,  Next: let,  Prev: Interactive Options,  Up: Writing Defuns
+
+3.5 Install Code Permanently
+============================
+
+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:
+
+   * If you have code that is just for yourself, you can put the code
+     for the function definition in your `.emacs' initialization file.
+     When you start Emacs, your `.emacs' file is automatically
+     evaluated and all the function definitions within it are installed.
+     *Note Your `.emacs' File: Emacs Initialization.
+
+   * Alternatively, you can put the function definitions that you want
+     installed in one or more files of their own and use the `load'
+     function to cause Emacs to evaluate and thereby install each of the
+     functions in the files.  *Note Loading Files: Loading Files.
+
+   * Thirdly, if you have code that your whole site will use, it is
+     usual to put it in a file called `site-init.el' that is loaded when
+     Emacs is built.  This makes the code available to everyone who uses
+     your machine.  (See the `INSTALL' file that is part of the Emacs
+     distribution.)
+
+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.
+
+
+File: eintr,  Node: let,  Next: if,  Prev: Permanent Installation,  Up: Writing Defuns
+
+3.6 `let'
+=========
+
+The `let' expression is a special form in Lisp that you will need to
+use in most function definitions.
+
+`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 `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 _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 `let'
+special form prevents this kind of confusion.
+
+* Menu:
+
+* Prevent confusion::
+* Parts of let Expression::
+* Sample let Expression::
+* Uninitialized let Variables::
+
+
+File: eintr,  Node: Prevent confusion,  Next: Parts of let Expression,  Prev: let,  Up: let
+
+`let' Prevents Confusion
+------------------------
+
+The `let' special form prevents confusion.  `let' creates a name for a
+"local variable" that overshadows any use of the same name outside the
+`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.  *Note The `defun' Special Form:
+defun.)
+
+Local variables created by a `let' expression retain their value _only_
+within the `let' expression itself (and within expressions called
+within the `let' expression); the local variables have no effect
+outside the `let' expression.
+
+Another way to think about `let' is that it is like a `setq' that is
+temporary and local.  The values set by `let' are automatically undone
+when the `let' is finished.  The setting only affects expressions that
+are inside the bounds of the `let' expression.  In computer science
+jargon, we would say "the binding of a symbol is visible only in
+functions called in the `let' form; in Emacs Lisp, scoping is dynamic,
+not lexical."
+
+`let' can create more than one variable at once.  Also, `let' gives
+each variable it creates an initial value, either a value specified by
+you, or `nil'.  (In the jargon, this is called `binding the variable to
+the value'.)  After `let' has created and bound the variables, it
+executes the code in the body of the `let', and returns the value of
+the last expression in the body, as the value of the whole `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'
+(`Oxford English Dictionary').  Since you evaluate an expression to
+perform an action, `execute' has evolved as a synonym to `evaluate'.)
+
+
+File: eintr,  Node: Parts of let Expression,  Next: Sample let Expression,  Prev: Prevent confusion,  Up: let
+
+3.6.1 The Parts of a `let' Expression
+-------------------------------------
+
+A `let' expression is a list of three parts.  The first part is the
+symbol `let'.  The second part is a list, called a "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 `let'
+expression is the body of the `let'.  The body usually consists of one
+or more lists.
+
+A template for a `let' expression looks like this:
+
+     (let VARLIST BODY...)
+
+The symbols in the varlist are the variables that are given initial
+values by the `let' special form.  Symbols by themselves are given the
+initial value of `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: `(thread (needles 3))'.  In this
+case, in a `let' expression, Emacs binds the symbol `thread' to an
+initial value of `nil', and binds the symbol `needles' to an initial
+value of 3.
+
+When you write a `let' expression, what you do is put the appropriate
+expressions in the slots of the `let' expression template.
+
+If the varlist is composed of two-element lists, as is often the case,
+the template for the `let' expression looks like this:
+
+     (let ((VARIABLE VALUE)
+           (VARIABLE VALUE)
+           ...)
+       BODY...)
+
+
+File: eintr,  Node: Sample let Expression,  Next: Uninitialized let Variables,  Prev: Parts of let Expression,  Up: let
+
+3.6.2 Sample `let' Expression
+-----------------------------
+
+The following expression creates and gives initial values to the two
+variables `zebra' and `tiger'.  The body of the `let' expression is a
+list which calls the `message' function.
+
+     (let ((zebra 'stripes)
+           (tiger 'fierce))
+       (message "One kind of animal has %s and another is %s."
+                zebra tiger))
+
+Here, the varlist is `((zebra 'stripes) (tiger 'fierce))'.
+
+The two variables are `zebra' and `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 `zebra'
+to the value `stripes'(1), and binds the variable `tiger' to the value
+`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 `let' follows after the list holding the
+variables.  In this example, the body is a list that uses the `message'
+function to print a string in the echo area.
+
+You may evaluate the example in the usual fashion, by placing the
+cursor after the last parenthesis and typing `C-x C-e'.  When you do
+this, the following will appear in the echo area:
+
+     "One kind of animal has stripes and another is fierce."
+
+As we have seen before, the `message' function prints its first
+argument, except for `%s'.  In this example, the value of the variable
+`zebra' is printed at the location of the first `%s' and the value of
+the variable `tiger' is printed at the location of the second `%s'.
+
+---------- Footnotes ----------
+
+(1) According to Jared Diamond in `Guns, Germs, and Steel', "... 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)
+
+
+File: eintr,  Node: Uninitialized let Variables,  Prev: Sample let Expression,  Up: let
+
+3.6.3 Uninitialized Variables in a `let' Statement
+--------------------------------------------------
+
+If you do not bind the variables in a `let' statement to specific
+initial values, they will automatically be bound to an initial value of
+`nil', as in the following expression:
+
+     (let ((birch 3)
+           pine
+           fir
+           (oak 'some))
+       (message
+        "Here are %d variables with %s, %s, and %s value."
+        birch pine fir oak))
+
+Here, the varlist is `((birch 3) pine fir (oak 'some))'.
+
+If you evaluate this expression in the usual way, the following will
+appear in your echo area:
+
+     "Here are 3 variables with nil, nil, and some value."
+
+In this example, Emacs binds the symbol `birch' to the number 3, binds
+the symbols `pine' and `fir' to `nil', and binds the symbol `oak' to
+the value `some'.
+
+Note that in the first part of the `let', the variables `pine' and
+`fir' stand alone as atoms that are not surrounded by parentheses; this
+is because they are being bound to `nil', the empty list.  But `oak' is
+bound to `some' and so is a part of the list `(oak 'some)'.  Similarly,
+`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 `%d' rather
+than a `%s'.)  The four variables as a group are put into a list to
+delimit them from the body of the `let'.
+
+
+File: eintr,  Node: if,  Next: else,  Prev: let,  Up: Writing Defuns
+
+3.7 The `if' Special Form
+=========================
+
+A third special form, in addition to `defun' and `let', is the
+conditional `if'.  This form is used to instruct the computer to make
+decisions.  You can write function definitions without using `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
+`beginning-of-buffer'.
+
+The basic idea behind an `if', is that "_if_ a test is true, _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::
+
+
+File: eintr,  Node: if in more detail,  Next: type-of-animal in detail,  Prev: if,  Up: if
+
+`if' in more detail
+-------------------
+
+An `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 `if'.  Nonetheless, the test part of an `if'
+expression is often called the "if-part" and the second argument is
+often called the "then-part".
+
+Also, when an `if' expression is written, the true-or-false-test is
+usually written on the same line as the symbol `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 `if' expression easier to
+read.
+
+     (if TRUE-OR-FALSE-TEST
+         ACTION-TO-CARRY-OUT-IF-TEST-IS-TRUE)
+
+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 `5 is greater than 4!' will be printed.
+
+     (if (> 5 4)                             ; if-part
+         (message "5 is greater than 4!"))   ; then-part
+
+(The function `>' tests whether its first argument is greater than its
+second argument and returns true if it is.)  
+
+Of course, in actual use, the test in an `if' expression will not be
+fixed for all time as it is by the expression `(> 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
+`characteristic' is `fierce', then the message, `It's a tiger!' will be
+printed; otherwise, `nil' will be returned.
+
+     (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!")))
+
+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:
+
+     (type-of-animal 'fierce)
+
+     (type-of-animal 'zebra)
+
+When you evaluate `(type-of-animal 'fierce)', you will see the
+following message printed in the echo area: `"It's a tiger!"'; and when
+you evaluate `(type-of-animal 'zebra)' you will see `nil' printed in
+the echo area.
+
+
+File: eintr,  Node: type-of-animal in detail,  Prev: if in more detail,  Up: if
+
+3.7.1 The `type-of-animal' Function in Detail
+---------------------------------------------
+
+Let's look at the `type-of-animal' function in detail.
+
+The function definition for `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 `if' expression.
+
+The template for every function that is not interactive is:
+
+     (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
+       "DOCUMENTATION..."
+       BODY...)
+
+The parts of the function that match this template look like this:
+
+     (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."
+       BODY: THE `if' EXPRESSION)
+
+The name of function is `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 `if'
+expression.
+
+The template for an `if' expression looks like this:
+
+     (if TRUE-OR-FALSE-TEST
+         ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE)
+
+In the `type-of-animal' function, the code for the `if' looks like this:
+
+     (if (equal characteristic 'fierce)
+         (message "It's a tiger!")))
+
+Here, the true-or-false-test is the expression:
+
+     (equal characteristic 'fierce)
+
+In Lisp, `equal' is a function that determines whether its first
+argument is equal to its second argument.  The second argument is the
+quoted symbol `'fierce' and the first argument is the value of the
+symbol `characteristic'--in other words, the argument passed to this
+function.
+
+In the first exercise of `type-of-animal', the argument `fierce' is
+passed to `type-of-animal'.  Since `fierce' is equal to `fierce', the
+expression, `(equal characteristic 'fierce)', returns a value of true.
+When this happens, the `if' evaluates the second argument or then-part
+of the `if': `(message "It's tiger!")'.
+
+On the other hand, in the second exercise of `type-of-animal', the
+argument `zebra' is passed to `type-of-animal'.  `zebra' is not equal
+to `fierce', so the then-part is not evaluated and `nil' is returned by
+the `if' expression.
+
+
+File: eintr,  Node: else,  Next: Truth & Falsehood,  Prev: if,  Up: Writing Defuns
+
+3.8 If-then-else Expressions
+============================
+
+An `if' expression may have an optional third argument, called the
+"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 `if'
+expression is _not_ evaluated, but the third or else-part _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
+`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:
+
+     (if TRUE-OR-FALSE-TEST
+         ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE
+       ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-FALSE)
+
+For example, the following `if' expression prints the message `4 is not
+greater than 5!' when you evaluate it in the usual way:
+
+     (if (> 4 5)                             ; if-part
+         (message "5 is greater than 4!")    ; then-part
+       (message "4 is not greater than 5!")) ; else-part
+
+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 `if' expressions correctly.  *Note
+GNU Emacs Helps You Type Lists: Typing Lists.)
+
+We can extend the `type-of-animal' function to include an else-part by
+simply incorporating an additional part to the `if' expression.
+
+You can see the consequences of doing this if you evaluate the following
+version of the `type-of-animal' function definition to install it and
+then evaluate the two subsequent expressions to pass different
+arguments to the function.
+
+     (defun type-of-animal (characteristic)  ; 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!")))
+
+
+     (type-of-animal 'fierce)
+
+     (type-of-animal 'zebra)
+
+When you evaluate `(type-of-animal 'fierce)', you will see the
+following message printed in the echo area: `"It's a tiger!"'; but when
+you evaluate `(type-of-animal 'zebra)', you will see `"It's not
+fierce!"'.
+
+(Of course, if the CHARACTERISTIC were `ferocious', the message `"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 `if' and write your program
+accordingly.)
+
+
+File: eintr,  Node: Truth & Falsehood,  Next: save-excursion,  Prev: else,  Up: Writing Defuns
+
+3.9 Truth and Falsehood in Emacs Lisp
+=====================================
+
+There is an important aspect to the truth test in an `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 `nil'.  Anything else--anything at all--is `true'.
+
+The expression that tests for truth is interpreted as "true" if the
+result of evaluating it is a value that is not `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 `"hello"', or a symbol (other than
+`nil') such as `flowers', or a list (so long as it is not empty), or
+even a buffer!
+
+* Menu:
+
+* nil explained::
+
+
+File: eintr,  Node: nil explained,  Prev: Truth & Falsehood,  Up: Truth & Falsehood
+
+An explanation of `nil'
+-----------------------
+
+Before illustrating a test for truth, we need an explanation of `nil'.
+
+In Emacs Lisp, the symbol `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.  `nil' can be written as an empty list,
+`()', or as `nil'.  As far as the Lisp interpreter is concerned, `()'
+and `nil' are the same.  Humans, however, tend to use `nil' for false
+and `()' for the empty list.
+
+In Emacs Lisp, any value that is not `nil'--is not the empty list--is
+considered true.  This means that if an evaluation returns something
+that is not an empty list, an `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 `if' expression will test true.
+The expression tests false only when `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 `if'
+expression and returns itself; consequently, the then-part of the
+expression is evaluated and returned: `true' appears in the echo area.
+In the second example, the `nil' indicates false; consequently, the
+else-part of the expression is evaluated and returned: `false' appears
+in the echo area.
+
+     (if 4
+         'true
+       'false)
+
+     (if nil
+         'true
+       'false)
+
+Incidentally, if some other useful value is not available for a test
+that returns true, then the Lisp interpreter will return the symbol `t'
+for true.  For example, the expression `(> 5 4)' returns `t' when
+evaluated, as you can see by evaluating it in the usual way:
+
+     (> 5 4)
+
+On the other hand, this function returns `nil' if the test is false.
+
+     (> 4 5)
+
+
+File: eintr,  Node: save-excursion,  Next: Review,  Prev: Truth & Falsehood,  Up: Writing Defuns
+
+3.10 `save-excursion'
+=====================
+
+The `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 `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::
+* Template for save-excursion::
+
+
+File: eintr,  Node: Point and mark,  Next: Template for save-excursion,  Prev: save-excursion,  Up: save-excursion
+
+Point and Mark
+--------------
+
+Before discussing `save-excursion', however, it may be useful first to
+review what point and mark are in GNU Emacs.  "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 `point' returns the
+current position of the cursor as a number.  Each buffer has its own
+value for point.
+
+The "mark" is another position in the buffer; its value can be set with
+a command such as `C-<SPC>' (`set-mark-command').  If a mark has been
+set, you can use the command `C-x C-x' (`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 `C-u C-<SPC>' one or more times.
+
+The part of the buffer between point and mark is called "the region".
+Numerous commands work on the region, including `center-region',
+`count-lines-region', `kill-region', and `print-region'.
+
+The `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 `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,
+`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, `save-excursion' is often used to keep point and
+mark in the location expected by the user.  The use of `save-excursion'
+is good housekeeping.
+
+To make sure the house stays clean, `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, `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
+`save-excursion' switch you back to the original buffer.  This is how
+`save-excursion' is used in `append-to-buffer'.  (*Note The Definition
+of `append-to-buffer': append-to-buffer.)
+
+
+File: eintr,  Node: Template for save-excursion,  Prev: Point and mark,  Up: save-excursion
+
+3.10.1 Template for a `save-excursion' Expression
+-------------------------------------------------
+
+The template for code using `save-excursion' is simple:
+
+     (save-excursion
+       BODY...)
+
+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 `save-excursion' function.  The other expressions
+in the body are evaluated only for their side effects; and
+`save-excursion' itself is used only for its side effect (which is
+restoring the positions of point and mark).
+
+In more detail, the template for a `save-excursion' expression looks
+like this:
+
+     (save-excursion
+       FIRST-EXPRESSION-IN-BODY
+       SECOND-EXPRESSION-IN-BODY
+       THIRD-EXPRESSION-IN-BODY
+        ...
+       LAST-EXPRESSION-IN-BODY)
+
+An expression, of course, may be a symbol on its own or a list.
+
+In Emacs Lisp code, a `save-excursion' expression often occurs within
+the body of a `let' expression.  It looks like this:
+
+     (let VARLIST
+       (save-excursion
+         BODY...))
+
+
+File: eintr,  Node: Review,  Next: defun Exercises,  Prev: save-excursion,  Up: Writing Defuns
+
+3.11 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.
+
+`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
+     `C-x C-e'.
+
+`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.
+
+     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.)
+
+          (defun back-to-indentation ()
+            "Move point to first visible character on line."
+            (interactive)
+            (beginning-of-line 1)
+            (skip-chars-forward " \t"))
+
+`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, `\n'.
+
+     Common code characters are:
+
+    `b'
+          The name of an existing buffer.
+
+    `f'
+          The name of an existing file.
+
+    `p'
+          The numeric prefix argument.  (Note that this `p' is lower
+          case.)
+
+    `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.
+
+     *Note Code Characters for `interactive': (elisp)Interactive Codes,
+     for a complete list of code characters.
+
+`let'
+     Declare that a list of variables is for use within the body of the
+     `let' and give them an initial value, either `nil' or a specified
+     value; then evaluate the rest of the expressions in the body of
+     the `let' and return the value of the last one.  Inside the body
+     of the `let', the Lisp interpreter does not see the values of the
+     variables of the same names that are bound outside of the `let'.
+
+     For example,
+
+          (let ((foo (buffer-name))
+                (bar (buffer-size)))
+            (message
+             "This buffer is %s and has %d characters."
+             foo bar))
+
+`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.
+
+     For example,
+
+          (message "We are %d characters into this buffer."
+                   (- (point)
+                      (save-excursion
+                        (goto-char (point-min)) (point))))
+
+`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 `if' special form is called a "conditional".  There are other
+     conditionals in Emacs Lisp, but `if' is perhaps the most commonly
+     used.
+
+     For example,
+
+          (if (string-equal
+               (number-to-string 22)
+               (substring (emacs-version) 10 12))
+              (message "This is version 22 Emacs")
+            (message "This is not version 22 Emacs"))
+
+`equal'
+`eq'
+     Test whether two objects are the same.  `equal' uses one meaning
+     of the word `same' and `eq' uses another:  `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, `eq', returns true if
+     both arguments are actually the same object.  
+
+`<'
+`>'
+`<='
+`>='
+     The `<' function tests whether its first argument is smaller than
+     its second argument.  A corresponding function, `>', tests whether
+     the first argument is greater than the second.  Likewise, `<='
+     tests whether the first argument is less than or equal to the
+     second and `>=' 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).
+
+`string<'
+`string-lessp'
+`string='
+`string-equal'
+     The `string-lessp' function tests whether its first argument is
+     smaller than the second argument.  A shorter, alternative name for
+     the same function (a `defalias') is `string<'.
+
+     The arguments to `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.
+
+     An empty string, `""', a string with no characters in it, is
+     smaller than any string of characters.
+
+     `string-equal' provides the corresponding test for equality.  Its
+     shorter, alternative name is `string='.  There are no string test
+     functions that correspond to >, `>=', or `<='.
+
+`message'
+     Print a message in the echo area. The first argument is a string
+     that can contain `%s', `%d', or `%c' to print the value of
+     arguments that follow the string.  The argument used by `%s' must
+     be a string or a symbol; the argument used by `%d' must be a
+     number.  The argument used by `%c' must be an ASCII code number;
+     it will be printed as the character with that ASCII code.
+     (Various other %-sequences have not been mentioned.)
+
+`setq'
+`set'
+     The `setq' function sets the value of its first argument to the
+     value of the second argument.  The first argument is automatically
+     quoted by `setq'.  It does the same for succeeding pairs of
+     arguments.  Another function, `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.
+
+`buffer-name'
+     Without an argument, return the name of the buffer, as a string.
+
+`buffer-file-name'
+     Without an argument, return the name of the file the buffer is
+     visiting.
+
+`current-buffer'
+     Return the buffer in which Emacs is active; it may not be the
+     buffer that is visible on the screen.
+
+`other-buffer'
+     Return the most recently selected buffer (other than the buffer
+     passed to `other-buffer' as an argument and other than the current
+     buffer).
+
+`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 `C-x b'.
+
+`set-buffer'
+     Switch Emacs' attention to a buffer on which programs will run.
+     Don't alter what the window is showing.
+
+`buffer-size'
+     Return the number of characters in the current buffer.
+
+`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.
+
+`point-min'
+     Return the minimum permissible value of point in the current
+     buffer.  This is 1, unless narrowing is in effect.
+
+`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.
+
+
+File: eintr,  Node: defun Exercises,  Prev: Review,  Up: Writing Defuns
+
+3.12 Exercises
+==============
+
+   * Write a non-interactive function that doubles the value of its
+     argument, a number.  Make that function interactive.
+
+   * Write a function that tests whether the current value of
+     `fill-column' is greater than the argument passed to the function,
+     and if so, prints an appropriate message.
+
+
+File: eintr,  Node: Buffer Walk Through,  Next: More Complex,  Prev: Writing Defuns,  Up: Top
+
+4 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::
+* simplified-beginning-of-buffer::
+* mark-whole-buffer::
+* append-to-buffer::
+* Buffer Related Review::
+* Buffer Exercises::
+
+
+File: eintr,  Node: Finding More,  Next: simplified-beginning-of-buffer,  Prev: Buffer Walk Through,  Up: Buffer Walk Through
+
+4.1 Finding More Information
+============================
+
+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 `C-h f' and then the name of the function (and then
+<RET>).  Similarly, you can get the full documentation for a variable
+by typing `C-h v' and then the name of the variable (and then <RET>).
+
+When a function is written in Emacs Lisp, `describe-function' will also
+tell you the location of the function definition.
+
+Put point into the name of the file that contains the function and
+press the <RET> key.  In this case, <RET> means `push-button' rather
+than `return' or `enter'.  Emacs will take you directly to the function
+definition.
+
+More generally, if you want to see a function in its original source
+file, you can use the `find-tags' function to jump to it.  `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, `find-tags' will
+jump to the various nodes in the Texinfo source file of this document.
+
+The `find-tags' function depends on `tags tables' that record the
+locations of the functions, variables, and other items to which
+`find-tags' jumps.
+
+To use the `find-tags' command, type `M-.'  (i.e., press the period key
+while holding down the <META> key, or else type the <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
+`mark-whole-buffer', and then type <RET>.  Emacs will switch buffers
+and display the source code for the function on your screen.  To switch
+back to your current buffer, type `C-x b <RET>'.  (On some keyboards,
+the <META> key is labelled <ALT>.)
+
+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 `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
+`/usr/local/share/emacs/' directory; thus you would use the `M-x
+visit-tags-table' command and specify a pathname such as
+`/usr/local/share/emacs/22.0.100/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 `/usr/local/src/emacs/src/TAGS'.
+
+To create a `TAGS' file in a specific directory, switch to that
+directory in Emacs using `M-x cd' command, or list the directory with
+`C-x d' (`dired').  Then run the compile command, with `etags *.el' as
+the command to execute:
+
+     M-x compile RET etags *.el RET
+
+For more information, see *Note Create Your Own `TAGS' File: etags.
+
+After you become more familiar with Emacs Lisp, you will find that you
+will frequently use `find-tags' to navigate your way around source code;
+and you will create your own `TAGS' tables.
+
+Incidentally, the files that contain Lisp code are conventionally
+called "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 `abbrev.el' for handling
+abbreviations and other typing shortcuts, and `help.el' for on-line
+help.  (Sometimes several libraries provide code for a single activity,
+as the various `rmail...' files provide code for reading electronic
+mail.)  In `The GNU Emacs Manual', you will see sentences such as "The
+`C-h p' command lets you search the standard Emacs Lisp libraries by
+topic keywords."
+
+
+File: eintr,  Node: simplified-beginning-of-buffer,  Next: mark-whole-buffer,  Prev: Finding More,  Up: Buffer Walk Through
+
+4.2 A Simplified `beginning-of-buffer' Definition
+=================================================
+
+The `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, `beginning-of-buffer'
+moves the cursor to the beginning of the buffer, leaving the mark at the
+previous position.  It is generally bound to `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.  (*Note
+Complete Definition of `beginning-of-buffer': 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 `M-x beginning-of-buffer' or
+by typing a keychord such as `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.
+
+Here is the complete text of the shortened version of the function:
+
+     (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)))
+
+Like all function definitions, this definition has five parts following
+the special form `defun':
+
+  1. The name: in this example, `simplified-beginning-of-buffer'.
+
+  2. A list of the arguments: in this example, an empty list, `()',
+
+  3. The documentation string.
+
+  4. The interactive expression.
+
+  5. The body.
+
+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, `interactive' does not have an
+argument because `simplified-beginning-of-buffer' does not require one.
+
+The body of the function consists of the two lines:
+
+     (push-mark)
+     (goto-char (point-min))
+
+The first of these lines is the expression, `(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 `(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.  *Note Narrowing and Widening: Narrowing & Widening.)
+
+The `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
+`(goto-char (point-min))' expression.  Consequently, you can, if you
+wish, go back to where you were originally by typing `C-x C-x'.
+
+That is all there is to the function definition!
+
+When you are reading code such as this and come upon an unfamiliar
+function, such as `goto-char', you can find out what it does by using
+the `describe-function' command.  To use this command, type `C-h f' and
+then type in the name of the function and press <RET>.  The
+`describe-function' command will print the function's documentation
+string in a `*Help*' window.  For example, the documentation for
+`goto-char' is:
+
+     Set point to POSITION, a number or marker.
+     Beginning of buffer is position (point-min), end is (point-max).
+
+The function's one argument is the desired position.
+
+(The prompt for `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 `C-h f <RET>'.)
+
+The `end-of-buffer' function definition is written in the same way as
+the `beginning-of-buffer' definition except that the body of the
+function contains the expression `(goto-char (point-max))' in place of
+`(goto-char (point-min))'.
+
+
+File: eintr,  Node: mark-whole-buffer,  Next: append-to-buffer,  Prev: simplified-beginning-of-buffer,  Up: Buffer Walk Through
+
+4.3 The Definition of `mark-whole-buffer'
+=========================================
+
+The `mark-whole-buffer' function is no harder to understand than the
+`simplified-beginning-of-buffer' function.  In this case, however, we
+will look at the complete function, not a shortened version.
+
+The `mark-whole-buffer' function is not as commonly used as the
+`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 `C-x h'.
+
+* Menu:
+
+* mark-whole-buffer overview::
+* Body of mark-whole-buffer::
+
+
+File: eintr,  Node: mark-whole-buffer overview,  Next: Body of mark-whole-buffer,  Prev: mark-whole-buffer,  Up: mark-whole-buffer
+
+An overview of `mark-whole-buffer'
+----------------------------------
+
+In GNU Emacs 22, the code for the complete function looks like this:
+
+     (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)))
+
+Like all other functions, the `mark-whole-buffer' function fits into
+the template for a function definition.  The template looks like this:
+
+     (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
+       "DOCUMENTATION..."
+       (INTERACTIVE-EXPRESSION...)
+       BODY...)
+
+Here is how the function works: the name of the function is
+`mark-whole-buffer'; it is followed by an empty argument list, `()',
+which means that the function does not require arguments.  The
+documentation comes next.
+
+The next line is an `(interactive)' expression that tells Emacs that
+the function will be used interactively.  These details are similar to
+the `simplified-beginning-of-buffer' function described in the previous
+section.
+
+
+File: eintr,  Node: Body of mark-whole-buffer,  Prev: mark-whole-buffer overview,  Up: mark-whole-buffer
+
+4.3.1 Body of `mark-whole-buffer'
+---------------------------------
+
+The body of the `mark-whole-buffer' function consists of three lines of
+code:
+
+     (push-mark (point))
+     (push-mark (point-max) nil t)
+     (goto-char (point-min))
+
+The first of these lines is the expression, `(push-mark (point))'.
+
+This line does exactly the same job as the first line of the body of
+the `simplified-beginning-of-buffer' function, which is written
+`(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 `mark-whole-buffer' is written
+`(push-mark (point))' and the expression in `beginning-of-buffer' is
+written `(push-mark)'.  Perhaps whoever wrote the code did not know
+that the arguments for `push-mark' are optional and that if `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 `mark-whole-buffer'
+was `(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.  *Note Narrowing and Widening: Narrowing &
+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 `C-u C-<SPC>' twice.
+
+In GNU Emacs 22, the `(point-max)' is slightly more complicated.  The
+line reads
+
+     (push-mark (point-max) nil t)
+
+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, `push-mark' has two additional arguments.  The second argument
+to `push-mark' is `nil'.  This tells the function it _should_ display a
+message that says `Mark set' when it pushes the mark.  The third
+argument is `t'.  This tells `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 `(goto-char (point-min)))'.
+This is written exactly the same way as it is written in
+`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.
+
+
+File: eintr,  Node: append-to-buffer,  Next: Buffer Related Review,  Prev: mark-whole-buffer,  Up: Buffer Walk Through
+
+4.4 The Definition of `append-to-buffer'
+========================================
+
+The `append-to-buffer' command is more complex than the
+`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::
+* append-to-buffer body::
+* append save-excursion::
+
+
+File: eintr,  Node: append-to-buffer overview,  Next: append interactive,  Prev: append-to-buffer,  Up: append-to-buffer
+
+An Overview of `append-to-buffer'
+---------------------------------
+
+The `append-to-buffer' command uses the `insert-buffer-substring'
+function to copy the region.  `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 `append-to-buffer' is concerned with setting up the conditions
+for `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.
+
+Here is the complete text of the function:
+
+     (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))))))))
+
+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):
+
+     (defun append-to-buffer (buffer start end)
+       "DOCUMENTATION..."
+       (interactive ...)
+       BODY...)
+
+The first line of the function includes its name and three arguments.
+The arguments are the `buffer' to which the text will be copied, and
+the `start' and `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.)
+
+
+File: eintr,  Node: append interactive,  Next: append-to-buffer body,  Prev: append-to-buffer overview,  Up: append-to-buffer
+
+4.4.1 The `append-to-buffer' Interactive Expression
+---------------------------------------------------
+
+Since the `append-to-buffer' function will be used interactively, the
+function must have an `interactive' expression.  (For a review of
+`interactive', see *Note Making a Function Interactive: Interactive.)
+The expression reads as follows:
+
+     (interactive
+        (list (read-buffer
+               "Append to buffer: "
+               (other-buffer (current-buffer) t))
+     	 (region-beginning)
+              (region-end)))
+
+This expression is not one with letters standing for parts, as
+described earlier.  Instead, it starts a list with thee 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 `read-buffer'.  The function
+requires a prompt as its first argument, `"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 `other-buffer', an exception, and a `t', standing for true.
+
+The first argument to `other-buffer', the exception, is yet another
+function, `current-buffer'.  That is not going to be returned.  The
+second argument is the symbol for true, `t'. that tells `other-buffer'
+that it may show visible buffers (except in this case, it will not show
+the current buffer, which makes sense).
+
+The expression looks like this:
+
+     (other-buffer (current-buffer) t)
+
+The second and third arguments to the `list' expression are
+`(region-beginning)' and `(region-end)'.  These two functions specify
+the beginning and end of the text to be appended.
+
+Originally, the command used the letters `B' and `r'.  The whole
+`interactive' expression looked like this:
+
+     (interactive "BAppend to buffer: \nr")
+
+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,
+`\n'.  It was followed by an `r' that told Emacs to bind the two
+arguments that follow the symbol `buffer' in the function's argument
+list (that is, `start' and `end') to the values of point and mark.
+That argument worked fine.)
+
+
+File: eintr,  Node: append-to-buffer body,  Next: append save-excursion,  Prev: append interactive,  Up: append-to-buffer
+
+4.4.2 The Body of `append-to-buffer'
+------------------------------------
+
+The body of the `append-to-buffer' function begins with `let'.
+
+As we have seen before (*note `let': let.), the purpose of a `let'
+expression is to create and give initial values to one or more
+variables that will only be used within the body of the `let'.  This
+means that such a variable will not be confused with any variable of
+the same name outside the `let' expression.
+
+We can see how the `let' expression fits into the function as a whole
+by showing a template for `append-to-buffer' with the `let' expression
+in outline:
+
+     (defun append-to-buffer (buffer start end)
+       "DOCUMENTATION..."
+       (interactive ...)
+       (let ((VARIABLE VALUE))
+             BODY...)
+
+The `let' expression has three elements:
+
+  1. The symbol `let';
+
+  2. A varlist containing, in this case, a single two-element list,
+     `(VARIABLE VALUE)';
+
+  3. The body of the `let' expression.
+
+In the `append-to-buffer' function, the varlist looks like this:
+
+     (oldbuf (current-buffer))
+
+In this part of the `let' expression, the one variable, `oldbuf', is
+bound to the value returned by the `(current-buffer)' expression.  The
+variable, `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 `let'.  As a consequence, the two-element list within
+the varlist is surrounded by a circumscribing set of parentheses.  The
+line looks like this:
+
+     (let ((oldbuf (current-buffer)))
+       ... )
+
+The two parentheses before `oldbuf' might surprise you if you did not
+realize that the first parenthesis before `oldbuf' marks the boundary
+of the varlist and the second parenthesis marks the beginning of the
+two-element list, `(oldbuf (current-buffer))'.
+
+
+File: eintr,  Node: append save-excursion,  Prev: append-to-buffer body,  Up: append-to-buffer
+
+4.4.3 `save-excursion' in `append-to-buffer'
+--------------------------------------------
+
+The body of the `let' expression in `append-to-buffer' consists of a
+`save-excursion' expression.
+
+The `save-excursion' function saves the locations of point and mark,
+and restores them to those positions after the expressions in the body
+of the `save-excursion' complete execution.  In addition,
+`save-excursion' keeps track of the original buffer, and restores it.
+This is how `save-excursion' is used in `append-to-buffer'.
+
+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 `let' is indented more than the `defun', and the
+`save-excursion' is indented more than the `let', like this:
+
+     (defun ...
+       ...
+       ...
+       (let...
+         (save-excursion
+           ...
+
+This formatting convention makes it easy to see that the lines in the
+body of the `save-excursion' are enclosed by the parentheses associated
+with `save-excursion', just as the `save-excursion' itself is enclosed
+by the parentheses associated with the `let':
+
+     (let ((oldbuf (current-buffer)))
+       (save-excursion
+         ...
+         (set-buffer ...)
+         (insert-buffer-substring oldbuf start end)
+         ...))
+
+The use of the `save-excursion' function can be viewed as a process of
+filling in the slots of a template:
+
+     (save-excursion
+       FIRST-EXPRESSION-IN-BODY
+       SECOND-EXPRESSION-IN-BODY
+        ...
+       LAST-EXPRESSION-IN-BODY)
+
+In this function, the body of the `save-excursion' contains only one
+expression, the `let*' expression.  You know about a `let' function.
+The `let*' function is different.  It has a `*' 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.
+*Note The `let*' expression: fwd-para let.
+
+We will skip functions like `let*' and focus on two: the `set-buffer'
+function and the `insert-buffer-substring' function.
+
+In the old days, the `set-buffer' expression was simply
+
+     (set-buffer (get-buffer-create buffer))
+
+but now it is
+
+     (set-buffer append-to)
+
+`append-to' is bound to `(get-buffer-create buffer)' earlier on in the
+`let*' expression.  That extra binding would not be necessary except
+for that `append-to' is used later in the varlist as an argument to
+`get-buffer-window-list'.
+
+The `append-to-buffer' function definition inserts text from the buffer
+in which you are currently to a named buffer.  It happens that
+`insert-buffer-substring' copies text from another buffer to the
+current buffer, just the reverse--that is why the `append-to-buffer'
+definition starts out with a `let' that binds the local symbol `oldbuf'
+to the value returned by `current-buffer'.
+
+The `insert-buffer-substring' expression looks like this:
+
+     (insert-buffer-substring oldbuf start end)
+
+The `insert-buffer-substring' function copies a string _from_ the
+buffer specified as its first argument and inserts the string into the
+present buffer.  In this case, the argument to
+`insert-buffer-substring' is the value of the variable created and
+bound by the `let', namely the value of `oldbuf', which was the current
+buffer when you gave the `append-to-buffer' command.
+
+After `insert-buffer-substring' has done its work, `save-excursion'
+will restore the action to the original buffer and `append-to-buffer'
+will have done its job.
+
+Written in skeletal form, the workings of the body look like this:
+
+     (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
+       (save-excursion                       ; Keep track of buffer.
+         CHANGE-BUFFER
+         INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)
+
+       CHANGE-BACK-TO-ORIGINAL-BUFFER-WHEN-FINISHED
+     LET-THE-LOCAL-MEANING-OF-`oldbuf'-DISAPPEAR-WHEN-FINISHED
+
+In summary, `append-to-buffer' works as follows: it saves the value of
+the current buffer in the variable called `oldbuf'.  It gets the new
+buffer (creating one if need be) and switches Emacs' attention to it.
+Using the value of `oldbuf', it inserts the region of text from the old
+buffer into the new buffer; and then using `save-excursion', it brings
+you back to your original buffer.
+
+In looking at `append-to-buffer', you have explored a fairly complex
+function.  It shows how to use `let' and `save-excursion', and how to
+change to and come back from another buffer.  Many function definitions
+use `let', `save-excursion', and `set-buffer' this way.
+
+
+File: eintr,  Node: Buffer Related Review,  Next: Buffer Exercises,  Prev: append-to-buffer,  Up: Buffer Walk Through
+
+4.5 Review
+==========
+
+Here is a brief summary of the various functions discussed in this
+chapter.
+
+`describe-function'
+`describe-variable'
+     Print the documentation for a function or variable.
+     Conventionally bound to `C-h f' and `C-h v'.
+
+`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 `M-.' (that's a period following the
+     <META> key).
+
+`save-excursion'
+     Save the location of point and mark and restore their values after
+     the arguments to `save-excursion' have been evaluated.  Also,
+     remember the current buffer and return to it.
+
+`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.
+
+`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 `(point-min)'.
+
+`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.
+
+`mark-whole-buffer'
+     Mark the whole buffer as a region.  Normally bound to `C-x h'.
+
+`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.
+
+`get-buffer-create'
+`get-buffer'
+     Find a named buffer or create one if a buffer of that name does not
+     exist.  The `get-buffer' function returns `nil' if the named
+     buffer does not exist.
+
+
+File: eintr,  Node: Buffer Exercises,  Prev: Buffer Related Review,  Up: Buffer Walk Through
+
+4.6 Exercises
+=============
+
+   * Write your own `simplified-end-of-buffer' function definition;
+     then test it to see whether it works.
+
+   * Use `if' and `get-buffer' to write a function that prints a
+     message telling you whether a buffer exists.
+
+   * Using `find-tag', find the source for the `copy-to-buffer'
+     function.
+
+
+File: eintr,  Node: More Complex,  Next: Narrowing & Widening,  Prev: Buffer Walk Through,  Up: Top
+
+5 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 `copy-to-buffer' function
+illustrates use of two `save-excursion' expressions in one definition,
+while the `insert-buffer' function illustrates use of an asterisk in an
+`interactive' expression, use of `or', and the important distinction
+between a name and the object to which the name refers.
+
+* Menu:
+
+* copy-to-buffer::
+* insert-buffer::
+* beginning-of-buffer::
+* Second Buffer Related Review::
+* optional Exercise::
+
+
+File: eintr,  Node: copy-to-buffer,  Next: insert-buffer,  Prev: More Complex,  Up: More Complex
+
+5.1 The Definition of `copy-to-buffer'
+======================================
+
+After understanding how `append-to-buffer' works, it is easy to
+understand `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.
+
+The body of `copy-to-buffer' looks like this,
+
+     ...
+     (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)))))
+
+The `copy-to-buffer' function has a simpler `interactive' expression
+than `append-to-buffer'.
+
+The definition then says
+
+     (with-current-buffer (get-buffer-create buffer) ...
+
+First, look at the earliest inner expression; that is evaluated first.
+That expression starts with `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 `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 `append-to-buffer' function showed how to do the
+same with `save-excursion' and `set-buffer'.  `with-current-buffer' is
+a newer, and arguably easier, mechanism.)
+
+The `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 `erase-buffer' function as its sole contents.
+That function erases the buffer.
+
+Finally, the last two lines contain the `save-excursion' expression
+with `insert-buffer-substring' as its body.  The
+`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 `oldbuf').
+
+Incidentally, this is what is meant by `replacement'.  To replace text,
+Emacs erases the previous text and then inserts new text.
+
+In outline, the body of `copy-to-buffer' looks like this:
+
+     (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
+         (WITH-THE-BUFFER-YOU-ARE-COPYING-TO
+           (BUT-DO-NOT-ERASE-OR-COPY-TO-A-READ-ONLY-BUFFER)
+           (erase-buffer)
+           (save-excursion
+             INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)))
+
+
+File: eintr,  Node: insert-buffer,  Next: beginning-of-buffer,  Prev: copy-to-buffer,  Up: More Complex
+
+5.2 The Definition of `insert-buffer'
+=====================================
+
+`insert-buffer' is yet another buffer-related function.  This command
+copies another buffer _into_ the current buffer.  It is the reverse of
+`append-to-buffer' or `copy-to-buffer', since they copy a region of
+text _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.
+
+*Note New Body for `insert-buffer': New insert-buffer, to see a
+discussion of the new body.)
+
+In addition, this code illustrates the use of `interactive' with a
+buffer that might be "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::
+* insert-buffer body::
+* if & or::
+* Insert or::
+* Insert let::
+* New insert-buffer ::
+
+
+File: eintr,  Node: insert-buffer code,  Next: insert-buffer interactive,  Prev: insert-buffer,  Up: insert-buffer
+
+The Code for `insert-buffer'
+----------------------------
+
+Here is the earlier code:
+
+     (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: ")
+       (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)))
+           (insert-buffer-substring buffer start end)
+           (setq newmark (point)))
+         (push-mark newmark)))
+
+As with other function definitions, you can use a template to see an
+outline of the function:
+
+     (defun insert-buffer (buffer)
+       "DOCUMENTATION..."
+       (interactive "*bInsert buffer: ")
+       BODY...)
+
+
+File: eintr,  Node: insert-buffer interactive,  Next: insert-buffer body,  Prev: insert-buffer code,  Up: insert-buffer
+
+5.2.1 The Interactive Expression in `insert-buffer'
+---------------------------------------------------
+
+In `insert-buffer', the argument to the `interactive' declaration has
+two parts, an asterisk, `*', and `bInsert buffer: '.
+
+* Menu:
+
+* Read-only buffer::
+* b for interactive::
+
+
+File: eintr,  Node: Read-only buffer,  Next: b for interactive,  Prev: insert-buffer interactive,  Up: insert-buffer interactive
+
+A 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 `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.
+
+
+File: eintr,  Node: b for interactive,  Prev: Read-only buffer,  Up: insert-buffer interactive
+
+`b' in an Interactive Expression
+................................
+
+The next argument in the interactive expression starts with a lower
+case `b'.  (This is different from the code for `append-to-buffer',
+which uses an upper-case `B'.  *Note The Definition of
+`append-to-buffer': append-to-buffer.)  The lower-case `b' tells the
+Lisp interpreter that the argument for `insert-buffer' should be an
+existing buffer or else its name.  (The upper-case `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 `interactive'.  It
+uses the `barf-if-buffer-read-only' and `read-buffer' functions with
+which we are already familiar and the `progn' special form with which
+we are not.  (It will be described later.)
+
+
+File: eintr,  Node: insert-buffer body,  Next: if & or,  Prev: insert-buffer interactive,  Up: insert-buffer
+
+5.2.2 The Body of the `insert-buffer' Function
+----------------------------------------------
+
+The body of the `insert-buffer' function has two major parts: an `or'
+expression and a `let' expression.  The purpose of the `or' expression
+is to ensure that the argument `buffer' is bound to a buffer and not
+just the name of a buffer.  The body of the `let' expression contains
+the code which copies the other buffer into the current buffer.
+
+In outline, the two expressions fit into the `insert-buffer' function
+like this:
+
+     (defun insert-buffer (buffer)
+       "DOCUMENTATION..."
+       (interactive "*bInsert buffer: ")
+       (or ...
+           ...
+       (let (VARLIST)
+           BODY-OF-`let'... )
+
+To understand how the `or' expression ensures that the argument
+`buffer' is bound to a buffer and not to the name of a buffer, it is
+first necessary to understand the `or' function.
+
+Before doing this, let me rewrite this part of the function using `if'
+so that you can see what is done in a manner that will be familiar.
+
+
+File: eintr,  Node: if & or,  Next: Insert or,  Prev: insert-buffer body,  Up: insert-buffer
+
+5.2.3 `insert-buffer' With an `if' Instead of an `or'
+-----------------------------------------------------
+
+The job to be done is to make sure the value of `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.
+
+In Lisp, you might describe this situation like this:
+
+     (if (not (holding-on-to-guest))
+         (find-and-take-arm-of-guest))
+
+We want to do the same thing with a buffer--if we do not have the
+buffer itself, we want to get it.
+
+Using a predicate called `bufferp' that tells us whether we have a
+buffer (rather than its name), we can write the code like this:
+
+     (if (not (bufferp buffer))              ; if-part
+         (setq buffer (get-buffer buffer)))  ; then-part
+
+Here, the true-or-false-test of the `if' expression is
+`(not (bufferp buffer))'; and the then-part is the expression
+`(setq buffer (get-buffer buffer))'.
+
+In the test, the function `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 `bufferp' is the character `p'; as we
+saw earlier, such use of `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.  *Note Using the
+Wrong Type Object as an Argument: Wrong Type of Argument.)
+
+The function `not' precedes the expression `(bufferp buffer)', so the
+true-or-false-test looks like this:
+
+     (not (bufferp buffer))
+
+`not' is a function that returns true if its argument is false and
+false if its argument is true.  So if `(bufferp buffer)' returns true,
+the `not' expression returns false and vice-verse: what is "not true"
+is false and what is "not false" is true.
+
+Using this test, the `if' expression works as follows: when the value
+of the variable `buffer' is actually a buffer rather than its name, the
+true-or-false-test returns false and the `if' expression does not
+evaluate the then-part.  This is fine, since we do not need to do
+anything to the variable `buffer' if it really is a buffer.
+
+On the other hand, when the value of `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 `(setq buffer (get-buffer buffer))'.  This expression uses the
+`get-buffer' function to return an actual buffer itself, given its
+name.  The `setq' then sets the variable `buffer' to the value of the
+buffer itself, replacing its previous value (which was the name of the
+buffer).
+
+
+File: eintr,  Node: Insert or,  Next: Insert let,  Prev: if & or,  Up: insert-buffer
+
+5.2.4 The `or' in the Body
+--------------------------
+
+The purpose of the `or' expression in the `insert-buffer' function is
+to ensure that the argument `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 `if' expression.  However, the `insert-buffer'
+function actually uses `or'.  To understand this, it is necessary to
+understand how `or' works.
+
+An `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 `nil'.  Also, and this is a crucial feature of `or', it
+does not evaluate any subsequent arguments after returning the first
+non-`nil' value.
+
+The `or' expression looks like this:
+
+     (or (bufferp buffer)
+         (setq buffer (get-buffer buffer)))
+
+The first argument to `or' is the expression `(bufferp buffer)'.  This
+expression returns true (a non-`nil' value) if the buffer is actually a
+buffer, and not just the name of a buffer.  In the `or' expression, if
+this is the case, the `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 `buffer' if it really is a
+buffer.
+
+On the other hand, if the value of `(bufferp buffer)' is `nil', which
+it will be if the value of `buffer' is the name of a buffer, the Lisp
+interpreter evaluates the next element of the `or' expression.  This is
+the expression `(setq buffer (get-buffer buffer))'.  This expression
+returns a non-`nil' value, which is the value to which it sets the
+variable `buffer'--and this value is a buffer itself, not the name of a
+buffer.
+
+The result of all this is that the symbol `buffer' is always bound to a
+buffer itself rather than to the name of a buffer.  All this is
+necessary because the `set-buffer' function in a following line only
+works with a buffer itself, not with the name to a buffer.
+
+Incidentally, using `or', the situation with the usher would be written
+like this:
+
+     (or (holding-on-to-guest) (find-and-take-arm-of-guest))
+
+
+File: eintr,  Node: Insert let,  Next: New insert-buffer,  Prev: Insert or,  Up: insert-buffer
+
+5.2.5 The `let' Expression in `insert-buffer'
+---------------------------------------------
+
+After ensuring that the variable `buffer' refers to a buffer itself and
+not just to the name of a buffer, the `insert-buffer function'
+continues with a `let' expression.  This specifies three local
+variables, `start', `end', and `newmark' and binds them to the initial
+value `nil'.  These variables are used inside the remainder of the
+`let' and temporarily hide any other occurrence of variables of the
+same name in Emacs until the end of the `let'.
+
+The body of the `let' contains two `save-excursion' expressions.
+First, we will look at the inner `save-excursion' expression in detail.
+The expression looks like this:
+
+     (save-excursion
+       (set-buffer buffer)
+       (setq start (point-min) end (point-max)))
+
+The expression `(set-buffer buffer)' changes Emacs' attention from the
+current buffer to the one from which the text will copied.  In that
+buffer, the variables `start' and `end' are set to the beginning and
+end of the buffer, using the commands `point-min' and `point-max'.
+Note that we have here an illustration of how `setq' is able to set two
+variables in the same expression.  The first argument of `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 `save-excursion' is evaluated, the
+`save-excursion' restores the original buffer, but `start' and `end'
+remain set to the values of the beginning and end of the buffer from
+which the text will be copied.
+
+The outer `save-excursion' expression looks like this:
+
+     (save-excursion
+       (INNER-`save-excursion'-EXPRESSION
+          (GO-TO-NEW-BUFFER-AND-SET-`start'-AND-`end')
+       (insert-buffer-substring buffer start end)
+       (setq newmark (point)))
+
+The `insert-buffer-substring' function copies the text _into_ the
+current buffer _from_ the region indicated by `start' and `end' in
+`buffer'.  Since the whole of the second buffer lies between `start'
+and `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 `newmark'.
+
+After the body of the outer `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 `newmark'
+variable records the end of the inserted text.  In the last line of the
+`let' expression, the `(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 `C-u C-<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 `save-excursion'.
+
+The whole `let' expression looks like this:
+
+     (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))
+
+Like the `append-to-buffer' function, the `insert-buffer' function uses
+`let', `save-excursion', and `set-buffer'.  In addition, the function
+illustrates one way to use `or'.  All these functions are building
+blocks that we will find and use again and again.
+
+
+File: eintr,  Node: New insert-buffer,  Prev: Insert let,  Up: insert-buffer
+
+5.2.6 New Body for `insert-buffer'
+----------------------------------
+
+The body in the GNU Emacs 22 version is more confusing than the
+original.
+
+It consists of two expressions,
+
+       (push-mark
+        (save-excursion
+          (insert-buffer-substring (get-buffer buffer))
+          (point)))
+
+        nil
+
+except, and this is what confuses novices, very important work is done
+inside the `push-mark' expression.
+
+The `get-buffer' function returns a buffer with the name provided.  You
+will note that the function is _not_ called `get-buffer-create'; it
+does not create a buffer if one does not already exist.  The buffer
+returned by `get-buffer', an existing buffer, is passed to
+`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
+`push-mark'.  Then the function returns `nil', the value of its last
+command.  Put another way, the `insert-buffer' function exists only to
+produce a side effect, inserting another buffer, not to return any
+value.
+
+
+File: eintr,  Node: beginning-of-buffer,  Next: Second Buffer Related Review,  Prev: insert-buffer,  Up: More Complex
+
+5.3 Complete Definition of `beginning-of-buffer'
+================================================
+
+The basic structure of the `beginning-of-buffer' function has already
+been discussed.  (*Note A Simplified `beginning-of-buffer' Definition:
+simplified-beginning-of-buffer.)  This section describes the complex
+part of the definition.
+
+As previously described, when invoked without an argument,
+`beginning-of-buffer' moves the cursor to the beginning of the buffer
+(in truth, 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
+`M-<', which will move the cursor to the beginning of the buffer, or
+with a key command such as `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 `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::
+* beginning-of-buffer complete::
+
+
+File: eintr,  Node: Optional Arguments,  Next: beginning-of-buffer opt arg,  Prev: beginning-of-buffer,  Up: beginning-of-buffer
+
+5.3.1 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
+`Wrong number of arguments'.
+
+However, optional arguments are a feature of Lisp: a particular
+"keyword" is used to tell the Lisp interpreter that an argument is
+optional.  The keyword is `&optional'.  (The `&' in front of `optional'
+is part of the keyword.)  In a function definition, if an argument
+follows the keyword `&optional', no value need be passed to that
+argument when the function is called.
+
+The first line of the function definition of `beginning-of-buffer'
+therefore looks like this:
+
+     (defun beginning-of-buffer (&optional arg)
+
+In outline, the whole function looks like this:
+
+     (defun beginning-of-buffer (&optional arg)
+       "DOCUMENTATION..."
+       (interactive "P")
+       (or (IS-THE-ARGUMENT-A-CONS-CELL arg)
+           (and ARE-BOTH-TRANSIENT-MARK-MODE-AND-MARK-ACTIVE-TRUE)
+           (push-mark))
+       (let (DETERMINE-SIZE-AND-SET-IT)
+       (goto-char
+         (IF-THERE-IS-AN-ARGUMENT
+             FIGURE-OUT-WHERE-TO-GO
+           ELSE-GO-TO
+           (point-min))))
+        DO-NICETY
+
+The function is similar to the `simplified-beginning-of-buffer'
+function except that the `interactive' expression has `"P"' as an
+argument and the `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 `consp'.  *Note How Lists are
+Implemented: List Implementation, and *Note Cons Cell and List Types:
+(elisp)Cons Cell Type.)
+
+The `"P"' in the `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 <META> key followed by a number, or by
+typing `C-u' and then a number.  (If you don't type a number, `C-u'
+defaults to a cons cell with a 4.  A lowercase `"p"' in the
+`interactive' expression causes the function to convert a prefix arg to
+a number.)
+
+The true-or-false-test of the `if' expression looks complex, but it is
+not: it checks whether `arg' has a value that is not `nil' and whether
+it is a cons cell.  (That is what `consp' does; it checks whether its
+argument is a cons cell.)  If `arg' has a value that is not `nil' (and
+is not a cons cell), which will be the case if `beginning-of-buffer' is
+called with a numeric argument, then this true-or-false-test will
+return true and the then-part of the `if' expression will be evaluated.
+On the other hand, if `beginning-of-buffer' is not called with an
+argument, the value of `arg' will be `nil' and the else-part of the
+`if' expression will be evaluated.  The else-part is simply
+`point-min', and when this is the outcome, the whole `goto-char'
+expression is `(goto-char (point-min))', which is how we saw the
+`beginning-of-buffer' function in its simplified form.
+
+
+File: eintr,  Node: beginning-of-buffer opt arg,  Next: beginning-of-buffer complete,  Prev: Optional Arguments,  Up: beginning-of-buffer
+
+5.3.2 `beginning-of-buffer' with an Argument
+--------------------------------------------
+
+When `beginning-of-buffer' is called with an argument, an expression is
+evaluated which calculates what value to pass to `goto-char'.  This
+expression is rather complicated at first sight.  It includes an inner
+`if' expression and much arithmetic.  It looks like this:
+
+     (if (> (buffer-size) 10000)
+         ;; Avoid overflow for large buffer sizes!
+     			  (* (prefix-numeric-value arg)
+     			     (/ size 10))
+       (/
+        (+ 10
+           (*
+            size (prefix-numeric-value arg))) 10)))
+
+* Menu:
+
+* Disentangle beginning-of-buffer::
+* Large buffer case::
+* Small buffer case::
+
+
+File: eintr,  Node: Disentangle beginning-of-buffer,  Next: Large buffer case,  Prev: beginning-of-buffer opt arg,  Up: beginning-of-buffer opt arg
+
+Disentangle `beginning-of-buffer'
+.................................
+
+Like other complex-looking expressions, the conditional expression
+within `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:
+
+     (if (BUFFER-IS-LARGE
+         DIVIDE-BUFFER-SIZE-BY-10-AND-MULTIPLY-BY-ARG
+       ELSE-USE-ALTERNATE-CALCULATION
+
+The true-or-false-test of this inner `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.  Version 21 Emacs uses 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.
+
+
+File: eintr,  Node: Large buffer case,  Next: Small buffer case,  Prev: Disentangle beginning-of-buffer,  Up: beginning-of-buffer opt arg
+
+What happens in a large buffer
+..............................
+
+In `beginning-of-buffer', the inner `if' expression tests whether the
+size of the buffer is greater than 10,000 characters.  To do this, it
+uses the `>' function and the computation of `size' that comes from the
+let expression.
+
+In the old days, the function `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.  (*Note Narrowing and
+Widening: Narrowing & Widening, for more information on focusing
+attention to an `accessible' part.)
+
+The line looks like this:
+
+     (if (> size 10000)
+
+When the buffer is large, the then-part of the `if' expression is
+evaluated.  It reads like this (after formatting for easy reading):
+
+     (*
+       (prefix-numeric-value arg)
+       (/ size 10))
+
+This expression is a multiplication, with two arguments to the function
+`*'.
+
+The first argument is `(prefix-numeric-value arg)'.  When `"P"' is used
+as the argument for `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 `prefix-numeric-value' does the job.
+
+The second argument is `(/ 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, `/' is used
+for division, just as `*' is used for multiplication.)
+
+In the multiplication expression as a whole, this amount is multiplied
+by the value of the prefix argument--the multiplication looks like this:
+
+     (* NUMERIC-VALUE-OF-PREFIX-ARG
+        NUMBER-OF-CHARACTERS-IN-ONE-TENTH-OF-THE-ACCESSIBLE-BUFFER)
+
+If, for example, the prefix argument is `7', the one-tenth value will
+be multiplied by 7 to give a position 70% of the way through.
+
+The result of all this is that if the accessible portion of the buffer
+is large, the `goto-char' expression reads like this:
+
+     (goto-char (* (prefix-numeric-value arg)
+                   (/ size 10)))
+
+This puts the cursor where we want it.
+
+
+File: eintr,  Node: Small buffer case,  Prev: Large buffer case,  Up: beginning-of-buffer opt arg
+
+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.
+
+The code looks like this:
+
+     (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
+
+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:
+
+       (/
+        (+ 10
+           (*
+            size
+            (prefix-numeric-value arg)))
+        10))
+
+Looking at parentheses, we see that the innermost operation is
+`(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:
+
+     (* size (prefix-numeric-value arg))
+
+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 `goto-char' and the
+cursor is moved to that point.
+
+
+File: eintr,  Node: beginning-of-buffer complete,  Prev: beginning-of-buffer opt arg,  Up: beginning-of-buffer
+
+5.3.3 The Complete `beginning-of-buffer'
+----------------------------------------
+
+Here is the complete text of the `beginning-of-buffer' function:
+
+     (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.
+
+     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))
+       (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)))
+
+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.
+
+In the documentation string, there is reference to an expression:
+
+     \\[universal-argument]
+
+A `\\' is used before the first square bracket of this expression.
+This `\\' tells the Lisp interpreter to substitute whatever key is
+currently bound to the `[...]'.  In the case of `universal-argument',
+that is usually `C-u', but it might be different.  (*Note Tips for
+Documentation Strings: (elisp)Documentation Tips, for more information.)
+
+Finally, the last line of the `beginning-of-buffer' command says to
+move point to the beginning of the next line if the command is invoked
+with an argument:
+
+     (if arg (forward-line 1)))
+
+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 _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
+`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 ...  I don't know whether this is intended
+or whether no one has dealt with the code to avoid this happening.
+
+
+File: eintr,  Node: Second Buffer Related Review,  Next: optional Exercise,  Prev: beginning-of-buffer,  Up: More Complex
+
+5.4 Review
+==========
+
+Here is a brief summary of some of the topics covered in this chapter.
+
+`or'
+     Evaluate each argument in sequence, and return the value of the
+     first argument that is not `nil'; if none return a value that is
+     not `nil', return `nil'.  In brief, return the first true value of
+     the arguments; return a true value if one _or_ any of the others
+     are true.
+
+`and'
+     Evaluate each argument in sequence, and if any are `nil', return
+     `nil'; if none are `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 _and_ each of the others is true.
+
+`&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.
+
+`prefix-numeric-value'
+     Convert the `raw prefix argument' produced by `(interactive "P")'
+     to a numeric value.
+
+`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, `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.
+
+`erase-buffer'
+     Delete the entire contents of the current buffer.
+
+`bufferp'
+     Return `t' if its argument is a buffer; otherwise return `nil'.
+
+
+File: eintr,  Node: optional Exercise,  Prev: Second Buffer Related Review,  Up: More Complex
+
+5.5 `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 `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.
+
+
+File: eintr,  Node: Narrowing & Widening,  Next: car cdr & cons,  Prev: More Complex,  Up: Top
+
+6 Narrowing and 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::
+* save-restriction::
+* what-line::
+* narrow Exercise::
+
+
+File: eintr,  Node: Narrowing advantages,  Next: save-restriction,  Prev: Narrowing & Widening,  Up: Narrowing & Widening
+
+The Advantages of Narrowing
+===========================
+
+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
+`narrow-to-region' is `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 `undo' command (which is
+usually bound to `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 `widen' command.
+(The key binding for `widen' is `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 `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 `count-lines' function, which is called by `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.
+
+
+File: eintr,  Node: save-restriction,  Next: what-line,  Prev: Narrowing advantages,  Up: Narrowing & Widening
+
+6.1 The `save-restriction' Special Form
+=======================================
+
+In Emacs Lisp, you can use the `save-restriction' special form to keep
+track of whatever narrowing is in effect, if any.  When the Lisp
+interpreter meets with `save-restriction', it executes the code in the
+body of the `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 `save-restriction' gets rid of the
+narrowing, `save-restriction' returns the buffer to its narrowed region
+afterwards.  In the `what-line' command, any narrowing the buffer may
+have is undone by the `widen' command that immediately follows the
+`save-restriction' command.  Any original narrowing is restored just
+before the completion of the function.
+
+The template for a `save-restriction' expression is simple:
+
+     (save-restriction
+       BODY... )
+
+The body of the `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 `save-excursion' and
+`save-restriction', one right after the other, you should use
+`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 `save-excursion'.  Thus, when written together,
+`save-excursion' and `save-restriction' should be written like this:
+
+     (save-excursion
+       (save-restriction
+         BODY...))
+
+In other circumstances, when not written together, the `save-excursion'
+and `save-restriction' special forms must be written in the order
+appropriate to the function.
+
+For example,
+
+       (save-restriction
+         (widen)
+         (save-excursion
+         BODY...))
+
+
+File: eintr,  Node: what-line,  Next: narrow Exercise,  Prev: save-restriction,  Up: Narrowing & Widening
+
+6.2 `what-line'
+===============
+
+The `what-line' command tells you the number of the line in which the
+cursor is located.  The function illustrates the use of the
+`save-restriction' and `save-excursion' commands.  Here is the original
+text of the function:
+
+     (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)))))))
+
+(In recent versions of GNU Emacs, the `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 `C-h f' (`describe-function').  The newer
+version uses a conditional to determine whether the buffer has been
+narrowed.
+
+(Also, it uses `line-number-at-pos', which among other simple
+expressions, such as `(goto-char (point-min))', moves point to the
+beginning of the current line with `(forward-line 0)' rather than
+`beginning-of-line'.)
+
+The `what-line' function as shown here has a documentation line and is
+interactive, as you would expect.  The next two lines use the functions
+`save-restriction' and `widen'.
+
+The `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 `save-restriction' has been evaluated.
+
+The `save-restriction' special form is followed by `widen'.  This
+function undoes any narrowing the current buffer may have had when
+`what-line' was called.  (The narrowing that was there is the narrowing
+that `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 `save-restriction' special form.
+
+The call to `widen' is followed by `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 `save-excursion' uses the
+`beginning-of-line' function to move point.
+
+(Note that the `(widen)' expression comes between the
+`save-restriction' and `save-excursion' special forms.  When you write
+the two `save- ...' expressions in sequence, write `save-excursion'
+outermost.)
+
+The last two lines of the `what-line' function are functions to count
+the number of lines in the buffer and then print the number in the echo
+area.
+
+     (message "Line %d"
+              (1+ (count-lines 1 (point)))))))
+
+The `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 `%d'
+expression to print a following argument.  `%d' prints the argument as
+a decimal, so the message will say something such as `Line 243'.
+
+The number that is printed in place of the `%d' is computed by the last
+line of the function:
+
+     (1+ (count-lines 1 (point)))
+
+What this does is count the lines from the first position of the
+buffer, indicated by the `1', up to `(point)', and then add one to that
+number.  (The `1+' function adds one to its argument.)  We add one to
+it because line 2 has only one line before it, and `count-lines' counts
+only the lines _before_ the current line.
+
+After `count-lines' has done its job, and the message has been printed
+in the echo area, the `save-excursion' restores point and mark to their
+original positions; and `save-restriction' restores the original
+narrowing, if any.
+
+
+File: eintr,  Node: narrow Exercise,  Prev: what-line,  Up: Narrowing & Widening
+
+6.3 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 `save-restriction', `widen', `goto-char',
+`point-min', `message', and `buffer-substring'.
+
+(`buffer-substring' is a previously unmentioned function you will have
+to investigate yourself; or perhaps you will have to use
+`buffer-substring-no-properties' or `filter-buffer-substring' ..., yet
+other functions.  Text properties are a feature otherwise not discussed
+here.  *Note Text Properties: (elisp)Text Properties.
+
+Additionally, do you really need `goto-char' or `point-min'?  Or can
+you write the function without them?)
+
+
+File: eintr,  Node: car cdr & cons,  Next: Cutting & Storing Text,  Prev: Narrowing & Widening,  Up: Top
+
+7 `car', `cdr', `cons': Fundamental Functions
+*********************************************
+
+In Lisp, `car', `cdr', and `cons' are fundamental functions.  The
+`cons' function is used to construct lists, and the `car' and `cdr'
+functions are used to take them apart.
+
+In the walk through of the `copy-region-as-kill' function, we will see
+`cons' as well as two variants on `cdr', namely, `setcdr' and `nthcdr'.
+(*Note copy-region-as-kill::.)
+
+* Menu:
+
+* Strange Names::
+* car & cdr::
+* cons::
+* nthcdr::
+* nth::
+* setcar::
+* setcdr::
+* cons Exercise::
+
+
+File: eintr,  Node: Strange Names,  Next: car & cdr,  Prev: car cdr & cons,  Up: car cdr & cons
+
+Strange Names
+=============
+
+The name of the `cons' function is not unreasonable: it is an
+abbreviation of the word `construct'.  The origins of the names for
+`car' and `cdr', on the other hand, are esoteric: `car' is an acronym
+from the phrase `Contents of the Address part of the Register'; and
+`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.
+
+
+File: eintr,  Node: car & cdr,  Next: cons,  Prev: Strange Names,  Up: car cdr & cons
+
+7.1 `car' and `cdr'
+===================
+
+The CAR of a list is, quite simply, the first item in the list.  Thus
+the CAR of the list `(rose violet daisy buttercup)' is `rose'.
+
+If you are reading this in Info in GNU Emacs, you can see this by
+evaluating the following:
+
+     (car '(rose violet daisy buttercup))
+
+After evaluating the expression, `rose' will appear in the echo area.
+
+Clearly, a more reasonable name for the `car' function would be `first'
+and this is often suggested.
+
+`car' does not remove the first item from the list; it only reports
+what it is.  After `car' has been applied to a list, the list is still
+the same as it was.  In the jargon, `car' is `non-destructive'.  This
+feature turns out to be important.
+
+The CDR of a list is the rest of the list, that is, the `cdr' function
+returns the part of the list that follows the first item.  Thus, while
+the CAR of the list `'(rose violet daisy buttercup)' is `rose', the
+rest of the list, the value returned by the `cdr' function, is `(violet
+daisy buttercup)'.
+
+You can see this by evaluating the following in the usual way:
+
+     (cdr '(rose violet daisy buttercup))
+
+When you evaluate this, `(violet daisy buttercup)' will appear in the
+echo area.
+
+Like `car', `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
+`rose' as a function.  In this example, we do not want to do that.
+
+Clearly, a more reasonable name for `cdr' would be `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 `car' and `cdr' are applied to a list made up of symbols, such as
+the list `(pine fir oak maple)', the element of the list returned by
+the function `car' is the symbol `pine' without any parentheses around
+it.  `pine' is the first element in the list.  However, the CDR of the
+list is a list itself, `(fir oak maple)', as you can see by evaluating
+the following expressions in the usual way:
+
+     (car '(pine fir oak maple))
+
+     (cdr '(pine fir oak maple))
+
+On the other hand, in a list of lists, the first element is itself a
+list.  `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:
+
+     (car '((lion tiger cheetah)
+            (gazelle antelope zebra)
+            (whale dolphin seal)))
+
+In this example, the first element or CAR of the list is the list of
+carnivores, `(lion tiger cheetah)', and the rest of the list is
+`((gazelle antelope zebra) (whale dolphin seal))'.
+
+     (cdr '((lion tiger cheetah)
+            (gazelle antelope zebra)
+            (whale dolphin seal)))
+
+It is worth saying again that `car' and `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."  (*Note Lisp Atoms::.)  The `car' and
+`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, `cons', can put together or construct a
+list, but not an array.  (Arrays are handled by array-specific
+functions.  *Note Arrays: (elisp)Arrays.)
+
+
+File: eintr,  Node: cons,  Next: nthcdr,  Prev: car & cdr,  Up: car cdr & cons
+
+7.2 `cons'
+==========
+
+The `cons' function constructs lists; it is the inverse of `car' and
+`cdr'.  For example, `cons' can be used to make a four element list
+from the three element list, `(fir oak maple)':
+
+     (cons 'pine '(fir oak maple))
+
+After evaluating this list, you will see
+
+     (pine fir oak maple)
+
+appear in the echo area.  `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 ``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 `cons' does not change an existing list, but
+creates a new one.
+
+Like `car' and `cdr', `cons' is non-destructive.
+
+* Menu:
+
+* Build a list::
+* length::
+
+
+File: eintr,  Node: Build a list,  Next: length,  Prev: cons,  Up: cons
+
+Build a list
+------------
+
+`cons' must have a list to attach to.(1)  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 `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 `=>', which you may
+read as `evaluates to'.
+
+     (cons 'buttercup ())
+          => (buttercup)
+
+     (cons 'daisy '(buttercup))
+          => (daisy buttercup)
+
+     (cons 'violet '(daisy buttercup))
+          => (violet daisy buttercup)
+
+     (cons 'rose '(violet daisy buttercup))
+          => (rose violet daisy buttercup)
+
+In the first example, the empty list is shown as `()' and a list made
+up of `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 `(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, `(cons 'daisy '(buttercup))' constructs a new, two
+element list by putting `daisy' in front of `buttercup'; and the third
+example constructs a three element list by putting `violet' in front of
+`daisy' and `buttercup'.
+
+---------- Footnotes ----------
+
+(1) Actually, you can `cons' an element to an atom to produce a dotted
+pair.  Dotted pairs are not discussed here; see *Note Dotted Pair
+Notation: (elisp)Dotted Pair Notation.
+
+
+File: eintr,  Node: length,  Prev: Build a list,  Up: cons
+
+7.2.1 Find the Length of a List: `length'
+-----------------------------------------
+
+You can find out how many elements there are in a list by using the Lisp
+function `length', as in the following examples:
+
+     (length '(buttercup))
+          => 1
+
+     (length '(daisy buttercup))
+          => 2
+
+     (length (cons 'violet '(daisy buttercup)))
+          => 3
+
+In the third example, the `cons' function is used to construct a three
+element list which is then passed to the `length' function as its
+argument.
+
+We can also use `length' to count the number of elements in an empty
+list:
+
+     (length ())
+          => 0
+
+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 `length'
+without giving it an argument, not even an empty list:
+
+     (length )
+
+What you see, if you evaluate this, is the error message
+
+     Lisp error: (wrong-number-of-arguments length 0)
+
+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 _one_ list is _one_ argument, even
+if the list has many elements inside it.)
+
+The part of the error message that says `length' is the name of the
+function.
+
+
+File: eintr,  Node: nthcdr,  Next: nth,  Prev: cons,  Up: car cdr & cons
+
+7.3 `nthcdr'
+============
+
+The `nthcdr' function is associated with the `cdr' function.  What it
+does is take the CDR of a list repeatedly.
+
+If you take the CDR of the list `(pine fir oak maple)', you will be
+returned the list `(fir oak maple)'.  If you repeat this on what was
+returned, you will be returned the list `(oak maple)'.  (Of course,
+repeated CDRing on the original list will just give you the original
+CDR since the function does not change the list.  You need to evaluate
+the CDR of the 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 `()' is shown as `nil'.
+
+For review, here is a series of repeated CDRs, the text following the
+`=>' shows what is returned.
+
+     (cdr '(pine fir oak maple))
+          =>(fir oak maple)
+
+     (cdr '(fir oak maple))
+          => (oak maple)
+
+     (cdr '(oak maple))
+          =>(maple)
+
+     (cdr '(maple))
+          => nil
+
+     (cdr 'nil)
+          => nil
+
+     (cdr ())
+          => nil
+
+You can also do several CDRs without printing the values in between,
+like this:
+
+     (cdr (cdr '(pine fir oak maple)))
+          => (oak maple)
+
+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 `cdr'.  This `cdr' passes a list made up of the
+second and subsequent elements of the list to the outermost `cdr',
+which produces a list composed of the third and subsequent elements of
+the original list.  In this example, the `cdr' function is repeated and
+returns a list that consists of the original list without its first two
+elements.
+
+The `nthcdr' function does the same as repeating the call to `cdr'.  In
+the following example, the argument 2 is passed to the function
+`nthcdr', along with the list, and the value returned is the list
+without its first two items, which is exactly the same as repeating
+`cdr' twice on the list:
+
+     (nthcdr 2 '(pine fir oak maple))
+          => (oak maple)
+
+Using the original four element list, we can see what happens when
+various numeric arguments are passed to `nthcdr', including 0, 1, and 5:
+
+     ;; Leave the list as it was.
+     (nthcdr 0 '(pine fir oak maple))
+          => (pine fir oak maple)
+
+     ;; Return a copy without the first element.
+     (nthcdr 1 '(pine fir oak maple))
+          => (fir oak maple)
+
+     ;; Return a copy of the list without three elements.
+     (nthcdr 3 '(pine fir oak maple))
+          => (maple)
+
+     ;; Return a copy lacking all four elements.
+     (nthcdr 4 '(pine fir oak maple))
+          => nil
+
+     ;; Return a copy lacking all elements.
+     (nthcdr 5 '(pine fir oak maple))
+          => nil
+
+
+File: eintr,  Node: nth,  Next: setcar,  Prev: nthcdr,  Up: car cdr & cons
+
+7.4 `nth'
+=========
+
+The `nthcdr' function takes the CDR of a list repeatedly.  The `nth'
+function takes the CAR of the result returned by `nthcdr'.  It returns
+the Nth element of the list.
+
+Thus, if it were not defined in C for speed, the definition of `nth'
+would be:
+
+     (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)))
+
+(Originally, `nth' was defined in Emacs Lisp in `subr.el', but its
+definition was redone in C in the 1980s.)
+
+The `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 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'.
+
+For example:
+
+     (nth 0 '("one" "two" "three"))
+         => "one"
+
+     (nth 1 '("one" "two" "three"))
+         => "two"
+
+It is worth mentioning that `nth', like `nthcdr' and `cdr', does not
+change the original list--the function is non-destructive.  This is in
+sharp contrast to the `setcar' and `setcdr' functions.
+
+
+File: eintr,  Node: setcar,  Next: setcdr,  Prev: nth,  Up: car cdr & cons
+
+7.5 `setcar'
+============
+
+As you might guess from their names, the `setcar' and `setcdr'
+functions set the CAR or the CDR of a list to a new value.  They
+actually change the original list, unlike `car' and `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 `setcar' function.
+
+First, we can make a list and then set the value of a variable to the
+list, using the `setq' function.  Here is a list of animals:
+
+     (setq animals '(antelope giraffe lion tiger))
+
+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 `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.)
+
+When we evaluate the variable `animals', we see that it is bound to the
+list `(antelope giraffe lion tiger)':
+
+     animals
+          => (antelope giraffe lion tiger)
+
+Put another way, the variable `animals' points to the list `(antelope
+giraffe lion tiger)'.
+
+Next, evaluate the function `setcar' while passing it two arguments,
+the variable `animals' and the quoted symbol `hippopotamus'; this is
+done by writing the three element list `(setcar animals 'hippopotamus)'
+and then evaluating it in the usual fashion:
+
+     (setcar animals 'hippopotamus)
+
+After evaluating this expression, evaluate the variable `animals'
+again.  You will see that the list of animals has changed:
+
+     animals
+          => (hippopotamus giraffe lion tiger)
+
+The first element on the list, `antelope' is replaced by `hippopotamus'.
+
+So we can see that `setcar' did not add a new element to the list as
+`cons' would have; it replaced `antelope' with `hippopotamus'; it
+_changed_ the list.
+
+
+File: eintr,  Node: setcdr,  Next: cons Exercise,  Prev: setcar,  Up: car cdr & cons
+
+7.6 `setcdr'
+============
+
+The `setcdr' function is similar to the `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 *Note
+The `kill-new' function: kill-new function, which uses the `nthcdr' and
+`setcdr' functions.)
+
+To see how this works, set the value of the variable to a list of
+domesticated animals by evaluating the following expression:
+
+     (setq domesticated-animals '(horse cow sheep goat))
+
+If you now evaluate the list, you will be returned the list `(horse cow
+sheep goat)':
+
+     domesticated-animals
+          => (horse cow sheep goat)
+
+Next, evaluate `setcdr' with two arguments, the name of the variable
+which has a list as its value, and the list to which the CDR of the
+first list will be set;
+
+     (setcdr domesticated-animals '(cat dog))
+
+If you evaluate this expression, the list `(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 `domesticated-animals':
+
+     domesticated-animals
+          => (horse cat dog)
+
+Indeed, the list is changed from `(horse cow sheep goat)' to `(horse
+cat dog)'.  The CDR of the list is changed from `(cow sheep goat)' to
+`(cat dog)'.
+
+
+File: eintr,  Node: cons Exercise,  Prev: setcdr,  Up: car cdr & cons
+
+7.7 Exercise
+============
+
+Construct a list of four birds by evaluating several expressions with
+`cons'.  Find out what happens when you `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.
+
+
+File: eintr,  Node: Cutting & Storing Text,  Next: List Implementation,  Prev: car cdr & cons,  Up: Top
+
+8 Cutting and Storing 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
+_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::
+* zap-to-char::
+* kill-region::
+* copy-region-as-kill::
+* Digression into C::
+* defvar::
+* cons & search-fwd Review::
+* search Exercises::
+
+
+File: eintr,  Node: Storing Text,  Next: zap-to-char,  Prev: Cutting & Storing Text,  Up: Cutting & Storing Text
+
+Storing Text in a List
+======================
+
+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:
+
+     ("a piece of text" "previous piece")
+
+The function `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:
+
+     (cons "another piece"
+           '("a piece of text" "previous piece"))
+
+If you evaluate this expression, a list of three elements will appear in
+the echo area:
+
+     ("another piece" "a piece of text" "previous piece")
+
+With the `car' and `nthcdr' functions, you can retrieve whichever piece
+of text you want.  For example, in the following code, `nthcdr 1 ...'
+returns the list with the first item removed; and the `car' returns the
+first element of that remainder--the second element of the original
+list:
+
+     (car (nthcdr 1 '("another piece"
+                      "a piece of text"
+                      "previous piece")))
+          => "a piece of text"
+
+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 "kill ring".  This
+chapter leads up to a description of the kill ring and how it is used
+by first tracing how the `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.  *Note Yanking Text Back: Yanking.
+
+
+File: eintr,  Node: zap-to-char,  Next: kill-region,  Prev: Storing Text,  Up: Cutting & Storing Text
+
+8.1 `zap-to-char'
+=================
+
+The `zap-to-char' function changed a little between GNU Emacs version
+19 and GNU Emacs version 22.  However, `zap-to-char' calls another
+function, `kill-region', which enjoyed a major rewrite.
+
+The `kill-region' function in Emacs 19 is complex, but does not use
+code that is important at this time.  We will skip it.
+
+The `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 `zap-to-char' function.
+
+* Menu:
+
+* Complete zap-to-char::
+* zap-to-char interactive::
+* zap-to-char body::
+* search-forward::
+* progn::
+* Summing up zap-to-char::
+
+
+File: eintr,  Node: Complete zap-to-char,  Next: zap-to-char interactive,  Prev: zap-to-char,  Up: zap-to-char
+
+The Complete `zap-to-char' Implementation
+-----------------------------------------
+
+The GNU Emacs version 19 and version 21 implementations of the
+`zap-to-char' function are nearly identical in form, and they work
+alike.  The 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 `zap-to-char'
+removes is put in the kill ring; and it can be retrieved from the kill
+ring by typing `C-y' (`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 `s',
+`Thus' would be removed.  If the argument were two, `Thus, if the curs'
+would be removed, up to and including the `s' in `cursor'.
+
+If the specified character is not found, `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, `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.
+
+Here is the complete text of the version 22 implementation of the
+function:
+
+     (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))))
+
+
+File: eintr,  Node: zap-to-char interactive,  Next: zap-to-char body,  Prev: Complete zap-to-char,  Up: zap-to-char
+
+8.1.1 The `interactive' Expression
+----------------------------------
+
+The interactive expression in the `zap-to-char' command looks like this:
+
+     (interactive "p\ncZap to char: ")
+
+The part within quotation marks, `"p\ncZap to char: "', specifies two
+different things.  First, and most simply, is the `p'.  This part is
+separated from the next part by a newline, `\n'.  The `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 `C-u' and
+a number, or `M-' and a number.  If the function is called
+interactively without a prefix, 1 is passed to this argument.
+
+The second part of `"p\ncZap to char: "' is `cZap to char:  '.  In this
+part, the lower case `c' indicates that `interactive' expects a prompt
+and that the argument will be a character.  The prompt follows the `c'
+and is the string `Zap to char: ' (with a space after the colon to make
+it look good).
+
+What all this does is prepare the arguments to `zap-to-char' so they
+are of the right type, and give the user a prompt.
+
+In a read-only buffer, the `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.
+
+Let us continue with the interactive specification.
+
+
+File: eintr,  Node: zap-to-char body,  Next: search-forward,  Prev: zap-to-char interactive,  Up: zap-to-char
+
+8.1.2 The Body of `zap-to-char'
+-------------------------------
+
+The body of the `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 documentation is thorough.  You do need to know the jargon meaning
+of the word `kill'.
+
+The first part of the code looks like this:
+
+     (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)))
+
+`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 `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 `aref' function extracts an element
+from an array.  It is an array-specific function that is not described
+in this document.  *Note Arrays: (elisp)Arrays.)
+
+`(point)' is the current position of the cursor.
+
+The next part of the code is an expression using `progn'.  The body of
+the `progn' consists of calls to `search-forward' and `point'.
+
+It is easier to understand how `progn' works after learning about
+`search-forward', so we will look at `search-forward' and then at
+`progn'.
+
+
+File: eintr,  Node: search-forward,  Next: progn,  Prev: zap-to-char body,  Up: zap-to-char
+
+8.1.3 The `search-forward' Function
+-----------------------------------
+
+The `search-forward' function is used to locate the
+zapped-for-character in `zap-to-char'.  If the search is successful,
+`search-forward' leaves point immediately after the last character in
+the target string.  (In `zap-to-char', the target string is just one
+character long.  `zap-to-char' uses the function `char-to-string' to
+ensure that the computer treats that character as a string.)  If the
+search is backwards, `search-forward' leaves point just before the
+first character in the target.  Also, `search-forward' returns `t' for
+true.  (Moving point is therefore a `side effect'.)
+
+In `zap-to-char', the `search-forward' function looks like this:
+
+     (search-forward (char-to-string char) nil nil arg)
+
+The `search-forward' function takes four arguments:
+
+  1. The first argument is the target, what is searched for.  This must
+     be a string, such as `"z"'.
+
+     As it happens, the argument passed to `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 `search-forward' function
+     searches for a string, the character that the `zap-to-char'
+     function receives as its argument must be converted inside the
+     computer from one format to the other; otherwise the
+     `search-forward' function will fail.  The `char-to-string'
+     function is used to make this conversion.
+
+  2. 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
+     `nil'.
+
+  3. 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 `nil'.  A `nil' as the third argument causes the
+     function to signal an error when the search fails.
+
+  4. The fourth argument to `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.
+
+In template form, a `search-forward' expression looks like this:
+
+     (search-forward "TARGET-STRING"
+                     LIMIT-OF-SEARCH
+                     WHAT-TO-DO-IF-SEARCH-FAILS
+                     REPEAT-COUNT)
+
+We will look at `progn' next.
+
+
+File: eintr,  Node: progn,  Next: Summing up zap-to-char,  Prev: search-forward,  Up: zap-to-char
+
+8.1.4 The `progn' Special Form
+------------------------------
+
+`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.
+
+The template for a `progn' expression is very simple:
+
+     (progn
+       BODY...)
+
+In `zap-to-char', the `progn' expression has to do two things: put
+point in exactly the right position; and return the location of point
+so that `kill-region' will know how far to kill to.
+
+The first argument to the `progn' is `search-forward'.  When
+`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, `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 `progn' is the expression `(point)'.
+This expression returns the value of point, which in this case will be
+the location to which it has been moved by `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 `point' is returned by the `progn' expression
+and is passed to `kill-region' as `kill-region''s second argument.
+
+
+File: eintr,  Node: Summing up zap-to-char,  Prev: progn,  Up: zap-to-char
+
+8.1.5 Summing up `zap-to-char'
+------------------------------
+
+Now that we have seen how `search-forward' and `progn' work, we can see
+how the `zap-to-char' function works as a whole.
+
+The first argument to `kill-region' is the position of the cursor when
+the `zap-to-char' command is given--the value of point at that time.
+Within the `progn', the search function then moves point to just after
+the zapped-to-character and `point' returns the value of this location.
+The `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 `progn' special form is necessary because the `kill-region' command
+takes two arguments; and it would fail if `search-forward' and `point'
+expressions were written in sequence as two additional arguments.  The
+`progn' expression is a single argument to `kill-region' and returns
+the one value that `kill-region' needs for its second argument.
+
+
+File: eintr,  Node: kill-region,  Next: copy-region-as-kill,  Prev: zap-to-char,  Up: Cutting & Storing Text
+
+8.2 `kill-region'
+=================
+
+The `zap-to-char' function uses the `kill-region' function.  This
+function clips text from a region and copies that text to the kill
+ring, from which it may be retrieved.
+
+The Emacs 22 version of that function uses `condition-case' and
+`copy-region-as-kill', both of which we will explain.  `condition-case'
+is an important special form.
+
+In essence, the `kill-region' function calls `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::
+* condition-case::
+* Lisp macro::
+
+
+File: eintr,  Node: Complete kill-region,  Next: condition-case,  Prev: kill-region,  Up: kill-region
+
+The Complete `kill-region' Definition
+-------------------------------------
+
+We will go through the `condition-case' code in a moment.  First, let
+us look at the definition of `kill-region', with comments added:
+
+     (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. ... "
+
+       ;; * Since order matters, pass point first.
+       (interactive (list (point) (mark)))
+       ;; * And tell us if we cannot cut the text.
+       (unless (and beg end)
+         (error "The mark is not set now, so there is no region"))
+
+       ;; * `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
+
+           ;; * The second argument to `condition-case' tells the
+           ;;    Lisp interpreter what to do when all goes well.
+
+           ;;    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.
+
+           ;;    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.
+
+           ;;    `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'.
+           (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)
+                   ;;    - `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)
+
+         ;;  * The third argument to `condition-case' tells the interpreter
+         ;;    what to do with an error.
+         ;;    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.
+         ;;    The first part of the third argument is the following:
+         ((buffer-read-only text-read-only) ;; the if-part
+          ;; ...  the then-part
+          (copy-region-as-kill beg end)
+          ;;    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.
+          (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)))))
+
+
+File: eintr,  Node: condition-case,  Next: Lisp macro,  Prev: Complete kill-region,  Up: kill-region
+
+8.2.1 `condition-case'
+----------------------
+
+As we have seen earlier (*note Generate an Error Message: Making
+Errors.), 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 `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 `kill-region' function contains code to
+handle this circumstance.  This code, which makes up the body of the
+`kill-region' function, is inside of a `condition-case' special form.
+
+The template for `condition-case' looks like this:
+
+     (condition-case
+       VAR
+       BODYFORM
+       ERROR-HANDLER...)
+
+The second argument, BODYFORM, is straightforward.  The
+`condition-case' special form causes the Lisp interpreter to evaluate
+the code in BODYFORM.  If no error occurs, the special form returns the
+code's value and produces the side-effects, if any.
+
+In short, the BODYFORM part of a `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 `condition case'.  An error
+handler has two parts, a CONDITION-NAME and a BODY.  If the
+CONDITION-NAME part of an error handler matches a condition name
+generated by an error, then the BODY part of the error handler is run.
+
+As you will expect, the CONDITION-NAME part of an error handler may be
+either a single condition name or a list of condition names.
+
+Also, a complete `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 `condition-case' expression, the 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
+`kill-region', that information is discarded.
+
+In brief, in the `kill-region' function, the code `condition-case'
+works like this:
+
+     IF NO ERRORS, RUN ONLY THIS CODE
+         BUT, IF ERRORS, RUN THIS OTHER CODE.
+
+
+File: eintr,  Node: Lisp macro,  Prev: condition-case,  Up: kill-region
+
+8.2.2 Lisp macro
+----------------
+
+The part of the `condition-case' expression that is evaluated in the
+expectation that all goes well has a `when'.  The code uses `when' to
+determine whether the `string' variable points to text that exists.
+
+A `when' expression is simply a programmers' convenience.  It is an
+`if' without the possibility of an else clause.  In your mind, you can
+replace `when' with `if' and understand what goes on.  That is what the
+Lisp interpreter does.
+
+Technically speaking, `when' is a Lisp macro.  A Lisp "macro" enables
+you to define new control constructs and other language features.  It
+tells the interpreter how to compute another Lisp expression which will
+in turn compute the value.  In this case, the `other expression' is an
+`if' expression.  For more about Lisp macros, see *Note Macros:
+(elisp)Macros.  The C programming language also provides macros.  These
+are different, but also useful.
+
+If the string has content, then another conditional expression is
+executed.  This is an `if' with both a then-part and an else-part.
+
+     (if (eq last-command 'kill-region)
+         (kill-append string (< end beg) yank-handler)
+       (kill-new string nil yank-handler))
+
+The then-part is evaluated if the previous command was another call to
+`kill-region'; if not, the else-part is evaluated.
+
+`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'.
+
+`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 `last-command' to the previous command.
+
+In this segment of the definition, the `if' expression checks whether
+the previous command was `kill-region'.  If it was,
+
+     (kill-append string (< end beg) yank-handler)
+
+concatenates a copy of the newly clipped text to the just previously
+clipped text in the kill ring.
+
+
+File: eintr,  Node: copy-region-as-kill,  Next: Digression into C,  Prev: kill-region,  Up: Cutting & Storing Text
+
+8.3 `copy-region-as-kill'
+=========================
+
+The `copy-region-as-kill' function copies a region of text from a
+buffer and (via either `kill-append' or `kill-new') saves it in the
+`kill-ring'.
+
+If you call `copy-region-as-kill' immediately after a `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 `copy-region-as-kill', the function copies the
+text into a separate entry in the kill ring.
+
+* Menu:
+
+* Complete copy-region-as-kill::
+* copy-region-as-kill body::
+
+
+File: eintr,  Node: Complete copy-region-as-kill,  Next: copy-region-as-kill body,  Prev: copy-region-as-kill,  Up: copy-region-as-kill
+
+The complete `copy-region-as-kill' function definition
+------------------------------------------------------
+
+Here is the complete text of the version 22 `copy-region-as-kill'
+function:
+
+     (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")
+       (if (eq last-command 'kill-region)
+           (kill-append (filter-buffer-substring beg end) (< end beg))
+         (kill-new (filter-buffer-substring beg end)))
+       (if transient-mark-mode
+           (setq deactivate-mark t))
+       nil)
+
+As usual, this function can be divided into its component parts:
+
+     (defun copy-region-as-kill (ARGUMENT-LIST)
+       "DOCUMENTATION..."
+       (interactive "r")
+       BODY...)
+
+The arguments are `beg' and `end' and the function is interactive with
+`"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 `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
+`interprogram-cut-function' function is `x-select-text', which works
+with the windowing system's equivalent of the Emacs kill ring.
+
+The body of the `copy-region-as-kill' function starts with an `if'
+clause.  What this clause does is distinguish between two different
+situations: whether or not this command is executed immediately after a
+previous `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 `copy-region-as-kill' merits discussion in detail.
+
+
+File: eintr,  Node: copy-region-as-kill body,  Prev: Complete copy-region-as-kill,  Up: copy-region-as-kill
+
+8.3.1 The Body of `copy-region-as-kill'
+---------------------------------------
+
+The `copy-region-as-kill' function works in much the same way as the
+`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 `kill-region', the `copy-region-as-kill' function makes use of the
+`last-command' variable that keeps track of the previous Emacs command.
+
+* Menu:
+
+* last-command & this-command::
+* kill-append function::
+* kill-new function::
+
+
+File: eintr,  Node: last-command & this-command,  Next: kill-append function,  Prev: copy-region-as-kill body,  Up: copy-region-as-kill body
+
+`last-command' and `this-command'
+.................................
+
+Normally, whenever a function is executed, Emacs sets the value of
+`this-command' to the function being executed (which in this case would
+be `copy-region-as-kill').  At the same time, Emacs sets the value of
+`last-command' to the previous value of `this-command'.
+
+In the first part of the body of the `copy-region-as-kill' function, an
+`if' expression determines whether the value of `last-command' is
+`kill-region'.  If so, the then-part of the `if' expression is
+evaluated; it uses the `kill-append' function to concatenate the text
+copied at this call to the function with the text already in the first
+element (the CAR) of the kill ring.  On the other hand, if the value of
+`last-command' is not `kill-region', then the `copy-region-as-kill'
+function attaches a new element to the kill ring using the `kill-new'
+function.
+
+The `if' expression reads as follows; it uses `eq', which is a function
+we have not yet seen:
+
+       (if (eq last-command 'kill-region)
+           ;; then-part
+           (kill-append  (filter-buffer-substring beg end) (< end beg))
+         ;; else-part
+         (kill-new  (filter-buffer-substring beg end)))
+
+(The `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
+`buffer-substring' function, which came before text properties were
+implemented.)
+
+The `eq' function tests whether its first argument is the same Lisp
+object as its second argument.  The `eq' function is similar to the
+`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.  `equal'
+determines whether the structure and contents of two expressions are
+the same.
+
+If the previous command was `kill-region', then the Emacs Lisp
+interpreter calls the `kill-append' function
+
+
+File: eintr,  Node: kill-append function,  Next: kill-new function,  Prev: last-command & this-command,  Up: copy-region-as-kill body
+
+The `kill-append' function
+..........................
+
+The `kill-append' function looks like this:
+
+     (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.
+     ... "
+       (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)))
+
+The `kill-append' function is fairly straightforward.  It uses the
+`kill-new' function, which we will discuss in more detail in a moment.
+
+(Also, the function provides an optional argument called
+`yank-handler'; when invoked, this argument tells the function how to
+deal with properties added to the text, such as `bold' or `italics'.)
+
+It has a `let*' function to set the value of the first element of the
+kill ring to `cur'.  (I do not know why the function does not use `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
+`kill-new'.  It uses `concat' to concatenate the new text to the CAR of
+the kill ring.  Whether it prepends or appends the text depends on the
+results of an `if' expression:
+
+     (if before-p                            ; if-part
+         (concat string cur)                 ; then-part
+       (concat cur string))                  ; else-part
+
+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 `if' expression depends on the predicate `before-p' to decide
+whether the newly saved text should be put before or after the
+previously saved text.
+
+The symbol `before-p' is the name of one of the arguments to
+`kill-append'.  When the `kill-append' function is evaluated, it is
+bound to the value returned by evaluating the actual argument.  In this
+case, this is the expression `(< 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 `end' is less than the
+value of the variable `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, `(< 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 `end' is greater than the value of
+the variable `beg', the text will be appended after the previous text.
+
+When the newly saved text will be prepended, then the string with the
+new text will be concatenated before the old text:
+
+     (concat string cur)
+
+But if the text will be appended, it will be concatenated after the old
+text:
+
+     (concat cur string))
+
+To understand how this works, we first need to review the `concat'
+function.  The `concat' function links together or unites two strings
+of text.  The result is a string.  For example:
+
+     (concat "abc" "def")
+          => "abcdef"
+
+     (concat "new "
+             (car '("first element" "second element")))
+          => "new first element"
+
+     (concat (car
+             '("first element" "second element")) " modified")
+          => "first element modified"
+
+We can now make sense of `kill-append': it modifies the contents of the
+kill ring.  The kill ring is a list, each element of which is saved
+text.  The `kill-append' function uses the `kill-new' function which in
+turn uses the `setcar' function.
+
+
+File: eintr,  Node: kill-new function,  Prev: kill-append function,  Up: copy-region-as-kill body
+
+The `kill-new' function
+.......................
+
+The `kill-new' function looks like this:
+
+     (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.
+     ..."
+       (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"))))
+       (if (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)
+         (push 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))))
+
+(Notice that the function is not interactive.)
+
+As usual, we can look at this function in parts.
+
+The function definition has an optional `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.
+
+The first line of the documentation makes sense:
+
+     Make STRING the latest kill in the kill ring.
+
+Let's skip over the rest of the documentation for the moment.
+
+Also, let's skip over the initial `if' expression and those lines of
+code involving `menu-bar-update-yank-menu'.  We will explain them below.
+
+The critical lines are these:
+
+       (if (and replace kill-ring)
+           ;; then
+           (setcar kill-ring string)
+         ;; else
+       (push string kill-ring)
+         (setq kill-ring (cons string kill-ring))
+         (if (> (length kill-ring) kill-ring-max)
+             ;; avoid overly long kill ring
+             (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))))
+
+The conditional test is `(and replace kill-ring)'.  This will be true
+when two conditions are met:  the kill ring has something in it, and
+the `replace' variable is true.
+
+When the `kill-append' function sets `replace' to be true and when the
+kill ring has at least one item in it, the `setcar' expression is
+executed:
+
+     (setcar kill-ring string)
+
+The `setcar' function actually changes the first element of the
+`kill-ring' list to the value of `string'.  It replaces the first
+element.
+
+On the other hand, if the kill ring is empty, or replace is false, the
+else-part of the condition is executed:
+
+     (push string kill-ring)
+
+`push' puts its first argument onto the second.  It is the same as the
+older
+
+     (setq kill-ring (cons string kill-ring))
+
+or the newer
+
+     (add-to-list kill-ring string)
+
+When it is false, the expression first constructs a new version of the
+kill ring by prepending `string' to the existing kill ring as a new
+element (that is what the `push' does).  Then it executes a second `if'
+clause.  This second `if' clause keeps the kill ring from growing too
+long.
+
+Let's look at these two expressions in order.
+
+The `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.
+
+First,
+
+     (setq example-list '("here is a clause" "another clause"))
+
+After evaluating this expression with `C-x C-e', you can evaluate
+`example-list' and see what it returns:
+
+     example-list
+          => ("here is a clause" "another clause")
+
+Now, we can add a new element on to this list by evaluating the
+following expression: 
+
+     (push "a third clause" example-list)
+
+When we evaluate `example-list', we find its value is:
+
+     example-list
+          => ("a third clause" "here is a clause" "another clause")
+
+Thus, the third clause is added to the list by `push'.
+
+Now for the second part of the `if' clause.  This expression keeps the
+kill ring from growing too long.  It looks like this:
+
+     (if (> (length kill-ring) kill-ring-max)
+         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
+
+The code checks whether the length of the kill ring is greater than the
+maximum permitted length.  This is the value of `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 `nil'.  It does
+this by using two functions, `nthcdr' and `setcdr'.
+
+We looked at `setcdr' earlier (*note `setcdr': setcdr.).  It sets the
+CDR of a list, just as `setcar' sets the CAR of a list.  In this case,
+however, `setcdr' will not be setting the CDR of the whole kill ring;
+the `nthcdr' function is used to cause it to set the CDR of the next to
+last element of the kill ring--this means that since the 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.
+
+The `nthcdr' function works by repeatedly taking the CDR of a list--it
+takes the CDR of the CDR of the CDR ...  It does this N times and
+returns the results.  (*Note `nthcdr': nthcdr.)
+
+Thus, if we had a four element list that was supposed to be three
+elements long, we could set the CDR of the next to last element to
+`nil', and thereby shorten the list.  (If you sent the last element to
+some other value than `nil', which you could do, then you would not
+have shortened the list.  *Note `setcdr': setcdr.)
+
+You can see shortening by evaluating the following three expressions in
+turn.  First set the value of `trees' to `(maple oak pine birch)', then
+set the CDR of its second CDR to `nil' and then find the value of
+`trees':
+
+     (setq trees '(maple oak pine birch))
+          => (maple oak pine birch)
+
+     (setcdr (nthcdr 2 trees) nil)
+          => nil
+
+     trees
+          => (maple oak pine)
+
+(The value returned by the `setcdr' expression is `nil' since that is
+what the CDR is set to.)
+
+To repeat, in `kill-new', the `nthcdr' function takes the CDR a number
+of times that is one less than the maximum permitted size of the kill
+ring and `setcdr' sets the CDR of that element (which will be the rest
+of the elements in the kill ring) to `nil'.  This prevents the kill
+ring from growing too long.
+
+The next to last expression in the `kill-new' function is
+
+     (setq kill-ring-yank-pointer kill-ring)
+
+The `kill-ring-yank-pointer' is a global variable that is set to be the
+`kill-ring'.
+
+Even though the `kill-ring-yank-pointer' is called a `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.  The variable is used
+in functions such as `yank' and `yank-pop' (*note Yanking Text Back:
+Yanking.).
+
+Now, to return to an early expression in the body of the function:
+
+       (if (fboundp 'menu-bar-update-yank-menu)
+            (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+
+It starts with an `if' expression
+
+In this case, the expression tests first to see whether
+`menu-bar-update-yank-menu' exists as a function, and if so, calls it.
+The `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 (*note Generate an Error Message:
+Making Errors.).
+
+The then-part contains an expression whose first element is the
+function `and'.
+
+The `and' special form evaluates each of its arguments until one of the
+arguments returns a value of `nil', in which case the `and' expression
+returns `nil'; however, if none of the arguments returns a value of
+`nil', the value resulting from evaluating the last argument is
+returned.  (Since such a value is not `nil', it is considered true in
+Emacs Lisp.)  In other words, an `and' expression returns a true value
+only if all its arguments are true.  (*Note Second Buffer Related
+Review::.)
+
+The expression determines whether the second argument to
+`menu-bar-update-yank-menu' is true or not.
+
+`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 `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 `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.
+
+The expression looks like this:
+
+       (if interprogram-cut-function
+           (funcall interprogram-cut-function string (not replace))))
+
+If an `interprogram-cut-function' exists, then Emacs executes
+`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 `if' expression could be replaced by an `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'.
+
+
+File: eintr,  Node: Digression into C,  Next: defvar,  Prev: copy-region-as-kill,  Up: Cutting & Storing Text
+
+8.4 Digression into C
+=====================
+
+The `copy-region-as-kill' function (*note `copy-region-as-kill':
+copy-region-as-kill.) uses the `filter-buffer-substring' function,
+which in turn uses the `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 `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.
+
+Like many of the other Emacs primitives, `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:
+
+     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);
+     }
+
+Without going into the details of the macro writing process, let me
+point out that this macro starts with the word `DEFUN'.  The word
+`DEFUN' was chosen since the code serves the same purpose as `defun'
+does in Lisp.  (The `DEFUN' C macro is defined in `emacs/src/lisp.h'.)
+
+The word `DEFUN' is followed by seven parts inside of parentheses:
+
+   * The first part is the name given to the function in Lisp,
+     `delete-and-extract-region'.
+
+   * The second part is the name of the function in C,
+     `Fdelete_and_extract_region'.  By convention, it starts with `F'.
+     Since C does not use hyphens in names, underscores are used
+     instead.
+
+   * 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 `S' instead of an `F'.
+
+   * The fourth and fifth parts specify the minimum and maximum number
+     of arguments the function can have.  This function demands exactly
+     2 arguments.
+
+   * The sixth part is nearly like the argument that follows the
+     `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
+     `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 `goto-char' includes `"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.
+
+   * 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 `\n' followed by a backslash and carriage
+     return.
+
+     Thus, the first two lines of documentation for  `goto-char' are
+     written like this:
+
+            "Set point to POSITION, a number or marker.\n\
+          Beginning of buffer is position (point-min), end is (point-max).
+
+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 `delete-and-extract-region' the `body' consists of the
+following four lines:
+
+     validate_region (&start, &end);
+     if (XINT (start) == XINT (end))
+       return build_string ("");
+     return del_range_1 (XINT (start), XINT (end), 1, 1);
+
+The   `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 `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
+`del_range'.  These are `XINT (start)' and `XINT (end)'.
+
+As far as the C language is concerned, `start' and `end' are two
+integers that mark the beginning and end of the region to be deleted(1).
+
+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'.
+
+`XINT' is a C macro that extracts the relevant number from the longer
+collection of bits; the three other bits are discarded.
+
+The command in `delete-and-extract-region' looks like this:
+
+     del_range_1 (XINT (start), XINT (end), 1, 1);
+
+It deletes the region between the beginning position, `start', and the
+ending position, `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.
+
+---------- Footnotes ----------
+
+(1) 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.
+
+
+File: eintr,  Node: defvar,  Next: cons & search-fwd Review,  Prev: Digression into C,  Up: Cutting & Storing Text
+
+8.5 Initializing a Variable with `defvar'
+=========================================
+
+The `copy-region-as-kill' function is written in Emacs Lisp.  Two
+functions within it, `kill-append' and `kill-new', copy a region in a
+buffer and save it in a variable called the `kill-ring'.  This section
+describes how the `kill-ring' variable is created and initialized using
+the `defvar' special form.
+
+(Again we note that the term `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 `kill-ring' is created and given
+an initial value by using the `defvar' special form.  The name comes
+from "define variable".
+
+The `defvar' special form is similar to `setq' in that it sets the
+value of a variable.  It is unlike `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, `defvar' does not override
+the existing value.  Second, `defvar' has a documentation string.
+
+(Another special form, `defcustom', is designed for variables that
+people customize.  It has more features than `defvar'.  (*Note Setting
+Variables with `defcustom': defcustom.)
+
+* Menu:
+
+* See variable current value::
+* defvar and asterisk::
+
+
+File: eintr,  Node: See variable current value,  Next: defvar and asterisk,  Prev: defvar,  Up: defvar
+
+Seeing the Current Value of a Variable
+--------------------------------------
+
+You can see the current value of a variable, any variable, by using the
+`describe-variable' function, which is usually invoked by typing `C-h
+v'.  If you type `C-h v' and then `kill-ring' (followed by <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 `kill-ring':
+
+     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
+     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.
+
+The kill ring is defined by a `defvar' in the following way:
+
+     (defvar kill-ring nil
+       "List of killed text sequences.
+     ...")
+
+In this variable definition, the variable is given an initial value of
+`nil', which makes sense, since if you have saved nothing, you want
+nothing back if you give a `yank' command.  The documentation string is
+written just like the documentation string of a `defun'.  As with the
+documentation string of the `defun', the first line of the
+documentation should be a complete sentence, since some commands, like
+`apropos', print only the first line of documentation.  Succeeding
+lines should not be indented; otherwise they look odd when you use `C-h
+v' (`describe-variable').
+