-\input ../man/texinfo @c -*-texinfo-*-
-@c \input texinfo @c -*-texinfo-*-
-@c change to \input texinfo if building on own.
+\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/eintr
@c setfilename emacs-lisp-intro.info
@comment %**end of header
-@set edition-number 3.06
-@set update-date 6 November 2006
+@set edition-number 3.07
+@set update-date 9 November 2006
@ignore
## Summary of shell commands to create various output formats:
## pushd /u/intro/
## Info output
- # makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
- ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "../info/eintr"))
+ ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
## DVI output
texi2dvi emacs-lisp-intro.texi
- ## View DVI output; see below also
- # xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
+ ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
## HTML output
makeinfo --html --no-split --verbose emacs-lisp-intro.texi
+ ## galeon emacs-lisp-intro.html
+
## Plain text output
makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
--verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
- ## DocBook output
- makeinfo --docbook --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+ popd
- ## XML output
- makeinfo --xml --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+# as user `root'
+# insert thumbdrive
+ mtusb # mount -v -t ext3 /dev/sda /mnt
+ cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
+ umtusb # umount -v /mnt
+# remove thumbdrive
- popd
+ ## Other shell commands
- #### (You must be in the same directory as the viewed file.)
+ pushd /usr/local/src/emacs/lispintro/
+ ## pushd /u/intro/
- ## View DVI output
- xdvi emacs-lisp-intro.dvi &
+ ## PDF
+ texi2dvi --pdf emacs-lisp-intro.texi
+ # xpdf emacs-lisp-intro.pdf &
- ## View HTML output
- galeon emacs-lisp-intro.html
+ ## DocBook -- note file extension
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
- ## View Info output with standalone reader
- info emacs-lisp-intro.info
+ ## XML with a Texinfo DTD -- note file extension
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
- ## popd
+ ## PostScript (needs DVI)
+ # gv emacs-lisp-intro.ps &
+ # Create DVI if we lack it
+ # texi2dvi emacs-lisp-intro.texi
+ dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
+ ## RTF (needs HTML)
+ # Use OpenOffice to view RTF
+ # Create HTML if we lack it
+ # makeinfo --no-split --html emacs-lisp-intro.texi
+ /usr/local/src/html2rtf.pl emacs-lisp-intro.html
-# as user `root'
-# insert thumbdrive
- mtusb # mount -v -t ext3 /dev/sda /mnt
- cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
- umtusb # umount -v /mnt
-# remove thumbdrive
+ ## LaTeX (needs RTF)
+ /usr/bin/rtf2latex emacs-lisp-intro.rtf
+
+ popd
@end ignore
@c After creating the Info file, edit your Info `dir' file, if the
@c `dircategory' section below does not enable your system to
@c install the manual automatically.
-@c (The `dir' file is often in the `/usr/local/info/' directory.)
+@c (The `dir' file is often in the `/usr/local/share/info/' directory.)
@c ================ How to Create an HTML file ================
Evaluation
+* How the Interpreter Acts:: Returns and Side Effects...
* Evaluating Inner Lists:: Lists within lists...
Variables
Make a Function Interactive
* Interactive multiply-by-seven:: An overview.
-* multiply-by-seven in detail:: The interactive version.
+* multiply-by-seven in detail:: The interactive version.
@code{let}
@code{copy-region-as-kill}
* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
+* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
The Body of @code{copy-region-as-kill}
* Loop Example:: A @code{while} loop that uses a list.
* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
* Incrementing Loop:: A loop with an incrementing counter.
+* Incrementing Loop Details::
* Decrementing Loop:: A loop with a decrementing counter.
-A Loop with an Incrementing Counter
+Details of an Incrementing Loop
* Incrementing Example:: Counting pebbles in a triangle.
* Inc Example parts:: The parts of the function definition.
Prepare the Data for Display in a Graph
+* Data for Display in Detail::
* Sorting:: Sorting lists.
* Files List:: Making a list of files.
* Counting function definitions::
Handling the Kill Ring
+* What the Kill Ring Does::
* current-kill::
* yank:: Paste a copy of a clipped element.
* yank-pop:: Insert element pointed to.
@code{current-kill} in Outline
+* Body of current-kill::
* Digression concerning error:: How to mislead humans, but not computers.
* Determining the Element::
The @code{print-Y-axis} Function
+* print-Y-axis in Detail::
* Height of label:: What height for the Y axis?
* Compute a Remainder:: How to compute the remainder of a division.
* Y Axis Element:: Construct a line for the Y axis.
editing in the most general sense of the word.)
@menu
-* Why::
-* On Reading this Text::
-* Who You Are::
+* 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::
+* Note for Novices:: You can read this as a novice.
* Thank You::
@end menu
Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
@menu
-* Lisp Lists::
-* Run a Program::
-* Making Errors::
-* Names & Definitions::
-* Lisp Interpreter::
-* Evaluation::
-* Variables::
-* Arguments::
-* set & setq::
-* Summary::
+* Lisp Lists:: What are lists?
+* Run a Program:: Any list in Lisp is a program ready to run.
+* Making Errors:: Generating an error message.
+* Names & Definitions:: Names of symbols and function definitions.
+* Lisp Interpreter:: What the Lisp interpreter does.
+* Evaluation:: Running a program.
+* Variables:: Returning a value from a variable.
+* Arguments:: Passing information to a function.
+* set & setq:: Setting the value of a variable.
+* Summary:: The major points.
* Error Message Exercises::
@end menu
@cindex Flowers in a field
@menu
-* Numbers Lists::
-* Lisp Atoms::
-* Whitespace in Lists::
-* Typing 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.
@end menu
@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
yourself or the computer.
@menu
-* Complications::
-* Byte Compiling::
+* Complications:: Variables, Special forms, Lists within.
+* Byte Compiling:: Specially processing code for speed.
@end menu
@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
value or amount of; to appraise', according to @cite{Webster's New
Collegiate Dictionary}.
+@menu
+* How the Interpreter Acts:: Returns and Side Effects...
+* Evaluating Inner Lists:: Lists within lists...
+@end menu
+
+@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
+@ifnottex
+@unnumberedsubsec How the Lisp Interpreter Acts
+@end ifnottex
+
+@cindex @samp{returned value} explained
After evaluating an expression, the Lisp interpreter will most likely
@dfn{return} the value that the computer produces by carrying out the
instructions it found in the function definition, or perhaps it will
Lisp interpreter to return a value and perhaps carry out a side effect;
or else produce an error.
-@menu
-* Evaluating Inner Lists::
-@end menu
-
-@node Evaluating Inner Lists, , Evaluation, Evaluation
+@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation
@comment node-name, next, previous, up
@subsection Evaluating Inner Lists
@cindex Inner list evaluation
@menu
* fill-column Example::
-* Void Function::
-* Void Variable::
+* Void Function:: The error message for a symbol
+ without a function.
+* Void Variable:: The error message for a symbol without a value.
@end menu
@node fill-column Example, Void Function, Variables, Variables
have two different function definitions at the same time.)}
@menu
-* Data types::
-* Args as Variable or List::
-* Variable Number of Arguments::
-* Wrong Type of Argument::
-* message::
+* Data types:: Types of data passed to a function.
+* Args as Variable or List:: An argument can be the value
+ of a variable or list.
+* Variable Number of Arguments:: Some functions may take a
+ variable number of arguments.
+* Wrong Type of Argument:: Passing an argument of the wrong type
+ to a function.
+* message:: A useful function for sending messages.
@end menu
@node Data types, Args as Variable or List, Arguments, Arguments
work but also illustrate how arguments are passed.
@menu
-* Using set::
-* Using setq::
-* Counting::
+* Using set:: Setting values.
+* Using setq:: Setting a quoted value.
+* Counting:: Using @code{setq} to count.
@end menu
@node Using set, Using setq, set & setq, set & setq
buffer-related functions, to see how they were written.
@menu
-* How to Evaluate::
-* Buffer Names::
-* Getting Buffers::
-* Switching Buffers::
-* Buffer Size & Locations::
+* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
+ causes evaluation.
+* Buffer Names:: Buffers and files are different.
+* Getting Buffers:: Getting a buffer itself, not merely its name.
+* Switching Buffers:: How to change to another buffer.
+* Buffer Size & Locations:: Where point is located and the size of
+ the buffer.
* Evaluation Exercise::
@end menu
@menu
* Primitive Functions::
-* defun::
-* Install::
-* Interactive::
-* Interactive Options::
-* Permanent Installation::
-* let::
-* if::
-* else::
-* Truth & Falsehood::
-* save-excursion::
+* defun:: The @code{defun} special form.
+* Install:: Install a function definition.
+* Interactive:: Making a function interactive.
+* Interactive Options:: Different options for @code{interactive}.
+* Permanent Installation:: Installing code permanently.
+* let:: Creating and initializing local variables.
+* if:: What if?
+* else:: If--then--else expressions.
+* Truth & Falsehood:: What Lisp considers false and true.
+* save-excursion:: Keeping track of point, mark, and buffer.
* Review::
* defun Exercises::
@end menu
@menu
* Effect of installation::
-* Change a defun::
+* Change a defun:: How to change a function definition.
@end menu
@node Effect of installation, Change a defun, Install, Install
each time you typed a key, it would be very distracting.
@menu
-* Interactive multiply-by-seven::
-* multiply-by-seven in detail::
+* Interactive multiply-by-seven:: An overview.
+* multiply-by-seven in detail:: The interactive version.
@end menu
@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
@menu
* if in more detail::
-* type-of-animal in detail::
+* type-of-animal in detail:: An example of an @code{if} expression.
@end menu
@node if in more detail, type-of-animal in detail, if, if
long as it is not empty), or even a buffer!
@menu
-* nil explained::
+* nil explained:: @code{nil} has two meanings.
@end menu
@node nil explained, , Truth & Falsehood, Truth & Falsehood
unexpected movement of point or mark.
@menu
-* Point and mark::
+* Point and mark:: A review of various locations.
* Template for save-excursion::
@end menu
@smallexample
@group
-(if (string-equal
- (number-to-string 22)
- (substring (emacs-version) 10 12))
+(if (= 22 emacs-major-version)
(message "This is version 22 Emacs")
(message "This is not version 22 Emacs"))
@end group
@end smallexample
-@item equal
-@itemx eq
-Test whether two objects are the same. @code{equal} uses one meaning
-of the word `same' and @code{eq} uses another: @code{equal} returns
-true if the two objects have a similar structure and contents, such as
-two copies of the same book. On the other hand, @code{eq}, returns
-true if both arguments are actually the same object.
-@findex equal
-@findex eq
-
@need 1250
@item <
@itemx >
The @code{=} function tests whether two arguments, both numbers or
markers, are equal.
+@need 1250
+@item equal
+@itemx eq
+Test whether two objects are the same. @code{equal} uses one meaning
+of the word `same' and @code{eq} uses another: @code{equal} returns
+true if the two objects have a similar structure and contents, such as
+two copies of the same book. On the other hand, @code{eq}, returns
+true if both arguments are actually the same object.
+@findex equal
+@findex eq
+
+@need 1250
@item string<
@itemx string-lessp
@itemx string=
buffers. Later, we will study other functions.
@menu
-* Finding More::
-* simplified-beginning-of-buffer::
-* mark-whole-buffer::
-* append-to-buffer::
-* Buffer Related Review::
+* Finding More:: How to find more information.
+* simplified-beginning-of-buffer:: Shows @code{goto-char},
+ @code{point-min}, and @code{push-mark}.
+* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
+* append-to-buffer:: Uses @code{save-excursion} and
+ @code{insert-buffer-substring}.
+* Buffer Related Review:: Review.
* Buffer Exercises::
@end menu
@menu
* mark-whole-buffer overview::
-* Body of mark-whole-buffer::
+* Body of mark-whole-buffer:: Only three lines of code.
@end menu
@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
@menu
* append-to-buffer overview::
-* append interactive::
-* append-to-buffer body::
-* append save-excursion::
+* append interactive:: A two part interactive expression.
+* append-to-buffer body:: Incorporates a @code{let} expression.
+* append save-excursion:: How the @code{save-excursion} works.
@end menu
@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
to which the name refers.
@menu
-* copy-to-buffer::
-* insert-buffer::
-* beginning-of-buffer::
+* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
+* insert-buffer:: Read-only, and with @code{or}.
+* beginning-of-buffer:: Shows @code{goto-char},
+ @code{point-min}, and @code{push-mark}.
* Second Buffer Related Review::
* optional Exercise::
@end menu
@menu
* insert-buffer code::
-* insert-buffer interactive::
-* insert-buffer body::
-* if & or::
-* Insert or::
-* Insert let::
-* New insert-buffer ::
+* insert-buffer interactive:: When you can read, but not write.
+* insert-buffer body:: The body has an @code{or} and a @code{let}.
+* if & or:: Using an @code{if} instead of an @code{or}.
+* Insert or:: How the @code{or} expression works.
+* Insert let:: Two @code{save-excursion} expressions.
+* New insert-buffer::
@end menu
@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
buffer:@: }.
@menu
-* Read-only buffer::
-* b for interactive::
+* Read-only buffer:: When a buffer cannot be modified.
+* b for interactive:: An existing buffer or else its name.
@end menu
@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
(or (holding-on-to-guest) (find-and-take-arm-of-guest))
@end smallexample
-@node Insert let, New insert-buffer , Insert or, insert-buffer
+@node Insert let, New insert-buffer, Insert or, insert-buffer
@comment node-name, next, previous, up
@subsection The @code{let} Expression in @code{insert-buffer}
use @code{or}. All these functions are building blocks that we will
find and use again and again.
-@node New insert-buffer , , Insert let, insert-buffer
+@node New insert-buffer, , Insert let, insert-buffer
@comment node-name, next, previous, up
@subsection New Body for @code{insert-buffer}
@findex insert-buffer, new version body
@menu
* Optional Arguments::
-* beginning-of-buffer opt arg::
+* beginning-of-buffer opt arg:: Example with optional argument.
* beginning-of-buffer complete::
@end menu
@end smallexample
The true-or-false-test of this inner @code{if} expression checks the
-size of the buffer. The reason for this is that the old Version 18
-Emacs used numbers that are no bigger than eight million or so
-and in the computation that followed, the programmer feared that Emacs
-might try to use over-large numbers if the buffer were large. The
-term `overflow', mentioned in the comment, means numbers that are over
-large. 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.
+size of the buffer. The reason for this is that the old version 18
+Emacs used numbers that are no bigger than eight million or so and in
+the computation that followed, the programmer feared that Emacs might
+try to use over-large numbers if the buffer were large. The term
+`overflow', mentioned in the comment, means numbers that are over
+large. More recent versions of Emacs use larger numbers, but this
+code has not been touched, if only because people now look at buffers
+that are far, far larger than ever before.
There are two cases: if the buffer is large and if it is not.
novices.
@menu
-* Narrowing advantages::
-* save-restriction::
-* what-line::
+* Narrowing advantages:: The advantages of narrowing
+* save-restriction:: The @code{save-restriction} special form.
+* what-line:: The number of the line that point is on.
* narrow Exercise::
@end menu
namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
@menu
-* Strange Names::
-* car & cdr::
-* cons::
-* nthcdr::
+* Strange Names:: An historical aside: why the strange names?
+* car & cdr:: Functions for extracting part of a list.
+* cons:: Constructing a list.
+* nthcdr:: Calling @code{cdr} repeatedly.
* nth::
-* setcar::
-* setcdr::
+* setcar:: Changing the first element of a list.
+* setcdr:: Changing the rest of a list.
* cons Exercise::
@end menu
@menu
* Build a list::
-* length::
+* length:: How to find the length of a list.
@end menu
@node Build a list, length, cons, cons
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::
+* Storing Text:: Text is stored in a list.
+* zap-to-char:: Cutting out text up to a character.
+* kill-region:: Cutting text out of a region.
+* copy-region-as-kill:: A definition for copying text.
+* Digression into C:: Minor note on C programming language macros.
+* defvar:: How to give a variable an initial value.
* cons & search-fwd Review::
* search Exercises::
@end menu
But first, let us look at the interactive @code{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::
+* Complete zap-to-char:: The complete implementation.
+* zap-to-char interactive:: A three part interactive expression.
+* zap-to-char body:: A short overview.
+* search-forward:: How to search for a string.
+* progn:: The @code{progn} special form.
+* Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
@end menu
@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
contains the code that is called in the event of an error.
@menu
-* Complete kill-region::
-* condition-case::
+* Complete kill-region:: The function definition.
+* condition-case:: Dealing with a problem.
* Lisp macro::
@end menu
the function copies the text into a separate entry in the kill ring.
@menu
-* Complete copy-region-as-kill::
-* copy-region-as-kill body::
+* Complete copy-region-as-kill:: The complete function definition.
+* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
@end menu
@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
@menu
* Lists diagrammed::
-* Symbols as Chest::
+* Symbols as Chest:: Exploring a powerful metaphor.
* List Exercise::
@end menu
@menu
* Kill Ring Overview::
-* kill-ring-yank-pointer::
-* yank nthcdr Exercises::
+* kill-ring-yank-pointer:: The kill ring is a list.
+* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
@end menu
@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
15 and 30 times their default value.}.
@menu
-* while::
+* while:: Causing a stretch of code to repeat.
* dolist dotimes::
-* Recursion::
+* Recursion:: Causing a function to call itself.
* Looping exercise::
@end menu
@end smallexample
@menu
-* Looping with while::
-* Loop Example::
-* print-elements-of-list::
-* Incrementing Loop::
-* Decrementing Loop::
+* Looping with while:: Repeat so long as test returns true.
+* Loop Example:: A @code{while} loop that uses a list.
+* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
+* Incrementing Loop:: A loop with an incrementing counter.
+* Incrementing Loop Details::
+* Decrementing Loop:: A loop with a decrementing counter.
@end menu
@node Looping with while, Loop Example, while, while
@code{while} loop, and since @code{while} loops always return
@code{nil}, a @code{nil} is printed after the last element of the list.
-@node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
+@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while
@comment node-name, next, previous, up
@subsection A Loop with an Incrementing Counter
have a counter---an expression that counts how many times the loop
repeats itself.
-The test can be an expression such as @code{(< count desired-number)}
-which returns @code{t} for true if the value of @code{count} is less
-than the @code{desired-number} of repetitions and @code{nil} for false if
-the value of @code{count} is equal to or is greater than the
-@code{desired-number}. The expression that increments the count can be
-a simple @code{setq} such as @code{(setq count (1+ count))}, where
+@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while
+@ifnottex
+@unnumberedsubsec Details of an Incrementing Loop
+@end ifnottex
+
+The test for a loop with an incrementing counter can be an expression
+such as @code{(< count desired-number)} which returns @code{t} for
+true if the value of @code{count} is less than the
+@code{desired-number} of repetitions and @code{nil} for false if the
+value of @code{count} is equal to or is greater than the
+@code{desired-number}. The expression that increments the count can
+be a simple @code{setq} such as @code{(setq count (1+ count))}, where
@code{1+} is a built-in function in Emacs Lisp that adds 1 to its
-argument. (The expression @w{@code{(1+ count)}} has the same result as
-@w{@code{(+ count 1)}}, but is easier for a human to read.)
+argument. (The expression @w{@code{(1+ count)}} has the same result
+as @w{@code{(+ count 1)}}, but is easier for a human to read.)
@need 1250
The template for a @code{while} loop controlled by an incrementing
is set to 1.
@menu
-* Incrementing Example::
-* Inc Example parts::
-* Inc Example altogether::
+* Incrementing Example:: Counting pebbles in a triangle.
+* Inc Example parts:: The parts of the function definition.
+* Inc Example altogether:: Putting the function definition together.
@end menu
-@node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
+@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
@unnumberedsubsubsec Example with incrementing counter
Suppose you are playing on the beach and decide to make a triangle of
complex loop the repetitive action might not be so simple, but it will
be simpler than doing everything all at once.
-@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
+@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details
@unnumberedsubsubsec The parts of the function definition
The preceding analysis gives us the bones of our function definition:
(setq row-number (1+ row-number))
@end smallexample
-@node Inc Example altogether, , Inc Example parts, Incrementing Loop
+@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details
@unnumberedsubsubsec Putting the function definition together
We have created the parts for the function definition; now we need to
The sum of the first four numbers is 10 and the sum of the first seven
numbers is 28.
-@node Decrementing Loop, , Incrementing Loop, while
+@node Decrementing Loop, , Incrementing Loop Details, while
@comment node-name, next, previous, up
@subsection Loop with a Decrementing Counter
@end smallexample
@menu
-* Decrementing Example::
-* Dec Example parts::
-* Dec Example altogether::
+* Decrementing Example:: More pebbles on the beach.
+* Dec Example parts:: The parts of the function definition.
+* Dec Example altogether:: Putting the function definition together.
@end menu
@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
arguments that the final instance will stop.
@menu
-* Building Robots::
-* Recursive Definition Parts::
-* Recursion with list::
+* 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::
-* No Deferment::
+* Recursive Patterns:: Often used templates.
+* No Deferment:: Don't store up work ...
* No deferment solution::
@end menu
introduces several new features.
@menu
-* sentence-end::
-* re-search-forward::
-* forward-sentence::
-* forward-paragraph::
-* etags::
+* sentence-end:: The regular expression for @code{sentence-end}.
+* re-search-forward:: Very similar to @code{search-forward}.
+* forward-sentence:: A straightforward example of regexp search.
+* forward-paragraph:: A somewhat complex example.
+* etags:: How to create your own @file{TAGS} table.
* Regexp Review::
* re-search Exercises::
@end menu
@menu
* Complete forward-sentence::
-* fwd-sentence while loops::
-* fwd-sentence re-search::
+* fwd-sentence while loops:: Two @code{while} loops.
+* fwd-sentence re-search:: A regular expression search.
@end menu
@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
This is an added complication.
@menu
-* forward-paragraph in brief::
-* fwd-para let::
-* fwd-para while::
+* forward-paragraph in brief:: Key parts of the function definition.
+* fwd-para let:: The @code{let*} expression.
+* fwd-para while:: The forward motion @code{while} loop.
@end menu
@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
@menu
* Why Count Words::
-* count-words-region::
-* recursive-count-words::
+* count-words-region:: Use a regexp, but find a problem.
+* recursive-count-words:: Start with case of no words in region.
* Counting Exercise::
@end menu
or to a @code{while} loop.
@menu
-* Design count-words-region::
-* Whitespace Bug::
+* Design count-words-region:: The definition using a @code{while} loop.
+* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
@end menu
@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
@menu
* Divide and Conquer::
-* Words and Symbols::
-* Syntax::
-* count-words-in-defun::
-* Several defuns::
-* Find a File::
-* lengths-list-file::
-* Several files::
-* Several files recursively::
-* Prepare the data::
+* Words and Symbols:: What to count?
+* Syntax:: What constitutes a word or symbol?
+* count-words-in-defun:: Very like @code{count-words}.
+* Several defuns:: Counting several defuns in a file.
+* Find a File:: Do you want to look at a file?
+* lengths-list-file:: A list of the lengths of many definitions.
+* Several files:: Counting in definitions in different files.
+* Several files recursively:: Recursively counting in different files.
+* Prepare the data:: Prepare the data for display in a graph.
@end menu
@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
either a @code{while} loop or recursion.
@menu
-* lengths-list-many-files::
-* append::
+* lengths-list-many-files:: Return a list of the lengths of defuns.
+* append:: Attach one list to another.
@end menu
@node lengths-list-many-files, append, Several files, Several files
the @file{*scratch*} buffer, edit them, and then evaluate them.
The results are shown after the @samp{@result{}}. (These results are
-for files from Emacs Version 22.1.1; files from other versions of
+for files from Emacs version 22.1.1; files from other versions of
Emacs may produce different results.)
@c !!! 22.1.1 lisp sources location here
of defuns within each range of lengths, and produce a list of those
numbers.
+@menu
+* Data for Display in Detail::
+* Sorting:: Sorting lists.
+* Files List:: Making a list of files.
+* Counting function definitions::
+@end menu
+
+@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
+@ifnottex
+@unnumberedsubsec The Data for Display in Detail
+@end ifnottex
+
Based on what we have done before, we can readily foresee that it
should not be too hard to write a function that `@sc{cdr}s' down the
lengths' list, looks at each element, determines which length range it
number, and thereby determine the largest and smallest length range
that we will need.
-@menu
-* Sorting::
-* Files List::
-* Counting function definitions::
-@end menu
-
-@node Sorting, Files List, Prepare the data, Prepare the data
+@node Sorting, Files List, Data for Display in Detail, Prepare the data
@subsection Sorting Lists
@findex sort
@menu
* Columns of a graph::
-* graph-body-print::
+* graph-body-print:: How to print the body of a graph.
* recursive-graph-body-print::
* Printed Axes::
* Line Graph Exercise::
@menu
* Default Configuration::
-* Site-wide Init::
-* defcustom::
-* Beginning a .emacs File::
-* Text and Auto-fill::
-* Mail Aliases::
-* Indent Tabs Mode::
-* Keybindings::
-* Keymaps::
-* Loading Files::
-* Autoload::
-* Simple Extension::
-* X11 Colors::
+* Site-wide Init:: You can write site-wide init files.
+* defcustom:: Emacs will write code for you.
+* Beginning a .emacs File:: How to write a @code{.emacs file}.
+* Text and Auto-fill:: Automatically wrap lines.
+* Mail Aliases:: Use abbreviations for email addresses.
+* Indent Tabs Mode:: Don't use tabs with @TeX{}
+* Keybindings:: Create some personal keybindings.
+* Keymaps:: More about key binding.
+* Loading Files:: Load (i.e., evaluate) files automatically.
+* Autoload:: Make functions available.
+* Simple Extension:: Define a function; bind it to a key.
+* X11 Colors:: Colors in X.
* Miscellaneous::
-* Mode Line::
+* Mode Line:: How to customize your mode line.
@end menu
@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
load that function's file with a @code{load} expression in your
@file{.emacs} file.
-In my @file{.emacs} file for Emacs version 22, I load 14 libraries
-that contain functions that would otherwise be autoloaded. (Actually,
-it would have been better to include these files in my `dumped' Emacs,
-but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU
-Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more
-about dumping.)
+In my @file{.emacs} file, I load 14 libraries that contain functions
+that would otherwise be autoloaded. (Actually, it would have been
+better to include these files in my `dumped' Emacs, but I forgot.
+@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
+Reference Manual}, and the @file{INSTALL} file for more about
+dumping.)
You may also want to include autoloaded expressions in your @file{.emacs}
file. @code{autoload} is a built-in function that takes up to five
@end group
@end smallexample
+@need 1250
+Alternatively, since @code{blink-cursor-mode} has existed since Emacs
+version 21 and is likely to continue, you could write
+
+@smallexample
+@group
+(when (>= emacs-major-version 21)
+ (blink-cursor-mode 0)
+@end group
+@end smallexample
+
+@noindent
+and add other expressions, too.
+
+
@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
@section X11 Colors
In this chapter, I will walk through a short example of each.
@menu
-* debug::
-* debug-on-entry::
-* debug-on-quit::
-* edebug::
+* debug:: How to use the built-in debugger.
+* debug-on-entry:: Start debugging when you call a function.
+* debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
+* edebug:: How to use Edebug, a source level debugger.
* Debugging Exercises::
@end menu
both the @code{yank} and the @code{yank-pop} commands, but first,
consider the workings of the kill ring.
+@menu
+* What the Kill Ring Does::
+* current-kill::
+* yank:: Paste a copy of a clipped element.
+* yank-pop:: Insert element pointed to.
+* ring file::
+@end menu
+
+@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
+@ifnottex
+@unnumberedsec What the Kill Ring Does
+@end ifnottex
+
@need 1250
The kill ring has a default maximum length of sixty items; this number
is too large for an explanation. Instead, set it to four. Please
(setq kill-ring-max old-kill-ring-max)
@end smallexample
-@menu
-* current-kill::
-* yank::
-* yank-pop::
-* ring file::
-@end menu
-
-@node current-kill, yank, Kill Ring, Kill Ring
+@node current-kill, yank, What the Kill Ring Does, Kill Ring
@comment node-name, next, previous, up
@appendixsec The @code{current-kill} Function
@findex current-kill
@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
and @code{kill-region}.)
+@menu
+* Code for current-kill::
+* Understanding current-kill::
+@end menu
+
+@node Code for current-kill, Understanding current-kill, current-kill, current-kill
+@ifnottex
+@unnumberedsubsec The code for @code{current-kill}
+@end ifnottex
+
+
@need 1500
The @code{current-kill} function is used by @code{yank} and by
@code{yank-pop}. Here is the code for @code{current-kill}:
(setq kill-ring-yank-pointer kill-ring)
@end smallexample
-@menu
-* Understanding current-kill::
-@end menu
-
-@node Understanding current-kill, , current-kill, current-kill
+@node Understanding current-kill, , Code for current-kill, current-kill
@ifnottex
@unnumberedsubsec @code{current-kill} in Outline
@end ifnottex
This function takes two arguments, one of which is optional. It has a
documentation string. It is @emph{not} interactive.
+@menu
+* Body of current-kill::
+* Digression concerning error:: How to mislead humans, but not computers.
+* Determining the Element::
+@end menu
+
+@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec The Body of @code{current-kill}
+@end ifnottex
+
The body of the function definition is a @code{let} expression, which
itself has a body as well as a @var{varlist}.
list. Finally, another expression returns the first element of the
list even if the @code{do-not-move} argument is true.
-@menu
-* Digression concerning error::
-* Determining the Element ::
-@end menu
-
-@node Digression concerning error, Determining the Element , Understanding current-kill, Understanding current-kill
+@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
@ifnottex
@unnumberedsubsubsec Digression about the word `error'
@end ifnottex
takes the same steps as it does when there is an `error', a term such as
`cancel' would have a clearer connotation.
-@node Determining the Element , , Digression concerning error, Understanding current-kill
+@node Determining the Element, , Digression concerning error, Understanding current-kill
@ifnottex
@unnumberedsubsubsec Determining the Element
@end ifnottex
@menu
* Labelled Example::
-* print-graph Varlist::
-* print-Y-axis::
-* print-X-axis::
-* Print Whole Graph::
+* print-graph Varlist:: @code{let} expression in @code{print-graph}.
+* print-Y-axis:: Print a label for the vertical axis.
+* print-X-axis:: Print a horizontal label.
+* Print Whole Graph:: The function to print a complete graph.
@end menu
@node Labelled Example, print-graph Varlist, Full Graph, Full Graph
The function should be passed the height of the graph, and then should
construct and insert the appropriate numbers and marks.
+@menu
+* print-Y-axis in Detail::
+* Height of label:: What height for the Y axis?
+* Compute a Remainder:: How to compute the remainder of a division.
+* Y Axis Element:: Construct a line for the Y axis.
+* Y-axis-column:: Generate a list of Y axis labels.
+* print-Y-axis Penultimate:: A not quite final version.
+@end menu
+
+@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
+@ifnottex
+@unnumberedsubsec The @code{print-Y-axis} Function in Detail
+@end ifnottex
+
It is easy enough to see in the figure what the Y axis label should
look like; but to say in words, and then to write a function
definition to do the job is another matter. It is not quite true to
the fifth line from the bottom and on every line that is a multiple of
five.
-@menu
-* Height of label::
-* Compute a Remainder::
-* Y Axis Element::
-* Y-axis-column::
-* print-Y-axis Penultimate::
-@end menu
-
-@node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
+@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis
@ifnottex
@unnumberedsubsec What height should the label be?
@end ifnottex
graph without changing the ways the graph is labelled.
@menu
-* Similarities differences::
-* X Axis Tic Marks::
+* Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
+* X Axis Tic Marks:: Create tic marks for the horizontal axis.
@end menu
@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
@end smallexample
@menu
-* The final version::
-* Test print-graph::
-* Graphing words in defuns::
-* lambda::
-* mapcar::
-* Another Bug::
-* Final printed graph::
+* The final version:: A few changes.
+* Test print-graph:: Run a short test.
+* Graphing words in defuns:: Executing the final code.
+* lambda:: How to write an anonymous function.
+* mapcar:: Apply a function to elements of a list.
+* Another Bug:: Yet another bug @dots{} most insidious.
+* Final printed graph:: The graph itself!
@end menu
@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph