-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/eintr
+@c setfilename emacs-lisp-intro.info
@c sethtmlfilename emacs-lisp-intro.html
@settitle Programming in Emacs Lisp
@syncodeindex vr cp
@c set for smallbook, which works for all sizes
@c of paper, and with Postscript figures >>>>
@smallbook
-@clear largebook
+@clear largebook
@set print-postscript-figures
@c set largebook
@c clear print-postscript-figures
@comment %**end of header
-@set edition-number 2.07
-@set update-date 2002 Aug 23
+@set edition-number 3.07
+@set update-date 9 November 2006
@ignore
## Summary of shell commands to create various output formats:
+ pushd /usr/local/src/emacs/lispintro/
+ ## pushd /u/intro/
+
## Info output
- makeinfo --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 "/usr/local/src/emacs/info/eintr"))
## DVI output
texi2dvi emacs-lisp-intro.texi
+ ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
+
## HTML output
makeinfo --html --no-split --verbose emacs-lisp-intro.texi
+ ## galeon emacs-lisp-intro.html
+
## Plain text output
makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
--verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
- ## DocBook output
+ popd
+
+# as user `root'
+# insert thumbdrive
+ mtusb # mount -v -t ext3 /dev/sda /mnt
+ cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
+ umtusb # umount -v /mnt
+# remove thumbdrive
+
+ ## Other shell commands
+
+ pushd /usr/local/src/emacs/lispintro/
+ ## pushd /u/intro/
+
+ ## PDF
+ texi2dvi --pdf emacs-lisp-intro.texi
+ # xpdf emacs-lisp-intro.pdf &
+
+ ## DocBook -- note file extension
makeinfo --docbook --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+ --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
- ## XML output
+ ## XML with a Texinfo DTD -- note file extension
makeinfo --xml --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+ --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
+
+ ## PostScript (needs DVI)
+ # gv emacs-lisp-intro.ps &
+ # Create DVI if we lack it
+ # texi2dvi emacs-lisp-intro.texi
+ dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
+
+ ## RTF (needs HTML)
+ # Use OpenOffice to view RTF
+ # Create HTML if we lack it
+ # makeinfo --no-split --html emacs-lisp-intro.texi
+ /usr/local/src/html2rtf.pl emacs-lisp-intro.html
+
+ ## LaTeX (needs RTF)
+ /usr/bin/rtf2latex emacs-lisp-intro.rtf
+
+ popd
@end ignore
@c Your site may require editing changes to print PostScript; in this
@c case, search for `print-postscript-figures' and make appropriate changes.
-
@c ================ How to Create an Info file ================
@c If you have `makeinfo' installed, run the following command
@c 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 ================
@c For all sized formats: print within-book cross
@c reference with ``...'' rather than [...]
+
+@c This works with the texinfo.tex file, version 2003-05-04.08,
+@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
+
@tex
-% Need following so comma appears after section numbers.
-\global\def\Ysectionnumberandtype{%
-\ifnum\secno=0 \putwordChapter\xreftie\the\chapno, \space %
-\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno, \space %
-\else \ifnum \subsubsecno=0 %
-\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno, \space %
-\else %
-\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno, \space%
-\fi \fi \fi }
-
-\global\def\Yappendixletterandtype{%
-\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}, \space%
-\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno, \space %
-\else \ifnum \subsubsecno=0 %
-\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno, \space %
-\else %
-\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno, \space %
-\fi \fi \fi }
-
-\global\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
- \def\printedmanual{\ignorespaces #5}%
- \def\printednodename{\ignorespaces #3}%
- \setbox1=\hbox{\printedmanual}%
- \setbox0=\hbox{\printednodename}%
- \ifdim \wd0 = 0pt
- % No printed node name was explicitly given.
- \ifx\SETxref-automatic-section-title\relax %
- % Use the actual chapter/section title appear inside
- % the square brackets. Use the real section title if we have it.
- \ifdim \wd1>0pt%
- % It is in another manual, so we don't have it.
- \def\printednodename{\ignorespaces #1}%
- \else
- \ifhavexrefs
- % We know the real title if we have the xref values.
- \def\printednodename{\refx{#1-title}}%
- \else
- % Otherwise just copy the Info node name.
- \def\printednodename{\ignorespaces #1}%
- \fi%
- \fi
- \def\printednodename{#1-title}%
- \else
- % Use the node name inside the square brackets.
- \def\printednodename{\ignorespaces #1}%
- \fi
- \fi
- %
- % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
- % insert empty discretionaries after hyphens, which means that it will
- % not find a line break at a hyphen in a node names. Since some manuals
- % are best written with fairly long node names, containing hyphens, this
- % is a loss. Therefore, we give the text of the node name again, so it
- % is as if TeX is seeing it for the first time.
- \ifdim \wd1 > 0pt
- \putwordsection{} ``\printednodename'' in \cite{\printedmanual}%
- \else
- % _ (for example) has to be the character _ for the purposes of the
- % control sequence corresponding to the node, but it has to expand
- % into the usual \leavevmode...\vrule stuff for purposes of
- % printing. So we \turnoffactive for the \refx-snt, back on for the
- % printing, back off for the \refx-pg.
- {\turnoffactive \refx{#1-snt}{}}%
-% \space [\printednodename],\space % <= original
-% \putwordsection{} ``\printednodename'',\space
- ``\printednodename'',\space
- \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
- \fi
-\endgroup}
+\if \xrefprintnodename
+ \global\def\xrefprintnodename#1{\unskip, ``#1''}
+ \else
+ \global\def\xrefprintnodename#1{ ``#1''}
+\fi
+% \global\def\xrefprintnodename#1{, ``#1''}
@end tex
@c ----------------------------------------------------
@dircategory Emacs
@direntry
* Emacs Lisp Intro: (eintr).
- A simple introduction to Emacs Lisp programming.
+ A simple introduction to Emacs Lisp programming.
@end direntry
@copying
-This is an introduction to @cite{Programming in Emacs Lisp}, for
+This is an @cite{Introduction to Programming in Emacs Lisp}, for
people who are not programmers.
-
+@sp 1
Edition @value{edition-number}, @value{update-date}
+@sp 1
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
+ 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@sp 1
-Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc.
-@sp 2
+@iftex
+Published by the:@*
+
+GNU Press, @hfill @uref{http://www.gnupress.org}@*
+a division of the @hfill General: @email{press@@gnu.org}@*
+Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
+51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
+Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
+@end iftex
+
+@ifnottex
+Published by the:
-Published by the Free Software Foundation, Inc.@*
-59 Temple Place, Suite 330@*
-Boston, MA 02111-1307 USA@*
+@example
+GNU Press, Website: http://www.gnupress.org
+a division of the General: press@@gnu.org
+Free Software Foundation, Inc. Orders: sales@@gnu.org
+51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
+Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
+@end example
+@end ifnottex
+@sp 1
@c Printed copies are available for $30 each.@*
ISBN 1-882114-43-4
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+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
@sp 2
@center @titlefont{Programming in Emacs Lisp}
@sp 2
-@center Second Edition
+@center Revised Third Edition
@sp 4
@center by Robert J. Chassell
@end iftex
@ifnothtml
-
-@c Keep T.O.C. short by tightening up.
+@c Keep T.O.C. short by tightening up for largebook
@ifset largebook
@tex
\global\parskip 2pt plus 1pt
\global\advance\baselineskip by -1pt
@end tex
@end ifset
+@end ifnothtml
@shortcontents
@contents
-@ifset largebook
-@tex
-\global\parskip 6pt plus 1pt
-\global\advance\baselineskip by 1pt
-@end tex
-@end ifset
+@ifnottex
+@node Top, Preface, (dir), (dir)
+@top An Introduction to Programming in Emacs Lisp
-@end ifnothtml
+@insertcopying
+
+This master menu first lists each chapter and index; then it lists
+every node in every chapter.
+@end ifnottex
@c >>>> Set pageno appropriately <<<<
@c right handed page after the Table of Contents; hence the following
@c setting must be for an odd negative number.
-@c if largebook, there are 8 pages in Table of Contents
-@ifset largebook
-@iftex
-@pageno = -9
-@end iftex
-@end ifset
-
-@c if smallbook, there are 10 pages in Table of Contents
-@ifclear largebook
@iftex
-@pageno = -11
+@global@pageno = -11
@end iftex
-@end ifclear
-
-@ifnottex
-@node Top, Preface, (dir), (dir)
-@top An Introduction to Programming in Emacs Lisp
-
-@insertcopying
-
-This master menu first lists each chapter and index; then it lists
-every node in every chapter.
-@end ifnottex
@menu
* Preface:: What to look for.
* 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::
* Numbers Lists:: List have numbers, other lists, in them.
* Lisp Atoms:: Elemental entities.
-* Whitespace in Lists:: Formating lists to be readable.
+* Whitespace in Lists:: Formatting lists to be readable.
* Typing Lists:: How GNU Emacs helps you type lists.
The Lisp Interpreter
Evaluation
+* How the Interpreter Acts:: Returns and Side Effects...
* Evaluating Inner Lists:: Lists within lists...
Variables
Setting the Value of a Variable
-* Using set:: Setting values.
-* Using setq:: Setting a quoted value.
-* Counting:: Using @code{setq} to count.
+* Using set:: Setting values.
+* Using setq:: Setting a quoted value.
+* Counting:: Using @code{setq} to count.
Practicing Evaluation
-* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
- causes evaluation.
-* Buffer Names:: Buffers and files are different.
-* Getting Buffers:: Getting a buffer itself, not merely its name.
-* Switching Buffers:: How to change to another buffer.
-* Buffer Size & Locations:: Where point is located and the size of
- the buffer.
+* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
+ causes evaluation.
+* Buffer Names:: Buffers and files are different.
+* Getting Buffers:: Getting a buffer itself, not merely its name.
+* Switching Buffers:: How to change to another buffer.
+* Buffer Size & Locations:: Where point is located and the size of
+ the buffer.
* Evaluation Exercise::
How To Write Function Definitions
* Primitive Functions::
-* defun:: The @code{defun} special form.
-* Install:: Install a function definition.
-* Interactive:: Making a function interactive.
-* Interactive Options:: Different options for @code{interactive}.
-* Permanent Installation:: Installing code permanently.
-* let:: Creating and initializing local variables.
-* if:: What if?
-* else:: If--then--else expressions.
-* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* 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::
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}
* if & or:: Using an @code{if} instead of an @code{or}.
* Insert or:: How the @code{or} expression works.
* Insert let:: Two @code{save-excursion} expressions.
+* New insert-buffer::
The Interactive Expression in @code{insert-buffer}
* 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.
-* copy-region-as-kill:: A definition for copying text.
* cons & search-fwd Review::
* search Exercises::
* Complete kill-region:: The function definition.
* condition-case:: Dealing with a problem.
-* delete-and-extract-region:: Doing the work.
-
-Initializing a Variable with @code{defvar}
-
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
+* Lisp macro::
@code{copy-region-as-kill}
* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
+* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
The Body of @code{copy-region-as-kill}
* kill-append function::
* kill-new function::
+Initializing a Variable with @code{defvar}
+
+* See variable current value::
+* defvar and asterisk::
+
How Lists are Implemented
* Lists diagrammed::
Yanking Text Back
-* Kill Ring Overview:: The kill ring is a list.
-* kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
-* yank nthcdr Exercises::
+* Kill Ring Overview::
+* kill-ring-yank-pointer:: The kill ring is a list.
+* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
Loops and Recursion
* 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.
* 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.
-* fwd-para between paragraphs:: Movement between paragraphs.
-* fwd-para within paragraph:: Movement within paragraphs.
-* fwd-para no fill prefix:: When there is no fill prefix.
-* fwd-para with fill prefix:: When there is a fill prefix.
-* fwd-para summary:: Summary of @code{forward-paragraph} code.
Counting: Repetition and Regexps
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::
* 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.
+* X11 Colors:: Colors in X.
* Miscellaneous::
* Mode Line:: How to customize your mode line.
Handling the Kill Ring
-* rotate-yank-pointer:: Move a pointer along a list and around.
+* What the Kill Ring Does::
+* current-kill::
* yank:: Paste a copy of a clipped element.
-* yank-pop:: Insert first element pointed to.
+* yank-pop:: Insert element pointed to.
+* ring file::
-The @code{rotate-yank-pointer} Function
+The @code{current-kill} Function
-* Understanding rotate-yk-ptr::
-* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
+* Understanding current-kill::
-The Body of @code{rotate-yank-pointer}
+@code{current-kill} in Outline
+* Body of current-kill::
* Digression concerning error:: How to mislead humans, but not computers.
-* rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
-* Remainder Function:: The remainder, @code{%}, function.
-* rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
-* kill-rng-yk-ptr last elt:: Pointing to the last element.
-
-@code{yank}
-
-* rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
-* rotate-yk-ptr negative arg:: Pass a negative argument.
+* Determining the Element::
A Graph with Labelled Axes
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.
@headings off
@evenheading @thispage @| @| @thischapter
@oddheading @thissection @| @| @thispage
-@pageno = 1
+@global@pageno = 1
@end iftex
@node List Processing, Practicing Evaluation, Preface, Top
@chapter List Processing
To the untutored eye, Lisp is a strange programming language. In Lisp
-code there are parentheses everywhere. Some people even claim that the
-name stands for `Lots of Isolated Silly Parentheses'. But the claim is
-unwarranted. Lisp stands for LISt Processing, and the programming
-language handles @emph{lists} (and lists of lists) by putting them
-between parentheses. The parentheses mark the boundaries of the list.
-Sometimes a list is preceded by a single apostrophe or quotation mark,
-@samp{'}. Lists are the basis of Lisp.
+code there are parentheses everywhere. Some people even claim that
+the name stands for `Lots of Isolated Silly Parentheses'. But the
+claim is unwarranted. Lisp stands for LISt Processing, and the
+programming language handles @emph{lists} (and lists of lists) by
+putting them between parentheses. The parentheses mark the boundaries
+of the list. Sometimes a list is preceded by a single apostrophe or
+quotation mark, @samp{'}@footnote{The single apostrophe or quotation
+mark is an abbreviation for the function @code{quote}; you need not
+think about functions now; functions are defined in @ref{Making
+Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
@menu
* Lisp Lists:: What are lists?
@menu
* Numbers Lists:: List have numbers, other lists, in them.
* Lisp Atoms:: Elemental entities.
-* Whitespace in Lists:: Formating lists to be readable.
+* Whitespace in Lists:: Formatting lists to be readable.
* Typing Lists:: How GNU Emacs helps you type lists.
@end menu
using in the lists cannot be divided into any smaller parts and still
mean the same thing as part of a program; likewise with numbers and
single character symbols like @samp{+}. On the other hand, unlike an
-atom, a list can be split into parts. (@xref{car cdr & cons, ,
-@code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
+ancient atom, a list can be split into parts. (@xref{car cdr & cons,
+, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
In a list, atoms are separated from each other by whitespace. They can be
right next to a parenthesis.
@noindent
What you see depends on which version of Emacs you are running. GNU
-Emacs version 21 provides more information than version 20 and before.
+Emacs version 22 provides more information than version 20 and before.
First, the more recent result of generating an error; then the
earlier, version 20 result.
@need 1250
@noindent
-In GNU Emacs version 21, a @file{*Backtrace*} window will open up and
+In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
you will see the following in it:
@smallexample
of locating the definition or set of instructions. What we see is the
name through which the instructions can be found. Names of people
work the same way. I can be referred to as @samp{Bob}; however, I am
-not the letters @samp{B}, @samp{o}, @samp{b} but am the consciousness
-consistently associated with a particular life-form. The name is not
-me, but it can be used to refer to me.
+not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
+consciousness consistently associated with a particular life-form.
+The name is not me, but it can be used to refer to me.
In Lisp, one set of instructions can be attached to several names.
For example, the computer instructions for adding numbers can be
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:: Lists within 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
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-versa.
+function definition, and vice-verse.
@menu
* fill-column Example::
@need 1250
@noindent
-In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer
+In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
that says:
@smallexample
(Remember, to quit the debugger and make the debugger window go away,
type @kbd{q} in the @file{*Backtrace*} buffer.)
+@ignore
@need 800
In GNU Emacs 20 and before, you will produce an error message that says:
@end smallexample
@noindent
-(The message will go away away as soon as you move the cursor or type
+(The message will go away as soon as you move the cursor or type
another key.)
+@end ignore
@node Void Variable, , Void Function, Variables
@comment node-name, next, previous, up
@need 1500
@noindent
-In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that
+In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
says:
@smallexample
definition, the error message reported that the symbol's value as a
variable was void.
+@ignore
@need 800
In GNU Emacs version 20 and before, your error message will say:
@end example
@noindent
-The meaning is the same as in GNU Emacs 21.
+The meaning is the same as in GNU Emacs 22.
+@end ignore
@node Arguments, set & setq, Variables, List Processing
@comment node-name, next, previous, up
@code{+} must have values that are numbers, since @code{+} adds numbers.
Other functions use different kinds of data for their arguments.
+@need 1250
@findex concat
For example, the @code{concat} function links together or unites two or
more strings of text to produce a string. The arguments are strings.
@noindent
The value will be a number two more than what you get by evaluating
-@code{fill-column} alone. For me, this is 74, because the value of
+@code{fill-column} alone. For me, this is 74, because my value of
@code{fill-column} is 72.
As we have just seen, an argument can be a symbol that returns a value
@w{@code{"The "}} and @w{@code{" red foxes."}} and the list
@code{(number-to-string (+ 2 fill-column))}.
-@c For Emacs 21, need number-to-string
+@c For GNU Emacs 22, need number-to-string
@smallexample
(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
@end smallexample
could not carry out its addition.
@need 1250
-In GNU Emacs version 21, you will create and enter a
+In GNU Emacs version 22, you will create and enter a
@file{*Backtrace*} buffer that says:
@noindent
@need 1250
As usual, the error message tries to be helpful and makes sense after you
-learn how to read it.
+learn how to read it.@footnote{@code{(quote hello)} is an expansion of
+the abbreviation @code{'hello}.}
The first part of the error message is straightforward; it says
@samp{wrong type argument}. Next comes the mysterious jargon word
would have been a number, such as 37, rather than a symbol like
@code{hello}. But then you would not have got the error message.
+@ignore
@need 1250
In GNU Emacs version 20 and before, the echo area displays an error
message that says:
This says, in different words, the same as the top line of the
@file{*Backtrace*} buffer.
+@end ignore
@node message, , Wrong Type of Argument, Arguments
@comment node-name, next, previous, up
@smallexample
@group
(message "He saw %d %s"
- (- fill-column 34)
+ (- fill-column 32)
(concat "red "
(substring
"The quick brown foxes jumped." 16 21)
in place of the @samp{%d}; and the value returned by the expression
beginning with @code{concat} is inserted in place of the @samp{%s}.
-When I evaluate the expression, the message @code{"He saw 38 red
-foxes leaping."} appears in my echo area.
+When your fill column is 70 and you evaluate the expression, the
+message @code{"He saw 38 red foxes leaping."} appears in your echo
+area.
@node set & setq, Summary, Arguments, List Processing
@comment node-name, next, previous, up
work but also illustrate how arguments are passed.
@menu
-* Using set:: Setting values.
-* Using setq:: Setting a quoted value.
-* Counting:: Using @code{setq} to count.
+* 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
@noindent
The list @code{(rose violet daisy buttercup)} will appear in the echo
area. This is what is @emph{returned} by the @code{set} function. As a
-side effect, the symbol @code{flowers} is bound to the list ; that is,
+side effect, the symbol @code{flowers} is bound to the list; that is,
the symbol @code{flowers}, which can be viewed as a variable, is given
the list as its value. (This process, by the way, illustrates how a
side effect to the Lisp interpreter, setting the value, can be the
steepest. You have now climbed the most difficult part; what remains
becomes easier as you progress onwards.
+@need 1000
In summary,
@itemize @bullet
Then the instructions in the function definition are carried out.
@item
-A single-quote, @code{'}, tells the Lisp interpreter that it should
+A single quotation mark,
+@ifinfo
+'
+@end ifinfo
+@ifnotinfo
+@code{'}
+@end ifnotinfo
+, tells the Lisp interpreter that it should
return the following expression as written, and not evaluate it as it
would if the quote were not there.
buffer-related functions, to see how they were written.
@menu
-* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
- causes evaluation.
-* Buffer Names:: Buffers and files are different.
-* Getting Buffers:: Getting a buffer itself, not merely its name.
-* Switching Buffers:: How to change to another buffer.
-* Buffer Size & Locations:: Where point is located and the size of
- the buffer.
+* 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
each of the following expressions by positioning the cursor after it and
typing @kbd{C-x C-e}.
-@smallexample
+@example
@group
(buffer-name)
(buffer-file-name)
@end group
-@end smallexample
+@end example
@noindent
-When I do this, @file{"introduction.texinfo"} is the value returned by
-evaluating @code{(buffer-name)}, and
-@file{"/gnu/work/intro/introduction.texinfo"} is the value returned by
-evaluating @code{(buffer-file-name)}. The former is the name of the
-buffer and the latter is the name of the file. (In the expressions, the
-parentheses tell the Lisp interpreter to treat @code{buffer-name} and
-@code{buffer-file-name} as functions; without the parentheses, the
-interpreter would attempt to evaluate the symbols as variables.
-@xref{Variables}.)
+When I do this in Info, the value returned by evaluating
+@code{(buffer-name)} is @file{"*info*"}, and the value returned by
+evaluating @code{(buffer-file-name)} is @file{nil}.
+
+On the other hand, while I am writing this Introduction, the value
+returned by evaluating @code{(buffer-name)} is
+@file{"introduction.texinfo"}, and the value returned by evaluating
+@code{(buffer-file-name)} is
+@file{"/gnu/work/intro/introduction.texinfo"}.
+
+@cindex @code{nil}, history of word
+The former is the name of the buffer and the latter is the name of the
+file. In Info, the buffer name is @file{"*info*"}. Info does not
+point to any file, so the result of evaluating
+@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
+from the Latin word for `nothing'; in this case, it means that the
+buffer is not associated with any file. (In Lisp, @code{nil} is also
+used to mean `false' and is a synonym for the empty list, @code{()}.)
+
+When I am writing, the name of my buffer is
+@file{"introduction.texinfo"}. The name of the file to which it
+points is @file{"/gnu/work/intro/introduction.texinfo"}.
+
+(In the expressions, the parentheses tell the Lisp interpreter to
+treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
+functions; without the parentheses, the interpreter would attempt to
+evaluate the symbols as variables. @xref{Variables}.)
In spite of the distinction between files and buffers, you will often
-find that people refer to a file when they mean a buffer and vice-versa.
+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
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, when you start
-an Emacs session by typing the command @code{emacs} alone, without
-naming any files, Emacs will start with the @file{*scratch*} buffer on
-the screen. This buffer is not visiting any file. Similarly, a
+Not all buffers are associated with files. For example, a
+@file{*scratch*} buffer does not visit any file. Similarly, a
@file{*Help*} buffer is not associated with any file.
-@cindex @code{nil}, history of word
-If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)},
-position the cursor after it, and type @kbd{C-x C-e} to evaluate the
-expression, the name @code{"*scratch*"} is returned and will appear in
-the echo area. @code{"*scratch*"} is the name of the buffer. However,
-if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and
-evaluate that, @code{nil} will appear in the echo area. @code{nil} is
-from the Latin word for `nothing'; in this case, it means that the
-@file{*scratch*} buffer is not associated with any file. (In Lisp,
-@code{nil} is also used to mean `false' and is a synonym for the empty
-list, @code{()}.)
+In the old days, when you lacked a @file{~/.emacs} file and started an
+Emacs session by typing the command @code{emacs} alone, without naming
+any files, Emacs started with the @file{*scratch*} buffer visible.
+Nowadays, you will see a splash screen. You can follow one of the
+commands suggested on the splash screen, visit a file, or press the
+spacebar to reach the @file{*scratch*} buffer.
+
+If you switch to the @file{*scratch*} buffer, type
+@code{(buffer-name)}, position the cursor after it, and then type
+@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
+will be returned and will appear in the echo area. @code{"*scratch*"}
+is the name of the buffer. When you type @code{(buffer-file-name)} in
+the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
+in the echo area, just as it does when you evaluate
+@code{(buffer-file-name)} in Info.
Incidentally, if you are in the @file{*scratch*} buffer and want the
value returned by an expression to appear in the @file{*scratch*}
@end smallexample
@noindent
-If you evaluate the expression in the usual way, @file{#<buffer *info*>}
-appears in the echo area. The special format indicates that the
-buffer itself is being returned, rather than just its name.
+If you evaluate this expression in Info in Emacs in the usual way,
+@file{#<buffer *info*>} will appear in the echo area. The special
+format indicates that the buffer itself is being returned, rather than
+just its name.
Incidentally, while you can type a number or symbol into a program, you
cannot do that with the printed representation of a buffer: the only way
to get a buffer itself is with a function such as @code{current-buffer}.
A related function is @code{other-buffer}. This returns the most
-recently selected buffer other than the one you are in currently. If
-you have recently switched back and forth from the @file{*scratch*}
-buffer, @code{other-buffer} will return that buffer.
+recently selected buffer other than the one you are in currently, not
+a printed representation of its name. If you have recently switched
+back and forth from the @file{*scratch*} buffer, @code{other-buffer}
+will return that buffer.
@need 800
You can see this by evaluating the expression:
function. When you switched back and forth from Info to the
@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
-rather, to save typing, you probably typed just part of the name, such
-as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to
-expand to the full name; and then typed your @kbd{RET} key.} when
-prompted in the minibuffer for the name of the buffer to which you
-wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp
-interpreter to evaluate the interactive function
+rather, to save typing, you probably only typed @kbd{RET} if the
+default buffer was @file{*scratch*}, or if it was different, then you
+typed just part of the name, such as @code{*sc}, pressed your
+@kbd{TAB} key to cause it to expand to the full name, and then typed
+your @kbd{RET} key.} when prompted in the minibuffer for the name of
+the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
+b}, cause the Lisp interpreter to evaluate the interactive function
@code{switch-to-buffer}. As we said before, this is how Emacs works:
different keystrokes call or run different functions. For example,
@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
@noindent
For me, the value of point in this location is 66043, which means that
-there are 319 characters (including spaces) between the two expressions.
+there are 319 characters (including spaces) between the two
+expressions. (Doubtless, you will see different numbers, since I will
+have edited this since I first evaluated point.)
@cindex @samp{narrowing} defined
The function @code{point-min} is somewhat similar to @code{point}, but
@menu
* Primitive Functions::
-* defun:: The @code{defun} special form.
-* Install:: Install a function definition.
-* Interactive:: Making a function interactive.
-* Interactive Options:: Different options for @code{interactive}.
-* Permanent Installation:: Installing code permanently.
-* let:: Creating and initializing local variables.
-* if:: What if?
-* else:: If--then--else expressions.
-* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* 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
Emacs. To reload code automatically whenever you start Emacs, see
@ref{Permanent Installation, , Installing Code Permanently}.)
-
@menu
* Effect of installation::
* Change a defun:: How to change a function definition.
@unnumberedsubsec The effect of installation
@end ifnottex
-
You can see the effect of installing @code{multiply-by-seven} by
evaluating the following sample. Place the cursor after the following
expression and type @kbd{C-x C-e}. The number 21 will appear in the
@smallexample
@group
-multiply-by-seven:
+multiply-by-seven is a Lisp function.
+(multiply-by-seven NUMBER)
+
Multiply NUMBER by seven.
@end group
@end smallexample
@menu
* Interactive multiply-by-seven:: An overview.
-* multiply-by-seven in detail:: The interactive version.
+* multiply-by-seven in detail:: The interactive version.
@end menu
@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
subsequent elements of the list to the function @code{message}.
As we have seen, @code{message} is an Emacs Lisp function especially
-designed for sending a one line message to a user. (@xref{message, , The
-@code{message} function}.)
-In summary, the @code{message} function prints its first argument in the
-echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or
-@samp{%c}. When it sees one of these control sequences, the function
-looks to the second and subsequent arguments and prints the value of the
-argument in the location in the string where the control sequence is
-located.
+designed for sending a one line message to a user. (@xref{message, ,
+The @code{message} function}.) In summary, the @code{message}
+function prints its first argument in the echo area as is, except for
+occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
+which we have not mentioned). When it sees a control sequence, the
+function looks to the second or subsequent arguments and prints the
+value of the argument in the location in the string where the control
+sequence is located.
In the interactive @code{multiply-by-seven} function, the control string
is @samp{%d}, which requires a number, and the value returned by
@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
@need 1250
-For example, the character @samp{r} causes Emacs to pass the beginning
-and end of the region (the current values of point and mark) to the
-function as two separate arguments. It is used as follows:
+Consider the function @code{zap-to-char}. Its interactive expression
+is
@smallexample
-(interactive "r")
+(interactive "p\ncZap to char: ")
@end smallexample
-On the other hand, a @samp{B} tells Emacs to ask for the name of a
-buffer that will be passed to the function. When it sees a @samp{B},
-Emacs will ask for the name by prompting the user in the minibuffer,
-using a string that follows the @samp{B}, as in @code{"BAppend to
-buffer:@: "}. Not only will Emacs prompt for the name, but Emacs will
-complete the name if you type enough of it and press @key{TAB}.
+The first part of the argument to @code{interactive} is @samp{p}, with
+which you are already familiar. This argument tells Emacs to
+interpret a `prefix', as a number to be passed to the function. You
+can specify a prefix either by typing @kbd{C-u} followed by a number
+or by typing @key{META} followed by a number. The prefix is the
+number of specified characters. Thus, if your prefix is three and the
+specified character is @samp{x}, then you will delete all the text up
+to and including the third next @samp{x}. If you do not set a prefix,
+then you delete all the text up to and including the specified
+character, but no more.
-A function with two or more arguments can have information passed to
-each argument by adding parts to the string that follows
-@code{interactive}. When you do this, the information is passed to
-each argument in the same order it is specified in the
+The @samp{c} tells the function the name of the character to which to delete.
+
+More formally, a function with two or more arguments can have
+information passed to each argument by adding parts to the string that
+follows @code{interactive}. When you do this, the information is
+passed to each argument in the same order it is specified in the
@code{interactive} list. In the string, each part is separated from
the next part by a @samp{\n}, which is a newline. For example, you
-could follow @code{"BAppend to buffer:@: "} with a @samp{\n}) and an
-@samp{r}. This would cause Emacs to pass the values of point and mark
-to the function as well as prompt you for the buffer---three arguments
-in all.
+can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
+This causes Emacs to pass the value of the prefix argument (if there
+is one) and the character.
-In this case, the function definition would look like the following,
-where @code{buffer}, @code{start}, and @code{end} are the symbols to
-which @code{interactive} binds the buffer and the current values of the
-beginning and ending of the region:
+In this case, the function definition looks like the following, where
+@code{arg} and @code{char} are the symbols to which @code{interactive}
+binds the prefix argument and the specified character:
@smallexample
@group
-(defun @var{name-of-function} (buffer start end)
+(defun @var{name-of-function} (arg char)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive "p\ncZap to char: ")
@var{body-of-function}@dots{})
@end group
@end smallexample
@noindent
(The space after the colon in the prompt makes it look better when you
-are prompted. The @code{append-to-buffer} function looks exactly like
-this. @xref{append-to-buffer, , The Definition of
-@code{append-to-buffer}}.)
+are prompted. @xref{copy-to-buffer, , The Definition of
+@code{copy-to-buffer}}, for an example.)
-If a function does not have arguments, then @code{interactive} does not
+When a function does not take arguments, @code{interactive} does not
require any. Such a function contains the simple expression
@code{(interactive)}. The @code{mark-whole-buffer} function is like
this.
Alternatively, if the special letter-codes are not right for your
application, you can pass your own arguments to @code{interactive} as
-a list. @xref{interactive, , Using @code{Interactive}, elisp, The
-GNU Emacs Lisp Reference Manual}, for more information about this advanced
-technique.
+a list.
+
+@xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
+for an example. @xref{Using Interactive, , Using @code{Interactive},
+elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
+explanation about this technique.
@node Permanent Installation, let, Interactive Options, Writing Defuns
@comment node-name, next, previous, up
@xref{Loading Files, , Loading Files}.
@item
-On the other hand, if you have code that your whole site will use, it
-is usual to put it in a file called @file{site-init.el} that is loaded
-when Emacs is built. This makes the code available to everyone who
-uses your machine. (See the @file{INSTALL} file that is part of the
-Emacs distribution.)
+Thirdly, if you have code that your whole site will use, it is usual
+to put it in a file called @file{site-init.el} that is loaded when
+Emacs is built. This makes the code available to everyone who uses
+your machine. (See the @file{INSTALL} file that is part of the Emacs
+distribution.)
@end itemize
Finally, if you have code that everyone who uses Emacs may want, you
@end ifnottex
@cindex @samp{local variable} defined
+@cindex @samp{variable, local}, defined
The @code{let} special form prevents confusion. @code{let} creates a
name for a @dfn{local variable} that overshadows any use of the same
name outside the @code{let} expression. This is like understanding
The two variables are @code{zebra} and @code{tiger}. Each variable is
the first element of a two-element list and each value is the second
element of its two-element list. In the varlist, Emacs binds the
-variable @code{zebra} to the value @code{stripes}, and binds the
+variable @code{zebra} to the value @code{stripes}@footnote{According
+to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
+become impossibly dangerous as they grow older'' but the claim here is
+that they do not become fierce like a tiger. (1997, W. W. Norton and
+Co., ISBN 0-393-03894-2, page 171)}, and binds the
variable @code{tiger} to the value @code{fierce}. In this example,
both values are symbols preceded by a quote. The values could just as
well have been another list or a string. The body of the @code{let}
-follows after the list holding the variables. In this example, the body
-is a list that uses the @code{message} function to print a string in
-the echo area.
+follows after the list holding the variables. In this example, the
+body is a list that uses the @code{message} function to print a string
+in the echo area.
@need 1500
You may evaluate the example in the usual fashion, by placing the
false. When this happens, the second argument or then-part of the
overall @code{if} expression is @emph{not} evaluated, but the third or
else-part @emph{is} evaluated. You might think of this as the cloudy
-day alternative for the decision `if it is warm and sunny, then go to
+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
(Of course, if the @var{characteristic} were @code{ferocious}, the
message @code{"It's not fierce!"} would be printed; and it would be
misleading! When you write code, you need to take into account the
-possibility that some such argument will be tested by the @code{if} and
-write your program accordingly.)
+possibility that some such argument will be tested by the @code{if}
+and write your program accordingly.)
@node Truth & Falsehood, save-excursion, else, Writing Defuns
@comment node-name, next, previous, up
if the result of evaluating it is a value that is not @code{nil}. In
other words, the result of the test is considered true if the value
returned is a number such as 47, a string such as @code{"hello"}, or a
-symbol (other than @code{nil}) such as @code{flowers}, or a list, or
-even a buffer!
+symbol (other than @code{nil}) such as @code{flowers}, or a list (so
+long as it is not empty), or even a buffer!
@menu
* nil explained:: @code{nil} has two meanings.
In addition to recording the values of point and mark,
@code{save-excursion} keeps track of the current buffer, and restores
it, too. This means you can write code that will change the buffer and
-have @code{save-excursion} switch you back to the original buffer. This
-is how @code{save-excursion} is used in @code{append-to-buffer}.
+have @code{save-excursion} switch you back to the original buffer.
+This is how @code{save-excursion} is used in @code{append-to-buffer}.
(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
@node Template for save-excursion, , Point and mark, save-excursion
definition.
@need 1250
-For example:
+For example, in an early version of Emacs, the function definition was
+as follows. (It is slightly more complex now that it seeks the first
+non-whitespace character rather than the first visible character.)
@smallexample
@group
@end group
@end smallexample
+@ignore
+In GNU Emacs 22,
+
+(defun backward-to-indentation (&optional arg)
+ "Move backward ARG lines and position at first nonblank character."
+ (interactive "p")
+ (forward-line (- (or arg 1)))
+ (skip-chars-forward " \t"))
+
+(defun back-to-indentation ()
+ "Move point to the first non-whitespace character on this line."
+ (interactive)
+ (beginning-of-line 1)
+ (skip-syntax-forward " " (line-end-position))
+ ;; Move back over chars that have whitespace syntax but have the p flag.
+ (backward-prefix-chars))
+@end ignore
+
@item interactive
Declare to the interpreter that the function can be used
interactively. This special form may be followed by a string with one
prompt for information. Parts of the string are separated by
newlines, @samp{\n}.
+@need 1000
Common code characters are:
@table @code
@smallexample
@group
-(if (string-equal
- (number-to-string 21)
- (substring (emacs-version) 10 12))
- (message "This is version 21 Emacs")
- (message "This is not version 21 Emacs"))
+(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 second. In all cases, both arguments must be numbers or markers
(markers indicate positions in buffers).
+@need 800
+@item =
+The @code{=} function tests whether two arguments, both numbers or
+markers, are equal.
+
+@need 1250
+@item equal
+@itemx eq
+Test whether two objects are the same. @code{equal} uses one meaning
+of the word `same' and @code{eq} uses another: @code{equal} returns
+true if the two objects have a similar structure and contents, such as
+two copies of the same book. On the other hand, @code{eq}, returns
+true if both arguments are actually the same object.
+@findex equal
+@findex eq
+
+@need 1250
@item string<
@itemx string-lessp
@itemx string=
can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
arguments that follow the string. The argument used by @samp{%s} must
be a string or a symbol; the argument used by @samp{%d} must be a
-number. The argument used by @samp{%c} must be an ascii code number;
-it will be printed as the character with that @sc{ascii} code.
+number. The argument used by @samp{%c} must be an @sc{ascii} code
+number; it will be printed as the character with that @sc{ascii} code.
+(Various other %-sequences have not been mentioned.)
@item setq
@itemx set
then @key{RET}).
@cindex Find source of function
-In versions 20 and higher, when a function is written in Emacs Lisp,
-@code{describe-function} will also tell you the location of the
-function definition. If you move point over the file name and press
-the @key{RET} key, which is this case means @code{help-follow} rather
+@c In version 22, tells location both of C and of Emacs Lisp
+Also, @code{describe-function} will tell you the location of the
+function definition.
+
+Put point into the name of the file that contains the function and
+press the @key{RET} key. In this case, @key{RET} means
+@code{push-button} rather than `return' or `enter'. Emacs will take
+you directly to the function definition.
+
+@ignore
+Not In version 22
+
+If you move point over the file name and press
+the @key{RET} key, which in this case means @code{help-follow} rather
than `return' or `enter', Emacs will take you directly to the function
definition.
+@end ignore
More generally, if you want to see a function in its original source
file, you can use the @code{find-tags} function to jump to it.
Lisp, and C, and it works with non-programming text as well. For
example, @code{find-tags} will jump to the various nodes in the
Texinfo source file of this document.
-
The @code{find-tags} function depends on `tags tables' that record
the locations of the functions, variables, and other items to which
@code{find-tags} jumps.
-To use the @code{find-tags} command, type @kbd{M-.} (i.e., type the
-@key{META} key and the period key at the same time, or else type the
+To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
+period key while holding down the @key{META} key, or else type the
@key{ESC} key and then type the period key), and then, at the prompt,
type in the name of the function whose source code you want to see,
such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
@key{RET}}. (On some keyboards, the @key{META} key is labelled
@key{ALT}.)
-@c !!! 21.0.100 tags table location in this paragraph
+@c !!! 22.1.1 tags table location in this paragraph
@cindex TAGS table, specifying
@findex find-tags
Depending on how the initial default values of your copy of Emacs are
if it has already been created for you, will be in a subdirectory of
the @file{/usr/local/share/emacs/} directory; thus you would use the
@code{M-x visit-tags-table} command and specify a pathname such as
-@file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
-@file{/usr/local/src/emacs/lisp/TAGS}. If the tags table has
-not already been created, you will have to create it yourself.
+@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
+has not already been created, you will have to create it yourself. It
+will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
@need 1250
To create a @file{TAGS} file in a specific directory, switch to that
directory in Emacs using @kbd{M-x cd} command, or list the directory
with @kbd{C-x d} (@code{dired}). Then run the compile command, with
-@w{@code{etags *.el}} as the command to execute
+@w{@code{etags *.el}} as the command to execute:
@smallexample
M-x compile RET etags *.el RET
@smallexample
@group
-One arg, a number. Set point to that number.
-Beginning of buffer is position (point-min),
-end is (point-max).
+Set point to POSITION, a number or marker.
+Beginning of buffer is position (point-min), end is (point-max).
@end group
@end smallexample
+@noindent
+The function's one argument is the desired position.
+
@noindent
(The prompt for @code{describe-function} will offer you the symbol
under or preceding the cursor, so you can save typing by positioning
a mark at the end of the buffer. It is generally bound to @kbd{C-x
h}.
-
@menu
* mark-whole-buffer overview::
* Body of mark-whole-buffer:: Only three lines of code.
@end menu
-
@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
@ifnottex
@unnumberedsubsec An overview of @code{mark-whole-buffer}
@end ifnottex
@need 1250
-In GNU Emacs 20, the code for the complete function looks like this:
+In GNU Emacs 22, the code for the complete function looks like this:
@smallexample
@group
(defun mark-whole-buffer ()
- "Put point at beginning and mark at end of buffer."
+ "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))
+ (push-mark (point-max) nil t)
(goto-char (point-min)))
@end group
@end smallexample
to the @code{simplified-beginning-of-buffer} function described in the
previous section.
+@need 1250
@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
@comment node-name, next, previous, up
@subsection Body of @code{mark-whole-buffer}
The body of the @code{mark-whole-buffer} function consists of three
lines of code:
+@c GNU Emacs 22
@smallexample
@group
(push-mark (point))
-(push-mark (point-max))
+(push-mark (point-max) nil t)
(goto-char (point-min))
@end group
@end smallexample
line causes Emacs to determine the position of point and set a mark
there.
-The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}.
-This expression sets a mark at the point in the buffer
-that has the highest number. This will be the end of the buffer (or,
-if the buffer is narrowed, the end of the accessible portion of the
-buffer. @xref{Narrowing & Widening, , Narrowing and Widening}, for
-more about narrowing.) After this mark has been set, the previous
-mark, the one set at point, is no longer set, but Emacs remembers its
-position, just as all other recent marks are always remembered. This
-means that you can, if you wish, go back to that position by typing
-@kbd{C-u C-@key{SPC}} twice.
+In earlier versions of GNU Emacs, the next line of
+@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
+expression sets a mark at the point in the buffer that has the highest
+number. This will be the end of the buffer (or, if the buffer is
+narrowed, the end of the accessible portion of the buffer.
+@xref{Narrowing & Widening, , Narrowing and Widening}, for more about
+narrowing.) After this mark has been set, the previous mark, the one
+set at point, is no longer set, but Emacs remembers its position, just
+as all other recent marks are always remembered. This means that you
+can, if you wish, go back to that position by typing @kbd{C-u
+C-@key{SPC}} twice.
-(In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
-complicated than shown here. The line reads
+@need 1250
+In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
+The line reads
@smallexample
(push-mark (point-max) nil t)
@end smallexample
@noindent
-(The expression works nearly the same as before. It sets a mark at
-the highest numbered place in the buffer that it can. However, in
-this version, @code{push-mark} has two additional arguments. The
-second argument to @code{push-mark} is @code{nil}. This tells the
-function it @emph{should} display a message that says `Mark set' when
-it pushes the mark. The third argument is @code{t}. This tells
+The expression works nearly the same as before. It sets a mark at the
+highest numbered place in the buffer that it can. However, in this
+version, @code{push-mark} has two additional arguments. The second
+argument to @code{push-mark} is @code{nil}. This tells the function
+it @emph{should} display a message that says `Mark set' when it pushes
+the mark. The third argument is @code{t}. This tells
@code{push-mark} to activate the mark when Transient Mark mode is
turned on. Transient Mark mode highlights the currently active
-region. It is usually turned off.)
+region. It is often turned off.
Finally, the last line of the function is @code{(goto-char
(point-min)))}. This is written exactly the same way as it is written
@section The Definition of @code{append-to-buffer}
@findex append-to-buffer
-The @code{append-to-buffer} command is very nearly as simple as the
-@code{mark-whole-buffer} command. What it does is copy the region (that
-is, the part of the buffer between point and mark) from the current
-buffer to a specified buffer.
+The @code{append-to-buffer} command is more complex than the
+@code{mark-whole-buffer} command. What it does is copy the region
+(that is, the part of the buffer between point and mark) from the
+current buffer to a specified buffer.
@menu
* append-to-buffer overview::
@code{insert-buffer-substring} function to copy the region.
@code{insert-buffer-substring} is described by its name: it takes a
string of characters from part of a buffer, a ``substring'', and
-inserts them into another buffer. Most of @code{append-to-buffer} is
+inserts them into another buffer.
+
+Most of @code{append-to-buffer} is
concerned with setting up the conditions for
@code{insert-buffer-substring} to work: the code must specify both the
-buffer to which the text will go and the region that will be copied.
+buffer to which the text will go, the window it comes from and goes
+to, and the region that will be copied.
+
+@need 1250
Here is the complete text of the function:
@smallexample
@group
When calling from a program, give three arguments:
-a buffer or the name of one, and two character numbers
-specifying the portion of the current buffer to be copied."
- (interactive "BAppend to buffer:@: \nr")
+BUFFER (or buffer name), START and END.
+START and END specify the portion of the current buffer to be copied."
+ (interactive
+ (list (read-buffer "Append to buffer: " (other-buffer
+ (current-buffer) t))
+ (region-beginning) (region-end)))
+@end group
+@group
(let ((oldbuf (current-buffer)))
(save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
@end group
@end smallexample
@group
(defun append-to-buffer (buffer start end)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
@var{body}@dots{})
@end group
@end smallexample
will be copied.
The next part of the function is the documentation, which is clear and
-complete.
+complete. As is conventional, the three arguments are written in
+upper case so you will notice them easily. Even better, they are
+described in the same order as in the argument list.
+
+Note that the documentation distinguishes between a buffer and its
+name. (The function can handle either.)
@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
@comment node-name, next, previous, up
Function Interactive}.) The expression reads as follows:
@smallexample
-(interactive "BAppend to buffer:@: \nr")
+@group
+(interactive
+ (list (read-buffer
+ "Append to buffer: "
+ (other-buffer (current-buffer) t))
+ (region-beginning)
+ (region-end)))
+@end group
@end smallexample
@noindent
-This expression has an argument inside of quotation marks and that
-argument has two parts, separated by @samp{\n}.
+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 @code{read-buffer}. The
+function requires a prompt as its first argument, @samp{"Append to
+buffer: "}. Its second argument tells the command what value to
+provide if you don't specify anything.
+
+In this case that second argument is an expression containing the
+function @code{other-buffer}, an exception, and a @samp{t}, standing
+for true.
+
+The first argument to @code{other-buffer}, the exception, is yet
+another function, @code{current-buffer}. That is not going to be
+returned. The second argument is the symbol for true, @code{t}. that
+tells @code{other-buffer} that it may show visible buffers (except in
+this case, it will not show the current buffer, which makes sense).
+
+@need 1250
+The expression looks like this:
+
+@smallexample
+(other-buffer (current-buffer) t)
+@end smallexample
+
+The second and third arguments to the @code{list} expression are
+@code{(region-beginning)} and @code{(region-end)}. These two
+functions specify the beginning and end of the text to be appended.
+
+@need 1250
+Originally, the command used the letters @samp{B} and @samp{r}.
+The whole @code{interactive} expression looked like this:
+
+@smallexample
+(interactive "BAppend to buffer:@: \nr")
+@end smallexample
-The first part is @samp{BAppend to buffer:@: }. Here, the @samp{B}
-tells Emacs to ask for the name of the buffer that will be passed to the
-function. Emacs will ask for the name by prompting the user in the
-minibuffer, using the string following the @samp{B}, which is the string
-@samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer}
-in the function's argument list to the specified buffer.
+@noindent
+But when that was done, the default value of the buffer switched to
+was invisible. That was not wanted.
-The newline, @samp{\n}, separates the first part of the argument from
-the second part. It is followed by an @samp{r} that tells Emacs to bind
-the two arguments that follow the symbol @code{buffer} in the function's
+(The prompt was separated from the second argument with a newline,
+@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
+two arguments that follow the symbol @code{buffer} in the function's
argument list (that is, @code{start} and @code{end}) to the values of
-point and mark.
+point and mark. That argument worked fine.)
@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
@comment node-name, next, previous, up
@subsection The Body of @code{append-to-buffer}
+@ignore
+in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
+
+(defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+It is inserted into that buffer before its point.
+
+When calling from a program, give three arguments:
+BUFFER (or buffer name), START and END.
+START and END specify the portion of the current buffer to be copied."
+ (interactive
+ (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
+ (region-beginning) (region-end)))
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
+@end ignore
+
The body of the @code{append-to-buffer} function begins with @code{let}.
As we have seen before (@pxref{let, , @code{let}}), the purpose of a
@group
(defun append-to-buffer (buffer start end)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
(let ((@var{variable} @var{value}))
@var{body}@dots{})
@end group
@need 1500
@noindent
-This formatting convention makes it easy to see that the two lines in
+This formatting convention makes it easy to see that the lines in
the body of the @code{save-excursion} are enclosed by the parentheses
associated with @code{save-excursion}, just as the
@code{save-excursion} itself is enclosed by the parentheses associated
@group
(let ((oldbuf (current-buffer)))
(save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
+ @dots{}
+ (set-buffer @dots{})
+ (insert-buffer-substring oldbuf start end)
+ @dots{}))
@end group
@end smallexample
@need 1200
@noindent
In this function, the body of the @code{save-excursion} contains only
-two expressions. The body looks like this:
+one expression, the @code{let*} expression. You know about a
+@code{let} function. The @code{let*} function is different. It has a
+@samp{*} in its name. It enables Emacs to set each variable in its
+varlist in sequence, one after another.
-@smallexample
-@group
-(set-buffer (get-buffer-create buffer))
-(insert-buffer-substring oldbuf start end)
-@end group
-@end smallexample
+Its critical feature is that variables later in the varlist can make
+use of the values to which Emacs set variables earlier in the varlist.
+@xref{fwd-para let, , The @code{let*} expression}.
-When the @code{append-to-buffer} function is evaluated, the two
-expressions in the body of the @code{save-excursion} are evaluated in
-sequence. The value of the last expression is returned as the value of
-the @code{save-excursion} function; the other expression is evaluated
-only for its side effects.
+We will skip functions like @code{let*} and focus on two: the
+@code{set-buffer} function and the @code{insert-buffer-substring}
+function.
-The first line in the body of the @code{save-excursion} uses the
-@code{set-buffer} function to change the current buffer to the one
-specified in the first argument to @code{append-to-buffer}. (Changing
-the buffer is the side effect; as we have said before, in Lisp, a side
-effect is often the primary thing we want.) The second line does the
-primary work of the function.
+@need 1250
+In the old days, the @code{set-buffer} expression was simply
-The @code{set-buffer} function changes Emacs' attention to the buffer to
-which the text will be copied and from which @code{save-excursion} will
-return.
+@smallexample
+(set-buffer (get-buffer-create buffer))
+@end smallexample
-@need 800
-The line looks like this:
+@need 1250
+@noindent
+but now it is
@smallexample
-(set-buffer (get-buffer-create buffer))
+(set-buffer append-to)
@end smallexample
-The innermost expression of this list is @code{(get-buffer-create
-buffer)}. This expression uses the @code{get-buffer-create} function,
-which either gets the named buffer, or if it does not exist, creates one
-with the given name. This means you can use @code{append-to-buffer} to
-put text into a buffer that did not previously exist.
+@noindent
+@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
+on in the @code{let*} expression. That extra binding would not be
+necessary except for that @code{append-to} is used later in the
+varlist as an argument to @code{get-buffer-window-list}.
+
+@ignore
+in GNU Emacs 22
+
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
+@end ignore
-@code{get-buffer-create} also keeps @code{set-buffer} from getting an
-unnecessary error: @code{set-buffer} needs a buffer to go to; if you
-were to specify a buffer that does not exist, Emacs would baulk.
-Since @code{get-buffer-create} will create a buffer if none exists,
-@code{set-buffer} is always provided with a buffer.
+The @code{append-to-buffer} function definition inserts text from the
+buffer in which you are currently to a named buffer. It happens that
+@code{insert-buffer-substring} copies text from another buffer to the
+current buffer, just the reverse---that is why the
+@code{append-to-buffer} definition starts out with a @code{let} that
+binds the local symbol @code{oldbuf} to the value returned by
+@code{current-buffer}.
@need 1250
-The last line of @code{append-to-buffer} does the work of appending
-the text:
+The @code{insert-buffer-substring} expression looks like this:
@smallexample
(insert-buffer-substring oldbuf start end)
@end smallexample
@noindent
-The @code{insert-buffer-substring} function copies a string @emph{from}
-the buffer specified as its first argument and inserts the string into
-the present buffer. In this case, the argument to
-@code{insert-buffer-substring} is the value of the variable created and
-bound by the @code{let}, namely the value of @code{oldbuf}, which was
-the current buffer when you gave the @code{append-to-buffer} command.
+The @code{insert-buffer-substring} function copies a string
+@emph{from} the buffer specified as its first argument and inserts the
+string into the present buffer. In this case, the argument to
+@code{insert-buffer-substring} is the value of the variable created
+and bound by the @code{let}, namely the value of @code{oldbuf}, which
+was the current buffer when you gave the @code{append-to-buffer}
+command.
After @code{insert-buffer-substring} has done its work,
-@code{save-excursion} will restore the action to the original buffer and
-@code{append-to-buffer} will have done its job.
+@code{save-excursion} will restore the action to the original buffer
+and @code{append-to-buffer} will have done its job.
@need 800
Written in skeletal form, the workings of the body look like this:
@var{change-back-to-original-buffer-when-finished}
@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
-
@end group
@end smallexample
-In summary, @code{append-to-buffer} works as follows: it saves the value
-of the current buffer in the variable called @code{oldbuf}. It gets the
-new buffer, creating one if need be, and switches Emacs to it. Using
-the value of @code{oldbuf}, it inserts the region of text from the old
-buffer into the new buffer; and then using @code{save-excursion}, it
-brings you back to your original buffer.
+In summary, @code{append-to-buffer} works as follows: it saves the
+value of the current buffer in the variable called @code{oldbuf}. It
+gets the new buffer (creating one if need be) and switches Emacs'
+attention to it. Using the value of @code{oldbuf}, it inserts the
+region of text from the old buffer into the new buffer; and then using
+@code{save-excursion}, it brings you back to your original buffer.
In looking at @code{append-to-buffer}, you have explored a fairly
complex function. It shows how to use @code{let} and
After understanding how @code{append-to-buffer} works, it is easy to
understand @code{copy-to-buffer}. This function copies text into a
-buffer, but instead of adding to the second buffer, it replaces the
-previous text in the second buffer. The code for the
-@code{copy-to-buffer} function is almost the same as the code for
-@code{append-to-buffer}, except that @code{erase-buffer} and a second
-@code{save-excursion} are used. (@xref{append-to-buffer, , The
-Definition of @code{append-to-buffer}}, for the description of
-@code{append-to-buffer}.)
+buffer, but instead of adding to the second buffer, it replaces all the
+previous text in the second buffer.
@need 800
-The body of @code{copy-to-buffer} looks like this
+The body of @code{copy-to-buffer} looks like this,
@smallexample
@group
@dots{}
-(interactive "BCopy to buffer:@: \nr")
- (let ((oldbuf (current-buffer)))
+(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
- (set-buffer (get-buffer-create buffer))
- (erase-buffer)
- (save-excursion
- (insert-buffer-substring oldbuf start end)))))
+ (insert-buffer-substring oldbuf start end)))))
@end group
@end smallexample
-This code is similar to the code in @code{append-to-buffer}: it is
-only after changing to the buffer to which the text will be copied
-that the definition for this function diverges from the definition for
-@code{append-to-buffer}: the @code{copy-to-buffer} function erases the
-buffer's former contents. (This is what is meant by `replacement'; to
-replace text, Emacs erases the previous text and then inserts new
-text.) After erasing the previous contents of the buffer,
-@code{save-excursion} is used for a second time and the new text is
-inserted.
+The @code{copy-to-buffer} function has a simpler @code{interactive}
+expression than @code{append-to-buffer}.
+
+@need 800
+The definition then says
+
+@smallexample
+(with-current-buffer (get-buffer-create buffer) @dots{}
+@end smallexample
+
+First, look at the earliest inner expression; that is evaluated first.
+That expression starts with @code{get-buffer-create buffer}. The
+function tells the computer to use the buffer with the name specified
+as the one to which you are copying, or if such a buffer does not
+exist, to create it. Then, the @code{with-current-buffer} function
+evaluates its body with that buffer temporarily current.
+
+(This demonstrates another way to shift the computer's attention but
+not the user's. The @code{append-to-buffer} function showed how to do
+the same with @code{save-excursion} and @code{set-buffer}.
+@code{with-current-buffer} is a newer, and arguably easier,
+mechanism.)
-Why is @code{save-excursion} used twice? Consider again what the
-function does.
+The @code{barf-if-buffer-read-only} function sends you an error
+message saying the buffer is read-only if you cannot modify it.
+
+The next line has the @code{erase-buffer} function as its sole
+contents. That function erases the buffer.
+
+Finally, the last two lines contain the @code{save-excursion}
+expression with @code{insert-buffer-substring} as its body.
+The @code{insert-buffer-substring} expression copies the text from
+the buffer you are in (and you have not seen the computer shift its
+attention, so you don't know that that buffer is now called
+@code{oldbuf}).
+
+Incidentally, this is what is meant by `replacement'. To replace text,
+Emacs erases the previous text and then inserts new text.
@need 1250
In outline, the body of @code{copy-to-buffer} looks like this:
@smallexample
@group
(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
- (save-excursion ; @r{First use of @code{save-excursion}.}
- @var{change-buffer}
+ (@var{with-the-buffer-you-are-copying-to}
+ (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
(erase-buffer)
- (save-excursion ; @r{Second use of @code{save-excursion}.}
+ (save-excursion
@var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
@end group
@end smallexample
-The first use of @code{save-excursion} returns Emacs to the buffer from
-which the text is being copied. That is clear, and is just like its use
-in @code{append-to-buffer}. Why the second use? The reason is that
-@code{insert-buffer-substring} always leaves point at the @emph{end} of
-the region being inserted. The second @code{save-excursion} causes
-Emacs to leave point at the beginning of the text being inserted. In
-most circumstances, users prefer to find point at the beginning of
-inserted text. (Of course, the @code{copy-to-buffer} function returns
-the user to the original buffer when done---but if the user @emph{then}
-switches to the copied-to buffer, point will go to the beginning of the
-text. Thus, this use of a second @code{save-excursion} is a little
-nicety.)
-
@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
@comment node-name, next, previous, up
@section The Definition of @code{insert-buffer}
reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
copy a region of text @emph{from} the current buffer to another buffer.
+Here is a discussion based on the original code. The code was
+simplified in 2003 and is harder to understand.
+
+(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
+a discussion of the new body.)
+
In addition, this code illustrates the use of @code{interactive} with a
buffer that might be @dfn{read-only} and the important distinction
between the name of an object and the object actually referred to.
* 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
@end ifnottex
@need 800
-Here is the code:
+Here is the earlier code:
@smallexample
@group
enabled. If the buffer does not exist, you receive a message that
says ``No match''; your terminal may beep at you as well.
+The new and simplified code generates a list for @code{interactive}.
+It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
+functions with which we are already familiar and the @code{progn}
+special form with which we are not. (It will be described later.)
+
@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
@comment node-name, next, previous, up
@subsection The Body of the @code{insert-buffer} Function
@noindent
@code{not} is a function that returns true if its argument is false
and false if its argument is true. So if @code{(bufferp buffer)}
-returns true, the @code{not} expression returns false and vice-versa:
+returns true, the @code{not} expression returns false and vice-verse:
what is ``not true'' is false and what is ``not false'' is true.
Using this test, the @code{if} expression works as follows: when the
-value of the variable @code{buffer} is actually a buffer rather then
+value of the variable @code{buffer} is actually a buffer rather than
its name, the true-or-false-test returns false and the @code{if}
expression does not evaluate the then-part. This is fine, since we do
not need to do anything to the variable @code{buffer} if it really is
(or (holding-on-to-guest) (find-and-take-arm-of-guest))
@end smallexample
-@node Insert let, , 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}
mark is still accessible; it is recorded on the mark ring and you can
go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
located at the beginning of the inserted text, which is where it was
-before you called the insert function.
+before you called the insert function, the position of which was saved
+by the first @code{save-excursion}.
@need 1250
The whole @code{let} expression looks like this:
use @code{or}. All these functions are building blocks that we will
find and use again and again.
-@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
+@node New insert-buffer, , Insert let, insert-buffer
@comment node-name, next, previous, up
-@section Complete Definition of @code{beginning-of-buffer}
+@subsection New Body for @code{insert-buffer}
+@findex insert-buffer, new version body
+@findex new version body for insert-buffer
+
+The body in the GNU Emacs 22 version is more confusing than the original.
+
+@need 1250
+It consists of two expressions,
+
+@smallexample
+@group
+ (push-mark
+ (save-excursion
+ (insert-buffer-substring (get-buffer buffer))
+ (point)))
+
+ nil
+@end group
+@end smallexample
+
+@noindent
+except, and this is what confuses novices, very important work is done
+inside the @code{push-mark} expression.
+
+The @code{get-buffer} function returns a buffer with the name
+provided. You will note that the function is @emph{not} called
+@code{get-buffer-create}; it does not create a buffer if one does not
+already exist. The buffer returned by @code{get-buffer}, an existing
+buffer, is passed to @code{insert-buffer-substring}, which inserts the
+whole of the buffer (since you did not specify anything else).
+
+The location into which the buffer is inserted is recorded by
+@code{push-mark}. Then the function returns @code{nil}, the value of
+its last command. Put another way, the @code{insert-buffer} function
+exists only to produce a side effect, inserting another buffer, not to
+return any value.
+
+@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
+@comment node-name, next, previous, up
+@section Complete Definition of @code{beginning-of-buffer}
@findex beginning-of-buffer
The basic structure of the @code{beginning-of-buffer} function has
As previously described, when invoked without an argument,
@code{beginning-of-buffer} moves the cursor to the beginning of the
-buffer, leaving the mark at the previous position. However, when the
+buffer (in truth, the beginning of the accessible portion of the
+buffer), leaving the mark at the previous position. However, when the
command is invoked with a number between one and ten, the function
considers that number to be a fraction of the length of the buffer,
-measured in tenths, and Emacs moves the cursor that fraction of the way
-from the beginning of the buffer. Thus, you can either call this
+measured in tenths, and Emacs moves the cursor that fraction of the
+way from the beginning of the buffer. Thus, you can either call this
function with the key command @kbd{M-<}, which will move the cursor to
the beginning of the buffer, or with a key command such as @kbd{C-u 7
M-<} which will move the cursor to a point 70% of the way through the
-buffer. If a number bigger than ten is used for the argument, it moves
-to the end of the buffer.
+buffer. If a number bigger than ten is used for the argument, it
+moves to the end of the buffer.
The @code{beginning-of-buffer} function can be called with or without an
argument. The use of the argument is optional.
@cindex Optional arguments
@cindex Keyword
@findex optional
-However, optional arguments are a feature of Lisp: a @dfn{keyword} may
-be used to tell the Lisp interpreter that an argument is optional.
-The keyword is @code{&optional}. (The @samp{&} in front of
+However, optional arguments are a feature of Lisp: a particular
+@dfn{keyword} is used to tell the Lisp interpreter that an argument is
+optional. The keyword is @code{&optional}. (The @samp{&} in front of
@samp{optional} is part of the keyword.) In a function definition, if
-an argument follows the keyword @code{&optional}, a value does not
-need to be passed to that argument when the function is called.
+an argument follows the keyword @code{&optional}, no value need be
+passed to that argument when the function is called.
@need 1200
The first line of the function definition of @code{beginning-of-buffer}
(defun beginning-of-buffer (&optional arg)
"@var{documentation}@dots{}"
(interactive "P")
- (push-mark)
+ (or (@var{is-the-argument-a-cons-cell} arg)
+ (and @var{are-both-transient-mark-mode-and-mark-active-true})
+ (push-mark))
+ (let (@var{determine-size-and-set-it})
(goto-char
(@var{if-there-is-an-argument}
@var{figure-out-where-to-go}
@var{else-go-to}
(point-min))))
+ @var{do-nicety}
@end group
@end smallexample
function except that the @code{interactive} expression has @code{"P"}
as an argument and the @code{goto-char} function is followed by an
if-then-else expression that figures out where to put the cursor if
-there is an argument.
-
-The @code{"P"} in the @code{interactive} expression tells Emacs to pass
-a prefix argument, if there is one, to the function. A prefix argument
-is made by typing the @key{META} key followed by a number, or by typing
-@kbd{C-u} and then a number (if you don't type a number, @kbd{C-u}
-defaults to 4).
-
-The true-or-false-test of the @code{if} expression is simple: it is
-simply the argument @code{arg}. If @code{arg} has a value that is not
-@code{nil}, which will be the case if @code{beginning-of-buffer} is
-called with an argument, then this true-or-false-test will return true
-and the then-part of the @code{if} expression will be evaluated. On the
+there is an argument that is not a cons cell.
+
+(Since I do not explain a cons cell for many more chapters, please
+consider ignoring the function @code{consp}. @xref{List
+Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
+, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
+Manual}.)
+
+The @code{"P"} in the @code{interactive} expression tells Emacs to
+pass a prefix argument, if there is one, to the function in raw form.
+A prefix argument is made by typing the @key{META} key followed by a
+number, or by typing @kbd{C-u} and then a number. (If you don't type
+a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
+@code{"p"} in the @code{interactive} expression causes the function to
+convert a prefix arg to a number.)
+
+The true-or-false-test of the @code{if} expression looks complex, but
+it is not: it checks whether @code{arg} has a value that is not
+@code{nil} and whether it is a cons cell. (That is what @code{consp}
+does; it checks whether its argument is a cons cell.) If @code{arg}
+has a value that is not @code{nil} (and is not a cons cell), which
+will be the case if @code{beginning-of-buffer} is called with a
+numeric argument, then this true-or-false-test will return true and
+the then-part of the @code{if} expression will be evaluated. On the
other hand, if @code{beginning-of-buffer} is not called with an
argument, the value of @code{arg} will be @code{nil} and the else-part
-of the @code{if} expression will be evaluated. The else-part is simply
-@code{point-min}, and when this is the outcome, the whole
-@code{goto-char} expression is @code{(goto-char (point-min))}, which is
-how we saw the @code{beginning-of-buffer} function in its simplified
-form.
+of the @code{if} expression will be evaluated. The else-part is
+simply @code{point-min}, and when this is the outcome, the whole
+@code{goto-char} expression is @code{(goto-char (point-min))}, which
+is how we saw the @code{beginning-of-buffer} function in its
+simplified form.
@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
@subsection @code{beginning-of-buffer} with an Argument
@group
(if (> (buffer-size) 10000)
;; @r{Avoid overflow for large buffer sizes!}
- (* (prefix-numeric-value arg) (/ (buffer-size) 10))
+ (* (prefix-numeric-value arg)
+ (/ size 10))
(/
(+ 10
(*
- (buffer-size) (prefix-numeric-value arg))) 10))
+ size (prefix-numeric-value arg))) 10)))
@end group
@end smallexample
@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.
In @code{beginning-of-buffer}, the inner @code{if} expression tests
whether the size of the buffer is greater than 10,000 characters. To do
-this, it uses the @code{>} function and the @code{buffer-size} function.
+this, it uses the @code{>} function and the computation of @code{size}
+that comes from the let expression.
+
+In the old days, the function @code{buffer-size} was used. Not only
+was that function called several times, it gave the size of the whole
+buffer, not the accessible part. The computation makes much more
+sense when it handles just the accessible part. (@xref{Narrowing &
+Widening, , Narrowing and Widening}, for more information on focusing
+attention to an `accessible' part.)
@need 800
The line looks like this:
@smallexample
-(if (> (buffer-size) 10000)
+(if (> size 10000)
@end smallexample
@need 1200
@group
(*
(prefix-numeric-value arg)
- (/ (buffer-size) 10))
+ (/ size 10))
@end group
@end smallexample
@findex / @r{(division)}
@cindex Division
-The second argument is @code{(/ (buffer-size) 10)}. This expression
-divides the numeric value of the buffer by ten. This produces a number
-that tells how many characters make up one tenth of the buffer size.
-(In Lisp, @code{/} is used for division, just as @code{*} is
-used for multiplication.)
+The second argument is @code{(/ size 10)}. This expression divides
+the numeric value by ten --- the numeric value of the size of the
+accessible portion of the buffer. This produces a number that tells
+how many characters make up one tenth of the buffer size. (In Lisp,
+@code{/} is used for division, just as @code{*} is used for
+multiplication.)
@need 1200
In the multiplication expression as a whole, this amount is multiplied
@smallexample
@group
(* @var{numeric-value-of-prefix-arg}
- @var{number-of-characters-in-one-tenth-of-the-buffer})
+ @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
@end group
@end smallexample
@noindent
If, for example, the prefix argument is @samp{7}, the one-tenth value
-will be multiplied by 7 to give a position 70% of the way through the
-buffer.
+will be multiplied by 7 to give a position 70% of the way through.
@need 1200
-The result of all this is that if the buffer is large, the
-@code{goto-char} expression reads like this:
+The result of all this is that if the accessible portion of the buffer
+is large, the @code{goto-char} expression reads like this:
@smallexample
@group
(goto-char (* (prefix-numeric-value arg)
- (/ (buffer-size) 10)))
+ (/ size 10)))
@end group
@end smallexample
@c Keep this on one line.
@smallexample
-(/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
+(/ (+ 10 (* size (prefix-numeric-value arg))) 10))
@end smallexample
@need 1200
(/
(+ 10
(*
- (buffer-size)
+ size
(prefix-numeric-value arg)))
10))
@end group
@need 1200
@noindent
Looking at parentheses, we see that the innermost operation is
-@code{(prefix-numeric-value arg)}, which converts the raw argument to a
-number. This number is multiplied by the buffer size in the following
-expression:
+@code{(prefix-numeric-value arg)}, which converts the raw argument to
+a number. In the following expression, this number is multiplied by
+the size of the accessible portion of the buffer:
@smallexample
-(* (buffer-size) (prefix-numeric-value arg)
+(* size (prefix-numeric-value arg))
@end smallexample
@noindent
The number that results from all this is passed to @code{goto-char} and
the cursor is moved to that point.
+@need 1500
@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
@comment node-name, next, previous, up
@subsection The Complete @code{beginning-of-buffer}
-@need 800
+@need 1000
Here is the complete text of the @code{beginning-of-buffer} function:
+@sp 1
+
+@c In GNU Emacs 22
+@smallexample
+@group
+(defun beginning-of-buffer (&optional arg)
+ "Move point to the beginning of the buffer;
+leave mark at previous position.
+With \\[universal-argument] prefix,
+do not set mark at previous position.
+With numeric arg N,
+put point N/10 of the way from the beginning.
+
+If the buffer is narrowed,
+this command uses the beginning and size
+of the accessible part of the buffer.
+@end group
+
+@group
+Don't use this command in Lisp programs!
+\(goto-char (point-min)) is faster
+and avoids clobbering the mark."
+ (interactive "P")
+ (or (consp arg)
+ (and transient-mark-mode mark-active)
+ (push-mark))
+@end group
+@group
+ (let ((size (- (point-max) (point-min))))
+ (goto-char (if (and arg (not (consp arg)))
+ (+ (point-min)
+ (if (> size 10000)
+ ;; Avoid overflow for large buffer sizes!
+ (* (prefix-numeric-value arg)
+ (/ size 10))
+ (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
+ (point-min))))
+ (if arg (forward-line 1)))
+@end group
+@end smallexample
+@ignore
+From before GNU Emacs 22
@smallexample
@group
(defun beginning-of-buffer (&optional arg)
leave mark at previous position.
With arg N, put point N/10 of the way
from the true beginning.
+@end group
+@group
Don't use this in Lisp programs!
\(goto-char (point-min)) is faster
and does not set the mark."
(if arg (forward-line 1)))
@end group
@end smallexample
+@end ignore
@noindent
Except for two small points, the previous discussion shows how this
In the documentation string, there is reference to an expression:
@smallexample
-\(goto-char (point-min))
+\\[universal-argument]
@end smallexample
@noindent
-A @samp{\} is used before the first parenthesis of this expression.
-This @samp{\} tells the Lisp interpreter that the expression should be
-printed as shown in the documentation rather than evaluated as a
-symbolic expression, which is what it looks like.
+A @samp{\\} is used before the first square bracket of this
+expression. This @samp{\\} tells the Lisp interpreter to substitute
+whatever key is currently bound to the @samp{[@dots{}]}. In the case
+of @code{universal-argument}, that is usually @kbd{C-u}, but it might
+be different. (@xref{Documentation Tips, , Tips for Documentation
+Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
+information.)
@need 1200
-Finally, the last line of the @code{beginning-of-buffer} command says to
-move point to the beginning of the next line if the command is
+Finally, the last line of the @code{beginning-of-buffer} command says
+to move point to the beginning of the next line if the command is
invoked with an argument:
@smallexample
appropriate tenths position in the buffer. This is a flourish that
means that the cursor is always located @emph{at least} the requested
tenths of the way through the buffer, which is a nicety that is,
-perhaps, not necessary, but which, if it did not occur, would be sure to
-draw complaints.
+perhaps, not necessary, but which, if it did not occur, would be sure
+to draw complaints.
+
+On the other hand, it also means that if you specify the command with
+a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
+argument' is simply a cons cell, then the command puts you at the
+beginning of the second line @dots{} I don't know whether this is
+intended or whether no one has dealt with the code to avoid this
+happening.
@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
@comment node-name, next, previous, up
argument that is not @code{nil}; if none return a value that is not
@code{nil}, return @code{nil}. In brief, return the first true value
of the arguments; return a true value if one @emph{or} any of the
-other are true.
+others are true.
@item and
Evaluate each argument in sequence, and if any are @code{nil}, return
@section @code{optional} Argument Exercise
Write an interactive function with an optional argument that tests
-whether its argument, a number, is greater or less than the value of
-@code{fill-column}, and tells you which, in a message. However, if you
-do not pass an argument to the function, use 56 as a default value.
+whether its argument, a number, is greater than or equal to, or else,
+less than the value of @code{fill-column}, and tells you which, in a
+message. However, if you do not pass an argument to the function, use
+56 as a default value.
@node Narrowing & Widening, car cdr & cons, More Complex, Top
@comment node-name, next, previous, up
@end group
@end smallexample
+@ignore
+Emacs 22
+/usr/local/src/emacs/lisp/simple.el
+
+(defun what-line ()
+ "Print the current buffer line number and narrowed line number of point."
+ (interactive)
+ (let ((start (point-min))
+ (n (line-number-at-pos)))
+ (if (= start 1)
+ (message "Line %d" n)
+ (save-excursion
+ (save-restriction
+ (widen)
+ (message "line %d (narrowed line %d)"
+ (+ n (line-number-at-pos start) -1) n))))))
+
+(defun line-number-at-pos (&optional pos)
+ "Return (narrowed) buffer line number at position POS.
+If POS is nil, use current buffer location.
+Counting starts at (point-min), so the value refers
+to the contents of the accessible portion of the buffer."
+ (let ((opoint (or pos (point))) start)
+ (save-excursion
+ (goto-char (point-min))
+ (setq start (point))
+ (goto-char opoint)
+ (forward-line 0)
+ (1+ (count-lines start (point))))))
+
+(defun count-lines (start end)
+ "Return number of lines between START and END.
+This is usually the number of newlines between them,
+but can be one more if START is not equal to END
+and the greater of them is not at the start of a line."
+ (save-excursion
+ (save-restriction
+ (narrow-to-region start end)
+ (goto-char (point-min))
+ (if (eq selective-display t)
+ (save-match-data
+ (let ((done 0))
+ (while (re-search-forward "[\n\C-m]" nil t 40)
+ (setq done (+ 40 done)))
+ (while (re-search-forward "[\n\C-m]" nil t 1)
+ (setq done (+ 1 done)))
+ (goto-char (point-max))
+ (if (and (/= start end)
+ (not (bolp)))
+ (1+ done)
+ done)))
+ (- (buffer-size) (forward-line (buffer-size)))))))
+@end ignore
+
@node what-line, narrow Exercise, save-restriction, Narrowing & Widening
@comment node-name, next, previous, up
@section @code{what-line}
The @code{what-line} command tells you the number of the line in which
the cursor is located. The function illustrates the use of the
@code{save-restriction} and @code{save-excursion} commands. Here is the
-text of the function in full:
+original text of the function:
@smallexample
@group
@end group
@end smallexample
-The function has a documentation line and is interactive, as you would
-expect. The next two lines use the functions @code{save-restriction} and
-@code{widen}.
+(In recent versions of GNU Emacs, the @code{what-line} function has
+been expanded to tell you your line number in a narrowed buffer as
+well as your line number in a widened buffer. The recent version is
+more complex than the version shown here. If you feel adventurous,
+you might want to look at it after figuring out how this version
+works. You will probably need to use @kbd{C-h f}
+(@code{describe-function}). The newer version uses a conditional to
+determine whether the buffer has been narrowed.
+
+(Also, it uses @code{line-number-at-pos}, which among other simple
+expressions, such as @code{(goto-char (point-min))}, moves point to
+the beginning of the current line with @code{(forward-line 0)} rather
+than @code{beginning-of-line}.)
+
+The @code{what-line} function as shown here has a documentation line
+and is interactive, as you would expect. The next two lines use the
+functions @code{save-restriction} and @code{widen}.
The @code{save-restriction} special form notes whatever narrowing is in
effect, if any, in the current buffer and restores that narrowing after
@end group
@end smallexample
-The @code{message} function prints a one-line message at the bottom of the
-Emacs screen. The first argument is inside of quotation marks and is
-printed as a string of characters. However, it may contain @samp{%d},
-@samp{%s}, or @samp{%c} to print arguments that follow the string.
-@samp{%d} prints the argument as a decimal, so the message will say
-something such as @samp{Line 243}.
+The @code{message} function prints a one-line message at the bottom of
+the Emacs screen. The first argument is inside of quotation marks and
+is printed as a string of characters. However, it may contain a
+@samp{%d} expression to print a following argument. @samp{%d} prints
+the argument as a decimal, so the message will say something such as
+@samp{Line 243}.
@need 1200
The number that is printed in place of the @samp{%d} is computed by the
(1+ (count-lines 1 (point)))
@end smallexample
+@ignore
+GNU Emacs 22
+
+(defun count-lines (start end)
+ "Return number of lines between START and END.
+This is usually the number of newlines between them,
+but can be one more if START is not equal to END
+and the greater of them is not at the start of a line."
+ (save-excursion
+ (save-restriction
+ (narrow-to-region start end)
+ (goto-char (point-min))
+ (if (eq selective-display t)
+ (save-match-data
+ (let ((done 0))
+ (while (re-search-forward "[\n\C-m]" nil t 40)
+ (setq done (+ 40 done)))
+ (while (re-search-forward "[\n\C-m]" nil t 1)
+ (setq done (+ 1 done)))
+ (goto-char (point-max))
+ (if (and (/= start end)
+ (not (bolp)))
+ (1+ done)
+ done)))
+ (- (buffer-size) (forward-line (buffer-size)))))))
+@end ignore
+
@noindent
What this does is count the lines from the first position of the
buffer, indicated by the @code{1}, up to @code{(point)}, and then add
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
-@code{save-restriction}, @code{widen}, @code{goto-char},
-@code{point-min}, @code{buffer-substring}, @code{message}, and other
-functions, a whole potpourri.
+half so that the first line is inaccessible. Restore point, mark, and
+narrowing. For this exercise, you need to use a whole potpourri of
+functions, including @code{save-restriction}, @code{widen},
+@code{goto-char}, @code{point-min}, @code{message}, and
+@code{buffer-substring}.
+
+@cindex Properties, mention of @code{buffer-substring-no-properties}
+(@code{buffer-substring} is a previously unmentioned function you will
+have to investigate yourself; or perhaps you will have to use
+@code{buffer-substring-no-properties} or
+@code{filter-buffer-substring} @dots{}, yet other functions. Text
+properties are a feature otherwise not discussed here. @xref{Text
+Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
+Manual}.)
+
+Additionally, do you really need @code{goto-char} or @code{point-min}?
+Or can you write the function without them?
@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
@comment node-name, next, previous, up
returned by the @code{cdr} function, is @code{(violet daisy
buttercup)}.
-@need 1250
+@need 800
You can see this by evaluating the following in the usual way:
@smallexample
What you see, if you evaluate this, is the error message
@smallexample
-Wrong number of arguments: #<subr length>, 0
+Lisp error: (wrong-number-of-arguments length 0)
@end smallexample
@noindent
length the function is measuring. (Note that @emph{one} list is
@emph{one} argument, even if the list has many elements inside it.)
-The part of the error message that says @samp{#<subr length>} is the
-name of the function. This is written with a special notation,
-@samp{#<subr}, that indicates that the function @code{length} is one
-of the primitive functions written in C rather than in Emacs Lisp.
-(@samp{subr} is an abbreviation for `subroutine'.) @xref{What Is a
-Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference
-Manual}, for more about subroutines.
+The part of the error message that says @samp{length} is the name of
+the function.
+
+@ignore
+@code{length} is still a subroutine, but you need C-h f to discover that.
+
+In an earlier version:
+ This is written with a special notation, @samp{#<subr},
+ that indicates that the function @code{length} is one of the primitive
+ functions written in C rather than in Emacs Lisp. (@samp{subr} is an
+ abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
+ Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
+ about subroutines.
+@end ignore
@node nthcdr, nth, cons, car cdr & cons
@comment node-name, next, previous, up
@noindent
If you are reading this in Info inside of GNU Emacs, you can evaluate
this expression in the usual fashion, by positioning the cursor after
-the expression and typing @kbd{C-x C-e}. (I'm doing this right here as
-I write this. This is one of the advantages of having the interpreter
-built into the computing environment.)
+the expression and typing @kbd{C-x C-e}. (I'm doing this right here
+as I write this. This is one of the advantages of having the
+interpreter built into the computing environment. Incidentally, when
+there is nothing on the line after the final parentheses, such as a
+comment, point can be on the next line. Thus, if your cursor is in
+the first column of the next line, you do not need to move it.
+Indeed, Emacs permits any amount of white space after the final
+parenthesis.)
@need 1200
When we evaluate the variable @code{animals}, we see that it is bound to
@code{hippopotamus}.
So we can see that @code{setcar} did not add a new element to the list
-as @code{cons} would have; it replaced @code{giraffe} with
+as @code{cons} would have; it replaced @code{antelope} with
@code{hippopotamus}; it @emph{changed} the list.
@node setcdr, cons Exercise, setcar, car cdr & cons
except that the function replaces the second and subsequent elements of
a list rather than the first element.
+(To see how to change the last element of a list, look ahead to
+@ref{kill-new function, , The @code{kill-new} function}, which uses
+the @code{nthcdr} and @code{setcdr} functions.)
+
@need 1200
To see how this works, set the value of the variable to a list of
domesticated animals by evaluating the following expression:
* 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.
-* copy-region-as-kill:: A definition for copying text.
* cons & search-fwd Review::
* search Exercises::
@end menu
@need 1200
@noindent
-The function @code{cons} can be used to to create a new list from a
-piece of text (an `atom', to use the jargon) and an existing list,
-like this:
+The function @code{cons} can be used to create a new list from a piece
+of text (an `atom', to use the jargon) and an existing list, like
+this:
@smallexample
@group
@section @code{zap-to-char}
@findex zap-to-char
-The @code{zap-to-char} function barely changed between GNU Emacs
-version 19 and GNU Emacs version 21. However, @code{zap-to-char}
-calls another function, @code{kill-region}, which enjoyed a major rewrite
-on the way to version 21.
+The @code{zap-to-char} function changed little between GNU Emacs
+version 19 and GNU Emacs version 22. However, @code{zap-to-char}
+calls another function, @code{kill-region}, which enjoyed a major
+rewrite.
The @code{kill-region} function in Emacs 19 is complex, but does not
use code that is important at this time. We will skip it.
-The @code{kill-region} function in Emacs 21 is easier to read than the
+The @code{kill-region} function in Emacs 22 is easier to read than the
same function in Emacs 19 and introduces a very important concept,
that of error handling. We will walk through the function.
@unnumberedsubsec The Complete @code{zap-to-char} Implementation
@end ifnottex
-The GNU Emacs version 19 and version 21 implementations of the
-@code{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 @code{zap-to-char}
-removes is put in the kill ring; and it can be retrieved from the kill
-ring by typing @kbd{C-y} (@code{yank}). If the command is given an
-argument, it removes text through that number of occurrences. Thus,
-if the cursor were at the beginning of this sentence and the character
-were @samp{s}, @samp{Thus} would be removed. If the argument were
-two, @samp{Thus, if the curs} would be removed, up to and including
-the @samp{s} in @samp{cursor}.
+The @code{zap-to-char} function removes the text in the region between
+the location of the cursor (i.e., of point) up to and including the
+next occurrence of a specified character. The text that
+@code{zap-to-char} removes is put in the kill ring; and it can be
+retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
+the command is given an argument, it removes text through that number
+of occurrences. Thus, if the cursor were at the beginning of this
+sentence and the character were @samp{s}, @samp{Thus} would be
+removed. If the argument were two, @samp{Thus, if the curs} would be
+removed, up to and including the @samp{s} in @samp{cursor}.
If the specified character is not found, @code{zap-to-char} will say
``Search failed'', tell you the character you typed, and not remove
manipulates text, and we will focus attention on them as well as on the
deletion command.
-@need 800
-Here is the complete text of the version 19 implementation of the function:
-
-@c v 19
-@smallexample
-@group
+@ignore
+@c GNU Emacs version 19
(defun zap-to-char (arg char) ; version 19 implementation
"Kill up to and including ARG'th occurrence of CHAR.
Goes backward if ARG is negative; error if CHAR not found."
(search-forward
(char-to-string char) nil nil arg)
(point))))
+@end ignore
+
+@need 1250
+Here is the complete text of the version 22 implementation of the function:
+
+@c GNU Emacs 22
+@smallexample
+@group
+(defun zap-to-char (arg char)
+ "Kill up to and including ARG'th occurrence of CHAR.
+Case is ignored if `case-fold-search' is non-nil in the current buffer.
+Goes backward if ARG is negative; error if CHAR not found."
+ (interactive "p\ncZap to char: ")
+ (if (char-table-p translation-table-for-input)
+ (setq char (or (aref translation-table-for-input char) char)))
+ (kill-region (point) (progn
+ (search-forward (char-to-string char) nil nil arg)
+ (point))))
@end group
@end smallexample
+The documentation is thorough. You do need to know the jargon meaning
+of the word `kill'.
+
@node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
@comment node-name, next, previous, up
@subsection The @code{interactive} Expression
this:
@smallexample
-(interactive "*p\ncZap to char: ")
+(interactive "p\ncZap to char: ")
@end smallexample
-The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies
-three different things. First, and most simply, the asterisk, @samp{*},
-causes an error to be signalled if the buffer is read-only. This means that
-if you try @code{zap-to-char} in a read-only buffer you will not be able to
-remove text, and you will receive a message that says ``Buffer is
-read-only''; your terminal may beep at you as well.
-
-The version 21 implementation does not have the asterisk, @samp{*}. The
-function works the same as in version 19: in both cases, it cannot
-remove text from a read-only buffer but the function does copy the
-text that would have been removed to the kill ring. Also, in both
-cases, you see an error message.
-
-However, the version 19 implementation copies text from a read-only
-buffer only because of a mistake in the implementation of
-@code{interactive}. According to the documentation for
-@code{interactive}, the asterisk, @samp{*}, should prevent the
-@code{zap-to-char} function from doing anything at all when the buffer
-is read only. The function should not copy the text to the kill ring.
-It is a bug that it does.
-
-In version 21, @code{interactive} is implemented correctly. So the
-asterisk, @samp{*}, had to be removed from the interactive
-specification. If you insert an @samp{*} and evaluate the function
-definition, then the next time you run the @code{zap-to-char} function
-on a read-only buffer, you will not copy any text.
-
-That change aside, and a change to the documentation, the two versions
-of the @code{zap-to-char} function are identical.
-
-Let us continue with the interactive specification.
-
-The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}.
+The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
+two different things. First, and most simply, is the @samp{p}.
This part is separated from the next part by a newline, @samp{\n}.
The @samp{p} means that the first argument to the function will be
passed the value of a `processed prefix'. The prefix argument is
the function is called interactively without a prefix, 1 is passed to
this argument.
-The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@:
-}. In this part, the lower case @samp{c} indicates that
-@code{interactive} expects a prompt and that the argument will be a
-character. The prompt follows the @samp{c} and is the string @samp{Zap
-to char:@: } (with a space after the colon to make it look good).
+The second part of @code{"p\ncZap to char:@: "} is
+@samp{cZap to char:@: }. In this part, the lower case @samp{c}
+indicates that @code{interactive} expects a prompt and that the
+argument will be a character. The prompt follows the @samp{c} and is
+the string @samp{Zap to char:@: } (with a space after the colon to
+make it look good).
What all this does is prepare the arguments to @code{zap-to-char} so they
are of the right type, and give the user a prompt.
+In a read-only buffer, the @code{zap-to-char} function copies the text
+to the kill ring, but does not remove it. The echo area displays a
+message saying that the buffer is read-only. Also, the terminal may
+beep or blink at you.
+
@node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
@comment node-name, next, previous, up
@subsection The Body of @code{zap-to-char}
The body of the @code{zap-to-char} function contains the code that
kills (that is, removes) the text in the region from the current
position of the cursor up to and including the specified character.
+
The first part of the code looks like this:
@smallexample
-(kill-region (point) @dots{}
+(if (char-table-p translation-table-for-input)
+ (setq char (or (aref translation-table-for-input char) char)))
+(kill-region (point) (progn
+ (search-forward (char-to-string char) nil nil arg)
+ (point)))
@end smallexample
+@noindent
+@code{char-table-p} is an hitherto unseen function. It determines
+whether its argument is a character table. When it is, it sets the
+character passed to @code{zap-to-char} to one of them, if that
+character exists, or to the character itself. (This becomes important
+for certain characters in non-European languages. The @code{aref}
+function extracts an element from an array. It is an array-specific
+function that is not described in this document. @xref{Arrays, ,
+Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
+
@noindent
@code{(point)} is the current position of the cursor.
zapped-for-character in @code{zap-to-char}. If the search is
successful, @code{search-forward} leaves point immediately after the
last character in the target string. (In @code{zap-to-char}, the
-target string is just one character long.) If the search is
-backwards, @code{search-forward} leaves point just before the first
-character in the target. Also, @code{search-forward} returns @code{t}
-for true. (Moving point is therefore a `side effect'.)
+target string is just one character long. @code{zap-to-char} uses the
+function @code{char-to-string} to ensure that the computer treats that
+character as a string.) If the search is backwards,
+@code{search-forward} leaves point just before the first character in
+the target. Also, @code{search-forward} returns @code{t} for true.
+(Moving point is therefore a `side effect'.)
@need 1250
In @code{zap-to-char}, the @code{search-forward} function looks like this:
The second and last argument to @code{progn} is the expression
@code{(point)}. This expression returns the value of point, which in
this case will be the location to which it has been moved by
-@code{search-forward}. This value is returned by the @code{progn}
-expression and is passed to @code{kill-region} as @code{kill-region}'s
-second argument.
+@code{search-forward}. (In the source, a line that tells the function
+to go to the previous character, if it is going forward, was commented
+out in 1999; I don't remember whether that feature or mis-feature was
+ever a part of the distributed source.) The value of @code{point} is
+returned by the @code{progn} expression and is passed to
+@code{kill-region} as @code{kill-region}'s second argument.
@node Summing up zap-to-char, , progn, zap-to-char
@comment node-name, next, previous, up
these two values of point, the first one as the beginning of the region
and the second one as the end of the region, and removes the region.
-The @code{progn} special form is necessary because the @code{kill-region}
-command takes two arguments; and it would fail if @code{search-forward}
-and @code{point} expressions were written in sequence as two
-additional arguments. The @code{progn} expression is a single argument
-to @code{kill-region} and returns the one value that @code{kill-region}
-needs for its second argument.
+The @code{progn} special form is necessary because the
+@code{kill-region} command takes two arguments; and it would fail if
+@code{search-forward} and @code{point} expressions were written in
+sequence as two additional arguments. The @code{progn} expression is
+a single argument to @code{kill-region} and returns the one value that
+@code{kill-region} needs for its second argument.
-@node kill-region, Digression into C, zap-to-char, Cutting & Storing Text
+@node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
@comment node-name, next, previous, up
@section @code{kill-region}
@findex kill-region
This function clips text from a region and copies that text to
the kill ring, from which it may be retrieved.
-The Emacs 21 version of that function uses @code{condition-case} and
+@ignore
+GNU Emacs 22:
+
+(defun kill-region (beg end &optional yank-handler)
+ "Kill (\"cut\") text between point and mark.
+This deletes the text from the buffer and saves it in the kill ring.
+The command \\[yank] can retrieve it from there.
+\(If you want to kill and then yank immediately, use \\[kill-ring-save].)
+
+If you want to append the killed region to the last killed text,
+use \\[append-next-kill] before \\[kill-region].
+
+If the buffer is read-only, Emacs will beep and refrain from deleting
+the text, but put the text in the kill ring anyway. This means that
+you can use the killing commands to copy text from a read-only buffer.
+
+This is the primitive for programs to kill text (as opposed to deleting it).
+Supply two arguments, character positions indicating the stretch of text
+ to be killed.
+Any command that calls this function is a \"kill command\".
+If the previous command was also a kill command,
+the text killed this time appends to the text killed last time
+to make one entry in the kill ring.
+
+In Lisp code, optional third arg YANK-HANDLER, if non-nil,
+specifies the yank-handler text property to be set on the killed
+text. See `insert-for-yank'."
+ ;; Pass point first, then mark, because the order matters
+ ;; when calling kill-append.
+ (interactive (list (point) (mark)))
+ (unless (and beg end)
+ (error "The mark is not set now, so there is no region"))
+ (condition-case nil
+ (let ((string (filter-buffer-substring beg end t)))
+ (when string ;STRING is nil if BEG = END
+ ;; Add that string to the kill ring, one way or another.
+ (if (eq last-command 'kill-region)
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler)))
+ (when (or string (eq last-command 'kill-region))
+ (setq this-command 'kill-region))
+ nil)
+ ((buffer-read-only text-read-only)
+ ;; The code above failed because the buffer, or some of the characters
+ ;; in the region, are read-only.
+ ;; We should beep, in case the user just isn't aware of this.
+ ;; However, there's no harm in putting
+ ;; the region's text in the kill ring, anyway.
+ (copy-region-as-kill beg end)
+ ;; Set this-command now, so it will be set even if we get an error.
+ (setq this-command 'kill-region)
+ ;; This should barf, if appropriate, and give us the correct error.
+ (if kill-read-only-ok
+ (progn (message "Read only text copied to kill ring") nil)
+ ;; Signal an error if the buffer is read-only.
+ (barf-if-buffer-read-only)
+ ;; If the buffer isn't read-only, the text is.
+ (signal 'text-read-only (list (current-buffer)))))))
+@end ignore
+
+The Emacs 22 version of that function uses @code{condition-case} and
@code{copy-region-as-kill}, both of which we will explain.
@code{condition-case} is an important special form.
@menu
* Complete kill-region:: The function definition.
* condition-case:: Dealing with a problem.
-* delete-and-extract-region:: Doing the work.
+* Lisp macro::
@end menu
@node Complete kill-region, condition-case, kill-region, kill-region
@need 1200
We will go through the @code{condition-case} code in a moment. First,
-let us look at the complete definition of @code{kill-region}, with
-comments added:
+let us look at the definition of @code{kill-region}, with comments
+added:
+
+@c GNU Emacs 22:
+@smallexample
+@group
+(defun kill-region (beg end)
+ "Kill (\"cut\") text between point and mark.
+This deletes the text from the buffer and saves it in the kill ring.
+The command \\[yank] can retrieve it from there. @dots{} "
+@end group
+
+@group
+ ;; @bullet{} Since order matters, pass point first.
+ (interactive (list (point) (mark)))
+ ;; @bullet{} And tell us if we cannot cut the text.
+ ;; `unless' is an `if' without a then-part.
+ (unless (and beg end)
+ (error "The mark is not set now, so there is no region"))
+@end group
+
+@group
+ ;; @bullet{} `condition-case' takes three arguments.
+ ;; If the first argument is nil, as it is here,
+ ;; information about the error signal is not
+ ;; stored for use by another function.
+ (condition-case nil
+@end group
+
+@group
+ ;; @bullet{} The second argument to `condition-case' tells the
+ ;; Lisp interpreter what to do when all goes well.
+@end group
+
+@group
+ ;; It starts with a `let' function that extracts the string
+ ;; and tests whether it exists. If so (that is what the
+ ;; `when' checks), it calls an `if' function that determines
+ ;; whether the previous command was another call to
+ ;; `kill-region'; if it was, then the new text is appended to
+ ;; the previous text; if not, then a different function,
+ ;; `kill-new', is called.
+@end group
+
+@group
+ ;; The `kill-append' function concatenates the new string and
+ ;; the old. The `kill-new' function inserts text into a new
+ ;; item in the kill ring.
+@end group
+
+@group
+ ;; `when' is an `if' without an else-part. The second `when'
+ ;; again checks whether the current string exists; in
+ ;; addition, it checks whether the previous command was
+ ;; another call to `kill-region'. If one or the other
+ ;; condition is true, then it sets the current command to
+ ;; be `kill-region'.
+@end group
+@group
+ (let ((string (filter-buffer-substring beg end t)))
+ (when string ;STRING is nil if BEG = END
+ ;; Add that string to the kill ring, one way or another.
+ (if (eq last-command 'kill-region)
+@end group
+@group
+ ;; @minus{} `yank-handler' is an optional argument to
+ ;; `kill-region' that tells the `kill-append' and
+ ;; `kill-new' functions how deal with properties
+ ;; added to the text, such as `bold' or `italics'.
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler)))
+ (when (or string (eq last-command 'kill-region))
+ (setq this-command 'kill-region))
+ nil)
+@end group
+
+@group
+ ;; @bullet{} The third argument to `condition-case' tells the interpreter
+ ;; what to do with an error.
+@end group
+@group
+ ;; The third argument has a conditions part and a body part.
+ ;; If the conditions are met (in this case,
+ ;; if text or buffer are read-only)
+ ;; then the body is executed.
+@end group
+@group
+ ;; The first part of the third argument is the following:
+ ((buffer-read-only text-read-only) ;; the if-part
+ ;; @dots{} the then-part
+ (copy-region-as-kill beg end)
+@end group
+@group
+ ;; Next, also as part of the then-part, set this-command, so
+ ;; it will be set in an error
+ (setq this-command 'kill-region)
+ ;; Finally, in the then-part, send a message if you may copy
+ ;; the text to the kill ring without signally an error, but
+ ;; don't if you may not.
+@end group
+@group
+ (if kill-read-only-ok
+ (progn (message "Read only text copied to kill ring") nil)
+ (barf-if-buffer-read-only)
+ ;; If the buffer isn't read-only, the text is.
+ (signal 'text-read-only (list (current-buffer)))))
+@end group
+@end smallexample
+@ignore
@c v 21
@smallexample
@group
@group
;; The third argument has a conditions part and a body part.
;; If the conditions are met (in this case,
- ;; if text or buffer is read-only)
+ ;; if text or buffer are read-only)
;; then the body is executed.
@end group
@group
(signal 'text-read-only (list (current-buffer)))))))
@end group
@end smallexample
+@end ignore
-@node condition-case, delete-and-extract-region, Complete kill-region, kill-region
+@node condition-case, Lisp macro, Complete kill-region, kill-region
@comment node-name, next, previous, up
@subsection @code{condition-case}
@findex condition-case
@end group
@end smallexample
-@node delete-and-extract-region, , condition-case, kill-region
-@comment node-name, next, previous, up
-@subsection @code{delete-and-extract-region}
-@findex delete-and-extract-region
-
-A @code{condition-case} expression has two parts, a part that is
-evaluated in the expectation that all will go well, but which may
-generate an error; and a part that is evaluated when there is an
-error.
-
-First, let us look at the code in @code{kill-region} that is run in
-the expectation that all goes well. This is the core of the function.
-The code looks like this:
-
-@smallexample
-@group
-(let ((string (delete-and-extract-region beg end)))
- (when string
- (if (eq last-command 'kill-region)
- (kill-append string (< end beg))
- (kill-new string)))
- (setq this-command 'kill-region))
-@end group
-@end smallexample
-
-It looks complicated because we have the new functions
-@code{delete-and-extract-region}, @code{kill-append}, and
-@code{kill-new} as well as the new variables,
-@code{last-command} and @code{this-command}.
-
-The @code{delete-and-extract-region} function is straightforward. It
-is a built-in function that deletes the text in a region (a side
-effect) and also returns that text. This is the function that
-actually removes the text. (And if it cannot do that, it signals the
-error.)
+@ignore
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
+
+see Initializing a Variable with @code{defvar}
+this is line 8054
+Initializing a Variable with @code{defvar} includes line 8350
+@end ignore
-In this @code{let} expression, the text that
-@code{delete-and-extract-region} returns is placed in the local
-variable called @samp{string}. This is the text that is removed from
-the buffer. (To be more precise, the variable is set to point to the
-address of the extracted text; to say it is `placed in' the variable
-is simply a shorthand.)
+@node Lisp macro, , condition-case, kill-region
+@comment node-name, next, previous, up
+@subsection Lisp macro
+@cindex Macro, lisp
+@cindex Lisp macro
-If the variable @samp{string} does point to text, that text is added
-to the kill ring. The variable will have a @code{nil} value if no
-text was removed.
+The part of the @code{condition-case} expression that is evaluated in
+the expectation that all goes well has a @code{when}. The code uses
+@code{when} to determine whether the @code{string} variable points to
+text that exists.
-The code uses @code{when} to determine whether the variable
-@samp{string} points to text. A @code{when} statement is simply a
-programmers' convenience. A @code{when} statement is an @code{if}
-statement without the possibility of an else clause. In your mind, you
-can replace @code{when} with @code{if} and understand what goes on.
-That is what the Lisp interpreter does.
+A @code{when} expression is simply a programmers' convenience. It is
+an @code{if} without the possibility of an else clause. In your mind,
+you can replace @code{when} with @code{if} and understand what goes
+on. That is what the Lisp interpreter does.
-@cindex Macro, lisp
-@cindex Lisp macro
Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
enables you to define new control constructs and other language
features. It tells the interpreter how to compute another Lisp
expression which will in turn compute the value. In this case, the
-`other expression' is an @code{if} expression. For more about Lisp
-macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
-Manual}. The C programming language also provides macros. These are
-different, but also useful. We will briefly look at C macros in
+`other expression' is an @code{if} expression.
+
+The @code{kill-region} function definition also has an @code{unless}
+macro; it is the converse of @code{when}. The @code{unless} macro is
+an @code{if} without a then clause
+
+For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
+Emacs Lisp Reference Manual}. The C programming language also
+provides macros. These are different, but also useful.
+
+@ignore
+We will briefly look at C macros in
@ref{Digression into C}.
+@end ignore
@need 1200
-If the string has content, then another conditional expression is
-executed. This is an @code{if} with both a then-part and an else-part.
+Regarding the @code{when} macro, in the @code{condition-case}
+expression, when the string has content, then another conditional
+expression is executed. This is an @code{if} with both a then-part
+and an else-part.
@smallexample
@group
(if (eq last-command 'kill-region)
- (kill-append string (< end beg))
- (kill-new string)))
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler))
@end group
@end smallexample
The then-part is evaluated if the previous command was another call to
@code{kill-region}; if not, the else-part is evaluated.
+@code{yank-handler} is an optional argument to @code{kill-region} that
+tells the @code{kill-append} and @code{kill-new} functions how deal
+with properties added to the text, such as `bold' or `italics'.
+
@code{last-command} is a variable that comes with Emacs that we have
not seen before. Normally, whenever a function is executed, Emacs
sets the value of @code{last-command} to the previous command.
whether the previous command was @code{kill-region}. If it was,
@smallexample
-(kill-append string (< end beg))
+(kill-append string (< end beg) yank-handler)
@end smallexample
@noindent
concatenates a copy of the newly clipped text to the just previously
-clipped text in the kill ring. (If the @w{@code{(< end beg))}}
-expression is true, @code{kill-append} prepends the string to the just
-previously clipped text. For a detailed discussion, see
-@ref{kill-append function, , The @code{kill-append} function}.)
-
-If you then yank back the text, i.e., `paste' it, you get both
-pieces of text at once. That way, if you delete two words in a row,
-and then yank them back, you get both words, in their proper order,
-with one yank. (The @w{@code{(< end beg))}} expression makes sure the
-order is correct.)
-
-On the other hand, if the previous command is not @code{kill-region},
-then the @code{kill-new} function is called, which adds the text to
-the kill ring as the latest item, and sets the
-@code{kill-ring-yank-pointer} variable to point to it.
+clipped text in the kill ring.
-@node Digression into C, defvar, kill-region, Cutting & Storing Text
+@node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
@comment node-name, next, previous, up
-@section Digression into C
-@findex delete-and-extract-region
-@cindex C, a digression into
-@cindex Digression into C
+@section @code{copy-region-as-kill}
+@findex copy-region-as-kill
+@findex nthcdr
+
+The @code{copy-region-as-kill} function copies a region of text from a
+buffer and (via either @code{kill-append} or @code{kill-new}) saves it
+in the @code{kill-ring}.
-The @code{zap-to-char} command uses the
-@code{delete-and-extract-region} function, which in turn uses two
-other functions, @code{copy-region-as-kill} and
-@code{del_range_1}. The @code{copy-region-as-kill} function will be
-described in a following section; it puts a copy of the region in the
-kill ring so it can be yanked back. (@xref{copy-region-as-kill, ,
-@code{copy-region-as-kill}}.)
+If you call @code{copy-region-as-kill} immediately after a
+@code{kill-region} command, Emacs appends the newly copied text to the
+previously copied text. This means that if you yank back the text, you
+get it all, from both this and the previous operation. On the other
+hand, if some other command precedes the @code{copy-region-as-kill},
+the function copies the text into a separate entry in the kill ring.
-The @code{delete-and-extract-region} function removes the contents of
-a region and you cannot get them back.
+@menu
+* Complete copy-region-as-kill:: The complete function definition.
+* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
+@end menu
-Unlike the other code discussed here, @code{delete-and-extract-region}
-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.
+@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
+@ifnottex
+@unnumberedsubsec The complete @code{copy-region-as-kill} function definition
+@end ifnottex
-@need 1500
-Like many of the other Emacs primitives,
-@code{delete-and-extract-region} is written as an instance of a C
-macro, a macro being a template for code. The complete macro looks
-like this:
+@need 1200
+Here is the complete text of the version 22 @code{copy-region-as-kill}
+function:
-@c /usr/local/src/emacs/src/editfns.c
@smallexample
@group
-DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
- Sdelete_and_extract_region, 2, 2, 0,
- "Delete the text between START and END and return it.")
- (start, end)
- Lisp_Object start, end;
-@{
- validate_region (&start, &end);
- return del_range_1 (XINT (start), XINT (end), 1, 1);
-@}
+(defun copy-region-as-kill (beg end)
+ "Save the region as if killed, but don't kill it.
+In Transient Mark mode, deactivate the mark.
+If `interprogram-cut-function' is non-nil, also save the text for a window
+system cut and paste."
+ (interactive "r")
+@end group
+@group
+ (if (eq last-command 'kill-region)
+ (kill-append (filter-buffer-substring beg end) (< end beg))
+ (kill-new (filter-buffer-substring beg end)))
+@end group
+@group
+ (if transient-mark-mode
+ (setq deactivate-mark t))
+ nil)
@end group
@end smallexample
-Without going into the details of the macro writing process, let me
-point out that this macro starts with the word @code{DEFUN}. The word
-@code{DEFUN} was chosen since the code serves the same purpose as
-@code{defun} does in Lisp. The word @code{DEFUN} is followed by seven
-parts inside of parentheses:
+@need 800
+As usual, this function can be divided into its component parts:
-@itemize @bullet
-@item
-The first part is the name given to the function in Lisp,
-@code{delete-and-extract-region}.
+@smallexample
+@group
+(defun copy-region-as-kill (@var{argument-list})
+ "@var{documentation}@dots{}"
+ (interactive "r")
+ @var{body}@dots{})
+@end group
+@end smallexample
-@item
-The second part is the name of the function in C,
-@code{Fdelete_and_extract_region}. By convention, it starts with
-@samp{F}. Since C does not use hyphens in names, underscores are used
-instead.
+The arguments are @code{beg} and @code{end} and the function is
+interactive with @code{"r"}, so the two arguments must refer to the
+beginning and end of the region. If you have been reading though this
+document from the beginning, understanding these parts of a function is
+almost becoming routine.
-@item
-The third part is the name for the C constant structure that records
-information on this function for internal use. It is the name of the
-function in C but begins with an @samp{S} instead of an @samp{F}.
+The documentation is somewhat confusing unless you remember that the
+word `kill' has a meaning different from usual. The `Transient Mark'
+and @code{interprogram-cut-function} comments explain certain
+side-effects.
-@item
-The fourth and fifth parts specify the minimum and maximum number of
-arguments the function can have. This function demands exactly 2
-arguments.
+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.)
-@item
-The sixth part is nearly like the argument that follows the
-@code{interactive} declaration in a function written in Lisp: a letter
-followed, perhaps, by a prompt. The only difference from the Lisp is
-when the macro is called with no arguments. Then you write a @code{0}
-(which is a `null string'), as in this macro.
+Also, a windowing system allows you to copy, cut, and paste among
+different programs. In the X windowing system, for example, the
+@code{interprogram-cut-function} function is @code{x-select-text},
+which works with the windowing system's equivalent of the Emacs kill
+ring.
-If you were to specify arguments, you would place them between
-quotation marks. The C macro for @code{goto-char} includes
-@code{"NGoto char: "} in this position to indicate that the function
-expects a raw prefix, in this case, a numerical location in a buffer,
-and provides a prompt.
+The body of the @code{copy-region-as-kill} function starts with an
+@code{if} clause. What this clause does is distinguish between two
+different situations: whether or not this command is executed
+immediately after a previous @code{kill-region} command. In the first
+case, the new region is appended to the previously copied text.
+Otherwise, it is inserted into the beginning of the kill ring as a
+separate piece of text from the previous piece.
-@item
-The seventh part is a documentation string, just like the one for a
-function written in Emacs Lisp, except that every newline must be
-written explicitly as @samp{\n} followed by a backslash and carriage
-return.
+The last two lines of the function prevent the region from lighting up
+if Transient Mark mode is turned on.
-@need 1000
-Thus, the first two lines of documentation for @code{goto-char} are
-written like this:
+The body of @code{copy-region-as-kill} merits discussion in detail.
-@smallexample
-@group
- "Set point to POSITION, a number or marker.\n\
-Beginning of buffer is position (point-min), end is (point-max).
-@end group
-@end smallexample
-@end itemize
+@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
+@comment node-name, next, previous, up
+@subsection The Body of @code{copy-region-as-kill}
-@need 1200
-In a C macro, the formal parameters come next, with a statement of
-what kind of object they are, followed by what might be called the `body'
-of the macro. For @code{delete-and-extract-region} the `body'
-consists of the following two lines:
+The @code{copy-region-as-kill} function works in much the same way as
+the @code{kill-region} function. Both are written so that two or more
+kills in a row combine their text into a single entry. If you yank
+back the text from the kill ring, you get it all in one piece.
+Moreover, kills that kill forward from the current position of the
+cursor are added to the end of the previously copied text and commands
+that copy text backwards add it to the beginning of the previously
+copied text. This way, the words in the text stay in the proper
+order.
+
+Like @code{kill-region}, the @code{copy-region-as-kill} function makes
+use of the @code{last-command} variable that keeps track of the
+previous Emacs command.
+
+@menu
+* last-command & this-command::
+* kill-append function::
+* kill-new function::
+@end menu
+
+@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
+@ifnottex
+@unnumberedsubsubsec @code{last-command} and @code{this-command}
+@end ifnottex
+
+Normally, whenever a function is executed, Emacs sets the value of
+@code{this-command} to the function being executed (which in this case
+would be @code{copy-region-as-kill}). At the same time, Emacs sets
+the value of @code{last-command} to the previous value of
+@code{this-command}.
+
+In the first part of the body of the @code{copy-region-as-kill}
+function, an @code{if} expression determines whether the value of
+@code{last-command} is @code{kill-region}. If so, the then-part of
+the @code{if} expression is evaluated; it uses the @code{kill-append}
+function to concatenate the text copied at this call to the function
+with the text already in the first element (the @sc{car}) of the kill
+ring. On the other hand, if the value of @code{last-command} is not
+@code{kill-region}, then the @code{copy-region-as-kill} function
+attaches a new element to the kill ring using the @code{kill-new}
+function.
+
+@need 1250
+The @code{if} expression reads as follows; it uses @code{eq}:
@smallexample
@group
-validate_region (&start, &end);
-return del_range_1 (XINT (start), XINT (end), 1, 1);
+ (if (eq last-command 'kill-region)
+ ;; @r{then-part}
+ (kill-append (filter-buffer-substring beg end) (< end beg))
+ ;; @r{else-part}
+ (kill-new (filter-buffer-substring beg end)))
@end group
@end smallexample
-The first function, @code{validate_region} checks whether the values
-passed as the beginning and end of the region are the proper type and
-are within range. The second function, @code{del_range_1}, actually
-deletes the text.
-
-@code{del_range_1} is a complex function we will not look into. It
-updates the buffer and does other things.
+@findex filter-buffer-substring
+(The @code{filter-buffer-substring} function returns a filtered
+substring of the buffer, if any. Optionally---the arguments are not
+here, so neither is done---the function may delete the initial text or
+return the text without its properties; this function is a replacement
+for the older @code{buffer-substring} function, which came before text
+properties were implemented.)
-However, it is worth looking at the two arguments passed to
-@code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT
-(end)}}.
-
-As far as the C language is concerned, @code{start} and @code{end} are
-two integers that mark the beginning and end of the region to be
-deleted@footnote{More precisely, and requiring more expert knowledge
-to understand, the two integers are of type `Lisp_Object', which can
-also be a C union instead of an integer type.}.
+@findex eq @r{(example of use)}
+@noindent
+The @code{eq} function tests whether its first argument is the same Lisp
+object as its second argument. The @code{eq} function is similar to the
+@code{equal} function in that it is used to test for equality, but
+differs in that it determines whether two representations are actually
+the same object inside the computer, but with different names.
+@code{equal} determines whether the structure and contents of two
+expressions are the same.
-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 and a fourth bit is used for handling the computer's
-memory; the remaining bits are used as `content'.
+If the previous command was @code{kill-region}, then the Emacs Lisp
+interpreter calls the @code{kill-append} function
-@samp{XINT} is a C macro that extracts the relevant number from the
-longer collection of bits; the four other bits are discarded.
+@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
+@unnumberedsubsubsec The @code{kill-append} function
+@findex kill-append
@need 800
-The command in @code{delete-and-extract-region} looks like this:
+The @code{kill-append} function looks like this:
+@c in GNU Emacs 22
@smallexample
-del_range_1 (XINT (start), XINT (end), 1, 1);
+@group
+(defun kill-append (string before-p &optional yank-handler)
+ "Append STRING to the end of the latest kill in the kill ring.
+If BEFORE-P is non-nil, prepend STRING to the kill.
+@dots{} "
+ (let* ((cur (car kill-ring)))
+ (kill-new (if before-p (concat string cur) (concat cur string))
+ (or (= (length cur) 0)
+ (equal yank-handler
+ (get-text-property 0 'yank-handler cur)))
+ yank-handler)))
+@end group
@end smallexample
-@noindent
-It deletes the region between the beginning position, @code{start},
-and the ending position, @code{end}.
+@ignore
+was:
+(defun kill-append (string before-p)
+ "Append STRING to the end of the latest kill in the kill ring.
+If BEFORE-P is non-nil, prepend STRING to the kill.
+If `interprogram-cut-function' is set, pass the resulting kill to
+it."
+ (kill-new (if before-p
+ (concat string (car kill-ring))
+ (concat (car kill-ring) string))
+ t))
+@end ignore
-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.
+@noindent
+The @code{kill-append} function is fairly straightforward. It uses
+the @code{kill-new} function, which we will discuss in more detail in
+a moment.
-@node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section Initializing a Variable with @code{defvar}
-@findex defvar
-@cindex Initializing a variable
-@cindex Variable initialization
+(Also, the function provides an optional argument called
+@code{yank-handler}; when invoked, this argument tells the function
+how to deal with properties added to the text, such as `bold' or
+`italics'.)
-Unlike the @code{delete-and-extract-region} function, the
-@code{copy-region-as-kill} function is written in Emacs Lisp. Two
-functions within it, @code{kill-append} and @code{kill-new}, copy a
-region in a buffer and save it in a variable called the
-@code{kill-ring}. This section describes how the @code{kill-ring}
-variable is created and initialized using the @code{defvar} special
-form.
+@c !!! bug in GNU Emacs 22 version of kill-append ?
+It has a @code{let*} function to set the value of the first element of
+the kill ring to @code{cur}. (I do not know why the function does not
+use @code{let} instead; only one value is set in the expression.
+Perhaps this is a bug that produces no problems?)
-(Again we note that the term @code{kill-ring} is a misnomer. The text
-that is clipped out of the buffer can be brought back; it is not a ring
-of corpses, but a ring of resurrectable text.)
+Consider the conditional that is one of the two arguments to
+@code{kill-new}. It uses @code{concat} to concatenate the new text to
+the @sc{car} of the kill ring. Whether it prepends or appends the
+text depends on the results of an @code{if} expression:
-In Emacs Lisp, a variable such as the @code{kill-ring} is created and
-given an initial value by using the @code{defvar} special form. The
-name comes from ``define variable''.
+@smallexample
+@group
+(if before-p ; @r{if-part}
+ (concat string cur) ; @r{then-part}
+ (concat cur string)) ; @r{else-part}
+@end group
+@end smallexample
-The @code{defvar} special form is similar to @code{setq} in that it sets
-the value of a variable. It is unlike @code{setq} in two ways: first,
-it only sets the value of the variable if the variable does not already
-have a value. If the variable already has a value, @code{defvar} does
-not override the existing value. Second, @code{defvar} has a
-documentation string.
+@noindent
+If the region being killed is before the region that was killed in the
+last command, then it should be prepended before the material that was
+saved in the previous kill; and conversely, if the killed text follows
+what was just killed, it should be appended after the previous text.
+The @code{if} expression depends on the predicate @code{before-p} to
+decide whether the newly saved text should be put before or after the
+previously saved text.
-(Another special form, @code{defcustom}, is designed for variables
-that people customize. It has more features than @code{defvar}.
-(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
+The symbol @code{before-p} is the name of one of the arguments to
+@code{kill-append}. When the @code{kill-append} function is
+evaluated, it is bound to the value returned by evaluating the actual
+argument. In this case, this is the expression @code{(< end beg)}.
+This expression does not directly determine whether the killed text in
+this command is located before or after the kill text of the last
+command; what it does is determine whether the value of the variable
+@code{end} is less than the value of the variable @code{beg}. If it
+is, it means that the user is most likely heading towards the
+beginning of the buffer. Also, the result of evaluating the predicate
+expression, @code{(< end beg)}, will be true and the text will be
+prepended before the previous text. On the other hand, if the value of
+the variable @code{end} is greater than the value of the variable
+@code{beg}, the text will be appended after the previous text.
-@menu
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
-@end menu
+@need 800
+When the newly saved text will be prepended, then the string with the new
+text will be concatenated before the old text:
-@node See variable current value, defvar and asterisk, defvar, defvar
-@ifnottex
-@unnumberedsubsec Seeing the Current Value of a Variable
-@end ifnottex
+@smallexample
+(concat string cur)
+@end smallexample
-You can see the current value of a variable, any variable, by using
-the @code{describe-variable} function, which is usually invoked by
-typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
-(followed by @key{RET}) when prompted, you will see what is in your
-current kill ring---this may be quite a lot! Conversely, if you have
-been doing nothing this Emacs session except read this document, you
-may have nothing in it. Also, you will see the documentation for
-@code{kill-ring}:
+@need 1200
+@noindent
+But if the text will be appended, it will be concatenated
+after the old text:
@smallexample
-@group
-Documentation:
-List of killed text sequences.
-Since the kill ring is supposed to interact nicely with cut-and-paste
-facilities offered by window systems, use of this variable should
-@end group
-@group
-interact nicely with `interprogram-cut-function' and
-`interprogram-paste-function'. The functions `kill-new',
-`kill-append', and `current-kill' are supposed to implement this
-interaction; you may want to use them instead of manipulating the kill
-ring directly.
-@end group
+(concat cur string))
@end smallexample
-@need 800
-The kill ring is defined by a @code{defvar} in the following way:
+To understand how this works, we first need to review the
+@code{concat} function. The @code{concat} function links together or
+unites two strings of text. The result is a string. For example:
@smallexample
@group
-(defvar kill-ring nil
- "List of killed text sequences.
-@dots{}")
+(concat "abc" "def")
+ @result{} "abcdef"
@end group
-@end smallexample
-@noindent
-In this variable definition, the variable is given an initial value of
-@code{nil}, which makes sense, since if you have saved nothing, you want
-nothing back if you give a @code{yank} command. The documentation
-string is written just like the documentation string of a @code{defun}.
-As with the documentation string of the @code{defun}, the first line of
-the documentation should be a complete sentence, since some commands,
-like @code{apropos}, print only the first line of documentation.
-Succeeding lines should not be indented; otherwise they look odd when
-you use @kbd{C-h v} (@code{describe-variable}).
+@group
+(concat "new "
+ (car '("first element" "second element")))
+ @result{} "new first element"
-@node defvar and asterisk, , See variable current value, defvar
-@subsection @code{defvar} and an asterisk
-@findex defvar @r{for a user customizable variable}
-@findex defvar @r{with an asterisk}
+(concat (car
+ '("first element" "second element")) " modified")
+ @result{} "first element modified"
+@end group
+@end smallexample
-In the past, Emacs used the @code{defvar} special form both for
-internal variables that you would not expect a user to change and for
-variables that you do expect a user to change. Although you can still
-use @code{defvar} for user customizable variables, please use
-@code{defcustom} instead, since that special form provides a path into
-the Customization commands. (@xref{defcustom, , Setting Variables
-with @code{defcustom}}.)
+We can now make sense of @code{kill-append}: it modifies the contents
+of the kill ring. The kill ring is a list, each element of which is
+saved text. The @code{kill-append} function uses the @code{kill-new}
+function which in turn uses the @code{setcar} function.
-When you specified a variable using the @code{defvar} special form,
-you could distinguish a readily settable variable from others by
-typing an asterisk, @samp{*}, in the first column of its documentation
-string. For example:
+@node kill-new function, , kill-append function, copy-region-as-kill body
+@unnumberedsubsubsec The @code{kill-new} function
+@findex kill-new
+
+@c in GNU Emacs 22, additional documentation to kill-new:
+@ignore
+Optional third arguments YANK-HANDLER controls how the STRING is later
+inserted into a buffer; see `insert-for-yank' for details.
+When a yank handler is specified, STRING must be non-empty (the yank
+handler, if non-nil, is stored as a `yank-handler' text property on STRING).
+
+When the yank handler has a non-nil PARAM element, the original STRING
+argument is not used by `insert-for-yank'. However, since Lisp code
+may access and use elements from the kill ring directly, the STRING
+argument should still be a \"useful\" string for such uses."
+@end ignore
+@need 1200
+The @code{kill-new} function looks like this:
@smallexample
@group
-(defvar shell-command-default-error-buffer nil
- "*Buffer name for `shell-command' @dots{} error output.
-@dots{} ")
+(defun kill-new (string &optional replace yank-handler)
+ "Make STRING the latest kill in the kill ring.
+Set `kill-ring-yank-pointer' to point to it.
+
+If `interprogram-cut-function' is non-nil, apply it to STRING.
+Optional second argument REPLACE non-nil means that STRING will replace
+the front of the kill ring, rather than being added to the list.
+@dots{}"
+@end group
+@group
+ (if (> (length string) 0)
+ (if yank-handler
+ (put-text-property 0 (length string)
+ 'yank-handler yank-handler string))
+ (if yank-handler
+ (signal 'args-out-of-range
+ (list string "yank-handler specified for empty string"))))
+@end group
+@group
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+@end group
+@group
+ (if (and replace kill-ring)
+ (setcar kill-ring string)
+ (push string kill-ring)
+ (if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+@end group
+@group
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
+@ignore
+was:
+(defun kill-new (string &optional replace)
+ "Make STRING the latest kill in the kill ring.
+Set the kill-ring-yank pointer to point to it.
+If `interprogram-cut-function' is non-nil, apply it to STRING.
+Optional second argument REPLACE non-nil means that STRING will replace
+the front of the kill ring, rather than being added to the list."
+ (and (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+ (if (and replace kill-ring)
+ (setcar kill-ring string)
+ (setq kill-ring (cons string kill-ring))
+ (if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
+@end ignore
-@noindent
-This means that you could (and still can) use the @code{edit-options}
-command to change the value of
-@code{shell-command-default-error-buffer} temporarily.
-
-@findex edit-options
-However, options set using @code{edit-options} are set only for the
-duration of your editing session. The new values are not saved
-between sessions. Each time Emacs starts, it reads the original
-value, unless you change the value within your @file{.emacs} file,
-either by setting it manually or by using @code{customize}.
-@xref{Emacs Initialization, , Your @file{.emacs} File}.
+(Notice that the function is not interactive.)
-For me, the major use of the @code{edit-options} command is to suggest
-variables that I might want to set in my @file{.emacs} file. I urge
-you to look through the list. (@xref{Edit Options, , Editing Variable
-Values, emacs, The GNU Emacs Manual}.)
+As usual, we can look at this function in parts.
-@node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section @code{copy-region-as-kill}
-@findex copy-region-as-kill
-@findex nthcdr
+The function definition has an optional @code{yank-handler} argument,
+which when invoked tells the function how to deal with properties
+added to the text, such as `bold' or `italics'. We will skip that.
-The @code{copy-region-as-kill} function copies a region of text from a
-buffer and (via either @code{kill-append} or @code{kill-new}) saves it
-in the @code{kill-ring}.
+@need 1200
+The first line of the documentation makes sense:
-If you call @code{copy-region-as-kill} immediately after a
-@code{kill-region} command, Emacs appends the newly copied text to the
-previously copied text. This means that if you yank back the text, you
-get it all, from both this and the previous operation. On the other
-hand, if some other command precedes the @code{copy-region-as-kill},
-the function copies the text into a separate entry in the kill ring.
+@smallexample
+Make STRING the latest kill in the kill ring.
+@end smallexample
-@menu
-* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
-@end menu
+@noindent
+Let's skip over the rest of the documentation for the moment.
-@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
-@ifnottex
-@unnumberedsubsec The complete @code{copy-region-as-kill} function definition
-@end ifnottex
+@noindent
+Also, let's skip over the initial @code{if} expression and those lines
+of code involving @code{menu-bar-update-yank-menu}. We will explain
+them below.
@need 1200
-Here is the complete text of the version 21 @code{copy-region-as-kill}
-function:
+The critical lines are these:
@smallexample
@group
-(defun copy-region-as-kill (beg end)
- "Save the region as if killed, but don't kill it.
-In Transient Mark mode, deactivate the mark.
-If `interprogram-cut-function' is non-nil, also save
-the text for a window system cut and paste."
- (interactive "r")
+ (if (and replace kill-ring)
+ ;; @r{then}
+ (setcar kill-ring string)
@end group
@group
- (if (eq last-command 'kill-region)
- (kill-append (buffer-substring beg end) (< end beg))
- (kill-new (buffer-substring beg end)))
+ ;; @r{else}
+ (push string kill-ring)
@end group
@group
- (if transient-mark-mode
- (setq deactivate-mark t))
- nil)
+ (setq kill-ring (cons string kill-ring))
+ (if (> (length kill-ring) kill-ring-max)
+ ;; @r{avoid overly long kill ring}
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+@end group
+@group
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
-@need 800
-As usual, this function can be divided into its component parts:
+The conditional test is @w{@code{(and replace kill-ring)}}.
+This will be true when two conditions are met: the kill ring has
+something in it, and the @code{replace} variable is true.
+
+@need 1250
+When the @code{kill-append} function sets @code{replace} to be true
+and when the kill ring has at least one item in it, the @code{setcar}
+expression is executed:
@smallexample
-@group
-(defun copy-region-as-kill (@var{argument-list})
- "@var{documentation}@dots{}"
- (interactive "r")
- @var{body}@dots{})
-@end group
+(setcar kill-ring string)
@end smallexample
-The arguments are @code{beg} and @code{end} and the function is
-interactive with @code{"r"}, so the two arguments must refer to the
-beginning and end of the region. If you have been reading though this
-document from the beginning, understanding these parts of a function is
-almost becoming routine.
-
-The documentation is somewhat confusing unless you remember that the
-word `kill' has a meaning different from its usual meaning. The
-`Transient Mark' and @code{interprogram-cut-function} comments explain
-certain side-effects.
+The @code{setcar} function actually changes the first element of the
+@code{kill-ring} list to the value of @code{string}. It replaces the
+first element.
-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.)
+@need 1250
+On the other hand, if the kill ring is empty, or replace is false, the
+else-part of the condition is executed:
-Also, a windowing system allows you to copy, cut, and paste among
-different programs. In the X windowing system, for example, the
-@code{interprogram-cut-function} function is @code{x-select-text},
-which works with the windowing system's equivalent of the Emacs kill
-ring.
+@smallexample
+(push string kill-ring)
+@end smallexample
-The body of the @code{copy-region-as-kill} function starts with an
-@code{if} clause. What this clause does is distinguish between two
-different situations: whether or not this command is executed
-immediately after a previous @code{kill-region} command. In the first
-case, the new region is appended to the previously copied text.
-Otherwise, it is inserted into the beginning of the kill ring as a
-separate piece of text from the previous piece.
+@noindent
+@need 1250
+@code{push} puts its first argument onto the second. It is similar to
+the older
-The last two lines of the function prevent the region from lighting up
-if Transient Mark mode is turned on.
+@smallexample
+(setq kill-ring (cons string kill-ring))
+@end smallexample
-The body of @code{copy-region-as-kill} merits discussion in detail.
+@noindent
+@need 1250
+or the newer
-@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
-@comment node-name, next, previous, up
-@subsection The Body of @code{copy-region-as-kill}
+@smallexample
+(add-to-list kill-ring string)
+@end smallexample
-The @code{copy-region-as-kill} function works in much the same way as
-the @code{kill-region} function (@pxref{kill-region,
-,@code{kill-region}}). 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.
+@noindent
+When it is false, the expression first constructs a new version of the
+kill ring by prepending @code{string} to the existing kill ring as a
+new element (that is what the @code{push} does). Then it executes a
+second @code{if} clause. This second @code{if} clause keeps the kill
+ring from growing too long.
-Like @code{kill-region}, the @code{copy-region-as-kill} function makes
-use of the @code{last-command} variable that keeps track of the
-previous Emacs command.
+Let's look at these two expressions in order.
-@menu
-* last-command & this-command::
-* kill-append function::
-* kill-new function::
-@end menu
+The @code{push} line of the else-part sets the new value of the kill
+ring to what results from adding the string being killed to the old
+kill ring.
-@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
-@ifnottex
-@unnumberedsubsubsec @code{last-command} and @code{this-command}
-@end ifnottex
+We can see how this works with an example.
-Normally, whenever a function is executed, Emacs sets the value of
-@code{this-command} to the function being executed (which in this case
-would be @code{copy-region-as-kill}). At the same time, Emacs sets
-the value of @code{last-command} to the previous value of
-@code{this-command}.
+@need 800
+First,
-In the first part of the body of the @code{copy-region-as-kill}
-function, an @code{if} expression determines whether the value of
-@code{last-command} is @code{kill-region}. If so, the then-part of
-the @code{if} expression is evaluated; it uses the @code{kill-append}
-function to concatenate the text copied at this call to the function
-with the text already in the first element (the @sc{car}) of the kill
-ring. On the other hand, if the value of @code{last-command} is not
-@code{kill-region}, then the @code{copy-region-as-kill} function
-attaches a new element to the kill ring using the @code{kill-new}
-function.
+@smallexample
+(setq example-list '("here is a clause" "another clause"))
+@end smallexample
-@need 1250
-The @code{if} expression reads as follows; it uses @code{eq}, which is
-a function we have not yet seen:
+@need 1200
+@noindent
+After evaluating this expression with @kbd{C-x C-e}, you can evaluate
+@code{example-list} and see what it returns:
@smallexample
@group
- (if (eq last-command 'kill-region)
- ;; @r{then-part}
- (kill-append (buffer-substring beg end) (< end beg))
- ;; @r{else-part}
- (kill-new (buffer-substring beg end)))
+example-list
+ @result{} ("here is a clause" "another clause")
@end group
@end smallexample
-@findex eq @r{(example of use)}
+@need 1200
@noindent
-The @code{eq} function tests whether its first argument is the same Lisp
-object as its second argument. The @code{eq} function is similar to the
-@code{equal} function in that it is used to test for equality, but
-differs in that it determines whether two representations are actually
-the same object inside the computer, but with different names.
-@code{equal} determines whether the structure and contents of two
-expressions are the same.
-
-If the previous command was @code{kill-region}, then the Emacs Lisp
-interpreter calls the @code{kill-append} function
+Now, we can add a new element on to this list by evaluating the
+following expression:
+@findex push, @r{example}
-@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
-@unnumberedsubsubsec The @code{kill-append} function
-@findex kill-append
+@smallexample
+(push "a third clause" example-list)
+@end smallexample
@need 800
-The @code{kill-append} function looks like this:
+@noindent
+When we evaluate @code{example-list}, we find its value is:
@smallexample
@group
-(defun kill-append (string before-p)
- "Append STRING to the end of the latest kill in the kill ring.
-If BEFORE-P is non-nil, prepend STRING to the kill.
-If `interprogram-cut-function' is set, pass the resulting kill to
-it."
- (kill-new (if before-p
- (concat string (car kill-ring))
- (concat (car kill-ring) string))
- t))
+example-list
+ @result{} ("a third clause" "here is a clause" "another clause")
@end group
@end smallexample
@noindent
-The @code{kill-append} function is fairly straightforward. It uses
-the @code{kill-new} function, which we will discuss in more detail in
-a moment.
+Thus, the third clause is added to the list by @code{push}.
+
+@need 1200
+Now for the second part of the @code{if} clause. This expression
+keeps the kill ring from growing too long. It looks like this:
+
+@smallexample
+@group
+(if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
+@end group
+@end smallexample
+
+The code checks whether the length of the kill ring is greater than
+the maximum permitted length. This is the value of
+@code{kill-ring-max} (which is 60, by default). If the length of the
+kill ring is too long, then this code sets the last element of the
+kill ring to @code{nil}. It does this by using two functions,
+@code{nthcdr} and @code{setcdr}.
+
+We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
+It sets the @sc{cdr} of a list, just as @code{setcar} sets the
+@sc{car} of a list. In this case, however, @code{setcdr} will not be
+setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
+function is used to cause it to set the @sc{cdr} of the next to last
+element of the kill ring---this means that since the @sc{cdr} of the
+next to last element is the last element of the kill ring, it will set
+the last element of the kill ring.
+
+@findex nthcdr, @r{example}
+The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
+list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
+@dots{} It does this @var{N} times and returns the results.
+(@xref{nthcdr, , @code{nthcdr}}.)
-First, let us look at the conditional that is one of the two arguments
-to @code{kill-new}. It uses @code{concat} to concatenate the new text
-to the @sc{car} of the kill ring. Whether it prepends or appends the
-text depends on the results of an @code{if} expression:
+@findex setcdr, @r{example}
+Thus, if we had a four element list that was supposed to be three
+elements long, we could set the @sc{cdr} of the next to last element
+to @code{nil}, and thereby shorten the list. (If you set the last
+element to some other value than @code{nil}, which you could do, then
+you would not have shortened the list. @xref{setcdr, ,
+@code{setcdr}}.)
+
+You can see shortening by evaluating the following three expressions
+in turn. First set the value of @code{trees} to @code{(maple oak pine
+birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
+and then find the value of @code{trees}:
@smallexample
@group
-(if before-p ; @r{if-part}
- (concat string (car kill-ring)) ; @r{then-part}
- (concat (car kill-ring) string)) ; @r{else-part}
+(setq trees '(maple oak pine birch))
+ @result{} (maple oak pine birch)
+@end group
+
+@group
+(setcdr (nthcdr 2 trees) nil)
+ @result{} nil
+
+trees
+ @result{} (maple oak pine)
@end group
@end smallexample
@noindent
-If the region being killed is before the region that was killed in the
-last command, then it should be prepended before the material that was
-saved in the previous kill; and conversely, if the killed text follows
-what was just killed, it should be appended after the previous text.
-The @code{if} expression depends on the predicate @code{before-p} to
-decide whether the newly saved text should be put before or after the
-previously saved text.
+(The value returned by the @code{setcdr} expression is @code{nil} since
+that is what the @sc{cdr} is set to.)
-The symbol @code{before-p} is the name of one of the arguments to
-@code{kill-append}. When the @code{kill-append} function is
-evaluated, it is bound to the value returned by evaluating the actual
-argument. In this case, this is the expression @code{(< end beg)}.
-This expression does not directly determine whether the killed text in
-this command is located before or after the kill text of the last
-command; what is does is determine whether the value of the variable
-@code{end} is less than the value of the variable @code{beg}. If it
-is, it means that the user is most likely heading towards the
-beginning of the buffer. Also, the result of evaluating the predicate
-expression, @code{(< end beg)}, will be true and the text will be
-prepended before the previous text. On the other hand, if the value of
-the variable @code{end} is greater than the value of the variable
-@code{beg}, the text will be appended after the previous text.
+To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
+@sc{cdr} a number of times that is one less than the maximum permitted
+size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
+element (which will be the rest of the elements in the kill ring) to
+@code{nil}. This prevents the kill ring from growing too long.
@need 800
-When the newly saved text will be prepended, then the string with the new
-text will be concatenated before the old text:
+The next to last expression in the @code{kill-new} function is
@smallexample
-(concat string (car kill-ring))
+(setq kill-ring-yank-pointer kill-ring)
@end smallexample
-@need 1200
-@noindent
-But if the text will be appended, it will be concatenated
-after the old text:
+The @code{kill-ring-yank-pointer} is a global variable that is set to be
+the @code{kill-ring}.
-@smallexample
-(concat (car kill-ring) string))
-@end smallexample
+Even though the @code{kill-ring-yank-pointer} is called a
+@samp{pointer}, it is a variable just like the kill ring. However, the
+name has been chosen to help humans understand how the variable is used.
-To understand how this works, we first need to review the
-@code{concat} function. The @code{concat} function links together or
-unites two strings of text. The result is a string. For example:
+@need 1200
+Now, to return to an early expression in the body of the function:
@smallexample
@group
-(concat "abc" "def")
- @result{} "abcdef"
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
@end group
+@end smallexample
-@group
-(concat "new "
- (car '("first element" "second element")))
- @result{} "new first element"
+@noindent
+It starts with an @code{if} expression
-(concat (car
- '("first element" "second element")) " modified")
- @result{} "first element modified"
-@end group
-@end smallexample
+In this case, the expression tests first to see whether
+@code{menu-bar-update-yank-menu} exists as a function, and if so,
+calls it. The @code{fboundp} function returns true if the symbol it
+is testing has a function definition that `is not void'. If the
+symbol's function definition were void, we would receive an error
+message, as we did when we created errors intentionally (@pxref{Making
+Errors, , Generate an Error Message}).
-We can now make sense of @code{kill-append}: it modifies the contents
-of the kill ring. The kill ring is a list, each element of which is
-saved text. The @code{kill-append} function uses the @code{kill-new}
-function which in turn uses the @code{setcar} function.
+@noindent
+The then-part contains an expression whose first element is the
+function @code{and}.
-@node kill-new function, , kill-append function, copy-region-as-kill body
-@unnumberedsubsubsec The @code{kill-new} function
-@findex kill-new
+@findex and
+The @code{and} special form evaluates each of its arguments until one
+of the arguments returns a value of @code{nil}, in which case the
+@code{and} expression returns @code{nil}; however, if none of the
+arguments returns a value of @code{nil}, the value resulting from
+evaluating the last argument is returned. (Since such a value is not
+@code{nil}, it is considered true in Emacs Lisp.) In other words, an
+@code{and} expression returns a true value only if all its arguments
+are true. (@xref{Second Buffer Related Review}.)
+
+The expression determines whether the second argument to
+@code{menu-bar-update-yank-menu} is true or not.
+@ignore
+ ;; If we're supposed to be extending an existing string, and that
+ ;; string really is at the front of the menu, then update it in place.
+@end ignore
+
+@code{menu-bar-update-yank-menu} is one of the functions that make it
+possible to use the `Select and Paste' menu in the Edit item of a menu
+bar; using a mouse, you can look at the various pieces of text you
+have saved and select one piece to paste.
+
+The last expression in the @code{kill-new} function adds the newly
+copied string to whatever facility exists for copying and pasting
+among different programs running in a windowing system. In the X
+Windowing system, for example, the @code{x-select-text} function takes
+the string and stores it in memory operated by X. You can paste the
+string in another program, such as an Xterm.
@need 1200
-The @code{kill-new} function looks like this:
+The expression looks like this:
@smallexample
@group
-(defun kill-new (string &optional replace)
- "Make STRING the latest kill in the kill ring.
-Set the kill-ring-yank pointer to point to it.
-If `interprogram-cut-function' is non-nil, apply it to STRING.
-Optional second argument REPLACE non-nil means that STRING will replace
-the front of the kill ring, rather than being added to the list."
-@end group
-@group
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
-@end group
-@group
- (if (and replace kill-ring)
- (setcar kill-ring string)
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
-@end group
-@group
- (setq kill-ring-yank-pointer kill-ring)
(if interprogram-cut-function
(funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
-As usual, we can look at this function in parts.
+If an @code{interprogram-cut-function} exists, then Emacs executes
+@code{funcall}, which in turn calls its first argument as a function
+and passes the remaining arguments to it. (Incidentally, as far as I
+can see, this @code{if} expression could be replaced by an @code{and}
+expression similar to the one in the first part of the function.)
-@need 1200
-The first line of the documentation makes sense:
+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.
-@smallexample
-Make STRING the latest kill in the kill ring.
-@end smallexample
+This code for placing text in the kill ring, either concatenated with
+an existing element or as a new element, leads us to the code for
+bringing back text that has been cut out of the buffer---the yank
+commands. However, before discussing the yank commands, it is better
+to learn how lists are implemented in a computer. This will make
+clear such mysteries as the use of the term `pointer'. But before
+that, we will digress into C.
-@noindent
-Let's skip over the rest of the documentation for the moment.
+@ignore
+@c is this true in Emacs 22? Does not seems to be
-Also, let's skip over the first two lines of code, those involving
-@code{menu-bar-update-yank-menu}. We will explain them below.
+ (If the @w{@code{(< end beg))}}
+expression is true, @code{kill-append} prepends the string to the just
+previously clipped text. For a detailed discussion, see
+@ref{kill-append function, , The @code{kill-append} function}.)
-@need 1200
-The critical lines are these:
+If you then yank back the text, i.e., `paste' it, you get both
+pieces of text at once. That way, if you delete two words in a row,
+and then yank them back, you get both words, in their proper order,
+with one yank. (The @w{@code{(< end beg))}} expression makes sure the
+order is correct.)
+
+On the other hand, if the previous command is not @code{kill-region},
+then the @code{kill-new} function is called, which adds the text to
+the kill ring as the latest item, and sets the
+@code{kill-ring-yank-pointer} variable to point to it.
+@end ignore
+@ignore
+
+@c Evidently, changed for Emacs 22. The zap-to-char command does not
+@c use the delete-and-extract-region function
+
+2006 Oct 26, the Digression into C is now OK but should come after
+copy-region-as-kill and filter-buffer-substring
+
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
+
+see Initializing a Variable with @code{defvar}
+@end ignore
+
+@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
+@comment node-name, next, previous, up
+@section Digression into C
+@findex delete-and-extract-region
+@cindex C, a digression into
+@cindex Digression into C
+
+The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
+@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
+function, which in turn uses the @code{delete-and-extract-region}
+function. It removes the contents of a region and you cannot get them
+back.
+
+Unlike the other code discussed here, the
+@code{delete-and-extract-region} function is not written in Emacs
+Lisp; it is written in C and is one of the primitives of the GNU Emacs
+system. Since it is very simple, I will digress briefly from Lisp and
+describe it here.
+
+@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
+@c the DEFUN for buffer-substring-no-properties
+
+@need 1500
+Like many of the other Emacs primitives,
+@code{delete-and-extract-region} is written as an instance of a C
+macro, a macro being a template for code. The complete macro looks
+like this:
@smallexample
@group
- (if (and replace kill-ring)
- ;; @r{then}
- (setcar kill-ring string)
-@end group
-@group
- ;; @r{else}
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- ;; @r{avoid overly long kill ring}
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
-@end group
-@group
- (setq kill-ring-yank-pointer kill-ring)
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
+DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
+ Sbuffer_substring_no_properties, 2, 2, 0,
+ doc: /* Return the characters of part of the buffer,
+without the text properties.
+The two arguments START and END are character positions;
+they can be in either order. */)
+ (start, end)
+ Lisp_Object start, end;
+@{
+ register int b, e;
+
+ validate_region (&start, &end);
+ b = XINT (start);
+ e = XINT (end);
+
+ return make_buffer_string (b, e, 0);
+@}
@end group
@end smallexample
-The conditional test is @w{@code{(and replace kill-ring)}}.
-This will be true when two conditions are met: the kill ring has
-something in it, and the @code{replace} variable is true.
+Without going into the details of the macro writing process, let me
+point out that this macro starts with the word @code{DEFUN}. The word
+@code{DEFUN} was chosen since the code serves the same purpose as
+@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
+@file{emacs/src/lisp.h}.)
-@need 1250
-The @code{kill-append} function sets @code{replace} to be true; then,
-when the kill ring has at least one item in it, the @code{setcar}
-expression is executed:
+The word @code{DEFUN} is followed by seven parts inside of
+parentheses:
+
+@itemize @bullet
+@item
+The first part is the name given to the function in Lisp,
+@code{delete-and-extract-region}.
+
+@item
+The second part is the name of the function in C,
+@code{Fdelete_and_extract_region}. By convention, it starts with
+@samp{F}. Since C does not use hyphens in names, underscores are used
+instead.
+
+@item
+The third part is the name for the C constant structure that records
+information on this function for internal use. It is the name of the
+function in C but begins with an @samp{S} instead of an @samp{F}.
+
+@item
+The fourth and fifth parts specify the minimum and maximum number of
+arguments the function can have. This function demands exactly 2
+arguments.
+
+@item
+The sixth part is nearly like the argument that follows the
+@code{interactive} declaration in a function written in Lisp: a letter
+followed, perhaps, by a prompt. The only difference from the Lisp is
+when the macro is called with no arguments. Then you write a @code{0}
+(which is a `null string'), as in this macro.
+
+If you were to specify arguments, you would place them between
+quotation marks. The C macro for @code{goto-char} includes
+@code{"NGoto char: "} in this position to indicate that the function
+expects a raw prefix, in this case, a numerical location in a buffer,
+and provides a prompt.
+
+@item
+The seventh part is a documentation string, just like the one for a
+function written in Emacs Lisp, except that every newline must be
+written explicitly as @samp{\n} followed by a backslash and carriage
+return.
+
+@need 1000
+Thus, the first two lines of documentation for @code{goto-char} are
+written like this:
@smallexample
-(setcar kill-ring string)
+@group
+ "Set point to POSITION, a number or marker.\n\
+Beginning of buffer is position (point-min), end is (point-max)."
+@end group
@end smallexample
+@end itemize
-The @code{setcar} function actually changes the first element of the
-@code{kill-ring} list to the value of @code{string}. It replaces the
-first element.
-
-On the other hand, if the kill ring is empty, or replace is false, the
-else-part of the condition is executed:
+@need 1200
+In a C macro, the formal parameters come next, with a statement of
+what kind of object they are, followed by what might be called the `body'
+of the macro. For @code{delete-and-extract-region} the `body'
+consists of the following four lines:
@smallexample
@group
-(setq kill-ring (cons string kill-ring))
-(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
+validate_region (&start, &end);
+if (XINT (start) == XINT (end))
+ return build_string ("");
+return del_range_1 (XINT (start), XINT (end), 1, 1);
@end group
@end smallexample
-@noindent
-This expression first constructs a new version of the kill ring by
-prepending @code{string} to the existing kill ring as a new element.
-Then it executes a second @code{if} clause. This second @code{if}
-clause keeps the kill ring from growing too long.
+The @code{validate_region} function checks whether the values
+passed as the beginning and end of the region are the proper type and
+are within range. If the beginning and end positions are the same,
+then return and empty string.
-Let's look at these two expressions in order.
+The @code{del_range_1} function actually deletes the text. It is a
+complex function we will not look into. It updates the buffer and
+does other things. However, it is worth looking at the two arguments
+passed to @code{del_range}. These are @w{@code{XINT (start)}} and
+@w{@code{XINT (end)}}.
-The @code{setq} 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.
+As far as the C language is concerned, @code{start} and @code{end} are
+two integers that mark the beginning and end of the region to be
+deleted@footnote{More precisely, and requiring more expert knowledge
+to understand, the two integers are of type `Lisp_Object', which can
+also be a C union instead of an integer type.}.
-@need 800
-We can see how this works with an example:
+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'.
-@smallexample
-(setq example-list '("here is a clause" "another clause"))
-@end smallexample
+@samp{XINT} is a C macro that extracts the relevant number from the
+longer collection of bits; the three other bits are discarded.
-@need 1200
-@noindent
-After evaluating this expression with @kbd{C-x C-e}, you can evaluate
-@code{example-list} and see what it returns:
+@need 800
+The command in @code{delete-and-extract-region} looks like this:
@smallexample
-@group
-example-list
- @result{} ("here is a clause" "another clause")
-@end group
+del_range_1 (XINT (start), XINT (end), 1, 1);
@end smallexample
-@need 1200
@noindent
-Now, we can add a new element on to this list by evaluating the
-following expression:
-@findex cons, @r{example}
+It deletes the region between the beginning position, @code{start},
+and the ending position, @code{end}.
-@smallexample
-(setq example-list (cons "a third clause" example-list))
-@end smallexample
+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.
-@need 800
-@noindent
-When we evaluate @code{example-list}, we find its value is:
+@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
+@comment node-name, next, previous, up
+@section Initializing a Variable with @code{defvar}
+@findex defvar
+@cindex Initializing a variable
+@cindex Variable initialization
-@smallexample
-@group
-example-list
- @result{} ("a third clause" "here is a clause" "another clause")
-@end group
-@end smallexample
+@ignore
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
-@noindent
-Thus, the third clause was added to the list by @code{cons}.
+see Initializing a Variable with @code{defvar}
-@need 1200
-This is exactly similar to what the @code{setq} and @code{cons} do in
-the function. Here is the line again:
+@end ignore
-@smallexample
-(setq kill-ring (cons string kill-ring))
-@end smallexample
+The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
+functions within it, @code{kill-append} and @code{kill-new}, copy a
+region in a buffer and save it in a variable called the
+@code{kill-ring}. This section describes how the @code{kill-ring}
+variable is created and initialized using the @code{defvar} special
+form.
-@need 1200
-Now for the second part of the @code{if} clause. This expression
-keeps the kill ring from growing too long. It looks like this:
+(Again we note that the term @code{kill-ring} is a misnomer. The text
+that is clipped out of the buffer can be brought back; it is not a ring
+of corpses, but a ring of resurrectable text.)
-@smallexample
-@group
-(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
-@end group
-@end smallexample
+In Emacs Lisp, a variable such as the @code{kill-ring} is created and
+given an initial value by using the @code{defvar} special form. The
+name comes from ``define variable''.
-The code checks whether the length of the kill ring is greater than
-the maximum permitted length. This is the value of
-@code{kill-ring-max} (which is 60, by default). If the length of the
-kill ring is too long, then this code sets the last element of the
-kill ring to @code{nil}. It does this by using two functions,
-@code{nthcdr} and @code{setcdr}.
+The @code{defvar} special form is similar to @code{setq} in that it sets
+the value of a variable. It is unlike @code{setq} in two ways: first,
+it only sets the value of the variable if the variable does not already
+have a value. If the variable already has a value, @code{defvar} does
+not override the existing value. Second, @code{defvar} has a
+documentation string.
-We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
-It sets the @sc{cdr} of a list, just as @code{setcar} sets the
-@sc{car} of a list. In this case, however, @code{setcdr} will not be
-setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
-function is used to cause it to set the @sc{cdr} of the next to last
-element of the kill ring---this means that since the @sc{cdr} of the
-next to last element is the last element of the kill ring, it will set
-the last element of the kill ring.
+(Another special form, @code{defcustom}, is designed for variables
+that people customize. It has more features than @code{defvar}.
+(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
-@findex nthcdr, @r{example}
-The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
-list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
-@dots{} It does this @var{N} times and returns the results.
+@menu
+* See variable current value::
+* defvar and asterisk::
+@end menu
-@findex setcdr, @r{example}
-Thus, if we had a four element list that was supposed to be three
-elements long, we could set the @sc{cdr} of the next to last element
-to @code{nil}, and thereby shorten the list.
+@node See variable current value, defvar and asterisk, defvar, defvar
+@ifnottex
+@unnumberedsubsec Seeing the Current Value of a Variable
+@end ifnottex
-You can see this by evaluating the following three expressions in turn.
-First set the value of @code{trees} to @code{(maple oak pine birch)},
-then set the @sc{cdr} of its second @sc{cdr} to @code{nil} and then
-find the value of @code{trees}:
+You can see the current value of a variable, any variable, by using
+the @code{describe-variable} function, which is usually invoked by
+typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
+(followed by @key{RET}) when prompted, you will see what is in your
+current kill ring---this may be quite a lot! Conversely, if you have
+been doing nothing this Emacs session except read this document, you
+may have nothing in it. Also, you will see the documentation for
+@code{kill-ring}:
@smallexample
@group
-(setq trees '(maple oak pine birch))
- @result{} (maple oak pine birch)
+Documentation:
+List of killed text sequences.
+Since the kill ring is supposed to interact nicely with cut-and-paste
+facilities offered by window systems, use of this variable should
@end group
-
@group
-(setcdr (nthcdr 2 trees) nil)
- @result{} nil
-
-trees
- @result{} (maple oak pine)
+interact nicely with `interprogram-cut-function' and
+`interprogram-paste-function'. The functions `kill-new',
+`kill-append', and `current-kill' are supposed to implement this
+interaction; you may want to use them instead of manipulating the kill
+ring directly.
@end group
@end smallexample
-@noindent
-(The value returned by the @code{setcdr} expression is @code{nil} since
-that is what the @sc{cdr} is set to.)
-
-To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
-@sc{cdr} a number of times that is one less than the maximum permitted
-size of the kill ring and sets the @sc{cdr} of that element (which
-will be the rest of the elements in the kill ring) to @code{nil}.
-This prevents the kill ring from growing too long.
-
@need 800
-The next to last expression in the @code{kill-new} function is
-
-@smallexample
-(setq kill-ring-yank-pointer kill-ring)
-@end smallexample
-
-The @code{kill-ring-yank-pointer} is a global variable that is set to be
-the @code{kill-ring}.
-
-Even though the @code{kill-ring-yank-pointer} is called a
-@samp{pointer}, it is a variable just like the kill ring. However, the
-name has been chosen to help humans understand how the variable is used.
-The variable is used in functions such as @code{yank} and
-@code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
-
-@need 1200
-Now, to return to the first two lines in the body of the function:
+The kill ring is defined by a @code{defvar} in the following way:
@smallexample
@group
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+(defvar kill-ring nil
+ "List of killed text sequences.
+@dots{}")
@end group
@end smallexample
@noindent
-This is an expression whose first element is the function @code{and}.
-
-@findex and, @r{introduced}
-The @code{and} special form evaluates each of its arguments until one of
-the arguments returns a value of @code{nil}, in which case the
-@code{and} expression returns @code{nil}; however, if none of the
-arguments returns a value of @code{nil}, the value resulting from
-evaluating the last argument is returned. (Since such a value is not
-@code{nil}, it is considered true in Emacs Lisp.) In other words, an
-@code{and} expression returns a true value only if all its arguments
-are true.
-@findex and
-
-In this case, the expression tests first to see whether
-@code{menu-bar-update-yank-menu} exists as a function, and if so,
-calls it. The @code{fboundp} function returns true if the symbol it
-is testing has a function definition that `is not void'. If the
-symbol's function definition were void, we would receive an error
-message, as we did when we created errors intentionally (@pxref{Making
-Errors, , Generate an Error Message}).
-
-@need 1200
-Essentially, the @code{and} is an @code{if} expression that reads like
-this:
-
-@smallexample
-@group
-if @var{the-menu-bar-function-exists}
- then @var{execute-it}
-@end group
-@end smallexample
+In this variable definition, the variable is given an initial value of
+@code{nil}, which makes sense, since if you have saved nothing, you want
+nothing back if you give a @code{yank} command. The documentation
+string is written just like the documentation string of a @code{defun}.
+As with the documentation string of the @code{defun}, the first line of
+the documentation should be a complete sentence, since some commands,
+like @code{apropos}, print only the first line of documentation.
+Succeeding lines should not be indented; otherwise they look odd when
+you use @kbd{C-h v} (@code{describe-variable}).
-@code{menu-bar-update-yank-menu} is one of the functions that make it
-possible to use the `Select and Paste' menu in the Edit item of a menu
-bar; using a mouse, you can look at the various pieces of text you
-have saved and select one piece to paste.
+@node defvar and asterisk, , See variable current value, defvar
+@subsection @code{defvar} and an asterisk
+@findex defvar @r{for a user customizable variable}
+@findex defvar @r{with an asterisk}
-Finally, the last expression in the @code{kill-new} function adds the
-newly copied string to whatever facility exists for copying and
-pasting among different programs running in a windowing system. In
-the X Windowing system, for example, the @code{x-select-text} function
-takes the string and stores it in memory operated by X. You can paste
-the string in another program, such as an Xterm.
+In the past, Emacs used the @code{defvar} special form both for
+internal variables that you would not expect a user to change and for
+variables that you do expect a user to change. Although you can still
+use @code{defvar} for user customizable variables, please use
+@code{defcustom} instead, since that special form provides a path into
+the Customization commands. (@xref{defcustom, , Specifying Variables
+using @code{defcustom}}.)
-@need 1200
-The expression looks like this:
+When you specified a variable using the @code{defvar} special form,
+you could distinguish a readily settable variable from others by
+typing an asterisk, @samp{*}, in the first column of its documentation
+string. For example:
@smallexample
@group
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
+(defvar shell-command-default-error-buffer nil
+ "*Buffer name for `shell-command' @dots{} error output.
+@dots{} ")
@end group
@end smallexample
-If an @code{interprogram-cut-function} exists, then Emacs executes
-@code{funcall}, which in turn calls its first argument as a function
-and passes the remaining arguments to it. (Incidentally, as far as I
-can see, this @code{if} expression could be replaced by an @code{and}
-expression similar to the one in the first part of the function.)
-
-We are not going to discuss windowing systems and other programs
-further, but merely note that this is a mechanism that enables GNU
-Emacs to work easily and well with other programs.
+@findex set-variable
+@noindent
+You could (and still can) use the @code{set-variable} command to
+change the value of @code{shell-command-default-error-buffer}
+temporarily. However, options set using @code{set-variable} are set
+only for the duration of your editing session. The new values are not
+saved between sessions. Each time Emacs starts, it reads the original
+value, unless you change the value within your @file{.emacs} file,
+either by setting it manually or by using @code{customize}.
+@xref{Emacs Initialization, , Your @file{.emacs} File}.
-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'.
+For me, the major use of the @code{set-variable} command is to suggest
+variables that I might want to set in my @file{.emacs} file. There
+are now more than 700 such variables --- far too many to remember
+readily. Fortunately, you can press @key{TAB} after calling the
+@code{M-x set-variable} command to see the list of variables.
+(@xref{Examining, , Examining and Setting Variables, emacs,
+The GNU Emacs Manual}.)
-@node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text
+@need 1250
+@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
@comment node-name, next, previous, up
@section Review
@end group
@end smallexample
+@item funcall
+@code{funcall} evaluates its first argument as a function. It passes
+its remaining arguments to its first argument.
+
@item nthcdr
Return the result of taking @sc{cdr} `n' times on a list.
@iftex
and restore that narrowing after evaluating the arguments.
@item search-forward
-Search for a string, and if the string is found, move point.
+Search for a string, and if the string is found, move point. With a
+regular expression, use the similar @code{re-search-forward}.
+(@xref{Regexp Search, , Regular Expression Searches}, for an
+explanation of regular expression patterns and searches.)
@need 1250
@noindent
-Takes four arguments:
+@code{search-forward} and @code{re-search-forward} take four
+arguments:
@enumerate
@item
-The string to search for.
+The string or regular expression to search for.
@item
Optionally, the limit of the search.
@end enumerate
@item kill-region
-@itemx delete-region
+@itemx delete-and-extract-region
@itemx copy-region-as-kill
@code{kill-region} cuts the text between point and mark from the
buffer and stores that text in the kill ring, so you can get it back
by yanking.
-@code{delete-and-extract-region} removes the text between point and
-mark from the buffer and throws it away. You cannot get it back.
-
@code{copy-region-as-kill} copies the text between point and mark into
the kill ring, from which you can get it by yanking. The function
does not cut or remove the text from the buffer.
@end table
+@code{delete-and-extract-region} removes the text between point and
+mark from the buffer and throws it away. You cannot get it back.
+(This is not an interactive command.)
+
@need 1500
@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
@section Searching Exercises
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-1}
+@center @image{cons-1}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-2}
+@center @image{cons-2}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-2a}
+@center @image{cons-2a}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-3}
+@center @image{cons-3}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
and the second of which holds the address of @code{buttercup}.
A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
-pair}. @xref{List Type, , List Type , elisp, The GNU Emacs Lisp
+pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
information about cons cells and dotted pairs.
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-4}
+@center @image{cons-4}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
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-versa.
+drawer holding the function definition, and vice-verse.
Actually, what is put in each drawer is the address of the value or
function definition. It is as if you found an old chest in the attic,
@ifset print-postscript-figures
@sp 1
@tex
-@image{drawers}
+@center @image{drawers}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
@comment node-name, next, previous, up
@chapter Yanking Text Back
@findex yank
-@findex rotate-yank-pointer
@cindex Text retrieval
@cindex Retrieving text
@cindex Pasting text
list is handled as a ring.)
@menu
-* Kill Ring Overview:: The kill ring is a list.
-* kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
-* yank nthcdr Exercises::
+* Kill Ring Overview::
+* kill-ring-yank-pointer:: The kill ring is a list.
+* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
@end menu
@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
(insert (car kill-ring-yank-pointer))
@end smallexample
+@noindent
+(Well, no more. In GNU Emacs 22, the function has been replaced by
+@code{insert-for-yank} which calls @code{insert-for-yank-1}
+repetitively for each @code{yank-handler} segment. In turn,
+@code{insert-for-yank-1} strips text properties from the inserted text
+according to @code{yank-excluded-properties}. Otherwise, it is just
+like @code{insert}. We will stick with plain @code{insert} since it
+is easier to understand.)
+
To begin to understand how @code{yank} and @code{yank-pop} work, it is
-first necessary to look at the @code{kill-ring-yank-pointer} variable
-and the @code{rotate-yank-pointer} function.
+first necessary to look at the @code{kill-ring-yank-pointer} variable.
@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
@comment node-name, next, previous, up
| | |
| | --> "yet more text"
| |
- | --> "a different piece of text
+ | --> "a different piece of text"
|
--> "some text"
@end group
@ifset print-postscript-figures
@sp 1
@tex
-@image{cons-5}
+@center @image{cons-5}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
of the kill ring of which the first element (the @sc{car}) will be
inserted.
-The @code{rotate-yank-pointer} function changes the element in the
-kill ring to which the @code{kill-ring-yank-pointer} points; when the
-pointer is set to point to the next element beyond the end of the kill
-ring, it automatically sets it to point to the first element of the
-kill ring. This is how the list is transformed into a ring. The
-@code{rotate-yank-pointer} function itself is not difficult, but
-contains many details. It and the much simpler @code{yank} and
-@code{yank-pop} functions are described in an appendix.
-@xref{Kill Ring, , Handling the Kill Ring}.
+@ignore
+In GNU Emacs 22, the @code{kill-new} function calls
+
+@code{(setq kill-ring-yank-pointer kill-ring)}
+
+(defun rotate-yank-pointer (arg)
+ "Rotate the yanking point in the kill ring.
+With argument, rotate that many kills forward (or backward, if negative)."
+ (interactive "p")
+ (current-kill arg))
+
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
+If N is zero, `interprogram-paste-function' is set, and calling it
+returns a string, then that string is added to the front of the
+kill ring and returned as the latest kill.
+If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
+yanking point; just return the Nth kill forward."
+ (let ((interprogram-paste (and (= n 0)
+ interprogram-paste-function
+ (funcall interprogram-paste-function))))
+ (if interprogram-paste
+ (progn
+ ;; Disable the interprogram cut function when we add the new
+ ;; text to the kill ring, so Emacs doesn't try to own the
+ ;; selection, with identical text.
+ (let ((interprogram-cut-function nil))
+ (kill-new interprogram-paste))
+ interprogram-paste)
+ (or kill-ring (error "Kill ring is empty"))
+ (let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element)))))
+
+@end ignore
@need 1500
@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
* 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
@cindex @file{*scratch*} buffer
The function requires several lines for its output. If you are
-reading this in Emacs 21 or a later version, you can evaluate the
-following expression inside of Info, as usual.
+reading this in a recent instance of GNU Emacs,
+@c GNU Emacs 21, GNU Emacs 22, or a later version,
+you can evaluate the following expression inside of Info, as usual.
If you are using an earlier version of Emacs, you need to copy the
necessary expressions to your @file{*scratch*} buffer and evaluate
You can copy the expressions by marking the beginning of the region
with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
the end of the region and then copying the region using @kbd{M-w}
-(@code{copy-region-as-kill}). In the @file{*scratch*} buffer, you can
-yank the expressions back by typing @kbd{C-y} (@code{yank}).
+(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
+then provides visual feedback). In the @file{*scratch*}
+buffer, you can yank the expressions back by typing @kbd{C-y}
+(@code{yank}).
After you have copied the expressions to the @file{*scratch*} buffer,
evaluate each expression in turn. Be sure to evaluate the last
each @samp{^J} stands for a `newline'.)
@need 1500
-If you are using Emacs 21 or later, you can evaluate these expressions
+In a recent instance of GNU Emacs, you can evaluate these expressions
directly in the Info buffer, and the echo area will grow to show the
results.
@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
* 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:
called @code{number-of-rows}.
Finally, we need a variable to use as a counter. We could call this
-variable @code{counter}, but a better name is @code{row-number}.
-That is because what the counter does is count rows, and a program
-should be written to be as understandable as possible.
+variable @code{counter}, but a better name is @code{row-number}. That
+is because what the counter does in this function is count rows, and a
+program should be written to be as understandable as possible.
When the Lisp interpreter first starts evaluating the expressions in the
function, the value of @code{total} should be set to zero, since we have
(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
(let (@var{varlist})
(while (@var{true-or-false-test})
@var{body-of-while}@dots{} )
- @dots{} ) ; @r{Need final expression here.}
+ @dots{} )) ; @r{Need final expression here.}
@end group
@end smallexample
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
of numbers can be written recursively. Here is the code, including
an expression to set the value of the variable @code{animals} to a list.
-If you are using Emacs 20 or before, this example must be copied to
-the @file{*scratch*} buffer and each expression must be evaluated
+If you are using GNU Emacs 20 or before, this example must be copied
+to the @file{*scratch*} buffer and each expression must be evaluated
there. Use @kbd{C-u C-x C-e} to evaluate the
@code{(print-elements-recursively animals)} expression so that the
results are printed in the buffer; otherwise the Lisp interpreter will
of the @code{print-elements-recursively} function, before the comment.
Otherwise, the Lisp interpreter will try to evaluate the comment.
-If you are using Emacs 21 or later, you can evaluate this expression
-directly in Info.
+If you are using a more recent version of Emacs, you can evaluate this
+expression directly in Info.
@findex print-elements-recursively
@smallexample
(defun print-elements-recursively (list)
"Print each element of LIST on a line of its own.
Uses recursion."
- (if list ; @r{do-again-test}
- (progn
+ (when list ; @r{do-again-test}
(print (car list)) ; @r{body}
(print-elements-recursively ; @r{recursive call}
- (cdr list))))) ; @r{next-step-expression}
+ (cdr list)))) ; @r{next-step-expression}
(print-elements-recursively animals)
@end group
assemblies a second robot and tells it what to do; the second robot is
a different individual from the first, but is the same model.
-When the second evaluation occurs, the @code{if} expression is
+When the second evaluation occurs, the @code{when} expression is
evaluated and if true, prints the first element of the list it
receives as its argument (which is the second element of the original
list). Then the function `calls itself' with the @sc{cdr} of the list
Eventually, the function invokes itself on an empty list. It creates
a new instance whose argument is @code{nil}. The conditional expression
tests the value of @code{list}. Since the value of @code{list} is
-@code{nil}, the @code{if} expression tests false so the then-part is
+@code{nil}, the @code{when} expression tests false so the then-part is
not evaluated. The function as a whole then returns @code{nil}.
@need 1200
@end group
@end smallexample
+@need 2000
@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
@comment node-name, next, previous, up
@subsection Recursion in Place of a Counter
(defun print-elements-recursively (list)
"Print each element of LIST on a line of its own.
Uses recursion."
- (if list ; @r{do-again-test}
- (progn
+ (when list ; @r{do-again-test}
(print (car list)) ; @r{body}
(print-elements-recursively ; @r{recursive call}
- (cdr list))))) ; @r{next-step-expression}
+ (cdr list)))) ; @r{next-step-expression}
(print-elements-recursively animals)
@end group
@itemize @bullet
@item
-If the list be empty, do nothing.
+When the list is empty, do nothing.
@item
-But if the list has at least one element,
+But when the list has at least one element,
@itemize @minus
@item
act on the beginning of the list (the @sc{car} of the list),
;; Third do-again-test: when to skip element;
;; recursively call shorter list with next-step expression
- (t (keep-three-letter-words (cdr word-list)))))
+ (t (keep-three-letter-words (cdr word-list)))))
@end group
@group
@need 1200
@noindent
and find that the result is false, so it will invoke
-the then-part of the @code{if} clause:
+the else-part of the @code{if} clause:
@smallexample
@group
@item
Write a function for Texinfo mode that creates an index entry at the
beginning of a paragraph for every @samp{@@dfn} within the paragraph.
-(In a Texinfo file, @samp{@@dfn} marks a definition. For more
-information, see
+(In a Texinfo file, @samp{@@dfn} marks a definition. This book is
+written in Texinfo.)
+
+Many of the functions you will need are described in two of the
+previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
+Text}, and @ref{Yanking, , Yanking Text Back}. If you use
+@code{forward-paragraph} to put the index entry at the beginning of
+the paragraph, you will have to use @w{@kbd{C-h f}}
+(@code{describe-function}) to find out how to make the command go
+backwards.
+
+For more information, see
@ifinfo
-@ref{Indicating, , Indicating Definitions, texinfo}.)
+@ref{Indicating, , Indicating Definitions, texinfo}.
@end ifinfo
@ifhtml
-@ref{Indicating, , Indicating, texinfo, Texinfo Manual}.)
+@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
+a Texinfo manual in the current directory. Or, if you are on the
+Internet, see
+@uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
@end ifhtml
@iftex
``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
-Documentation Format}.)
+Documentation Format}.
@end iftex
@end itemize
end of a sentence. What should this regular expression be?
Clearly, a sentence may be ended by a period, a question mark, or an
-exclamation mark. Indeed, only clauses that end with one of those three
-characters should be considered the end of a sentence. This means that
-the pattern should include the character set:
+exclamation mark. Indeed, in English, only clauses that end with one
+of those three characters should be considered the end of a sentence.
+This means that the pattern should include the character set:
@smallexample
[.?!]
@end group
@end smallexample
-@ignore
+@noindent
+(Well, not in GNU Emacs 22; that is because of an effort to make the
+process simpler and to handle more glyphs and languages. When the
+value of @code{sentence-end} is @code{nil}, then use the value defined
+by the function @code{sentence-end}. (Here is a use of the difference
+between a value and a function in Emacs Lisp.) The function returns a
+value constructed from the variables @code{sentence-end-base},
+@code{sentence-end-double-space}, @code{sentence-end-without-period},
+and @code{sentence-end-without-space}. The critical variable is
+@code{sentence-end-base}; its global value is similar to the one
+described above but it also contains two additional quotation marks.
+These have differing degrees of curliness. The
+@code{sentence-end-without-period} variable, when true, tells Emacs
+that a sentence may end without a period, such as text in Thai.)
+@ignore
@noindent
(Note that here the @key{TAB}, two spaces, and @key{RET} are shown
literally in the pattern.)
-This regular expression can be decyphered as follows:
+This regular expression can be deciphered as follows:
@table @code
@item [.?!]
the pattern, the carriage return is inserted as an actual carriage
return between square brackets but here it is shown as @key{RET}.
@end table
-
@end ignore
@node re-search-forward, forward-sentence, sentence-end, Regexp Search
@need 1200
In the @code{forward-sentence} function, the regular expression will be
-the value of the variable @code{sentence-end}, namely:
+the value of the variable @code{sentence-end}. In simple form, that is:
@smallexample
@group
@need 1250
Here is the code for @code{forward-sentence}:
+@c in GNU Emacs 22
+@smallexample
+@group
+(defun forward-sentence (&optional arg)
+ "Move forward to next `sentence-end'. With argument, repeat.
+With negative argument, move backward repeatedly to `sentence-beginning'.
+
+The variable `sentence-end' is a regular expression that matches ends of
+sentences. Also, every paragraph boundary terminates sentences as well."
+@end group
+@group
+ (interactive "p")
+ (or arg (setq arg 1))
+ (let ((opoint (point))
+ (sentence-end (sentence-end)))
+ (while (< arg 0)
+ (let ((pos (point))
+ (par-beg (save-excursion (start-of-paragraph-text) (point))))
+ (if (and (re-search-backward sentence-end par-beg t)
+ (or (< (match-end 0) pos)
+ (re-search-backward sentence-end par-beg t)))
+ (goto-char (match-end 0))
+ (goto-char par-beg)))
+ (setq arg (1+ arg)))
+@end group
+@group
+ (while (> arg 0)
+ (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
+ (if (re-search-forward sentence-end par-end t)
+ (skip-chars-backward " \t\n")
+ (goto-char par-end)))
+ (setq arg (1- arg)))
+ (constrain-to-field nil opoint t)))
+@end group
+@end smallexample
+
+@ignore
+GNU Emacs 21
@smallexample
@group
(defun forward-sentence (&optional arg)
(setq arg (1- arg))))
@end group
@end smallexample
+@end ignore
The function looks long at first sight and it is best to look at its
skeleton first, and then its muscle. The way to see the skeleton is to
"@var{documentation}@dots{}"
(interactive "p")
(or arg (setq arg 1))
- (while (< arg 0)
- @var{body-of-while-loop}
- (while (> arg 0)
- @var{body-of-while-loop}
+ (let ((opoint (point)) (sentence-end (sentence-end)))
+ (while (< arg 0)
+ (let ((pos (point))
+ (par-beg (save-excursion (start-of-paragraph-text) (point))))
+ @var{rest-of-body-of-while-loop-when-going-backwards}
+ (while (> arg 0)
+ (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
+ @var{rest-of-body-of-while-loop-when-going-forwards}
+ @var{handle-forms-and-equivalent}
@end group
@end smallexample
This looks much simpler! The function definition consists of
documentation, an @code{interactive} expression, an @code{or}
-expression, and @code{while} loops.
+expression, a @code{let} expression, and @code{while} loops.
Let's look at each of these parts in turn.
that the processed prefix argument, if any, is passed to the
function as its argument. (This will be a number.) If the function
is not passed an argument (it is optional) then the argument
-@code{arg} will be bound to 1. When @code{forward-sentence} is called
-non-interactively without an argument, @code{arg} is bound to
+@code{arg} will be bound to 1.
+
+When @code{forward-sentence} is called non-interactively without an
+argument, @code{arg} is bound to @code{nil}. The @code{or} expression
+handles this. What it does is either leave the value of @code{arg} as
+it is, but only if @code{arg} is bound to a value; or it sets the
+value of @code{arg} to 1, in the case when @code{arg} is bound to
@code{nil}.
-The @code{or} expression handles the prefix argument. What it does is
-either leave the value of @code{arg} as it is, but only if @code{arg}
-is bound to a value; or it sets the value of @code{arg} to 1, in the
-case when @code{arg} is bound to @code{nil}.
+Next is a @code{let}. That specifies the values of two local
+variables, @code{point} and @code{sentence-end}. The local value of
+point, from before the search, is used in the
+@code{constrain-to-field} function which handles forms and
+equivalents. The @code{sentence-end} variable is set by the
+@code{sentence-end} function.
@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
@unnumberedsubsec The @code{while} loops
-Two @code{while} loops follow the @code{or} expression. The first
-@code{while} has a true-or-false-test that tests true if the prefix
-argument for @code{forward-sentence} is a negative number. This is for
-going backwards. The body of this loop is similar to the body of the
-second @code{while} clause, but it is not exactly the same. We will
-skip this @code{while} loop and concentrate on the second @code{while}
+Two @code{while} loops follow. The first @code{while} has a
+true-or-false-test that tests true if the prefix argument for
+@code{forward-sentence} is a negative number. This is for going
+backwards. The body of this loop is similar to the body of the second
+@code{while} clause, but it is not exactly the same. We will skip
+this @code{while} loop and concentrate on the second @code{while}
loop.
@need 1500
@code{save-excursion} restores point to its original position. Thus,
the @code{let} binds @code{par-end} to the value returned by the
@code{save-excursion} expression, which is the position of the end of
-the paragraph. (The @code{(end-of-paragraph-text)} function uses
+the paragraph. (The @code{end-of-paragraph-text} function uses
@code{forward-paragraph}, which we will discuss shortly.)
@need 1200
argument, which is @code{(goto-char par-end)}: it moves point to the
end of the paragraph.
+(And if the text is in a form or equivalent, and point may not move
+fully, then the @code{constrain-to-field} function comes into play.)
+
Regular expression searches are exceptionally useful and the pattern
illustrated by @code{re-search-forward}, in which the search is the
test of an @code{if} expression, is handy. You will see or write code
@section @code{forward-paragraph}: a Goldmine of Functions
@findex forward-paragraph
+@ignore
+@c in GNU Emacs 22
+(defun forward-paragraph (&optional arg)
+ "Move forward to end of paragraph.
+With argument ARG, do it ARG times;
+a negative argument ARG = -N means move backward N paragraphs.
+
+A line which `paragraph-start' matches either separates paragraphs
+\(if `paragraph-separate' matches it also) or is the first line of a paragraph.
+A paragraph end is the beginning of a line which is not part of the paragraph
+to which the end of the previous line belongs, or the end of the buffer.
+Returns the count of paragraphs left to move."
+ (interactive "p")
+ (or arg (setq arg 1))
+ (let* ((opoint (point))
+ (fill-prefix-regexp
+ (and fill-prefix (not (equal fill-prefix ""))
+ (not paragraph-ignore-fill-prefix)
+ (regexp-quote fill-prefix)))
+ ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
+ ;; These regexps shouldn't be anchored, because we look for them
+ ;; starting at the left-margin. This allows paragraph commands to
+ ;; work normally with indented text.
+ ;; This hack will not find problem cases like "whatever\\|^something".
+ (parstart (if (and (not (equal "" paragraph-start))
+ (equal ?^ (aref paragraph-start 0)))
+ (substring paragraph-start 1)
+ paragraph-start))
+ (parsep (if (and (not (equal "" paragraph-separate))
+ (equal ?^ (aref paragraph-separate 0)))
+ (substring paragraph-separate 1)
+ paragraph-separate))
+ (parsep
+ (if fill-prefix-regexp
+ (concat parsep "\\|"
+ fill-prefix-regexp "[ \t]*$")
+ parsep))
+ ;; This is used for searching.
+ (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
+ start found-start)
+ (while (and (< arg 0) (not (bobp)))
+ (if (and (not (looking-at parsep))
+ (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
+ (looking-at parsep))
+ (setq arg (1+ arg))
+ (setq start (point))
+ ;; Move back over paragraph-separating lines.
+ (forward-char -1) (beginning-of-line)
+ (while (and (not (bobp))
+ (progn (move-to-left-margin)
+ (looking-at parsep)))
+ (forward-line -1))
+ (if (bobp)
+ nil
+ (setq arg (1+ arg))
+ ;; Go to end of the previous (non-separating) line.
+ (end-of-line)
+ ;; Search back for line that starts or separates paragraphs.
+ (if (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (let (multiple-lines)
+ (while (and (progn (beginning-of-line) (not (bobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (looking-at fill-prefix-regexp))
+ (unless (= (point) start)
+ (setq multiple-lines t))
+ (forward-line -1))
+ (move-to-left-margin)
+ ;; This deleted code caused a long hanging-indent line
+ ;; not to be filled together with the following lines.
+ ;; ;; Don't move back over a line before the paragraph
+ ;; ;; which doesn't start with fill-prefix
+ ;; ;; unless that is the only line we've moved over.
+ ;; (and (not (looking-at fill-prefix-regexp))
+ ;; multiple-lines
+ ;; (forward-line 1))
+ (not (bobp)))
+ (while (and (re-search-backward sp-parstart nil 1)
+ (setq found-start t)
+ ;; Found a candidate, but need to check if it is a
+ ;; REAL parstart.
+ (progn (setq start (point))
+ (move-to-left-margin)
+ (not (looking-at parsep)))
+ (not (and (looking-at parstart)
+ (or (not use-hard-newlines)
+ (bobp)
+ (get-text-property
+ (1- start) 'hard)))))
+ (setq found-start nil)
+ (goto-char start))
+ found-start)
+ ;; Found one.
+ (progn
+ ;; Move forward over paragraph separators.
+ ;; We know this cannot reach the place we started
+ ;; because we know we moved back over a non-separator.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin)
+ (looking-at parsep)))
+ (forward-line 1))
+ ;; If line before paragraph is just margin, back up to there.
+ (end-of-line 0)
+ (if (> (current-column) (current-left-margin))
+ (forward-char 1)
+ (skip-chars-backward " \t")
+ (if (not (bolp))
+ (forward-line 1))))
+ ;; No starter or separator line => use buffer beg.
+ (goto-char (point-min))))))
+
+ (while (and (> arg 0) (not (eobp)))
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+ (if (< (point) (point-max))
+ (goto-char start))))
+ (constrain-to-field nil opoint t)
+ ;; Return the number of steps that could not be done.
+ arg))
+@end ignore
+
The @code{forward-paragraph} function moves point forward to the end
of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
number of functions that are important in themselves, including
* 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.
-* fwd-para between paragraphs:: Movement between paragraphs.
-* fwd-para within paragraph:: Movement within paragraphs.
-* fwd-para no fill prefix:: When there is no fill prefix.
-* fwd-para with fill prefix:: When there is a fill prefix.
-* fwd-para summary:: Summary of @code{forward-paragraph} code.
@end menu
@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
(or arg (setq arg 1))
(let*
@var{varlist}
- (while (< arg 0) ; @r{backward-moving-code}
+ (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
@dots{}
- (setq arg (1+ arg)))
- (while (> arg 0) ; @r{forward-moving-code}
+ (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
@dots{}
- (setq arg (1- arg)))))
@end group
@end smallexample
@unnumberedsubsec The @code{let*} expression
The next line of the @code{forward-paragraph} function begins a
-@code{let*} expression. This is a different kind of expression than
-we have seen so far. The symbol is @code{let*} not @code{let}.
+@code{let*} expression. This is a different than @code{let}. The
+symbol is @code{let*} not @code{let}.
The @code{let*} special form is like @code{let} except that Emacs sets
each variable in sequence, one after another, and variables in the
latter part of the varlist can make use of the values to which Emacs
set variables in the earlier part of the varlist.
-In the @code{let*} expression in this function, Emacs binds two
-variables: @code{fill-prefix-regexp} and @code{paragraph-separate}.
-The value to which @code{paragraph-separate} is bound depends on the
-value of @code{fill-prefix-regexp}.
+@ignore
+( refappend save-excursion, , code save-excursion in code append-to-buffer .)
+@end ignore
+
+(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
-@need 1200
-Let's look at each in turn. The symbol @code{fill-prefix-regexp} is
-set to the value returned by evaluating the following list:
+In the @code{let*} expression in this function, Emacs binds a total of
+seven variables: @code{opoint}, @code{fill-prefix-regexp},
+@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
+@code{found-start}.
+
+The variable @code{parsep} appears twice, first, to remove instances
+of @samp{^}, and second, to handle fill prefixes.
+
+The variable @code{opoint} is just the value of @code{point}. As you
+can guess, it is used in a @code{constrain-to-field} expression, just
+as in @code{forward-sentence}.
+
+The variable @code{fill-prefix-regexp} is set to the value returned by
+evaluating the following list:
@smallexample
@group
will exactly match the fill prefix if the fill prefix exists.
Otherwise, the variable will be set to @code{nil}.
-The second local variable in the @code{let*} expression is
-@code{paragraph-separate}. It is bound to the value returned by
-evaluating the expression:
-
-@smallexample
-@group
-(if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^" fill-prefix-regexp "[ \t]*$")
- paragraph-separate)))
-@end group
-@end smallexample
+The next two local variables in the @code{let*} expression are
+designed to remove instances of @samp{^} from @code{parstart} and
+@code{parsep}, the local variables which indicate the paragraph start
+and the paragraph separator. The next expression sets @code{parsep}
+again. That is to handle fill prefixes.
-This expression shows why @code{let*} rather than @code{let} was used.
-The true-or-false-test for the @code{if} depends on whether the variable
-@code{fill-prefix-regexp} evaluates to @code{nil} or some other value.
+This is the setting that requires the definition call @code{let*}
+rather than @code{let}. The true-or-false-test for the @code{if}
+depends on whether the variable @code{fill-prefix-regexp} evaluates to
+@code{nil} or some other value.
If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
-the else-part of the @code{if} expression and binds
-@code{paragraph-separate} to its local value.
-(@code{paragraph-separate} is a regular expression that matches what
-separates paragraphs.)
+the else-part of the @code{if} expression and binds @code{parsep} to
+its local value. (@code{parsep} is a regular expression that matches
+what separates paragraphs.)
But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
-the then-part of the @code{if} expression and binds
-@code{paragraph-separate} to a regular expression that includes the
-@code{fill-prefix-regexp} as part of the pattern.
-
-Specifically, @code{paragraph-separate} is set to the original value
-of the paragraph separate regular expression concatenated with an
-alternative expression that consists of the @code{fill-prefix-regexp}
-followed by a blank line. The @samp{^} indicates that the
-@code{fill-prefix-regexp} must begin a line, and the optional
-whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.)
-The @samp{\\|} defines this portion of the regexp as an alternative to
-@code{paragraph-separate}.
+the then-part of the @code{if} expression and binds @code{parsep} to a
+regular expression that includes the @code{fill-prefix-regexp} as part
+of the pattern.
+
+Specifically, @code{parsep} is set to the original value of the
+paragraph separate regular expression concatenated with an alternative
+expression that consists of the @code{fill-prefix-regexp} followed by
+optional whitespace to the end of the line. The whitespace is defined
+by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
+regexp as an alternative to @code{parsep}.
+
+According to a comment in the code, the next local variable,
+@code{sp-parstart}, is used for searching, and then the final two,
+@code{start} and @code{found-start}, are set to @code{nil}.
Now we get into the body of the @code{let*}. The first part of the body
of the @code{let*} deals with the case when the function is given a
negative argument and is therefore moving backwards. We will skip this
section.
-@node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph
+@node fwd-para while, , fwd-para let, forward-paragraph
@unnumberedsubsec The forward motion @code{while} loop
The second part of the body of the @code{let*} deals with forward
@code{while} loop is evaluated exactly once, and the cursor moves
forward one paragraph.
+@ignore
+(while (and (> arg 0) (not (eobp)))
+
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
+
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
+
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+
+ (if (< (point) (point-max))
+ (goto-char start))))
+@end ignore
+
This part handles three situations: when point is between paragraphs,
-when point is within a paragraph and there is a fill prefix, and
-when point is within a paragraph and there is no fill prefix.
+when there is a fill prefix and when there is no fill prefix.
@need 800
The @code{while} loop looks like this:
@smallexample
@group
-(while (> arg 0)
- (beginning-of-line)
+;; @r{going forwards and not at the end of the buffer}
+(while (and (> arg 0) (not (eobp)))
;; @r{between paragraphs}
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ ;; @r{This decrements the loop}
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
@end group
@group
- ;; @r{within paragraphs, with a fill prefix}
(if fill-prefix-regexp
- ;; @r{There is a fill prefix; it overrides paragraph-start.}
+ ;; There is a fill prefix; it overrides parstart;
+ ;; we go forward line by line
(while (and (not (eobp))
- (not (looking-at paragraph-separate))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
(looking-at fill-prefix-regexp))
(forward-line 1))
@end group
@group
- ;; @r{within paragraphs, no fill prefix}
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
+ ;; There is no fill prefix;
+ ;; we go forward character by character
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+@end group
- (setq arg (1- arg)))
+@group
+ ;; and if there is no fill prefix and if we are not at the end,
+ ;; go to whatever was found in the regular expression search
+ ;; for sp-parstart
+ (if (< (point) (point-max))
+ (goto-char start))))
@end group
@end smallexample
-We can see immediately that this is a decrementing counter @code{while}
-loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
+@findex eobp
+We can see that this is a decrementing counter @code{while} loop,
+using the expression @code{(setq arg (1- arg))} as the decrementer.
+That expression is not far from the @code{while}, but is hidden in
+another Lisp macro, an @code{unless} macro. Unless we are at the end
+of the buffer --- that is what the @code{eobp} function determines; it
+is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
+of @code{arg} by one.
+
+(If we are at the end of the buffer, we cannot go forward any more and
+the next loop of the @code{while} expression will test false since the
+test is an @code{and} with @code{(not (eobp))}. The @code{not}
+function means exactly as you expect; it is another name for
+@code{null}, a function that returns true when its argument is false.)
+
+Interestingly, the loop count is not decremented until we leave the
+space between paragraphs, unless we come to the end of buffer or stop
+seeing the local value of the paragraph separator.
+
+That second @code{while} also has a @code{(move-to-left-margin)}
+expression. The function is self-explanatory. It is inside a
+@code{progn} expression and not the last element of its body, so it is
+only invoked for its side effect, which is to move point to the left
+margin of the current line.
-@need 800
-The body of the loop consists of three expressions:
+@findex looking-at
+The @code{looking-at} function is also self-explanatory; it returns
+true if the text after point matches the regular expression given as
+its argument.
-@smallexample
-@group
-;; @r{between paragraphs}
-(beginning-of-line)
-(while
- @var{body-of-while})
-@end group
+The rest of the body of the loop looks difficult at first, but makes
+sense as you come to understand it.
-@group
-;; @r{within paragraphs, with fill prefix}
-(if @var{true-or-false-test}
- @var{then-part}
-@end group
+@need 800
+First consider what happens if there is a fill prefix:
+@smallexample
@group
-;; @r{within paragraphs, no fill prefix}
- @var{else-part}
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart;
+ ;; we go forward line by line
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
@end group
@end smallexample
@noindent
-When the Emacs Lisp interpreter evaluates the body of the
-@code{while} loop, the first thing it does is evaluate the
-@code{(beginning-of-line)} expression and move point to the beginning
-of the line. Then there is an inner @code{while} loop. This
-@code{while} loop is designed to move the cursor out of the blank
-space between paragraphs, if it should happen to be there. Finally,
-there is an @code{if} expression that actually moves point to the end
-of the paragraph.
-
-@node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph
-@unnumberedsubsec Between paragraphs
-
-First, let us look at the inner @code{while} loop. This loop handles
-the case when point is between paragraphs; it uses three functions
-that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}.
-@findex prog1
-@findex eobp
-@findex looking-at
+This expression moves point forward line by line so long
+as four conditions are true:
-@itemize @bullet
+@enumerate
@item
-@code{prog1} is similar to the @code{progn} special form,
-except that @code{prog1} evaluates its arguments in sequence and then
-returns the value of its first argument as the value of the whole
-expression. (@code{progn} returns the value of its last argument as the
-value of the expression.) The second and subsequent arguments to
-@code{prog1} are evaluated only for their side effects.
+Point is not at the end of the buffer.
@item
-@code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a
-function that returns true if point is at the end of the buffer.
+We can move to the left margin of the text and are
+not at the end of the buffer.
@item
-@code{looking-at} is a function that returns true if the text following
-point matches the regular expression passed @code{looking-at} as its
-argument.
-@end itemize
+The text following point does not separate paragraphs.
-@need 800
-The @code{while} loop we are studying looks like this:
+@item
+The pattern following point is the fill prefix regular expression.
+@end enumerate
-@smallexample
-@group
-(while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-@end group
-@end smallexample
+The last condition may be puzzling, until you remember that point was
+moved to the beginning of the line early in the @code{forward-paragraph}
+function. This means that if the text has a fill prefix, the
+@code{looking-at} function will see it.
-@need 1200
-@noindent
-This is a @code{while} loop with no body! The true-or-false-test of the
-loop is the expression:
+@need 1250
+Consider what happens when there is no fill prefix.
@smallexample
@group
-(prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
@end group
@end smallexample
@noindent
-The first argument to the @code{prog1} is the @code{and} expression. It
-has within in it a test of whether point is at the end of the buffer and
-also a test of whether the pattern following point matches the regular
-expression for separating paragraphs.
-
-If the cursor is not at the end of the buffer and if the characters
-following the cursor mark the separation between two paragraphs, then
-the @code{and} expression is true. After evaluating the @code{and}
-expression, the Lisp interpreter evaluates the second argument to
-@code{prog1}, which is @code{forward-line}. This moves point forward
-one line. The value returned by the @code{prog1} however, is the
-value of its first argument, so the @code{while} loop continues so
-long as point is not at the end of the buffer and is between
-paragraphs. When, finally, point is moved to a paragraph, the
-@code{and} expression tests false. Note however, that the
-@code{forward-line} command is carried out anyhow. This means that
-when point is moved from between paragraphs to a paragraph, it is left
-at the beginning of the second line of the paragraph.
-
-@node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph
-@unnumberedsubsec Within paragraphs
-
-The next expression in the outer @code{while} loop is an @code{if}
-expression. The Lisp interpreter evaluates the then-part of the
-@code{if} when the @code{fill-prefix-regexp} variable has a value other
-than @code{nil}, and it evaluates the else-part when the value of
-@code{if fill-prefix-regexp} is @code{nil}, that is, when there is no
-fill prefix.
-
-@node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph
-@unnumberedsubsec No fill prefix
+This @code{while} loop has us searching forward for
+@code{sp-parstart}, which is the combination of possible whitespace
+with a the local value of the start of a paragraph or of a paragraph
+separator. (The latter two are within an expression starting
+@code{\(?:} so that they are not referenced by the
+@code{match-beginning} function.)
-It is simplest to look at the code for the case when there is no fill
-prefix first. This code consists of yet another inner @code{if}
-expression, and reads as follows:
+@need 800
+The two expressions,
@smallexample
@group
-(if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max)))
+(setq start (match-beginning 0))
+(goto-char start)
@end group
@end smallexample
@noindent
-This expression actually does the work that most people think of as
-the primary purpose of the @code{forward-paragraph} command: it causes
-a regular expression search to occur that searches forward to the
-start of the next paragraph and if it is found, moves point there; but
-if the start of another paragraph if not found, it moves point to the
-end of the accessible region of the buffer.
+mean go to the start of the text matched by the regular expression
+search.
-The only unfamiliar part of this is the use of @code{match-beginning}.
-This is another function that is new to us. The
-@code{match-beginning} function returns a number specifying the
-location of the start of the text that was matched by the last regular
-expression search.
+The @code{(match-beginning 0)} expression is new. It returns a number
+specifying the location of the start of the text that was matched by
+the last search.
The @code{match-beginning} function is used here because of a
characteristic of a forward search: a successful forward search,
regardless of whether it is a plain search or a regular expression
-search, will move point to the end of the text that is found. In this
-case, a successful search will move point to the end of the pattern for
-@code{paragraph-start}, which will be the beginning of the next
-paragraph rather than the end of the current one.
+search, moves point to the end of the text that is found. In this
+case, a successful search moves point to the end of the pattern for
+@code{sp-parstart}.
-However, we want to put point at the end of the current paragraph, not at
-the beginning of the next one. The two positions may be different,
-because there may be several blank lines between paragraphs.
+However, we want to put point at the end of the current paragraph, not
+somewhere else. Indeed, since the search possibly includes the
+paragraph separator, point may end up at the beginning of the next one
+unless we use an expression that includes @code{match-beginning}.
@findex match-beginning
-When given an argument of 0, @code{match-beginning} returns the position
-that is the start of the text that the most recent regular
-expression search matched. In this case, the most recent regular
-expression search is the one looking for @code{paragraph-start}, so
-@code{match-beginning} returns the beginning position of the pattern,
-rather than the end of the pattern. The beginning position is the end
-of the paragraph.
+When given an argument of 0, @code{match-beginning} returns the
+position that is the start of the text matched by the most recent
+search. In this case, the most recent search looks for
+@code{sp-parstart}. The @code{(match-beginning 0)} expression returns
+the beginning position of that pattern, rather than the end position
+of that pattern.
(Incidentally, when passed a positive number as an argument, the
-@code{match-beginning} function will place point at that parenthesized
-expression in the last regular expression. It is a useful function.)
+@code{match-beginning} function returns the location of point at that
+parenthesized expression in the last search unless that parenthesized
+expression begins with @code{\(?:}. I don't know why @code{\(?:}
+appears here since the argument is 0.)
-@node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph
-@unnumberedsubsec With a fill prefix
-
-The inner @code{if} expression just discussed is the else-part of an enclosing
-@code{if} expression which tests whether there is a fill prefix. If
-there is a fill prefix, the then-part of this @code{if} is evaluated.
-It looks like this:
+@need 1250
+The last expression when there is no fill prefix is
@smallexample
@group
-(while (and (not (eobp))
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
+(if (< (point) (point-max))
+ (goto-char start))))
@end group
@end smallexample
@noindent
-What this expression does is move point forward line by line so long
-as three conditions are true:
-
-@enumerate
-@item
-Point is not at the end of the buffer.
-
-@item
-The text following point does not separate paragraphs.
-
-@item
-The pattern following point is the fill prefix regular expression.
-@end enumerate
-
-The last condition may be puzzling, until you remember that point was
-moved to the beginning of the line early in the @code{forward-paragraph}
-function. This means that if the text has a fill prefix, the
-@code{looking-at} function will see it.
-
-@node fwd-para summary, , fwd-para with fill prefix, forward-paragraph
-@unnumberedsubsec Summary
-
-In summary, when moving forward, the @code{forward-paragraph} function
-does the following:
-
-@itemize @bullet
-@item
-Move point to the beginning of the line.
-
-@item
-Skip over lines between paragraphs.
-
-@item
-Check whether there is a fill prefix, and if there is:
-
-@itemize ---
-
-@item
-Go forward line by line so long as the line is not a paragraph
-separating line.
-@end itemize
-
-@item
-But if there is no fill prefix,
-
-@itemize ---
-
-@item
-Search for the next paragraph start pattern.
-
-@item
-Go to the beginning of the paragraph start pattern, which will be the
-end of the previous paragraph.
-
-@item
-Or else go to the end of the accessible portion of the buffer.
-@end itemize
-@end itemize
-
-@need 1200
-For review, here is the code we have just been discussing, formatted
-for clarity:
-
-@smallexample
-@group
-(interactive "p")
-(or arg (setq arg 1))
-(let* (
- (fill-prefix-regexp
- (and fill-prefix (not (equal fill-prefix ""))
- (not paragraph-ignore-fill-prefix)
- (regexp-quote fill-prefix)))
-@end group
-
-@group
- (paragraph-separate
- (if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^"
- fill-prefix-regexp
- "[ \t]*$")
- paragraph-separate)))
-
- @var{omitted-backward-moving-code} @dots{}
-@end group
-
-@group
- (while (> arg 0) ; @r{forward-moving-code}
- (beginning-of-line)
-
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-@end group
-
-@group
- (if fill-prefix-regexp
- (while (and (not (eobp)) ; @r{then-part}
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
-@end group
-@group
- ; @r{else-part: the inner-if}
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
-
- (setq arg (1- arg))))) ; @r{decrementer}
-@end group
-@end smallexample
+This says that if there is no fill prefix and if we are not at the
+end, point should move to the beginning of whatever was found by the
+regular expression search for @code{sp-parstart}.
The full definition for the @code{forward-paragraph} function not only
-includes this code for going forwards, but also code for going backwards.
+includes code for going forwards, but also code for going backwards.
If you are reading this inside of GNU Emacs and you want to see the
whole function, you can type @kbd{C-h f} (@code{describe-function})
your sources! Without them, you are like a person who tries to drive
a car with his eyes shut!)
-@c !!! again, 21.0.100 tags table location in this paragraph
-Or -- a good habit to get into -- you can type @kbd{M-.}
-(@code{find-tag}) and the name of the function when prompted for it.
-This will take you directly to the source. If the @code{find-tag}
-function first asks you for the name of a @file{TAGS} table, give it
-the name of the @file{TAGS} file such as
-@file{/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to your
-@file{TAGS} file depends on how your copy of Emacs was installed.)
-
-You can also create your own @file{TAGS} file for directories that
-lack one.
-@ifnottex
-@xref{etags, , Create Your Own @file{TAGS} File}.
-@end ifnottex
-
@node etags, Regexp Review, forward-paragraph, Regexp Search
@section Create Your Own @file{TAGS} File
@findex etags
@cindex @file{TAGS} file, create own
-The @kbd{M-.} (@code{find-tag}) command takes you directly to the
-source for a function, variable, node, or other source. The function
-depends on tags tables to tell it where to go.
+Besides @kbd{C-h f} (@code{describe-function}), another way to see the
+source of a function is to type @kbd{M-.} (@code{find-tag}) and the
+name of the function when prompted for it. This is a good habit to
+get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
+to the source for a function, variable, or node. The function depends
+on tags tables to tell it where to go.
+
+If the @code{find-tag} function first asks you for the name of a
+@file{TAGS} table, give it the name of a @file{TAGS} file such as
+@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
+@file{TAGS} file depends on how your copy of Emacs was installed. I
+just told you the location that provides both my C and my Emacs Lisp
+sources.)
+
+You can also create your own @file{TAGS} file for directories that
+lack one.
You often need to build and install tags tables yourself. They are
not built automatically. A tags table is called a @file{TAGS} file;
@end smallexample
@noindent
-to create a @file{TAGS} file.
+to create a @file{TAGS} file for Emacs Lisp.
For example, if you have a large number of files in your
@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
Lisp files in that directory.
@need 1250
-The @code{etags} program takes all the
-usual shell `wildcards'. For example, if you have two directories for
-which you want a single @file{TAGS file}, type
-@w{@code{etags *.el ../elisp/*.el}},
-where @file{../elisp/} is the second directory:
+The @code{etags} program takes all the usual shell `wildcards'. For
+example, if you have two directories for which you want a single
+@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
+@file{../elisp/} is the second directory:
@smallexample
M-x compile RET etags *.el ../elisp/*.el RET
list of supported languages.
The @code{etags} program handles more than 20 languages, including
-Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX,
-Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The
-program has no switches for specifying the language; it recognizes the
-language in an input file according to its file name and contents.
+Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
+LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and
+most assemblers. The program has no switches for specifying the
+language; it recognizes the language in an input file according to its
+file name and contents.
@file{etags} is very helpful when you are writing code yourself and
want to refer back to functions you have already written. Just run
you want, but do not know where it is, you can use the @code{locate}
program to attempt to find it.
-Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the
-full path names of all your @file{TAGS} files. On my system, this
-command lists 34 @file{TAGS} files. On the other hand, a `plain
-vanilla' system I recently installed did not contain any @file{TAGS}
-files.
+Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
+for you the full path names of all your @file{TAGS} files. On my
+system, this command lists 34 @file{TAGS} files. On the other hand, a
+`plain vanilla' system I recently installed did not contain any
+@file{TAGS} files.
If the tags table you want has been created, you can use the @code{M-x
visit-tags-table} command to specify it. Otherwise, you will need to
The GNU Emacs sources come with a @file{Makefile} that contains a
sophisticated @code{etags} command that creates, collects, and merges
tags tables from all over the Emacs sources and puts the information
-into one @file{TAGS} file in the @file{src/} directory below the top
-level of your Emacs source directory.
+into one @file{TAGS} file in the @file{src/} directory. (The
+@file{src/} directory is below the top level of your Emacs directory.)
@need 1250
To build this @file{TAGS} file, go to the top level of your Emacs
nil
@end group
@end smallexample
+
@noindent
(The @code{insert} function inserts its arguments at point; the
@code{format} function returns a string formatted from its arguments
@enumerate
@item
A regular expression that specifies the pattern to search for.
+(Remember to put quotation marks around this argument!)
@item
Optionally, the limit of the search.
of a buffer. The end of the accessible part is the end of the buffer
if the buffer is not narrowed; it is the end of the narrowed part if
the buffer is narrowed.
-
-@item prog1
-Evaluate each argument in sequence and then return the value of the
-@emph{first}.
-
-@need 1250
-For example:
-
-@smallexample
-@group
-(prog1 1 2 3 4)
- @result{} 1
-@end group
-@end smallexample
@end table
@need 1500
words in just a section, rather than all of a buffer. So it makes
more sense to design the command to count the number of words in a
region. Once you have a @code{count-words-region} command, you can,
-if you wish, count words in a whole buffer by marking it with @kbd{C-x
-h} (@code{mark-whole-buffer}).
+if you wish, count words in a whole buffer by marking it with
+@w{@kbd{C-x h}} (@code{mark-whole-buffer}).
Clearly, counting words is a repetitive act: starting from the
beginning of the region, you count the first word, then the second
@noindent
(Note that paired backslashes precede the @samp{w} and @samp{W}. A
-single backslash has special meaning to the Emacs Lisp interpreter. It
-indicates that the following character is interpreted differently than
-usual. For example, the two characters, @samp{\n}, stand for
+single backslash has special meaning to the Emacs Lisp interpreter.
+It indicates that the following character is interpreted differently
+than usual. For example, the two characters, @samp{\n}, stand for
@samp{newline}, rather than for a backslash followed by @samp{n}. Two
-backslashes in a row stand for an ordinary, `unspecial' backslash.)
+backslashes in a row stand for an ordinary, `unspecial' backslash, so
+Emacs Lisp interpreter ends of seeing a single backslash followed by a
+letter. So it discovers the letter is special.)
We need a counter to count how many words there are; this variable
must first be set to 0 and then incremented each time Emacs goes
@iftex
@noindent
(For information about @code{and}, see
-@ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
-Functions}.)
+@ref{kill-new function, , The @code{kill-new} function}.)
@end iftex
@ifinfo
@noindent
-(@xref{forward-paragraph}, for information about @code{and}.)
+(@xref{kill-new function, , The @code{kill-new} function}, for
+information about @code{and}.)
@end ifinfo
The @code{re-search-forward} expression returns @code{t} if the search
succeeds and as a side effect moves point. Consequently, as words are
-found, point is moved through the region. When the search
-expression fails to find another word, or when point reaches the end
-of the region, the true-or-false-test tests false, the @code{while}
-loop exists, and the @code{count-words-region} function displays one
-or other of its messages.
+found, point is moved through the region. When the search expression
+fails to find another word, or when point reaches the end of the
+region, the true-or-false-test tests false, the @code{while} loop
+exits, and the @code{count-words-region} function displays one or
+other of its messages.
After incorporating these final changes, the @code{count-words-region}
works without bugs (or at least, without bugs that I have found!).
each word, the counting mechanism must be an expression that adds one
to the value returned by a call to @code{recursive-count-words}.
+@need 800
Consider several cases:
@itemize @bullet
@node Several defuns, Find a File, count-words-in-defun, Words in a defun
@section Count Several @code{defuns} Within a File
-A file such as @file{simple.el} may have 80 or more function
+A file such as @file{simple.el} may have a hundred or more function
definitions within it. Our long term goal is to collect statistics on
many files, but as a first step, our immediate goal is to collect
statistics on one file.
problem.
@need 1200
-Let's look at the source for @code{find-file} (you can use the
-@code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to
-find the source of a function):
+Let's look at the source for @code{find-file}:
@smallexample
@group
@end group
@end smallexample
-The definition possesses short but complete documentation and an
-interactive specification that prompts you for a file name when you
-use the command interactively. The body of the definition contains
-two functions, @code{find-file-noselect} and @code{switch-to-buffer}.
+@noindent
+(The most recent version of the @code{find-file} function definition
+permits you to specify optional wildcards to visit multiple files; that
+makes the definition more complex and we will not discuss it here,
+since it is not relevant. You can see its source using either
+@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
+
+@ignore
+In Emacs 22
+(defun find-file (filename &optional wildcards)
+ "Edit file FILENAME.
+Switch to a buffer visiting file FILENAME,
+creating one if none already exists.
+Interactively, the default if you just type RET is the current directory,
+but the visited file name is available through the minibuffer history:
+type M-n to pull it into the minibuffer.
+
+Interactively, or if WILDCARDS is non-nil in a call from Lisp,
+expand wildcards (if any) and visit multiple files. You can
+suppress wildcard expansion by setting `find-file-wildcards' to nil.
+
+To visit a file without any kind of conversion and without
+automatically choosing a major mode, use \\[find-file-literally]."
+ (interactive (find-file-read-args "Find file: " nil))
+ (let ((value (find-file-noselect filename nil nil wildcards)))
+ (if (listp value)
+ (mapcar 'switch-to-buffer (nreverse value))
+ (switch-to-buffer value))))
+@end ignore
+
+The definition I am showing possesses short but complete documentation
+and an interactive specification that prompts you for a file name when
+you use the command interactively. The body of the definition
+contains two functions, @code{find-file-noselect} and
+@code{switch-to-buffer}.
According to its documentation as shown by @kbd{C-h f} (the
@code{describe-function} command), the @code{find-file-noselect}
function reads the named file into a buffer and returns the buffer.
-However, the buffer is not selected. Emacs does not switch its
-attention (or yours if you are using @code{find-file-noselect}) to the
-named buffer. That is what @code{switch-to-buffer} does: it switches
-the buffer to which Emacs attention is directed; and it switches the
+(Its most recent version includes an optional wildcards argument,
+too, as well as another to read a file literally and an other you
+suppress warning messages. These optional arguments are irrelevant.)
+
+However, the @code{find-file-noselect} function does not select the
+buffer in which it puts the file. Emacs does not switch its attention
+(or yours if you are using @code{find-file-noselect}) to the selected
+buffer. That is what @code{switch-to-buffer} does: it switches the
+buffer to which Emacs attention is directed; and it switches the
buffer displayed in the window to the new buffer. We have discussed
buffer switching elsewhere. (@xref{Switching Buffers}.)
So instead of calling on @code{find-file} to do the job, we must write
our own expression.
-The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
+The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
@node lengths-list-file, Several files, Find a File, Words in a defun
@section @code{lengths-list-file} in Detail
Besides, the buffer is not going to be saved, even if it were changed.
This line is entirely the consequence of great, perhaps excessive,
caution. The reason for the caution is that this function and those
-it calls work on the sources for Emacs and it is very inconvenient if
-they are inadvertently modified. It goes without saying that I did
-not realize a need for this line until an experiment went awry and
-started to modify my Emacs source files @dots{}
+it calls work on the sources for Emacs and it is inconvenient if they
+are inadvertently modified. It goes without saying that I did not
+realize a need for this line until an experiment went awry and started
+to modify my Emacs source files @dots{}
Next comes a call to widen the buffer if it is narrowed. This
function is usually not needed---Emacs creates a fresh buffer if none
definition and constructs a lengths' list containing the information.
Emacs kills the buffer after working through it. This is to save
-space inside of Emacs. My version of Emacs 19 contained over 300
-source files of interest; Emacs 21 contains over 800 source files.
-Another function will apply @code{lengths-list-file} to each of the
-files.
+space inside of Emacs. My version of GNU Emacs 19 contained over 300
+source files of interest; GNU Emacs 22 contains over a thousand source
+files. Another function will apply @code{lengths-list-file} to each
+of the files.
Finally, the last expression within the @code{let} expression is the
@code{lengths-list} variable; its value is returned as the value of
place your cursor after the following expression and type @kbd{C-x
C-e} (@code{eval-last-sexp}).
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
(lengths-list-file
- "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
+ "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
@end smallexample
-@c was: (lengths-list-file "../lisp/debug.el")
-@c !!! as of 21, Info file is in
-@c /usr/share/info/emacs-lisp-intro.info.gz
-@c but debug.el is in /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
-
@noindent
-(You may need to change the pathname of the file; the one here worked
-with GNU Emacs version 21.0.100. To change the expression, copy it to
+(You may need to change the pathname of the file; the one here is for
+GNU Emacs version 22.1.1. To change the expression, copy it to
the @file{*scratch*} buffer and edit it.
@need 1200
@end smallexample
@noindent
-(@xref{defcustom, , Setting Variables with @code{defcustom}}.
+(@xref{defcustom, , Specifying Variables using @code{defcustom}}.
Then evaluate the @code{lengths-list-file} expression.)
@need 1200
The lengths' list for @file{debug.el} takes less than a second to
-produce and looks like this:
+produce and looks like this in GNU Emacs 22:
@smallexample
-(77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
+(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
@end smallexample
@need 1500
(75 41 80 62 20 45 44 68 45 12 34 235)
@end smallexample
-(The newer version of @file{debug.el} contains more defuns than the
+(The newer version of @file{debug.el} contains more defuns than the
earlier one; and my new machine is much faster than the old one.)
Note that the length of the last definition in the file is first in
@end smallexample
@code{expand-file-name} is a built-in function that converts a file
-name to the absolute, long, path name form of the directory in which
-the function is called.
+name to the absolute, long, path name form. The function employs the
+name of the directory in which the function is called.
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@need 1500
Thus, if @code{expand-file-name} is called on @code{debug.el} when
Emacs is visiting the
-@file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
+@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
@smallexample
debug.el
@noindent
becomes
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
-/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
+/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
@end smallexample
The only other new element of this function definition is the as yet
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 21.0.100; files from other versions of
+for files from Emacs version 22.1.1; files from other versions of
Emacs may produce different results.)
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
@group
-(cd "/usr/local/share/emacs/21.0.100/")
+(cd "/usr/local/share/emacs/22.1.1/")
(lengths-list-file "./lisp/macros.el")
- @result{} (273 263 456 90)
+ @result{} (283 263 480 90)
@end group
@group
(lengths-list-file "./lisp/mail/mailalias.el")
- @result{} (38 32 26 77 174 180 321 198 324)
+ @result{} (38 32 29 95 178 180 321 218 324)
@end group
@group
@end group
@group
-(recursive-lengths-list-many-files
- '("./lisp/macros.el"
- "./lisp/mail/mailalias.el"
- "./lisp/makesum.el"))
- @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
+ (recursive-lengths-list-many-files
+ '("./lisp/macros.el"
+ "./lisp/mail/mailalias.el"
+ "./lisp/makesum.el"))
+ @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
@end group
@end smallexample
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:: Sorting lists.
-* Files List:: Making a list of files.
-* 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
symbols are not evaluated before being passed to @code{sort} as
arguments.)
-Sorting the list returned by the
-@code{recursive-lengths-list-many-files} function is straightforward;
-it uses the @code{<} function:
+Sorting the list returned by the
+@code{recursive-lengths-list-many-files} function is straightforward;
+it uses the @code{<} function:
+
+@ignore
+2006 Oct 29
+In GNU Emacs 22, eval
+(progn
+ (cd "/usr/local/share/emacs/22.0.50/")
+ (sort
+ (recursive-lengths-list-many-files
+ '("./lisp/macros.el"
+ "./lisp/mail/mailalias.el"
+ "./lisp/makesum.el"))
+ '<))
+
+@end ignore
@smallexample
@group
(sort
(recursive-lengths-list-many-files
- '("../lisp/macros.el"
- "../lisp/mailalias.el"
- "../lisp/makesum.el"))
- '<
+ '("./lisp/macros.el"
+ "./lisp/mailalias.el"
+ "./lisp/makesum.el"))
+ '<)
@end group
@end smallexample
which produces:
@smallexample
-(85 86 116 122 154 176 179 265)
+(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
@end smallexample
@noindent
@smallexample
@group
-("../lisp/macros.el"
- "../lisp/mail/rmail.el"
- "../lisp/makesum.el")
+("./lisp/macros.el"
+ "./lisp/mail/rmail.el"
+ "./lisp/makesum.el")
@end group
@end smallexample
For example, the first @samp{.el} file in the @file{lisp/} directory
is @file{abbrev.el}. Its name is
-@file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
+@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
directory or a symbolic link.
@need 1000
@smallexample
@group
-("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
+("abbrev.el"
nil
1
1000
100
@end group
@group
-(15019 32380)
-(14883 48041)
-(15214 49336)
-11583
+(17733 259)
+(17491 28834)
+(17596 62124)
+13157
"-rw-rw-r--"
@end group
@group
-t
-341385
-776)
+nil
+2971624
+773)
@end group
@end smallexample
@smallexample
@group
-("/usr/local/share/emacs/21.0.100/lisp/mail"
+("mail"
t
@dots{}
)
@end group
@end smallexample
-(Look at the documentation of @code{file-attributes} to learn about
-the different attributes. Bear in mind that the
-@code{file-attributes} function does not list the filename, so its
-first element is @code{directory-files-and-attributes}'s second
-element.)
+(To learn about the different attributes, look at the documentation of
+@code{file-attributes}. Bear in mind that the @code{file-attributes}
+function does not list the filename, so its first element is
+@code{directory-files-and-attributes}'s second element.)
We will want our new function, @code{files-in-below-directory}, to
list the @samp{.el} files in the directory it is told to check, and in
using @code{append} as the combiner.
@ignore
-(directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$")
-(shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'")
+(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
+(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
+
+(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
+(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
@end ignore
-@c /usr/local/share/emacs/21.0.100/lisp/
+@c /usr/local/share/emacs/22.1.1/lisp/
@need 800
Here is the function:
;; Although the function will be used non-interactively,
;; it will be easier to test if we make it interactive.
;; The directory will have a name such as
- ;; "/usr/local/share/emacs/21.0.100/lisp/"
+ ;; "/usr/local/share/emacs/22.1.1/lisp/"
(interactive "DDirectory name: ")
@end group
@group
((eq t (car (cdr (car current-directory-list))))
;; decide whether to skip or recurse
(if
- (equal (or "." "..")
+ (equal "."
(substring (car (car current-directory-list)) -1))
- ;; then do nothing if filename is that of
- ;; current directory or parent
+ ;; then do nothing since filename is that of
+ ;; current directory or parent, "." or ".."
()
@end group
@group
@end group
@end smallexample
-@c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
+@c (files-in-below-directory "/usr/local/src/emacs/lisp/")
+@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
The @code{files-in-below-directory} @code{directory-files} function
takes one argument, the name of a directory.
@need 1250
Thus, on my system,
-@c !!! 21.0.100 lisp sources location here
+@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
+
+@c !!! 22.1.1 lisp sources location here
@smallexample
@group
(length
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
+ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
@end group
@end smallexample
@noindent
-tells me that my version 21.0.100 Lisp sources directory contains 754
+tells me that in and below my Lisp sources directory are 1031
@samp{.el} files.
@code{files-in-below-directory} returns a list in reverse alphabetical
@smallexample
@group
(sort
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
+ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
'string-lessp)
@end group
@end smallexample
@ignore
(defun test ()
- "Test how long it takes to find lengths of all elisp defuns."
+ "Test how long it takes to find lengths of all sorted elisp defuns."
(insert "\n" (current-time-string) "\n")
(sit-for 0)
(sort
(recursive-lengths-list-many-files
- '("../lisp/macros.el"
- "../lisp/mailalias.el"
- "../lisp/makesum.el"))
+ (files-in-below-directory "/usr/local/src/emacs/lisp/"))
'<)
(insert (format "%s" (current-time-string))))
-
@end ignore
@node Counting function definitions, , Files List, Prepare the data
@c colon in printed section title causes problem in Info cross reference
This way, we avoid an error.
@iftex
-@xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
-Functions}, for more information about @code{and}.
+@noindent
+(For information about @code{and}, see
+@ref{kill-new function, , The @code{kill-new} function}.)
@end iftex
@ifinfo
-@xref{forward-paragraph}, for more information about @code{and}.
+@noindent
+(@xref{kill-new function, , The @code{kill-new} function}, for
+information about @code{and}.)
@end ifinfo
Here is a short test of the @code{defuns-per-range} function. First,
of 200 or larger.
@c The next step is to turn this numbers' list into a graph.
-
@node Readying a Graph, Emacs Initialization, Words in a defun, Top
@chapter Readying a Graph
@cindex Readying a graph
own column-insertion function or discover whether one exists in Emacs.
To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
-command. This command is like the @kbd{C-h a} (command-apropos)
+command. This command is like the @kbd{C-h a} (@code{command-apropos})
command, except that the latter finds only those functions that are
commands. The @kbd{M-x apropos} command lists all symbols that match
a regular expression, including functions that are not interactive.
the word `print' or the word `insert' or the word `column'.
Therefore, we can simply type @kbd{M-x apropos RET
print\|insert\|column RET} and look at the result. On my system, this
-command takes quite some time, and then produces a list of 79
-functions and variables. Scanning down the list, the only function
-that looks as if it might do the job is @code{insert-rectangle}.
+command once too takes quite some time, and then produced a list of 79
+functions and variables. Now it does not take much time at all and
+produces a list of 211 functions and variables. Scanning down the
+list, the only function that looks as if it might do the job is
+@code{insert-rectangle}.
@need 1200
Indeed, this is the function we want; its documentation says:
RECTANGLE's first line is inserted at point,
its second line is inserted at a point vertically under point, etc.
RECTANGLE should be a list of strings.
+After this command, the mark is at the upper left corner
+and point is at the lower right corner.
@end group
@end smallexample
@group
(insert-rectangle '("first" "second" "third"))first
second
- third
-nil
+ thirdnil
@end group
@end smallexample
If you are reading this in Info, you can see how this works by
switching to another buffer, such as the @file{*scratch*} buffer,
-placing point somewhere in the buffer, typing @kbd{M-:},
-typing the @code{insert-rectangle} expression into the minibuffer at
-the prompt, and then typing @key{RET}. This causes Emacs to evaluate
-the expression in the minibuffer, but to use as the value of point the
-position of point in the @file{*scratch*} buffer. (@kbd{M-:}
-is the keybinding for @code{eval-expression}.)
+placing point somewhere in the buffer, typing @kbd{M-:}, typing the
+@code{insert-rectangle} expression into the minibuffer at the prompt,
+and then typing @key{RET}. This causes Emacs to evaluate the
+expression in the minibuffer, but to use as the value of point the
+position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
+keybinding for @code{eval-expression}. Also, @code{nil} does not
+appear in the @file{*scratch*} buffer since the expression is
+evaluated in the minibuffer.)
We find when we do this that point ends up at the end of the last
inserted line---that is to say, this function moves point as a
The recursive function is a little more difficult. It has four parts:
the `do-again-test', the printing code, the recursive call, and the
-`next-step-expression'. The `do-again-test' is an @code{if}
+`next-step-expression'. The `do-again-test' is a @code{when}
expression that determines whether the @code{numbers-list} contains
any remaining elements; if it does, the function prints one column of
the graph using the printing code and calls itself again. The
@end group
@group
- (if numbers-list
- (progn
+ (when numbers-list
(setq from-position (point))
(insert-rectangle
(column-of-graph height (car numbers-list)))
(forward-char symbol-width)
(sit-for 0) ; @r{Draw graph column by column.}
(recursive-graph-body-print-internal
- (cdr numbers-list) height symbol-width))))
+ (cdr numbers-list) height symbol-width)))
@end group
@end smallexample
* 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.
+* X11 Colors:: Colors in X.
* Miscellaneous::
* Mode Line:: How to customize your mode line.
@end menu
sense, if you do not know who is going to use Emacs. Who knows what a
person hopes to do with an unadorned file? Fundamental mode is the
right default for such a file, just as C mode is the right default for
-editing C code. But when you do know who is going to use Emacs---you,
+editing C code. (Enough programming languages have syntaxes
+that enable them to share or nearly share features, so C mode is
+now provided by by CC mode, the `C Collection'.)
+
+But when you do know who is going to use Emacs---you,
yourself---then it makes sense to customize Emacs.
For example, I seldom want Fundamental mode when I edit an
arguments are optional.)
Each of these arguments consists of a keyword followed by a value.
-Each keyword starts with the character @code{:}.
+Each keyword starts with the colon character @samp{:}.
@need 1250
For example, the customizable user option variable
The name of the variable is @code{text-mode-hook}; it has no default
value; and its documentation string tells you what it does.
-The @code{:type} keyword tells Emacs what kind of data
-@code{text-mode-hook} should be set to and how to display the value in
-a Customization buffer.
+The @code{:type} keyword tells Emacs the kind of data to which
+@code{text-mode-hook} should be set and how to display the value in a
+Customization buffer.
The @code{:options} keyword specifies a suggested list of values for
-the variable. Currently, you can use @code{:options} only for a hook.
+the variable. Usually, @code{:options} applies to a hook.
The list is only a suggestion; it is not exclusive; a person who sets
the variable may set it to other values; the list shown following the
@code{:options} keyword is intended to offer convenient choices to a
command in which group the variable is located. This tells where to
find it.
+The @code{defcustom} function recognizes more than a dozen keywords.
For more information, see @ref{Customization, , Writing Customization
Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
@noindent
and find that the group for editing files of data is called `data'.
Enter that group. Text Mode Hook is the first member. You can click
-on its various options to set the values. After you click on the
-button to
+on its various options, such as @code{turn-on-auto-fill}, to set the
+values. After you click on the button to
@smallexample
Save for Future Sessions
@smallexample
@group
(custom-set-variables
- ;; custom-set-variables was added by Custom --
- ;; don't edit or cut/paste it!
+ ;; custom-set-variables was added by Custom.
+ ;; If you edit it by hand, you could mess it up, so be careful.
;; Your init file should contain only one such instance.
+ ;; If there is more than one, they won't work right.
'(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
@end group
@end smallexample
@noindent
(The @code{text-mode-hook-identify} function tells
-@code{toggle-text-mode-auto-fill} which buffers are in Text mode.)
-
-In spite of the warning, you certainly may edit, cut, and paste the
-expression! I do all time. The purpose of the warning is to scare
-those who do not know what they are doing, so they do not
-inadvertently generate an error.
+@code{toggle-text-mode-auto-fill} which buffers are in Text mode.
+It comes on automatically.)
-The @code{custom-set-variables} works somewhat differently than a
-@code{setq}. While I have never learned the differences, I do modify
-the @code{custom-set-variables} expressions in my @file{.emacs} file
-by hand: I make the changes in what appears to me to be a reasonable
-manner and have not had any problems. Others prefer to use the
-Customization command and let Emacs do the work for them.
+The @code{custom-set-variables} function works somewhat differently
+than a @code{setq}. While I have never learned the differences, I
+modify the @code{custom-set-variables} expressions in my @file{.emacs}
+file by hand: I make the changes in what appears to me to be a
+reasonable manner and have not had any problems. Others prefer to use
+the Customization command and let Emacs do the work for them.
Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
This function sets the various font faces. Over time, I have set a
message that says
@smallexample
-this option has been changed outside the customize buffer.
+CHANGED outside Customize; operating on it here may be unreliable.
@end smallexample
@need 800
I myself use @code{customize} for hardly anything. Mostly, I write
expressions myself.
+@findex defsubst
+@findex defconst
+Incidentally, to be more complete concerning defines: @code{defsubst}
+defines an inline function. The syntax is just like that of
+@code{defun}. @code{defconst} defines a symbol as a constant. The
+intent is that neither programs nor users should ever change a value
+set by @code{defconst}. (You can change it; the value set is a
+variable; but please do not.)
+
@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
@section Beginning a @file{.emacs} File
@cindex @file{.emacs} file, beginning of
By now, of course, I remember these things, but when I started, I did
not.
+@need 1200
@smallexample
@group
;;;; Bob's .emacs file
@noindent
This describes the usual conventions for comments in Emacs Lisp.
Everything on a line that follows a semicolon is a comment. Two,
-three, and four semicolons are used as section and subsection
-markers. (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference
-Manual}, for more about comments.)
+three, and four semicolons are used as subsection and section markers.
+(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
+more about comments.)
@smallexample
@group
@smallexample
@group
;;; Text mode and Auto Fill mode
-; The next three lines put Emacs into Text mode
+; The next two lines put Emacs into Text mode
; and Auto Fill mode, and are for writers who
; want to start writing prose rather than code.
-
(setq default-major-mode 'text-mode)
-(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end group
@end smallexample
else in Emacs.
@need 800
-Here are the next two lines:
+Here is the next line:
@cindex Auto Fill mode turned on
@findex add-hook
@smallexample
-(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end smallexample
@noindent
-In these two lines, the @code{add-hook} command first adds
-@code{text-mode-hook-identify} to the variable called
-@code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the
-variable.
+In this line, the @code{add-hook} command adds
+@code{turn-on-auto-fill} to the variable.
@code{turn-on-auto-fill} is the name of a program, that, you guessed
-it!, turns on Auto Fill mode. @code{text-mode-hook-identify} is a
-function that tells @code{toggle-text-mode-auto-fill} which buffers
-are in Text mode.
+it!, turns on Auto Fill mode.
Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
onto Text mode. So every time Emacs turns on Text mode, Emacs also
turns on Auto Fill mode.
-In brief, the first line causes Emacs to enter Text mode when you edit
-a file, unless the file name extension, first non-blank line, or local
-variables tell Emacs otherwise.
+In brief, the first line causes Emacs to enter Text mode when you edit a
+file, unless the file name extension, a first non-blank line, or local
+variables to tell Emacs otherwise.
Text mode among other actions, sets the syntax table to work
conveniently for writers. In Text mode, Emacs considers an apostrophe
@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
the @samp{t} of @samp{it's}.
-The second and third lines causes Emacs to turn on Auto Fill mode when
-it turns on Text mode. In Auto Fill mode, Emacs automatically breaks
-a line that is too wide and brings the excessively wide part of the
-line down to the next line. Emacs breaks lines between words, not
-within them.
+The second line causes Emacs to turn on Auto Fill mode when it turns
+on Text mode. In Auto Fill mode, Emacs automatically breaks a line
+that is too wide and brings the excessively wide part of the line down
+to the next line. Emacs breaks lines between words, not within them.
When Auto Fill mode is turned off, lines continue to the right as you
type them. Depending on how you set the value of
; To enter mail mode, type `C-x m'
; To enter RMAIL (for reading mail),
; type `M-x rmail'
-
(setq mail-aliases t)
@end group
@end smallexample
Files'' in @cite{The GNU Emacs Manual}.
@end iftex
+@need 1700
@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
@section Some Keybindings
The command is @code{global-set-key}. It is followed by the
keybinding. In a @file{.emacs} file, the keybinding is written as
shown: @code{\C-c} stands for `control-c', which means `press the
-control key and the @kbd{c} key at the same time'. The @code{w} means
-`press the @kbd{w} key'. The keybinding is surrounded by double
-quotation marks. In documentation, you would write this as @kbd{C-c
-w}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather
-than a @key{CTL} key, you would write @code{\M-c}. @xref{Init
-Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs
-Manual}, for details.)
+control key and the @key{c} key at the same time'. The @code{w} means
+`press the @key{w} key'. The keybinding is surrounded by double
+quotation marks. In documentation, you would write this as
+@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
+@kbd{M-c}, rather than a @key{CTRL} key, you would write
+@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
+Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
+details.)
The command invoked by the keys is @code{compare-windows}. Note that
@code{compare-windows} is preceded by a single quote; otherwise, Emacs
Many people in the GNU Emacs community have written extensions to
Emacs. As time goes by, these extensions are often included in new
releases. For example, the Calendar and Diary packages are now part
-of the standard GNU Emacs.
-
-(Calc, which I consider a vital part of Emacs, would be part of the
-standard distribution except that it was so large it was packaged
-separately and no one has changed that.)
+of the standard GNU Emacs, as is Calc.
You can use a @code{load} command to evaluate a complete file and
thereby install all the functions and variables in the file into Emacs.
(defun load-library (library)
"Load the library named LIBRARY.
This is an interface to the function `load'."
- (interactive "sLoad library: ")
+ (interactive
+ (list (completing-read "Load library: "
+ 'locate-file-completion
+ (cons load-path (get-load-suffixes)))))
(load library))
@end group
@end smallexample
load that function's file with a @code{load} expression in your
@file{.emacs} file.
-In my @file{.emacs} file for Emacs version 21, I load 12 libraries
-that contain functions that would otherwise be autoloaded. (Actually,
-it would have been better to include these files in my `dumped' Emacs
-when I built it, 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 smallexample
@noindent
-(@code{html-helper-mode} is an alternative to @code{html-mode}, which
-is a standard part of the distribution).
+(@code{html-helper-mode} is an older alternative to @code{html-mode},
+which is a standard part of the distribution.)
@noindent
This expression autoloads the @code{html-helper-mode} function. It
@cindex Conditional 'twixt two versions of Emacs
@cindex Version of Emacs, choosing
@cindex Emacs version, choosing
-If you run two versions of GNU Emacs, such as versions 20 and 21, and
+If you run two versions of GNU Emacs, such as versions 21 and 22, and
use one @file{.emacs} file, you can select which code to evaluate with
the following conditional:
@smallexample
@group
(cond
- ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
- ;; evaluate version 20 code
- ( @dots{} ))
- ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
+ (= 21 emacs-major-version)
;; evaluate version 21 code
+ ( @dots{} ))
+ (= 22 emacs-major-version)
+ ;; evaluate version 22 code
( @dots{} )))
@end group
@end smallexample
-For example, in contrast to version 20, version 21 blinks its cursor
-by default. I hate such blinking, as well as some other features in
-version 21, so I placed the following in my @file{.emacs}
+For example, in contrast to version 20, more recent versions blink
+their cursors by default. I hate such blinking, as well as other
+features, so I placed the following in my @file{.emacs}
file@footnote{When I start instances of Emacs that do not load my
@file{.emacs} file or any site file, I also turn off blinking:
@smallexample
emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
+
+@exdent Or nowadays, using an even more sophisticated set of options,
+
+emacs -Q - D
@end smallexample
}:
@smallexample
@group
-(if (string-equal "21" (substring (emacs-version) 10 12))
- (progn
+(when (or (= 21 emacs-major-version)
+ (= 22 emacs-major-version))
(blink-cursor-mode 0)
;; Insert newline when you press `C-n' (next-line)
;; at the end of the buffer
;; (Use numeric argument to turn on)
(tooltip-mode nil)
;; If tooltips turned on, make tips appear promptly
- (setq tooltip-delay 0.1) ; default is one second
- ))
+ (setq tooltip-delay 0.1) ; default is 0.7 second
+ )
+@end group
+@end smallexample
+
+@need 1250
+Alternatively, since @code{blink-cursor-mode} has existed since Emacs
+version 21 and is likely to continue, you could write
+
+@smallexample
+@group
+(when (>= emacs-major-version 21)
+ (blink-cursor-mode 0)
@end group
@end smallexample
@noindent
-(You will note that instead of typing @code{(number-to-string 21)}, I
-decided to save typing and wrote `21' as a string, @code{"21"}, rather
-than convert it from an integer to a string. In this instance, this
-expression is better than the longer, but more general
-@code{(number-to-string 21)}. However, if you do not know ahead of
-time what type of information will be returned, then the
-@code{number-to-string} function will be needed.)
+and add other expressions, too.
+
@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
@section X11 Colors
@end smallexample
In any event, since it is not part of Emacs, I set the root color of
-my X window in my @file{~/.xinitrc} file, like this@footnote{I
-occasionally run more modern window managers, such as Sawfish with
-GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an
-image rather than a plain color.}:
+my X window in my @file{~/.xinitrc} file, like this@footnote{I also
+run more modern window managers, such as Enlightenment, Gnome, or KDE;
+in those cases, I often specify an image rather than a plain color.}:
@smallexample
-@group
-# I use TWM for window manager.
xsetroot -solid Navy -fg white &
-@end group
@end smallexample
+@need 1700
@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
@section Miscellaneous Settings for a @file{.emacs} File
+@need 1250
Here are a few miscellaneous settings:
@sp 1
@itemize @minus
@item
Set the shape and color of the mouse cursor:
+
@smallexample
@group
; Cursor shapes are defined in
(set-mouse-color "white"))
@end group
@end smallexample
+
+@item
+Or you can set the values of a variety of features in an alist, like
+this:
+
+@smallexample
+@group
+(setq-default
+ default-frame-alist
+ '((cursor-color . "white")
+ (mouse-color . "white")
+ (foreground-color . "white")
+ (background-color . "DodgerBlue4")
+ ;; (cursor-type . bar)
+ (cursor-type . box)
+@end group
+@group
+ (tool-bar-lines . 0)
+ (menu-bar-lines . 1)
+ (width . 80)
+ (height . 58)
+ (font .
+ "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
+ ))
+@end group
+@end smallexample
+
+@item
+Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
+into @kbd{@key{CTRL}-h}.@*
+(Some older keyboards needed this, although I have not seen the
+problem recently.)
+
+@smallexample
+@group
+;; Translate `C-h' to <DEL>.
+; (keyboard-translate ?\C-h ?\C-?)
+
+;; Translate <DEL> to `C-h'.
+(keyboard-translate ?\C-? ?\C-h)
+@end group
+@end smallexample
+
+@item Turn off a blinking cursor!
+
+@smallexample
+@group
+(if (fboundp 'blink-cursor-mode)
+ (blink-cursor-mode -1))
+@end group
+@end smallexample
+
+@noindent
+or start GNU Emacs with the command @code{emacs -nbc}.
+
+@need 1250
+@item When using `grep'@*
+@samp{-i}@w{ } Ignore case distinctions@*
+@samp{-n}@w{ } Prefix each line of output with line number@*
+@samp{-H}@w{ } Print the filename for each match.@*
+@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
+
+@smallexample
+(setq grep-command "grep -i -nH -e ")
+@end smallexample
+
+@ignore
+@c Evidently, no longer needed in GNU Emacs 22
+
+item Automatically uncompress compressed files when visiting them
+
+smallexample
+(load "uncompress")
+end smallexample
+
+@end ignore
+
+@item Find an existing buffer, even if it has a different name@*
+This avoids problems with symbolic links.
+
+@smallexample
+(setq find-file-existing-other-name t)
+@end smallexample
+
+@item Set your language environment and default input method
+
+@smallexample
+@group
+(set-language-environment "latin-1")
+;; Remember you can enable or disable multilingual text input
+;; with the @code{toggle-input-method'} (@kbd{C-\}) command
+(setq default-input-method "latin-1-prefix")
+@end group
+@end smallexample
+
+If you want to write with Chinese `GB' characters, set this instead:
+
+@smallexample
+@group
+(set-language-environment "Chinese-GB")
+(setq default-input-method "chinese-tonepy")
+@end group
+@end smallexample
@end itemize
+@subsubheading Fixing Unpleasant Key Bindings
+@cindex Key bindings, fixing
+@cindex Bindings, key, fixing unpleasant
+
+Some systems bind keys unpleasantly. Sometimes, for example, the
+@key{CTRL} key appears in an awkward spot rather than at the far left
+of the home row.
+
+Usually, when people fix these sorts of keybindings, they do not
+change their @file{~/.emacs} file. Instead, they bind the proper keys
+on their consoles with the @code{loadkeys} or @code{install-keymap}
+commands in their boot script and then include @code{xmodmap} commands
+in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
+
+@need 1250
+@noindent
+For a boot script:
+
+@smallexample
+@group
+loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
+@exdent or
+install-keymap emacs2
+@end group
+@end smallexample
+
+@need 1250
+@noindent
+For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
+Lock} key is at the far left of the home row:
+
+@smallexample
+@group
+# Bind the key labeled `Caps Lock' to `Control'
+# (Such a broken user interface suggests that keyboard manufacturers
+# think that computers are typewriters from 1885.)
+
+xmodmap -e "clear Lock"
+xmodmap -e "add Control = Caps_Lock"
+@end group
+@end smallexample
+
+@need 1250
+@noindent
+In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
+key to a @key{META} key:
+
+@smallexample
+@group
+# Some ill designed keyboards have a key labeled ALT and no Meta
+xmodmap -e "keysym Alt_L = Meta_L Alt_L"
+@end group
+@end smallexample
+
+@need 1700
@node Mode Line, , Miscellaneous, Emacs Initialization
@section A Modified Mode Line
@vindex default-mode-line-format
on. However, the format looks complicated because of two features we
have not discussed.
+@cindex Properties, in mode line example
The first string in the mode line is a dash or hyphen, @samp{-}. In
the old days, it would have been specified simply as @code{"-"}. But
nowadays, Emacs can add properties to a string, such as highlighting
or, as in this case, a help feature. If you place your mouse cursor
-over the hyphen, some help information appears (By default, you must
-wait one second before the information appears. You can change that
-timing by changing the value of @code{tooltip-delay}.)
+over the hyphen, some help information appears (By default, you must
+wait seven-tenths of a second before the information appears. You can
+change that timing by changing the value of @code{tooltip-delay}.)
@need 1000
The new string format has a special syntax:
case, a string. The second, third, and fourth elements of this new
string format can be repeated.
-@xref{Text Props and Strings, , Text Properties in String, elisp, The
-GNU Emacs Lisp Reference Manual}, and see @ref{Mode Line Format, , Mode
-Line Format, elisp, The GNU Emacs Lisp Reference Manual}, for more
-information.
+@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
+Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
+elisp, The GNU Emacs Lisp Reference Manual}, for more information.
@code{mode-line-buffer-identification}
displays the current buffer name. It is a list
characters; this length works well in a typical 80 column wide
window.)
-@code{:eval} is a new feature in GNU Emacs version 21. It says to
-evaluate the following form and use the result as a string to display.
-In this case, the expression displays the first component of the full
-system name. The end of the first component is a @samp{.} (`period'),
-so I use the @code{string-match} function to tell me the length of the
-first component. The substring from the zeroth character to that
-length is the name of the machine.
+@code{:eval} says to evaluate the following form and use the result as
+a string to display. In this case, the expression displays the first
+component of the full system name. The end of the first component is
+a @samp{.} (`period'), so I use the @code{string-match} function to
+tell me the length of the first component. The substring from the
+zeroth character to that length is the name of the machine.
@need 1250
This is the expression:
@end smallexample
@noindent
-In GNU Emacs version 21, you will create and enter a
-@file{*Backtrace*} buffer that says:
+In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
+buffer that says:
@noindent
@smallexample
tell you what you need to know to correct the definition. The
function @code{1=} is `void'.
+@ignore
@need 800
In GNU Emacs 20 and before, you will see:
@noindent
which has the same meaning as the @file{*Backtrace*} buffer line in
version 21.
+@end ignore
However, suppose you are not quite certain what is going on?
You can read the complete backtrace.
-In this case, you need to run GNU Emacs 21, which automatically starts
-the debugger that puts you in the @file{*Backtrace*} buffer; or else,
-you need to start the debugger manually as described below.
+In this case, you need to run a recent GNU Emacs, which automatically
+starts the debugger that puts you in the @file{*Backtrace*} buffer; or
+else, you need to start the debugger manually as described below.
Read the @file{*Backtrace*} buffer from the bottom up; it tells you
what Emacs did that led to the error. Emacs made an interactive call
@section @code{debug-on-entry}
@findex debug-on-entry
-GNU Emacs 21 starts the debugger automatically when your function has
-an error. GNU Emacs version 20 and before did not; it simply
+A recent GNU Emacs starts the debugger automatically when your
+function has an error.
+
+@ignore
+GNU Emacs version 20 and before did not; it simply
presented you with an error message. You had to start the debugger
manually.
+@end ignore
-You can start the debugger manually for all versions of Emacs; the
-advantage is that the debugger runs even if you do not have a bug in
-your code. Sometimes your code will be free of bugs!
+Incidentally, you can start the debugger manually for all versions of
+Emacs; the advantage is that the debugger runs even if you do not have
+a bug in your code. Sometimes your code will be free of bugs!
You can enter the debugger when you call the function by calling
@code{debug-on-entry}.
@end group
@end smallexample
+@need 1500
@noindent
Finally, after you type @kbd{d} two more times, Emacs will reach the
error, and the top two lines of the @file{*Backtrace*} buffer will look
Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
Lisp Reference Manual}.
+@need 1250
Here is a bugged function definition for @code{triangle-recursively}.
@xref{Recursive triangle function, , Recursion in place of a counter},
for a review of it.
@need 1500
However, to prepare this function definition for Edebug, you must
first @dfn{instrument} the code using a different command. You can do
-this by positioning your cursor within the definition and typing
+this by positioning your cursor within or just after the definition
+and typing
@smallexample
M-x edebug-defun RET
move point past @code{number}, you will see the following:
@smallexample
-Result: 3 = C-c
+Result: 3 (#o3, #x3, ?\C-c)
@end smallexample
@noindent
-This means the value of @code{number} is 3, which is @sc{ascii}
-`control-c' (the third letter of the alphabet).
+This means the value of @code{number} is 3, which is octal three,
+hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
+alphabet, in case you need to know this information).
You can continue moving through the code until you reach the line with
the error. Before evaluation, that line looks like this:
@item
While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
-@kbd{@key{CTL}-x} followed by an upper case @kbd{X}; use this prefix
+@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
for commands made outside of the Edebug debugging buffer.)
@item
@code{count-words-region} is working.
@item
-Move point to some spot further down function and then type the
+Move point to some spot further down the function and then type the
@kbd{h} (@code{edebug-goto-here}) command to jump to that location.
@item
on-line and as a typeset, printed book.)
Go to the other on-line help that is part of GNU Emacs: the on-line
-documentation for all functions, and @code{find-tags}, the program
-that takes you to sources.
+documentation for all functions and variables, and @code{find-tags},
+the program that takes you to sources.
Here is an example of how I explore the sources. Because of its name,
@file{simple.el} is the file I looked at first, a long time ago. As
function, for example, looks complicated.
You may want to walk through this function slowly, as we did with the
-@code{forward-sentence} function.
-@ifnottex
-(@xref{forward-sentence}.)
-@end ifnottex
-@iftex
-(@xref{forward-sentence, , @code{forward-sentence}}.)
-@end iftex
-Or you may want to skip that function and look at another, such as
-@code{split-line}. You don't need to read all the functions.
-According to @code{count-words-in-defun}, the @code{split-line}
-function contains 27 words and symbols.
-
-Even though it is short, @code{split-line} contains four expressions
+@code{forward-sentence} function. (@xref{forward-sentence, The
+@code{forward-sentence} function}.) Or you may want to skip that
+function and look at another, such as @code{split-line}. You don't
+need to read all the functions. According to
+@code{count-words-in-defun}, the @code{split-line} function contains
+102 words and symbols.
+
+Even though it is short, @code{split-line} contains expressions
we have not studied: @code{skip-chars-forward}, @code{indent-to},
-@code{current-column} and @samp{?\n}.
+@code{current-column} and @code{insert-and-inherit}.
Consider the @code{skip-chars-forward} function. (It is part of the
function definition for @code{back-to-indentation}, which is shown in
character codes; and it shows how to create a temporary buffer.
(The @code{indent-to} function is written in C rather than Emacs Lisp;
-it is a `built-in' function. @code{help-follow} only provides you
-with the documentation of a built-in function; it does not take you to
-the source. But @code{find-tag} will take you to the source, if
-properly set up.)
+it is a `built-in' function. @code{help-follow} takes you to its
+source as does @code{find-tag}, when properly set up.)
You can look at a function's source using @code{find-tag}, which is
bound to @kbd{M-.} Finally, you can find out what the Reference
Manual has to say by visiting the manual in Info, and typing @kbd{i}
-(@code{Info-index}) and the name of the function, or by looking up
-@code{skip-chars-forward} in the index to a printed copy of the
-manual.
-
-Similarly, you can find out what is meant by @samp{?\n}. You can try
-using @code{Info-index} with @samp{?\n}. It turns out that this
-action won't help; but don't give up. If you search the index for
-@samp{\n} without the @samp{?}, you will be taken directly to the
-relevant section of the manual. (@xref{Character Type, , Character
-Type, elisp, The GNU Emacs Lisp Reference Manual}. @samp{?\n} stands
-for the newline character.)
+(@code{Info-index}) and the name of the function, or by looking up the
+function in the index to a printed copy of the manual.
+
+Similarly, you can find out what is meant by
+@code{insert-and-inherit}.
Other interesting source files include @file{paragraphs.el},
@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
Sometimes when you you write text, you duplicate words---as with ``you
you'' near the beginning of this sentence. I find that most
-frequently, I duplicate ``the'; hence, I call the function for
+frequently, I duplicate ``the''; hence, I call the function for
detecting duplicated words, @code{the-the}.
@need 1250
@cindex Ring, making a list like a
The kill ring is a list that is transformed into a ring by the
-workings of the @code{rotate-yank-pointer} function. The @code{yank}
-and @code{yank-pop} commands use the @code{rotate-yank-pointer}
-function. This appendix describes the @code{rotate-yank-pointer}
-function as well as both the @code{yank} and the @code{yank-pop}
-commands.
-
-@menu
-* rotate-yank-pointer:: Move a pointer along a list and around.
-* yank:: Paste a copy of a clipped element.
-* yank-pop:: Insert first element pointed to.
-@end menu
-
-@node rotate-yank-pointer, yank, Kill Ring, Kill Ring
-@comment node-name, next, previous, up
-@appendixsec The @code{rotate-yank-pointer} Function
-@findex rotate-yank-pointer
-
-The @code{rotate-yank-pointer} function changes the element in the kill
-ring to which @code{kill-ring-yank-pointer} points. For example, it can
-change @code{kill-ring-yank-pointer} from pointing to the second
-element to point to the third element.
-
-@need 800
-Here is the code for @code{rotate-yank-pointer}:
-
-@smallexample
-@group
-(defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
- (let ((length (length kill-ring)))
-@end group
-@group
- (if (zerop length)
- ;; @r{then-part}
- (error "Kill ring is empty")
-@end group
-@group
- ;; @r{else-part}
- (setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length
- kill-ring-yank-pointer)))
- length)
- kill-ring)))))
-@end group
-@end smallexample
-
-@menu
-* Understanding rotate-yk-ptr::
-* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
-@end menu
-
-@node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer
-@ifnottex
-@unnumberedsubsec @code{rotate-yank-pointer} in Outline
-@end ifnottex
-
-The @code{rotate-yank-pointer} function looks complex, but as usual,
-it can be understood by taking it apart piece by piece. First look at
-it in skeletal form:
+workings of the @code{current-kill} function. The @code{yank} and
+@code{yank-pop} commands use the @code{current-kill} function.
-@smallexample
-@group
-(defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
- (let @var{varlist}
- @var{body}@dots{})
-@end group
-@end smallexample
-
-This function takes one argument, called @code{arg}. It has a brief
-documentation string; and it is interactive with a small @samp{p}, which
-means that the argument must be a processed prefix passed to the
-function as a number.
-
-The body of the function definition is a @code{let} expression, which
-itself has a body as well as a @var{varlist}.
-
-The @code{let} expression declares a variable that will be only usable
-within the bounds of this function. This variable is called
-@code{length} and is bound to a value that is equal to the number of
-items in the kill ring. This is done by using the function called
-@code{length}. (Note that this function has the same name as the
-variable called @code{length}; but one use of the word is to name the
-function and the other is to name the variable. The two are quite
-distinct. Similarly, an English speaker will distinguish between the
-meanings of the word @samp{ship} when he says: "I must ship this package
-immediately." and "I must get aboard the ship immediately.")
-
-The function @code{length} tells the number of items there are in a list,
-so @code{(length kill-ring)} returns the number of items there are in the
-kill ring.
-
-@node rotate-yk-ptr body, , Understanding rotate-yk-ptr, rotate-yank-pointer
-@comment node-name, next, previous, up
-@appendixsubsec The Body of @code{rotate-yank-pointer}
-
-The body of @code{rotate-yank-pointer} is a @code{let} expression and
-the body of the @code{let} expression is an @code{if} expression.
-
-The purpose of the @code{if} expression is to find out whether there is
-anything in the kill ring. If the kill ring is empty, the @code{error}
-function stops evaluation of the function and prints a message in the
-echo area. On the other hand, if the kill ring has something in it, the
-work of the function is done.
-
-Here is the if-part and then-part of the @code{if} expression:
-
-@findex zerop
-@findex error
-@smallexample
-@group
-(if (zerop length) ; @r{if-part}
- (error "Kill ring is empty") ; @r{then-part}
- @dots{}
-@end group
-@end smallexample
-
-@noindent
-If there is not anything in the kill ring, its length must be zero and
-an error message sent to the user: @samp{Kill ring is empty}. The
-@code{if} expression uses the function @code{zerop} which returns true
-if the value it is testing is zero. When @code{zerop} tests true, the
-then-part of the @code{if} is evaluated. The then-part is a list
-starting with the function @code{error}, which is a function that is
-similar to the @code{message} function (@pxref{message}), in that it
-prints a one-line message in the echo area. However, in addition to
-printing a message, @code{error} also stops evaluation of the function
-within which it is embedded. This means that the rest of the function
-will not be evaluated if the length of the kill ring is zero.
+This appendix describes the @code{current-kill} function as well as
+both the @code{yank} and the @code{yank-pop} commands, but first,
+consider the workings of the kill ring.
@menu
-* Digression concerning error:: How to mislead humans, but not computers.
-* rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
-* Remainder Function:: The remainder, @code{%}, function.
-* rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
-* kill-rng-yk-ptr last elt:: Pointing to the last element.
+* 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 Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body
+@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
@ifnottex
-@unnumberedsubsubsec Digression about the word `error'
+@unnumberedsec What the Kill Ring Does
@end ifnottex
-(In my opinion, it is slightly misleading, at least to humans, to use
-the term `error' as the name of the @code{error} function. A better
-term would be `cancel'. Strictly speaking, of course, you cannot
-point to, much less rotate a pointer to a list that has no length, so
-from the point of view of the computer, the word `error' is correct.
-But a human expects to attempt this sort of thing, if only to find out
-whether the kill ring is full or empty. This is an act of
-exploration.
-
-(From the human point of view, the act of exploration and discovery is
-not necessarily an error, and therefore should not be labelled as one,
-even in the bowels of a computer. As it is, the code in Emacs implies
-that a human who is acting virtuously, by exploring his or her
-environment, is making an error. This is bad. Even though the computer
-takes the same steps as it does when there is an `error', a term such as
-`cancel' would have a clearer connotation.)
-
-@node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body
-@unnumberedsubsubsec The else-part of the @code{if} expression
-
-The else-part of the @code{if} expression is dedicated to setting the
-value of @code{kill-ring-yank-pointer} when the kill ring has something
-in it. The code looks like this:
-
-@smallexample
-@group
-(setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
- kill-ring)))))
-@end group
-@end smallexample
-
-This needs some examination. Clearly, @code{kill-ring-yank-pointer}
-is being set to be equal to some @sc{cdr} of the kill ring, using the
-@code{nthcdr} function that is described in an earlier section.
-(@xref{copy-region-as-kill}.) But exactly how does it do this?
-
-Before looking at the details of the code let's first consider the
-purpose of the @code{rotate-yank-pointer} function.
-
-The @code{rotate-yank-pointer} function changes what
-@code{kill-ring-yank-pointer} points to. If
-@code{kill-ring-yank-pointer} starts by pointing to the first element
-of a list, a call to @code{rotate-yank-pointer} causes it to point to
-the second element; and if @code{kill-ring-yank-pointer} points to the
-second element, a call to @code{rotate-yank-pointer} causes it to
-point to the third element. (And if @code{rotate-yank-pointer} is
-given an argument greater than 1, it jumps the pointer that many
-elements.)
-
-The @code{rotate-yank-pointer} function uses @code{setq} to reset what
-the @code{kill-ring-yank-pointer} points to. If
-@code{kill-ring-yank-pointer} points to the first element of the kill
-ring, then, in the simplest case, the @code{rotate-yank-pointer}
-function must cause it to point to the second element. Put another
-way, @code{kill-ring-yank-pointer} must be reset to have a value equal
-to the @sc{cdr} of the kill ring.
-
@need 1250
-That is, under these circumstances,
+The kill ring has a default maximum length of sixty items; this number
+is too large for an explanation. Instead, set it to four. Please
+evaluate the following:
@smallexample
@group
-(setq kill-ring-yank-pointer
- ("some text" "a different piece of text" "yet more text"))
-
-(setq kill-ring
- ("some text" "a different piece of text" "yet more text"))
+(setq old-kill-ring-max kill-ring-max)
+(setq kill-ring-max 4)
@end group
@end smallexample
-@need 800
-@noindent
-the code should do this:
-
-@smallexample
-(setq kill-ring-yank-pointer (cdr kill-ring))
-@end smallexample
-
-@need 1000
@noindent
-As a result, the @code{kill-ring-yank-pointer} will look like this:
-
-@smallexample
-@group
-kill-ring-yank-pointer
- @result{} ("a different piece of text" "yet more text"))
-@end group
-@end smallexample
-
-The actual @code{setq} expression uses the @code{nthcdr} function to do
-the job.
-
-As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
-works by repeatedly taking the @sc{cdr} of a list---it takes the
-@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
-
-@need 800
-The two following expressions produce the same result:
-
-@smallexample
-@group
-(setq kill-ring-yank-pointer (cdr kill-ring))
-
-(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
-@end group
-@end smallexample
-
-In the @code{rotate-yank-pointer} function, however, the first
-argument to @code{nthcdr} is a rather complex looking expression with
-lots of arithmetic inside of it:
-
-@smallexample
-@group
-(% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
-@end group
-@end smallexample
-
-As usual, we need to look at the most deeply embedded expression first
-and then work our way towards the light.
+Then, please copy each line of the following indented example into the
+kill ring. You may kill each line with @kbd{C-k} or mark it and copy
+it with @kbd{M-w}.
-The most deeply embedded expression is @code{(length
-kill-ring-yank-pointer)}. This finds the length of the current value of
-the @code{kill-ring-yank-pointer}. (Remember that the
-@code{kill-ring-yank-pointer} is the name of a variable whose value is a
-list.)
+@noindent
+(In a read-only buffer, such as the @file{*info*} buffer, the kill
+command, @kbd{C-k} (@code{kill-line}), will not remove the text,
+merely copy it to the kill ring. However, your machine may beep at
+you. Alternatively, for silence, you may copy the region of each line
+with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
+each line for this command to succeed, but it does not matter at which
+end you put point or mark.)
-@need 800
-The measurement of the length is inside the expression:
+@need 1250
+@noindent
+Please invoke the calls in order, so that five elements attempt to
+fill the kill ring:
@smallexample
-(- length (length kill-ring-yank-pointer))
+@group
+first some text
+second piece of text
+third line
+fourth line of text
+fifth bit of text
+@end group
@end smallexample
+@need 1250
@noindent
-In this expression, the first @code{length} is the variable that was
-assigned the length of the kill ring in the @code{let} statement at the
-beginning of the function. (One might think this function would be
-clearer if the variable @code{length} were named
-@code{length-of-kill-ring} instead; but if you look at the text of the
-whole function, you will see that it is so short that naming this
-variable @code{length} is not a bother, unless you are pulling the
-function apart into very tiny pieces as we are doing here.)
-
-So the line @code{(- length (length kill-ring-yank-pointer))} tells the
-difference between the length of the kill ring and the length of the list
-whose name is @code{kill-ring-yank-pointer}.
-
-To see how all this fits into the @code{rotate-yank-pointer}
-function, let's begin by analyzing the case where
-@code{kill-ring-yank-pointer} points to the first element of the kill
-ring, just as @code{kill-ring} does, and see what happens when
-@code{rotate-yank-pointer} is called with an argument of 1.
-
-The variable @code{length} and the value of the expression
-@code{(length kill-ring-yank-pointer)} will be the same since the
-variable @code{length} is the length of the kill ring and the
-@code{kill-ring-yank-pointer} is pointing to the whole kill ring.
-Consequently, the value of
+Then find the value of @code{kill-ring} by evaluating
@smallexample
-(- length (length kill-ring-yank-pointer))
+kill-ring
@end smallexample
+@need 800
@noindent
-will be zero. Since the value of @code{arg} will be 1, this will mean
-that the value of the whole expression
+It is:
@smallexample
-(+ arg (- length (length kill-ring-yank-pointer)))
+@group
+("fifth bit of text" "fourth line of text"
+"third line" "second piece of text")
+@end group
@end smallexample
@noindent
-will be 1.
+The first element, @samp{first some text}, was dropped.
-Consequently, the argument to @code{nthcdr} will be found as the result of
-the expression
+@need 1250
+To return to the old value for the length of the kill ring, evaluate:
@smallexample
-(% 1 length)
+(setq kill-ring-max old-kill-ring-max)
@end smallexample
-@node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body
-@unnumberedsubsubsec The @code{%} remainder function
+@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
-To understand @code{(% 1 length)}, we need to understand @code{%}.
-According to its documentation (which I just found by typing @kbd{C-h
-f @kbd{%} @key{RET}}), the @code{%} function returns the remainder of
-its first argument divided by its second argument. For example, the
-remainder of 5 divided by 2 is 1. (2 goes into 5 twice with a
-remainder of 1.)
+The @code{current-kill} function changes the element in the kill ring
+to which @code{kill-ring-yank-pointer} points. (Also, the
+@code{kill-new} function sets @code{kill-ring-yank-pointer} to point
+to the latest element of the the kill ring. The @code{kill-new}
+function is used directly or indirectly by @code{kill-append},
+@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
+and @code{kill-region}.)
-What surprises people who don't often do arithmetic is that a smaller
-number can be divided by a larger number and have a remainder. In the
-example we just used, 5 was divided by 2. We can reverse that and ask,
-what is the result of dividing 2 by 5? If you can use fractions, the
-answer is obviously 2/5 or .4; but if, as here, you can only use whole
-numbers, the result has to be something different. Clearly, 5 can go into
-2 zero times, but what of the remainder? To see what the answer is,
-consider a case that has to be familiar from childhood:
+@menu
+* Code for current-kill::
+* Understanding current-kill::
+@end menu
-@itemize @bullet
-@item
-5 divided by 5 is 1 with a remainder of 0;
+@node Code for current-kill, Understanding current-kill, current-kill, current-kill
+@ifnottex
+@unnumberedsubsec The code for @code{current-kill}
+@end ifnottex
-@item
-6 divided by 5 is 1 with a remainder of 1;
-@item
-7 divided by 5 is 1 with a remainder of 2.
+@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}:
-@item
-Similarly, 10 divided by 5 is 2 with a remainder of 0;
+@smallexample
+@group
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
+If N is zero, `interprogram-paste-function' is set, and calling it
+returns a string, then that string is added to the front of the
+kill ring and returned as the latest kill.
+@end group
+@group
+If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
+yanking point; just return the Nth kill forward."
+ (let ((interprogram-paste (and (= n 0)
+ interprogram-paste-function
+ (funcall interprogram-paste-function))))
+@end group
+@group
+ (if interprogram-paste
+ (progn
+ ;; Disable the interprogram cut function when we add the new
+ ;; text to the kill ring, so Emacs doesn't try to own the
+ ;; selection, with identical text.
+ (let ((interprogram-cut-function nil))
+ (kill-new interprogram-paste))
+ interprogram-paste)
+@end group
+@group
+ (or kill-ring (error "Kill ring is empty"))
+ (let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element)))))
+@end group
+@end smallexample
-@item
-11 divided by 5 is 2 with a remainder of 1;
+Remember also that the @code{kill-new} function sets
+@code{kill-ring-yank-pointer} to the latest element of the the kill
+ring, which means that all the functions that call it set the value
+indirectly: @code{kill-append}, @code{copy-region-as-kill},
+@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
-@item
-12 divided by 5 is 1 with a remainder of 2.
-@end itemize
+@need 1500
+Here is the line in @code{kill-new}, which is explained in
+@ref{kill-new function, , The @code{kill-new} function}.
-@need 1250
-@noindent
-By considering the cases as parallel, we can see that
+@smallexample
+(setq kill-ring-yank-pointer kill-ring)
+@end smallexample
-@itemize @bullet
-@item
-zero divided by 5 must be zero with a remainder of zero;
+@node Understanding current-kill, , Code for current-kill, current-kill
+@ifnottex
+@unnumberedsubsec @code{current-kill} in Outline
+@end ifnottex
-@item
-1 divided by 5 must be zero with a remainder of 1;
+The @code{current-kill} function looks complex, but as usual, it can
+be understood by taking it apart piece by piece. First look at it in
+skeletal form:
-@item
-2 divided by 5 must be zero with a remainder of 2;
-@end itemize
+@smallexample
+@group
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill."
+ (let @var{varlist}
+ @var{body}@dots{})
+@end group
+@end smallexample
-@noindent
-and so on.
+This function takes two arguments, one of which is optional. It has a
+documentation string. It is @emph{not} interactive.
-@need 1250
-So, in this code, if the value of @code{length} is 5, then the result of
-evaluating
+@menu
+* Body of current-kill::
+* Digression concerning error:: How to mislead humans, but not computers.
+* Determining the Element::
+@end menu
-@smallexample
-(% 1 5)
-@end smallexample
+@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec The Body of @code{current-kill}
+@end ifnottex
-@noindent
-is 1. (I just checked this by placing the cursor after the expression
-and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.)
+The body of the function definition is a @code{let} expression, which
+itself has a body as well as a @var{varlist}.
+
+The @code{let} expression declares a variable that will be only usable
+within the bounds of this function. This variable is called
+@code{interprogram-paste} and is for copying to another program. It
+is not for copying within this instance of GNU Emacs. Most window
+systems provide a facility for interprogram pasting. Sadly, that
+facility usually provides only for the last element. Most windowing
+systems have not adopted a ring of many possibilities, even though
+Emacs has provided it for decades.
-@node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body
-@unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer}
+The @code{if} expression has two parts, one if there exists
+@code{interprogram-paste} and one if not.
-When the @code{kill-ring-yank-pointer} points to the
-beginning of the kill ring, and the argument passed to
-@code{rotate-yank-pointer} is 1, the @code{%} expression returns 1:
+@need 2000
+Let us consider the `if not' or else-part of the @code{current-kill}
+function. (The then-part uses the the @code{kill-new} function, which
+we have already described. @xref{kill-new function, , The
+@code{kill-new} function}.)
@smallexample
@group
-(- length (length kill-ring-yank-pointer))
- @result{} 0
+(or kill-ring (error "Kill ring is empty"))
+(let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element))
@end group
@end smallexample
-@need 1250
@noindent
-therefore,
+The code first checks whether the kill ring has content; otherwise it
+signals an error.
+
+@need 1000
+Note that the @code{or} expression is very similar to testing length
+with an @code{if}:
+@findex zerop
+@findex error
@smallexample
@group
-(+ arg (- length (length kill-ring-yank-pointer)))
- @result{} 1
+(if (zerop (length kill-ring)) ; @r{if-part}
+ (error "Kill ring is empty")) ; @r{then-part}
+ ;; No else-part
@end group
@end smallexample
-@need 1250
@noindent
-and consequently:
+If there is not anything in the kill ring, its length must be zero and
+an error message sent to the user: @samp{Kill ring is empty}. The
+@code{current-kill} function uses an @code{or} expression which is
+simpler. But an @code{if} expression reminds us what goes on.
+
+This @code{if} expression uses the function @code{zerop} which returns
+true if the value it is testing is zero. When @code{zerop} tests
+true, the then-part of the @code{if} is evaluated. The then-part is a
+list starting with the function @code{error}, which is a function that
+is similar to the @code{message} function
+(@pxref{message, , The @code{message} Function}) in that
+it prints a one-line message in the echo area. However, in addition
+to printing a message, @code{error} also stops evaluation of the
+function within which it is embedded. This means that the rest of the
+function will not be evaluated if the length of the kill ring is zero.
+
+Then the @code{current-kill} function selects the element to return.
+The selection depends on the number of places that @code{current-kill}
+rotates and on where @code{kill-ring-yank-pointer} points.
+
+Next, either the optional @code{do-not-move} argument is true or the
+current value of @code{kill-ring-yank-pointer} is set to point to the
+list. Finally, another expression returns the first element of the
+list even if the @code{do-not-move} argument is true.
+
+@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec Digression about the word `error'
+@end ifnottex
+
+In my opinion, it is slightly misleading, at least to humans, to use
+the term `error' as the name of the @code{error} function. A better
+term would be `cancel'. Strictly speaking, of course, you cannot
+point to, much less rotate a pointer to a list that has no length, so
+from the point of view of the computer, the word `error' is correct.
+But a human expects to attempt this sort of thing, if only to find out
+whether the kill ring is full or empty. This is an act of
+exploration.
+
+From the human point of view, the act of exploration and discovery is
+not necessarily an error, and therefore should not be labelled as one,
+even in the bowels of a computer. As it is, the code in Emacs implies
+that a human who is acting virtuously, by exploring his or her
+environment, is making an error. This is bad. Even though the computer
+takes the same steps as it does when there is an `error', a term such as
+`cancel' would have a clearer connotation.
+
+@node Determining the Element, , Digression concerning error, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec Determining the Element
+@end ifnottex
+
+Among other actions, the else-part of the @code{if} expression sets
+the value of @code{kill-ring-yank-pointer} to
+@code{ARGth-kill-element} when the kill ring has something in it and
+the value of @code{do-not-move} is @code{nil}.
+
+@need 800
+The code looks like this:
@smallexample
@group
-(% (+ arg (- length (length kill-ring-yank-pointer)))
- length)
- @result{} 1
+(nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
@end group
@end smallexample
-@noindent
-regardless of the value of @code{length}.
+This needs some examination. Unless it is not supposed to move the
+pointer, the @code{current-kill} function changes where
+@code{kill-ring-yank-pointer} points.
+That is what the
+@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
+expression does. Also, clearly, @code{ARGth-kill-element} is being
+set to be equal to some @sc{cdr} of the kill ring, using the
+@code{nthcdr} function that is described in an earlier section.
+(@xref{copy-region-as-kill}.) How does it do this?
-@need 1250
-@noindent
-As a result of this, the @code{setq kill-ring-yank-pointer} expression
-simplifies to:
+As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
+works by repeatedly taking the @sc{cdr} of a list---it takes the
+@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
+
+@need 800
+The two following expressions produce the same result:
@smallexample
+@group
+(setq kill-ring-yank-pointer (cdr kill-ring))
+
(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
+@end group
@end smallexample
-@noindent
-What it does is now easy to understand. Instead of pointing as it did
-to the first element of the kill ring, the
-@code{kill-ring-yank-pointer} is set to point to the second element.
-
-Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then
-the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)};
-and so on for different values of the argument.
+However, the @code{nthcdr} expression is more complicated. It uses
+the @code{mod} function to determine which @sc{cdr} to select.
-Similarly, if the @code{kill-ring-yank-pointer} starts out pointing to
-the second element of the kill ring, its length is shorter than the
-length of the kill ring by 1, so the computation of the remainder is
-based on the expression @code{(% (+ arg 1) length)}. This means that
-the @code{kill-ring-yank-pointer} is moved from the second element of
-the kill ring to the third element if the argument passed to
-@code{rotate-yank-pointer} is 1.
+(You will remember to look at inner functions first; indeed, we will
+have to go inside the @code{mod}.)
-@node kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder, rotate-yk-ptr body
-@unnumberedsubsubsec Pointing to the last element
+The @code{mod} function returns the value of its first argument modulo
+the second; that is to say, it returns the remainder after dividing
+the first argument by the second. The value returned has the same
+sign as the second argument.
-The final question is, what happens if the @code{kill-ring-yank-pointer}
-is set to the @emph{last} element of the kill ring? Will a call to
-@code{rotate-yank-pointer} mean that nothing more can be taken from the
-kill ring? The answer is no. What happens is different and useful.
-The @code{kill-ring-yank-pointer} is set to point to the beginning of
-the kill ring instead.
-
-Let's see how this works by looking at the code, assuming the length of the
-kill ring is 5 and the argument passed to @code{rotate-yank-pointer} is 1.
-When the @code{kill-ring-yank-pointer} points to the last element of
-the kill ring, its length is 1. The code looks like this:
+@need 800
+Thus,
@smallexample
-(% (+ arg (- length (length kill-ring-yank-pointer))) length)
+@group
+(mod 12 4)
+ @result{} 0 ;; @r{because there is no remainder}
+(mod 13 4)
+ @result{} 1
+@end group
@end smallexample
@need 1250
-When the variables are replaced by their numeric values, the expression
-looks like this:
-
-@smallexample
-(% (+ 1 (- 5 1)) 5)
-@end smallexample
-
-@noindent
-This expression can be evaluated by looking at the most embedded inner
-expression first and working outwards: The value of @code{(- 5 1)} is 4;
-the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is
-zero. So what @code{rotate-yank-pointer} will do is
+In this case, the first argument is often smaller than the second.
+That is fine.
@smallexample
-(setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
+@group
+(mod 0 4)
+ @result{} 0
+(mod 1 4)
+ @result{} 1
+@end group
@end smallexample
-@noindent
-which will set the @code{kill-ring-yank-pointer} to point to the beginning
-of the kill ring.
-
-So what happens with successive calls to @code{rotate-yank-pointer} is that
-it moves the @code{kill-ring-yank-pointer} from element to element in the
-kill ring until it reaches the end; then it jumps back to the beginning.
-And this is why the kill ring is called a ring, since by jumping back to
-the beginning, it is as if the list has no end! (And what is a ring, but
-an entity with no end?)
-
-@node yank, yank-pop, rotate-yank-pointer, Kill Ring
-@comment node-name, next, previous, up
-@appendixsec @code{yank}
-@findex yank
+We can guess what the @code{-} function does. It is like @code{+} but
+subtracts instead of adds; the @code{-} function subtracts its second
+argument from its first. Also, we already know what the @code{length}
+function does (@pxref{length}). It returns the length of a list.
-After learning about @code{rotate-yank-pointer}, the code for the
-@code{yank} function is almost easy. It has only one tricky part, which is
-the computation of the argument to be passed to @code{rotate-yank-pointer}.
+And @code{n} is the name of the required argument to the
+@code{current-kill} function.
@need 1250
-The code looks like this:
+So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
+expression returns the whole list, as you can see by evaluating the
+following:
@smallexample
@group
-(defun yank (&optional arg)
- "Reinsert the last stretch of killed text.
-More precisely, reinsert the stretch of killed text most
-recently killed OR yanked.
-With just C-U as argument, same but put point in front
-(and mark at end). With argument n, reinsert the nth
-most recently killed stretch of killed text.
-See also the command \\[yank-pop]."
-@end group
-@group
-
- (interactive "*P")
- (rotate-yank-pointer (if (listp arg) 0
- (if (eq arg '-) -1
- (1- arg))))
- (push-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if (consp arg)
- (exchange-point-and-mark)))
+;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
+;; @r{and} (mod (- 0 4) 4) @result{} 0
+(nthcdr (mod (- 0 4) 4)
+ '("fourth line of text"
+ "third line"
+ "second piece of text"
+ "first some text"))
@end group
@end smallexample
-Glancing over this code, we can understand the last few lines readily
-enough. The mark is pushed, that is, remembered; then the first element
-(the @sc{car}) of what the @code{kill-ring-yank-pointer} points to is
-inserted; and then, if the argument passed the function is a
-@code{cons}, point and mark are exchanged so the point is put in the
-front of the inserted text rather than at the end. This option is
-explained in the documentation. The function itself is interactive with
-@code{"*P"}. This means it will not work on a read-only buffer, and that
-the unprocessed prefix argument is passed to the function.
-
-@menu
-* rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
-* rotate-yk-ptr negative arg:: Pass a negative argument.
-@end menu
-
-@node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
-@unnumberedsubsubsec Passing the argument
-
-The hard part of @code{yank} is understanding the computation that
-determines the value of the argument passed to
-@code{rotate-yank-pointer}. Fortunately, it is not so difficult as it
-looks at first sight.
-
-What happens is that the result of evaluating one or both of the
-@code{if} expressions will be a number and that number will be the
-argument passed to @code{rotate-yank-pointer}.
-
@need 1250
-Laid out with comments, the code looks like this:
+When the first argument to the @code{current-kill} function is one,
+the @code{nthcdr} expression returns the list without its first
+element.
@smallexample
@group
-(if (listp arg) ; @r{if-part}
- 0 ; @r{then-part}
- (if (eq arg '-) ; @r{else-part, inner if}
- -1 ; @r{inner if's then-part}
- (1- arg)))) ; @r{inner if's else-part}
+(nthcdr (mod (- 1 4) 4)
+ '("fourth line of text"
+ "third line"
+ "second piece of text"
+ "first some text"))
@end group
@end smallexample
-@noindent
-This code consists of two @code{if} expression, one the else-part of
-the other.
-
-The first or outer @code{if} expression tests whether the argument
-passed to @code{yank} is a list. Oddly enough, this will be true if
-@code{yank} is called without an argument---because then it will be
-passed the value of @code{nil} for the optional argument and an
-evaluation of @code{(listp nil)} returns true! So, if no argument is
-passed to @code{yank}, the argument passed to
-@code{rotate-yank-pointer} inside of @code{yank} is zero. This means
-the pointer is not moved and the first element to which
-@code{kill-ring-yank-pointer} points is inserted, as we expect.
-Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be
-read as a list, so again, a zero will be passed to
-@code{rotate-yank-pointer}. (@kbd{C-u} produces an unprocessed prefix
-argument of @code{(4)}, which is a list of one element.) At the same
-time, later in the function, this argument will be read as a
-@code{cons} so point will be put in the front and mark at the end of
-the insertion. (The @code{P} argument to @code{interactive} is
-designed to provide these values for the case when an optional
-argument is not provided or when it is @kbd{C-u}.)
-
-The then-part of the outer @code{if} expression handles the case when
-there is no argument or when it is @kbd{C-u}. The else-part handles the
-other situations. The else-part is itself another @code{if} expression.
-
-The inner @code{if} expression tests whether the argument is a minus
-sign. (This is done by pressing the @key{META} and @kbd{-} keys at the
-same time, or the @key{ESC} key and then the @kbd{-} key). In this
-case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an
-argument. This moves the @code{kill-ring-yank-pointer} backwards, which
-is what is desired.
+@cindex @samp{global variable} defined
+@cindex @samp{variable, global}, defined
+Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
+are @dfn{global variables}. That means that any expression in Emacs
+Lisp can access them. They are not like the local variables set by
+@code{let} or like the symbols in an argument list.
+Local variables can only be accessed
+within the @code{let} that defines them or the function that specifies
+them in an argument list (and within expressions called by them).
-If the true-or-false-test of the inner @code{if} expression is false
-(that is, if the argument is not a minus sign), the else-part of the
-expression is evaluated. This is the expression @code{(1- arg)}.
-Because of the two @code{if} expressions, it will only occur when the
-argument is a positive number or when it is a negative number (not
-just a minus sign on its own). What @code{(1- arg)} does is decrement
-the number and return it. (The @code{1-} function subtracts one from
-its argument.) This means that if the argument to
-@code{rotate-yank-pointer} is 1, it is reduced to zero, which means
-the first element to which @code{kill-ring-yank-pointer} points is
-yanked back, as you would expect.
+@ignore
+@c texi2dvi fails when the name of the section is within ifnottex ...
+(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
+@ref{defun, , The @code{defun} Special Form}.)
+@end ignore
-@node rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank
-@unnumberedsubsubsec Passing a negative argument
+@node yank, yank-pop, current-kill, Kill Ring
+@comment node-name, next, previous, up
+@appendixsec @code{yank}
+@findex yank
-Finally, the question arises, what happens if either the remainder
-function, @code{%}, or the @code{nthcdr} function is passed a negative
-argument, as they quite well may?
+After learning about @code{current-kill}, the code for the
+@code{yank} function is almost easy.
-The answers can be found by a quick test. When @code{(% -1 5)} is
-evaluated, a negative number is returned; and if @code{nthcdr} is
-called with a negative number, it returns the same value as if it were
-called with a first argument of zero. This can be seen by evaluating
-the following code.
+The @code{yank} function does not use the
+@code{kill-ring-yank-pointer} variable directly. It calls
+@code{insert-for-yank} which calls @code{current-kill} which sets the
+@code{kill-ring-yank-pointer} variable.
-Here the @samp{@result{}} points to the result of evaluating the code
-preceding it. This was done by positioning the cursor after the code
-and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion.
-You can do this if you are reading this in Info inside of GNU Emacs.
+@need 1250
+The code looks like this:
+@c in GNU Emacs 22
@smallexample
@group
-(% -1 5)
- @result{} -1
-@end group
+(defun yank (&optional arg)
+ "Reinsert (\"paste\") the last stretch of killed text.
+More precisely, reinsert the stretch of killed text most recently
+killed OR yanked. Put point at end, and set mark at beginning.
+With just \\[universal-argument] as argument, same but put point at
+beginning (and mark at end). With argument N, reinsert the Nth most
+recently killed stretch of killed text.
-@group
-(setq animals '(cats dogs elephants))
- @result{} (cats dogs elephants)
-@end group
+When this command inserts killed text into the buffer, it honors
+`yank-excluded-properties' and `yank-handler' as described in the
+doc string for `insert-for-yank-1', which see.
+See also the command \\[yank-pop]."
+@end group
@group
-(nthcdr 1 animals)
- @result{} (dogs elephants)
+ (interactive "*P")
+ (setq yank-window-start (window-start))
+ ;; If we don't get all the way thru, make last-command indicate that
+ ;; for the following command.
+ (setq this-command t)
+ (push-mark (point))
@end group
-
@group
-(nthcdr 0 animals)
- @result{} (cats dogs elephants)
+ (insert-for-yank (current-kill (cond
+ ((listp arg) 0)
+ ((eq arg '-) -2)
+ (t (1- arg)))))
+ (if (consp arg)
+ ;; This is like exchange-point-and-mark,
+ ;; but doesn't activate the mark.
+ ;; It is cleaner to avoid activation, even though the command
+ ;; loop would deactivate the mark because we inserted text.
+ (goto-char (prog1 (mark t)
+ (set-marker (mark-marker) (point) (current-buffer)))))
@end group
-
@group
-(nthcdr -1 animals)
- @result{} (cats dogs elephants)
+ ;; If we do get all the way thru, make this-command indicate that.
+ (if (eq this-command t)
+ (setq this-command 'yank))
+ nil)
@end group
@end smallexample
-So, if a minus sign or a negative number is passed to @code{yank}, the
-@code{kill-ring-yank-point} is rotated backwards until it reaches the
-beginning of the list. Then it stays there. Unlike the other case,
-when it jumps from the end of the list to the beginning of the list,
-making a ring, it stops. This makes sense. You often want to get back
-to the most recently clipped out piece of text, but you don't usually
-want to insert text from as many as thirty kill commands ago. So you
-need to work through the ring to get to the end, but won't cycle around
-it inadvertently if you are trying to come back to the beginning.
+The key expression is @code{insert-for-yank}, which inserts the string
+returned by @code{current-kill}, but removes some text properties from
+it.
+
+However, before getting to that expression, the function sets the value
+of @code{yank-window-start} to the position returned by the
+@code{(window-start)} expression, the position at which the display
+currently starts. The @code{yank} function also sets
+@code{this-command} and pushes the mark.
+
+After it yanks the appropriate element, if the optional argument is a
+@sc{cons} rather than a number or nothing, it puts point at beginning
+of the yanked text and mark at its end.
-Incidentally, any number passed to @code{yank} with a minus sign
-preceding it will be treated as @minus{}1. This is evidently a
-simplification for writing the program. You don't need to jump back
-towards the beginning of the kill ring more than one place at a time
-and doing this is easier than writing a function to determine the
-magnitude of the number that follows the minus sign.
+(The @code{prog1} function is like @code{progn} but returns the value
+of its first argument rather than the value of its last argument. Its
+first argument is forced to return the buffer's mark as an integer.
+You can see the documentation for these functions by placing point
+over them in this buffer and then typing @kbd{C-h f}
+(@code{describe-function}) followed by a @kbd{RET}; the default is the
+function.)
-@node yank-pop, , yank, Kill Ring
+The last part of the function tells what to do when it succeeds.
+
+@node yank-pop, ring file, yank, Kill Ring
@comment node-name, next, previous, up
@appendixsec @code{yank-pop}
@findex yank-pop
-After understanding @code{yank}, the @code{yank-pop} function is easy.
-Leaving out the documentation to save space, it looks like this:
+After understanding @code{yank} and @code{current-kill}, you know how
+to approach the @code{yank-pop} function. Leaving out the
+documentation to save space, it looks like this:
+@c GNU Emacs 22
@smallexample
@group
-(defun yank-pop (arg)
+(defun yank-pop (&optional arg)
+ "@dots{}"
(interactive "*p")
(if (not (eq last-command 'yank))
(error "Previous command was not a yank"))
@end group
@group
(setq this-command 'yank)
- (let ((before (< (point) (mark))))
- (delete-region (point) (mark))
- (rotate-yank-pointer arg)
+ (unless arg (setq arg 1))
+ (let ((inhibit-read-only t)
+ (before (< (point) (mark t))))
+@end group
+@group
+ (if before
+ (funcall (or yank-undo-function 'delete-region) (point) (mark t))
+ (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
+ (setq yank-undo-function nil)
+@end group
+@group
+ (set-marker (mark-marker) (point) (current-buffer))
+ (insert-for-yank (current-kill arg))
+ ;; Set the window start back where it was in the yank command,
+ ;; if possible.
+ (set-window-start (selected-window) yank-window-start t)
@end group
@group
- (set-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if before (exchange-point-and-mark))))
+ (if before
+ ;; This is like exchange-point-and-mark,
+ ;; but doesn't activate the mark.
+ ;; It is cleaner to avoid activation, even though the command
+ ;; loop would deactivate the mark because we inserted text.
+ (goto-char (prog1 (mark t)
+ (set-marker (mark-marker)
+ (point)
+ (current-buffer))))))
+ nil)
@end group
@end smallexample
The function is interactive with a small @samp{p} so the prefix
argument is processed and passed to the function. The command can
only be used after a previous yank; otherwise an error message is
-sent. This check uses the variable @code{last-command} which is
-discussed elsewhere. (@xref{copy-region-as-kill}.)
+sent. This check uses the variable @code{last-command} which is set
+by @code{yank} and is discussed elsewhere.
+(@xref{copy-region-as-kill}.)
The @code{let} clause sets the variable @code{before} to true or false
depending whether point is before or after mark and then the region
between point and mark is deleted. This is the region that was just
inserted by the previous yank and it is this text that will be
-replaced. Next the @code{kill-ring-yank-pointer} is rotated so that
-the previously inserted text is not reinserted yet again. Mark is set
-at the beginning of the place the new text will be inserted and then
-the first element to which @code{kill-ring-yank-pointer} points is
-inserted. This leaves point after the new text. If in the previous
-yank, point was left before the inserted text, point and mark are now
-exchanged so point is again left in front of the newly inserted text.
-That is all there is to it!
-
-@node Full Graph, GNU Free Documentation License, Kill Ring, Top
+replaced.
+
+@code{funcall} calls its first argument as a function, passing
+remaining arguments to it. The first argument is whatever the
+@code{or} expression returns. The two remaining arguments are the
+positions of point and mark set by the preceding @code{yank} command.
+
+There is more, but that is the hardest part.
+
+@node ring file, , yank-pop, Kill Ring
+@comment node-name, next, previous, up
+@appendixsec The @file{ring.el} File
+@cindex @file{ring.el} file
+
+Interestingly, GNU Emacs posses a file called @file{ring.el} that
+provides many of the features we just discussed. But functions such
+as @code{kill-ring-yank-pointer} do not use this library, possibly
+because they were written earlier.
+
+@node Full Graph, Free Software and Free Manuals, Kill Ring, Top
@appendix A Graph with Labelled Axes
Printed axes help you understand a graph. They convey scale. In an
@noindent
As we shall see, this expression is not quite right.
+@need 2000
@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
@comment node-name, next, previous, up
@appendixsec The @code{print-Y-axis} Function
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:: 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 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
divided into several smaller problems.
First, consider the case when the highest value of the graph is an
-integral multiple of five---when it is 5, 10, 15 ,or some higher
+integral multiple of five---when it is 5, 10, 15, or some higher
multiple of five. We can use this value as the Y axis height.
A fairly simply way to determine whether a number is a multiple of
that you cannot discover using @code{apropos}: you find nothing if you
type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
learn of the existence of @code{%} is to read about it in a book such
-as this or in the Emacs Lisp sources. The @code{%} function is used
-in the code for @code{rotate-yank-pointer}, which is described in an
-appendix. (@xref{rotate-yk-ptr body, , The Body of
-@code{rotate-yank-pointer}}.)
+as this or in the Emacs Lisp sources.
You can try the @code{%} function by evaluating the following two
expressions:
special format. The format is a question mark followed by a blank
space, like this, @samp{? }. @xref{Character Type, , Character Type,
elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
-syntax for characters.
+syntax for characters. (Of course, you might want to replace the
+blank space by some other character @dots{} You know what to do.)
The @code{number-to-string} function is used in the concatenation
expression, to convert the number to a string that is concatenated
blank label using the @code{make-string} function. The base line
consists of the number one followed by a tic mark.
+@need 2000
@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
@appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
Press @key{RET} to evaluate the expression.
@end enumerate
-Emacs will print labels vertically, the top one being
-@w{@samp{10 -@w{ }}}. (The @code{print-graph} function
-will pass the value of @code{height-of-top-line}, which
-in this case would end up as 15.)
+Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
+}}}. (The @code{print-graph} function will pass the value of
+@code{height-of-top-line}, which in this case will end up as 15,
+thereby getting rid of what might appear as a bug.)
+@need 2000
@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
@appendixsec The @code{print-X-axis} Function
@cindex Axis, print horizontal
@cindex Print horizontal axis
@cindex Horizontal axis printing
-X axis labels are much like Y axis labels, except that the tics are on a
+X axis labels are much like Y axis labels, except that the ticks are on a
line above the numbers. Labels should look like this:
@smallexample
The first tic is under the first column of the graph and is preceded by
several blank spaces. These spaces provide room in rows above for the Y
-axis labels. The second, third, fourth, and subsequent tics are all
+axis labels. The second, third, fourth, and subsequent ticks are all
spaced equally, according to the value of @code{X-axis-label-spacing}.
The second row of the X axis consists of numbers, preceded by several
@noindent
(Note that the value of @code{graph-blank} is set by another
@code{defvar}. The @code{boundp} predicate checks whether it has
-already been set; @code{boundp} returns @code{nil} if it has not.
-If @code{graph-blank} were unbound and we did not use this conditional
-construction, in GNU Emacs 21, we would enter the debugger and see an
-error message saying
-@samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.)
+already been set; @code{boundp} returns @code{nil} if it has not. If
+@code{graph-blank} were unbound and we did not use this conditional
+construction, in a recent GNU Emacs, we would enter the debugger and
+see an error message saying @samp{@w{Debugger entered--Lisp error:}
+@w{(void-variable graph-blank)}}.)
@need 1200
Here is the @code{defvar} for @code{X-axis-tic-symbol}:
@end smallexample
We also need to determine the length of the horizontal axis, which is
-the length of the numbers list, and the number of tics in the horizontal
+the length of the numbers list, and the number of ticks in the horizontal
axis:
@smallexample
@end group
@group
-;; number-of-X-tics
+;; number-of-X-ticks
(if (zerop (% (X-length tic-width)))
(/ (X-length tic-width))
(1+ (/ (X-length tic-width))))
@group
(defun print-X-axis-tic-line
(number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
- "Print tics for X axis."
+ "Print ticks for X axis."
(insert X-axis-leading-spaces)
(insert X-axis-tic-symbol) ; @r{Under first column.}
@end group
X-axis-tic-symbol))
@end group
@group
- ;; @r{Insert remaining tics.}
+ ;; @r{Insert remaining ticks.}
(while (> number-of-X-tics 1)
(insert X-axis-tic-element)
(setq number-of-X-tics (1- number-of-X-tics))))
@need 1250
Emacs will print the horizontal axis like this:
+@sp 1
@smallexample
@group
@end group
@end smallexample
+@need 1200
On the other hand, if you pass @code{print-graph} a
@code{vertical-step} value of 2, by evaluating this expression:
@end smallexample
@noindent
-On my machine, this takes about an hour. It looks though 303 Lisp
+On my old machine, this took about an hour. It looked though 303 Lisp
files in my copy of Emacs version 19.23. After all that computing,
-the @code{list-for-graph} has this value:
+the @code{list-for-graph} had this value:
@smallexample
@group
@end smallexample
@noindent
-This means that my copy of Emacs has 537 function definitions with
+This means that my copy of Emacs had 537 function definitions with
fewer than 10 words or symbols in them, 1,027 function definitions
with 10 to 19 words or symbols in them, 955 function definitions with
20 to 29 words or symbols in them, and so on.
is a function definition that says `return the value resulting from
dividing whatever is passed to me as @code{arg} by 50'.
+@need 1200
Earlier, for example, we had a function @code{multiply-by-seven}; it
multiplied its argument by 7. This function is similar, except it
divides its argument by 50; and, it has no name. The anonymous
@ifset print-postscript-figures
@sp 1
@tex
-@image{lambda-1}
+@center @image{lambda-1}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
@ifset print-postscript-figures
@sp 1
@tex
-@image{lambda-2}
+@center @image{lambda-2}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
@ifset print-postscript-figures
@sp 1
@tex
-@image{lambda-3}
+@center @image{lambda-3}
%%%% old method of including an image
% \input /usr/local/lib/tex/inputs/psfig.tex
% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
@end smallexample
@end ifnottex
+@c qqq
@ignore
Graphing Definitions Re-listed
@group
(defun print-X-axis-tic-line
(number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
- "Print tics for X axis."
+ "Print ticks for X axis."
(insert X-axis-leading-spaces)
(insert X-axis-tic-symbol) ; @r{Under first column.}
@end group
X-axis-tic-symbol))
@end group
@group
- ;; @r{Insert remaining tics.}
+ ;; @r{Insert remaining ticks.}
(while (> number-of-X-tics 1)
(insert X-axis-tic-element)
(setq number-of-X-tics (1- number-of-X-tics))))
(print-X-axis numbers-list horizontal-step)))
@end group
@end smallexample
+@c qqq
@end ignore
@page
When made and installed, you can call the @code{print-graph} command
like this:
+@sp 1
@smallexample
@group
(print-graph fiftieth-list-for-graph 50 10)
@end group
@end smallexample
+@sp 1
+@noindent
Here is the graph:
-
@sp 2
@smallexample
@sp 2
+@noindent
The largest group of functions contain 10 -- 19 words and symbols each.
-@node GNU Free Documentation License, Index, Full Graph, Top
+@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
+@appendix Free Software and Free Manuals
+
+@strong{by Richard M. Stallman}
+@sp 1
+
+The biggest deficiency in free operating systems is not in the
+software---it is the lack of good free manuals that we can include in
+these systems. Many of our most important programs do not come with
+full manuals. Documentation is an essential part of any software
+package; when an important free software package does not come with a
+free manual, that is a major gap. We have many such gaps today.
+
+Once upon a time, many years ago, I thought I would learn Perl. I got
+a copy of a free manual, but I found it hard to read. When I asked
+Perl users about alternatives, they told me that there were better
+introductory manuals---but those were not free.
+
+Why was this? The authors of the good manuals had written them for
+O'Reilly Associates, which published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software community.
+
+That wasn't the first time this sort of thing has happened, and (to
+our community's great loss) it was far from the last. Proprietary
+manual publishers have enticed a great many authors to restrict their
+manuals since then. Many times I have heard a GNU user eagerly tell me
+about a manual that he is writing, with which he expects to help the
+GNU project---and then had my hopes dashed, as he proceeded to explain
+that he had signed a contract with a publisher that would restrict it
+so that we cannot use it.
+
+Given that writing good English is a rare skill among programmers, we
+can ill afford to lose manuals this way.
+
+@c (texinfo)uref
+(The Free Software Foundation
+@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
+sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
+GNU manuals}, too.)
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with these manuals was not that O'Reilly Associates
+charged a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of free GNU manuals, too.)
+But GNU manuals are available in source code form, while these manuals
+are available only on paper. GNU manuals come with permission to copy
+and modify; the Perl manuals do not. These restrictions are the
+problems.
+
+The criterion for a free manual is pretty much the same as for free
+software: it is a matter of giving all users certain
+freedoms. Redistribution (including commercial redistribution) must be
+permitted, so that the manual can accompany every copy of the program,
+on-line or on paper. Permission for modification is crucial too.
+
+As a general rule, I don't believe that it is essential for people to
+have permission to modify all sorts of articles and books. The issues
+for writings are not necessarily the same as those for software. For
+example, I don't think you or I are obliged to give permission to
+modify articles like this one, which describe our actions and our
+views.
+
+But there is a particular reason why the freedom to modify is crucial
+for documentation for free software. When people exercise their right
+to modify the software, and add or change its features, if they are
+conscientious they will change the manual too---so they can provide
+accurate and usable documentation with the modified program. A manual
+which forbids programmers to be conscientious and finish the job, or
+more precisely requires them to write a new manual from scratch if
+they change the program, does not fill our community's needs.
+
+While a blanket prohibition on modification is unacceptable, some
+kinds of limits on the method of modification pose no problem. For
+example, requirements to preserve the original author's copyright
+notice, the distribution terms, or the list of authors, are ok. It is
+also no problem to require modified versions to include notice that
+they were modified, even to have entire sections that may not be
+deleted or changed, as long as these sections deal with nontechnical
+topics. (Some GNU manuals have them.)
+
+These kinds of restrictions are not a problem because, as a practical
+matter, they don't stop the conscientious programmer from adapting the
+manual to fit the modified program. In other words, they don't block
+the free software community from making full use of the manual.
+
+However, it must be possible to modify all the technical content of
+the manual, and then distribute the result in all the usual media,
+through all the usual channels; otherwise, the restrictions do block
+the community, the manual is not free, and so we need another manual.
+
+Unfortunately, it is often hard to find someone to write another
+manual when a proprietary manual exists. The obstacle is that many
+users think that a proprietary manual is good enough---so they don't
+see the need to write a free manual. They do not see that the free
+operating system has a gap that needs filling.
+
+Why do users think that proprietary manuals are good enough? Some have
+not considered the issue. I hope this article will do something to
+change that.
+
+Other users consider proprietary manuals acceptable for the same
+reason so many people consider proprietary software acceptable: they
+judge in purely practical terms, not using freedom as a
+criterion. These people are entitled to their opinions, but since
+those opinions spring from values which do not include freedom, they
+are no guide for those of us who do value freedom.
+
+Please spread the word about this issue. We continue to lose manuals
+to proprietary publishing. If we spread the word that proprietary
+manuals are not sufficient, perhaps the next person who wants to help
+GNU by writing documentation will realize, before it is too late, that
+he must above all make it free.
+
+We can also encourage commercial publishers to sell free, copylefted
+manuals instead of proprietary ones. One way you can help this is to
+check the distribution terms of a manual before you buy it, and prefer
+copylefted manuals to non-copylefted ones.
+
+@sp 2
+@noindent
+Note: The Free Software Foundation maintains a page on its Web site
+that lists free books available from other publishers:@*
+@uref{http://www.gnu.org/doc/other-free-books.html}
+
+@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
-@center Version 1.1, March 2000
+@center Version 1.2, November 2002
@display
-Copyright @copyright{} 2000 Free Software Foundation, Inc.
-59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
-written document @dfn{free} in the sense of freedom: to assure everyone
-the effective freedom to copy and redistribute it, with or without
-modifying it, either commercially or noncommercially. Secondarily,
-this License preserves for the author and publisher a way to get
-credit for their work, while not being considered responsible for
-modifications made by others.
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
@item
APPLICABILITY AND DEFINITIONS
-This License applies to any manual or other work that contains a
-notice placed by the copyright holder saying it can be distributed
-under the terms of this License. The ``Document'', below, refers to any
-such manual or work. Any member of the public is a licensee, and is
-addressed as ``you''.
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
-A ``Secondary Section'' is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (For example, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
-general public, whose contents can be viewed and edited directly and
+general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
-format whose markup has been designed to thwart or discourage
-subsequent modification by readers is not Transparent. A copy that is
-not ``Transparent'' is called ``Opaque''.
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
-@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
-@acronym{SGML} or @acronym{XML} using a publicly available
-@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
-for human modification. Opaque formats include PostScript,
-@acronym{PDF}, proprietary formats that can be read and edited only by
-proprietary word processors, @acronym{SGML} or @acronym{XML} for which
-the @acronym{DTD} and/or processing tools are not generally available,
-and the machine-generated @acronym{HTML} produced by some word
-processors for output purposes only.
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+@acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
@item
VERBATIM COPYING
@item
COPYING IN QUANTITY
-If you publish printed copies of the Document numbering more than 100,
-and the Document's license notice requires Cover Texts, you must enclose
-the copies in covers that carry, clearly and legibly, all these Cover
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
-a publicly-accessible computer-network location containing a complete
-Transparent copy of the Document, free of added material, which the
-general network-using public has access to download anonymously at no
-charge using public-standard network protocols. If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location
-until at least one year after the last time you distribute an Opaque
-copy (directly or through your agents or retailers) of that edition to
-the public.
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has less than five).
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
Include an unaltered copy of this License.
@item
-Preserve the section entitled ``History'', and its title, and add to
-it an item stating at least the title, year, new authors, and
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
-there is no section entitled ``History'' in the Document, create one
+there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
publisher of the version it refers to gives permission.
@item
-In any section entitled ``Acknowledgments'' or ``Dedications'',
-preserve the section's title, and preserve in the section all the
-substance and tone of each of the contributor acknowledgments
-and/or dedications given therein.
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
or the equivalent are not considered part of the section titles.
@item
-Delete any section entitled ``Endorsements''. Such a section
+Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
-Do not retitle any existing section as ``Endorsements''
-or to conflict in title with any Invariant Section.
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
-You may add a section entitled ``Endorsements'', provided it contains
+You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
-license notice.
+license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
-In the combination, you must combine any sections entitled ``History''
-in the various original documents, forming one section entitled
-``History''; likewise combine any sections entitled ``Acknowledgments'',
-and any sections entitled ``Dedications''. You must delete all sections
-entitled ``Endorsements.''
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
-distribution medium, does not as a whole count as a Modified Version
-of the Document, provided no compilation copyright is claimed for the
-compilation. Such a compilation is called an ``aggregate'', and this
-License does not apply to the other self-contained works thus compiled
-with the Document, on account of their being thus compiled, if they
-are not themselves derivative works of the Document.
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one quarter
-of the entire aggregate, the Document's Cover Texts may be placed on
-covers that surround only the Document within the aggregate.
-Otherwise they must appear on covers around the whole aggregate.
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
@item
TRANSLATION
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
-translation of this License provided that you also include the
-original English version of this License. In case of a disagreement
-between the translation and the original English version of this
-License, the original English version will prevail.
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
@item
TERMINATION
as a draft) by the Free Software Foundation.
@end enumerate
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+Copyright (C) @var{year} @var{your name}.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
+@smallexample
+@group
+with the Invariant Sections being @var{list their titles}, with
+the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
@node Index, About the Author, GNU Free Documentation License, Top
@comment node-name, next, previous, up
@unnumbered Index
@end iftex
@bye
+
+@ignore
+ arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
+@end ignore