@comment %**end of header
-@set edition-number 3.01
-@set update-date 2006 Oct 31
+@set edition-number 3.07
+@set update-date 9 November 2006
@ignore
## Summary of shell commands to create various output formats:
## pushd /u/intro/
## Info output
- # makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
- ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/u/intro/emacs-lisp-intro.info"))
+ ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
## DVI output
texi2dvi emacs-lisp-intro.texi
- ## View DVI output; see below also
- # xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
+ ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
## HTML output
makeinfo --html --no-split --verbose emacs-lisp-intro.texi
+ ## galeon emacs-lisp-intro.html
+
## Plain text output
makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
--verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
- ## DocBook output
- makeinfo --docbook --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+ popd
- ## XML output
- makeinfo --xml --no-split --paragraph-indent=0 \
- --verbose emacs-lisp-intro.texi
+# as user `root'
+# insert thumbdrive
+ mtusb # mount -v -t ext3 /dev/sda /mnt
+ cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
+ umtusb # umount -v /mnt
+# remove thumbdrive
- popd
+ ## Other shell commands
+
+ pushd /usr/local/src/emacs/lispintro/
+ ## pushd /u/intro/
- #### (You must be in the same directory as the viewed file.)
+ ## PDF
+ texi2dvi --pdf emacs-lisp-intro.texi
+ # xpdf emacs-lisp-intro.pdf &
- ## View DVI output
- xdvi emacs-lisp-intro.dvi &
+ ## DocBook -- note file extension
+ makeinfo --docbook --no-split --paragraph-indent=0 \
+ --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
- ## View HTML output
- galeon emacs-lisp-intro.html
+ ## XML with a Texinfo DTD -- note file extension
+ makeinfo --xml --no-split --paragraph-indent=0 \
+ --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
- ## View Info output with standalone reader
- info emacs-lisp-intro.info
+ ## 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
- ## popd
+ ## 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
-# as user `root'
-# insert thumbdrive
- mtusb # mount -v -t ext3 /dev/sda /mnt
- cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
- umtusb # umount -v /mnt
-# remove thumbdrive
+ popd
@end ignore
@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
@tex
-\global\def\xrefprintnodename#1{\unskip, ``#1''}
+\if \xrefprintnodename
+ \global\def\xrefprintnodename#1{\unskip, ``#1''}
+ \else
+ \global\def\xrefprintnodename#1{ ``#1''}
+\fi
% \global\def\xrefprintnodename#1{, ``#1''}
@end tex
@dircategory Emacs
@direntry
* Emacs Lisp Intro: (eintr).
- A simple introduction to Emacs Lisp programming.
+ A simple introduction to Emacs Lisp programming.
@end direntry
@copying
Evaluation
+* How the Interpreter Acts:: Returns and Side Effects...
* Evaluating Inner Lists:: Lists within lists...
Variables
* Loop Example:: A @code{while} loop that uses a list.
* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
* Incrementing Loop:: A loop with an incrementing counter.
+* Incrementing Loop Details::
* Decrementing Loop:: A loop with a decrementing counter.
-A Loop with an Incrementing Counter
+Details of an Incrementing Loop
* Incrementing Example:: Counting pebbles in a triangle.
* Inc Example parts:: The parts of the function definition.
Prepare the Data for Display in a Graph
+* Data for Display in Detail::
* Sorting:: Sorting lists.
* Files List:: Making a list of files.
* Counting function definitions::
Handling the Kill Ring
+* What the Kill Ring Does::
* current-kill::
* yank:: Paste a copy of a clipped element.
* yank-pop:: Insert element pointed to.
@code{current-kill} in Outline
+* Body of current-kill::
* Digression concerning error:: How to mislead humans, but not computers.
* Determining the Element::
The @code{print-Y-axis} Function
+* print-Y-axis in Detail::
* Height of label:: What height for the Y axis?
* Compute a Remainder:: How to compute the remainder of a division.
* Y Axis Element:: Construct a line for the Y axis.
value or amount of; to appraise', according to @cite{Webster's New
Collegiate Dictionary}.
+@menu
+* How the Interpreter Acts::
+* Evaluating Inner Lists::
+@end menu
+
+@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
+@ifnottex
+@unnumberedsubsec How the Lisp Interpreter Acts
+@end ifnottex
+
+@cindex @samp{returned value} explained
After evaluating an expression, the Lisp interpreter will most likely
@dfn{return} the value that the computer produces by carrying out the
instructions it found in the function definition, or perhaps it will
Lisp interpreter to return a value and perhaps carry out a side effect;
or else produce an error.
-@menu
-* Evaluating Inner Lists::
-@end menu
-
-@node Evaluating Inner Lists, , Evaluation, Evaluation
+@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation
@comment node-name, next, previous, up
@subsection Evaluating Inner Lists
@cindex Inner list evaluation
@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
@smallexample
@group
-(if (string-equal
- (number-to-string 22)
- (substring (emacs-version) 10 12))
+(if (= 22 emacs-major-version)
(message "This is version 22 Emacs")
(message "This is not version 22 Emacs"))
@end group
@end smallexample
-@item equal
-@itemx eq
-Test whether two objects are the same. @code{equal} uses one meaning
-of the word `same' and @code{eq} uses another: @code{equal} returns
-true if the two objects have a similar structure and contents, such as
-two copies of the same book. On the other hand, @code{eq}, returns
-true if both arguments are actually the same object.
-@findex equal
-@findex eq
-
@need 1250
@item <
@itemx >
the 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
+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=
then @key{RET}).
@cindex Find source of function
-@c In version 22
-When a function is written in Emacs Lisp, @code{describe-function}
-will also tell you the location of the function definition.
+@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
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.
@key{RET}}. (On some keyboards, the @key{META} key is labelled
@key{ALT}.)
-@c !!! 22.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/22.0.100/lisp/TAGS}. If the tags table
+@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}.
(interactive
(list (read-buffer "Append to buffer: " (other-buffer
(current-buffer) t))
- (region-beginning) (region-end)))
+ (region-beginning) (region-end)))
@end group
@group
(let ((oldbuf (current-buffer)))
(save-excursion
(let* ((append-to (get-buffer-create buffer))
- (windows (get-buffer-window-list append-to t t))
- point)
- (set-buffer append-to)
- (setq point (point))
- (barf-if-buffer-read-only)
- (insert-buffer-substring oldbuf start end)
- (dolist (window windows)
- (when (= (window-point window) point)
- (set-window-point window (point))))))))
+ (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
Function Interactive}.) The expression reads as follows:
@smallexample
+@group
(interactive
- (list (read-buffer
- "Append to buffer: "
- (other-buffer (current-buffer) t))
- (region-beginning)
- (region-end)))
+ (list (read-buffer
+ "Append to buffer: "
+ (other-buffer (current-buffer) t))
+ (region-beginning)
+ (region-end)))
+@end group
@end smallexample
@noindent
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)))
+ (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))))))))
+ (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}.
(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))))))))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
@end ignore
The @code{append-to-buffer} function definition inserts text from the
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
+(@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
* if & or::
* Insert or::
* Insert let::
-* New insert-buffer ::
+* New insert-buffer::
@end menu
@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
(or (holding-on-to-guest) (find-and-take-arm-of-guest))
@end smallexample
-@node Insert let, New insert-buffer , Insert or, insert-buffer
+@node Insert let, New insert-buffer, Insert or, insert-buffer
@comment node-name, next, previous, up
@subsection The @code{let} Expression in @code{insert-buffer}
use @code{or}. All these functions are building blocks that we will
find and use again and again.
-@node New insert-buffer , , Insert let, insert-buffer
+@node New insert-buffer, , Insert let, insert-buffer
@comment node-name, next, previous, up
@subsection New Body for @code{insert-buffer}
@findex insert-buffer, new version body
As previously described, when invoked without an argument,
@code{beginning-of-buffer} moves the cursor to the beginning of the
-buffer (in truth, the accessible portion of the buffer), leaving the
-mark at the previous position. However, when the command is invoked
-with a number between one and ten, the function considers that number
-to be a fraction of the length of the buffer, measured in tenths, and
-Emacs moves the cursor that fraction of the way from the beginning of
-the buffer. Thus, you can either call this function with the key
-command @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 (in truth, the beginning of the accessible portion of the
+buffer), leaving the mark at the previous position. However, when the
+command is invoked with a number between one and ten, the function
+considers that number to be a fraction of the length of the buffer,
+measured in tenths, and Emacs moves the cursor that fraction of the
+way from the beginning of the buffer. Thus, you can either call this
+function with the key command @kbd{M-<}, which will move the cursor to
+the beginning of the buffer, or with a key command such as @kbd{C-u 7
+M-<} which will move the cursor to a point 70% of the way through the
+buffer. If a number bigger than ten is used for the argument, it
+moves to the end of the buffer.
The @code{beginning-of-buffer} function can be called with or without an
argument. The use of the argument is optional.
@group
(if (> (buffer-size) 10000)
;; @r{Avoid overflow for large buffer sizes!}
- (* (prefix-numeric-value arg)
- (/ size 10))
+ (* (prefix-numeric-value arg)
+ (/ size 10))
(/
(+ 10
(*
@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.
@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))))
+ (+ (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
"Print the current buffer line number and narrowed line number of point."
(interactive)
(let ((start (point-min))
- (n (line-number-at-pos)))
+ (n (line-number-at-pos)))
(if (= start 1)
- (message "Line %d" n)
+ (message "Line %d" n)
(save-excursion
- (save-restriction
- (widen)
- (message "line %d (narrowed line %d)"
- (+ n (line-number-at-pos start) -1) n))))))
+ (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.
(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)))))))
+ (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
(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)))))))
+ (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
@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}.
+Manual}.)
Additionally, do you really need @code{goto-char} or @code{point-min}?
-Or can you write the function without them?)
+Or can you write the function without them?
@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
@comment node-name, next, previous, up
@section @code{zap-to-char}
@findex zap-to-char
-The @code{zap-to-char} function changed a little between GNU Emacs
+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.
@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
(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))))
+ (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
message saying that the buffer is read-only. Also, the terminal may
beep or blink at you.
-Let us continue with the interactive specification.
-
@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}
kills (that is, removes) the text in the region from the current
position of the cursor up to and including the specified character.
-The documentation is thorough. You do need to know the jargon meaning
-of the word `kill'.
-
The first part of the code looks like this:
@smallexample
(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)
+ (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.
(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)
+ (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.
;; @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
@end group
@group
(let ((string (filter-buffer-substring beg end t)))
- (when string ;STRING is nil if BEG = END
+ (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
;; `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)
+ (kill-new string nil yank-handler)))
+ (when (or string (eq last-command 'kill-region))
+ (setq this-command 'kill-region))
+ nil)
@end group
@group
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.
+`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
@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
function.
@need 1250
-The @code{if} expression reads as follows; it uses @code{eq}, which is
-a function we have not yet seen:
+The @code{if} expression reads as follows; it uses @code{eq}:
@smallexample
@group
@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)))
+ (or (= (length cur) 0)
+ (equal yank-handler
+ (get-text-property 0 'yank-handler cur)))
+ yank-handler)))
@end group
@end smallexample
@group
(if (> (length string) 0)
(if yank-handler
- (put-text-property 0 (length string)
- 'yank-handler yank-handler string))
+ (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"))))
+ (signal 'args-out-of-range
+ (list string "yank-handler specified for empty string"))))
@end group
@group
(if (fboundp 'menu-bar-update-yank-menu)
(setcar kill-ring string)
(push string kill-ring)
(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
@end group
@group
(setq kill-ring-yank-pointer kill-ring)
(funcall interprogram-cut-function string (not replace))))
@end ignore
-@noindent
(Notice that the function is not interactive.)
As usual, we can look at this function in parts.
@noindent
Let's skip over the rest of the documentation for the moment.
+@noindent
Also, let's skip over the initial @code{if} expression and those lines
of code involving @code{menu-bar-update-yank-menu}. We will explain
them below.
@noindent
@need 1250
-@code{push} puts its first argument onto the second. It is the same
-as the older
+@code{push} puts its first argument onto the second. It is similar to
+the older
@smallexample
(setq kill-ring (cons string kill-ring))
@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 sent the last
+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}}.)
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 an early expression in the body of the function:
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'.
+clear such mysteries as the use of the term `pointer'. But before
+that, we will digress into C.
@ignore
@c is this true in Emacs 22? Does not seems to be
@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.
@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}}
@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}}
@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
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
@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}}
@code{(setq kill-ring-yank-pointer kill-ring)}
(defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
+ "Rotate the yanking point in the kill ring.
With argument, rotate that many kills forward (or backward, if negative)."
(interactive "p")
(current-kill arg))
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))))
+ 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)
+ (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)))))
+ (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
* Loop Example::
* print-elements-of-list::
* Incrementing Loop::
+* Incrementing Loop Details::
* Decrementing Loop::
@end menu
@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::
@end menu
-@node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
+@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
@unnumberedsubsubsec Example with incrementing counter
Suppose you are playing on the beach and decide to make a triangle of
complex loop the repetitive action might not be so simple, but it will
be simpler than doing everything all at once.
-@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
+@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details
@unnumberedsubsubsec The parts of the function definition
The preceding analysis gives us the bones of our function definition:
(setq row-number (1+ row-number))
@end smallexample
-@node Inc Example altogether, , Inc Example parts, Incrementing Loop
+@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details
@unnumberedsubsubsec Putting the function definition together
We have created the parts for the function definition; now we need to
The sum of the first four numbers is 10 and the sum of the first seven
numbers is 28.
-@node Decrementing Loop, , Incrementing Loop, while
+@node Decrementing Loop, , Incrementing Loop Details, while
@comment node-name, next, previous, up
@subsection Loop with a Decrementing Counter
of the @code{print-elements-recursively} function, before the comment.
Otherwise, the Lisp interpreter will try to evaluate the comment.
-If you are using a more recent version, you can evaluate this
+If you are using a more recent version of Emacs, you can evaluate this
expression directly in Info.
@findex print-elements-recursively
(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
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
[.?!]
@noindent
(Well, not in GNU Emacs 22; that is because of an effort to make the
-process simpler. When its value is @code{nil}, then use the value
-defined by the function @code{sentence-end}, and that returns a value
-constructed from the variables @code{sentence-end-base},
+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
(sentence-end (sentence-end)))
(while (< arg 0)
(let ((pos (point))
- (par-beg (save-excursion (start-of-paragraph-text) (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)))
+ (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)))
+ (skip-chars-backward " \t\n")
+ (goto-char par-end)))
(setq arg (1- arg)))
(constrain-to-field nil opoint t)))
@end group
(let ((opoint (point)) (sentence-end (sentence-end)))
(while (< arg 0)
(let ((pos (point))
- (par-beg (save-excursion (start-of-paragraph-text) (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))))
@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
(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)
+ (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))))))
+ (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))
+ (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))))
+ ;; 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))
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 indicate the paragraph start and
-the paragraph separator. The next expression sets @code{parsep}
+@code{parsep}, the local variables which indicate the paragraph start
+and the paragraph separator. The next expression sets @code{parsep}
again. That is to handle fill prefixes.
This is the setting that requires the definition call @code{let*}
@cindex @file{TAGS} file, create own
Besides @kbd{C-h f} (@code{describe-function}), another way to see the
-source of a function is to type @kbd{M-.} (@code{find-tag}) and the
+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. 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 a @file{TAGS} file such as
+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
You can also create your own @file{TAGS} file for directories that
lack one.
-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.
-
You often need to build and install tags tables yourself. They are
not built automatically. A tags table is called a @file{TAGS} file;
the name is in upper case letters.
@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
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
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,
-which in this case is followed by a letter, the combination of which
-is important to @code{re-search-forward}.)
+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
@noindent
(The most recent version of the @code{find-file} function definition
-permits you to specify optional wildcards visit multiple files; that
+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}).)
(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))
+ (mapcar 'switch-to-buffer (nreverse value))
(switch-to-buffer value))))
@end ignore
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 named
+(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
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
place your cursor after the following expression and type @kbd{C-x
C-e} (@code{eval-last-sexp}).
-@c !!! 22.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
(lengths-list-file
- "/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/debug.el")
+ "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
@end smallexample
@noindent
(You may need to change the pathname of the file; the one here is for
-GNU Emacs version 22.0.100. To change the expression, copy it to
+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, , Specifying Variables using @code{defcustom}}.)
+(@xref{defcustom, , Specifying Variables using @code{defcustom}}.
Then evaluate the @code{lengths-list-file} expression.)
@need 1200
@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 !!! 22.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/22.0.100/lisp/emacs-lisp/} directory,
+@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
@smallexample
debug.el
@noindent
becomes
-@c !!! 22.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
-/usr/local/share/emacs/22.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 22.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 !!! 22.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
@group
-(cd "/usr/local/share/emacs/22.0.100/")
+(cd "/usr/local/share/emacs/22.1.1/")
(lengths-list-file "./lisp/macros.el")
@result{} (283 263 480 90)
of defuns within each range of lengths, and produce a list of those
numbers.
+@menu
+* Data for Display in Detail::
+* Sorting::
+* Files List::
+* Counting function definitions::
+@end menu
+
+@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
+@ifnottex
+@unnumberedsubsec The Data for Display in Detail
+@end ifnottex
+
Based on what we have done before, we can readily foresee that it
should not be too hard to write a function that `@sc{cdr}s' down the
lengths' list, looks at each element, determines which length range it
number, and thereby determine the largest and smallest length range
that we will need.
-@menu
-* Sorting::
-* Files List::
-* Counting function definitions::
-@end menu
-
-@node Sorting, Files List, Prepare the data, Prepare the data
+@node Sorting, Files List, Data for Display in Detail, Prepare the data
@subsection Sorting Lists
@findex sort
For example, the first @samp{.el} file in the @file{lisp/} directory
is @file{abbrev.el}. Its name is
-@file{/usr/local/share/emacs/22.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
(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.0.100/lisp/" t "\\.el$")
-(shell-command "find /usr/local/share/emacs/22.0.100/lisp/ -name '*.el'")
+(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
+(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
@end ignore
-@c /usr/local/share/emacs/22.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/22.0.100/lisp/"
+ ;; "/usr/local/share/emacs/22.1.1/lisp/"
(interactive "DDirectory name: ")
@end group
@group
@end smallexample
@c (files-in-below-directory "/usr/local/src/emacs/lisp/")
-@c (files-in-below-directory "/usr/local/share/emacs/22.0.100/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.
@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
-@c !!! 22.0.100 lisp sources location here
+@c !!! 22.1.1 lisp sources location here
@smallexample
@group
(length
- (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/"))
+ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
@end group
@end smallexample
@noindent
-tells me that my Lisp sources directory contains 1031 @samp{.el}
-files.
+tells me that in and below my Lisp sources directory are 1031
+@samp{.el} files.
@code{files-in-below-directory} returns a list in reverse alphabetical
order. An expression to sort the list in alphabetical order looks
@smallexample
@group
(sort
- (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/")
+ (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
'string-lessp)
@end group
@end smallexample
The recursive function is a little more difficult. It has four parts:
the `do-again-test', the printing code, the recursive call, and the
-`next-step-expression'. The `do-again-test' is 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
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
(The @code{text-mode-hook-identify} function tells
@code{toggle-text-mode-auto-fill} which buffers are in Text mode.
-It comes on automatically.
-)
+It comes on automatically.)
The @code{custom-set-variables} function works somewhat differently
than a @code{setq}. While I have never learned the differences, I
@findex defsubst
@findex defconst
-Incidentally, @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}
+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
@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
; The next two lines put Emacs into Text mode
; and Auto Fill mode, and are for writers who
; want to start writing prose rather than code.
-
(setq default-major-mode 'text-mode)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end group
; 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{CTRL} 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
This is an interface to the function `load'."
(interactive
(list (completing-read "Load library: "
- 'locate-file-completion
- (cons load-path (get-load-suffixes)))))
+ '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 22, I load 14 libraries
-that contain functions that would otherwise be autoloaded. (Actually,
-it would have been better to include these files in my `dumped' Emacs,
-but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU
-Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more
-about dumping.)
+In my @file{.emacs} file, I load 14 libraries that contain functions
+that would otherwise be autoloaded. (Actually, it would have been
+better to include these files in my `dumped' Emacs, but I forgot.
+@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
+Reference Manual}, and the @file{INSTALL} file for more about
+dumping.)
You may also want to include autoloaded expressions in your @file{.emacs}
file. @code{autoload} is a built-in function that takes up to five
@end 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
@smallexample
@group
(cond
- ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
+ (= 21 emacs-major-version)
;; evaluate version 21 code
( @dots{} ))
- ((string-equal (number-to-string 22) (substring (emacs-version) 10 12))
+ (= 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
@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
xsetroot -solid Navy -fg white &
@end smallexample
+@need 1700
@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
@section Miscellaneous Settings for a @file{.emacs} File
+@need 1250
Here are a few miscellaneous settings:
@sp 1
@noindent
or start GNU Emacs with the command @code{emacs -nbc}.
-@item Ignore case when using `grep'@*
-@samp{-n}@w{ } Prefix each line of output with line number@*
+@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 -n -i -e ")
+(setq grep-command "grep -i -nH -e ")
@end smallexample
@ignore
@smallexample
@group
loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
-
@exdent or
-
install-keymap emacs2
@end group
@end smallexample
@end group
@end smallexample
+@need 1700
@node Mode Line, , Miscellaneous, Emacs Initialization
@section A Modified Mode Line
@vindex default-mode-line-format
@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
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 22, 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 22 starts the debugger automatically when your function has
-an error.
+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
@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
both the @code{yank} and the @code{yank-pop} commands, but first,
consider the workings of the kill ring.
+@menu
+* What the Kill Ring Does::
+* current-kill::
+* yank::
+* yank-pop::
+* ring file::
+@end menu
+
+@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
+@ifnottex
+@unnumberedsec What the Kill Ring Does
+@end ifnottex
+
@need 1250
The kill ring has a default maximum length of sixty items; this number
is too large for an explanation. Instead, set it to four. Please
(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. (@code{kill-line} calls @code{kill-region}.) 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.)
-
-@ignore
-@c texi2dvi fails when the name of the section is within ifnottex ...
-For a discussion of how @code{condition-case} deals with error, see
-@ref{Complete kill-region, , The Complete @code{kill-region}
-Definition}.
-@end ignore
+you. Alternatively, for silence, you may copy the region of each line
+with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
+each line for this command to succeed, but it does not matter at which
+end you put point or mark.)
@need 1250
@noindent
(setq kill-ring-max old-kill-ring-max)
@end smallexample
-@menu
-* current-kill::
-* yank::
-* yank-pop::
-* ring file::
-@end menu
-
-@node current-kill, yank, Kill Ring, Kill Ring
+@node current-kill, yank, What the Kill Ring Does, Kill Ring
@comment node-name, next, previous, up
@appendixsec The @code{current-kill} Function
@findex current-kill
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.)
+to the latest element of the the kill ring. The @code{kill-new}
+function is used directly or indirectly by @code{kill-append},
+@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
+and @code{kill-region}.)
+
+@menu
+* Code for current-kill::
+* Understanding current-kill::
+@end menu
+
+@node Code for current-kill, Understanding current-kill, current-kill, current-kill
+@ifnottex
+@unnumberedsubsec The code for @code{current-kill}
+@end ifnottex
+
@need 1500
The @code{current-kill} function is used by @code{yank} and by
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))))
+ 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)
+ (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)))))
+ (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
-In addition, the @code{kill-new} function sets
+Remember also that the @code{kill-new} function sets
@code{kill-ring-yank-pointer} to the latest element of the the kill
-ring. And indirectly so does @code{kill-append}, since it calls
-@code{kill-new}. In addition, @code{kill-region} and @code{kill-line}
-call the @code{kill-new} function.
+ring, which means that all the functions that call it set the value
+indirectly: @code{kill-append}, @code{copy-region-as-kill},
+@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
@need 1500
Here is the line in @code{kill-new}, which is explained in
(setq kill-ring-yank-pointer kill-ring)
@end smallexample
-@menu
-* Understanding current-kill::
-@end menu
-
-@node Understanding current-kill, , current-kill, current-kill
+@node Understanding current-kill, , Code for current-kill, current-kill
@ifnottex
@unnumberedsubsec @code{current-kill} in Outline
@end ifnottex
This function takes two arguments, one of which is optional. It has a
documentation string. It is @emph{not} interactive.
+@menu
+* Body of current-kill::
+* Digression concerning error::
+* Determining the Element::
+@end menu
+
+@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec The Body of @code{current-kill}
+@end ifnottex
+
The body of the function definition is a @code{let} expression, which
itself has a body as well as a @var{varlist}.
@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 lasted element. Most windowing
+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.
@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
+we have already described. @xref{kill-new function, , The
@code{kill-new} function}.)
@smallexample
signals an error.
@need 1000
-Note that the @code{or} expression is very similar to writing
+Note that the @code{or} expression is very similar to testing length
+with an @code{if}:
@findex zerop
@findex error
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
+(@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
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, the first element of which is returned even if the
-@code{do-not-move} argument is true.
+list. Finally, another expression returns the first element of the
+list even if the @code{do-not-move} argument is true.
-@menu
-* Digression concerning error::
-* Determining the Element ::
-@end menu
-
-@node Digression concerning error, Determining the Element , Understanding current-kill, Understanding current-kill
+@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
@ifnottex
@unnumberedsubsubsec Digression about the word `error'
@end ifnottex
takes the same steps as it does when there is an `error', a term such as
`cancel' would have a clearer connotation.
-@node Determining the Element , , Digression concerning error, Understanding current-kill
+@node Determining the Element, , Digression concerning error, Understanding current-kill
@ifnottex
@unnumberedsubsubsec Determining the Element
@end ifnottex
@smallexample
@group
;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
-(nthcdr (mod (- 0 4) 4) ; (mod -4 4) @result{} 0
+;; @r{and} (mod (- 0 4) 4) @result{} 0
+(nthcdr (mod (- 0 4) 4)
'("fourth line of text"
"third line"
"second piece of text"
@findex yank
After learning about @code{current-kill}, 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}.
+@code{yank} function is almost easy.
+
+The @code{yank} function does not use the
+@code{kill-ring-yank-pointer} variable directly. It calls
+@code{insert-for-yank} which calls @code{current-kill} which sets the
+@code{kill-ring-yank-pointer} variable.
@need 1250
The code looks like this:
@end group
@group
(insert-for-yank (current-kill (cond
- ((listp arg) 0)
- ((eq arg '-) -2)
- (t (1- arg)))))
+ ((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)))))
+ (set-marker (mark-marker) (point) (current-buffer)))))
@end group
@group
;; If we do get all the way thru, make this-command indicate that.
returned by @code{current-kill}, but removes some text properties from
it.
-However, before getting to that expression, the function set the value
+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. It also set @code{this-command} and pushed the
-mark.
+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, put point at beginning of
-the yanked text and mark at its end. (The @code{prog1} function is
-like @code{progn} but returns the value of its first argument rather
-than the value of its last argument. Its first argument is forced to
-return the buffer's mark as an integer. You can see the documentation
-for these functions by placing point over them in this buffer and then
-typing @kbd{C-h f} (@code{describe-function}) followed by a @kbd{RET};
-the default is the function.)
+@sc{cons} rather than a number or nothing, it puts point at beginning
+of the yanked text and mark at its end.
+
+(The @code{prog1} function is like @code{progn} but returns the value
+of its first argument rather than the value of its last argument. Its
+first argument is forced to return the buffer's mark as an integer.
+You can see the documentation for these functions by placing point
+over them in this buffer and then typing @kbd{C-h f}
+(@code{describe-function}) followed by a @kbd{RET}; the default is the
+function.)
The last part of the function tells what to do when it succeeds.
@findex yank-pop
After understanding @code{yank} and @code{current-kill}, you know how
-to approach the @code{yank-pop} function Leaving out the documentation
-to save space, it looks like this:
+to approach the @code{yank-pop} function. Leaving out the
+documentation to save space, it looks like this:
@c GNU Emacs 22
@smallexample
(setq this-command 'yank)
(unless arg (setq arg 1))
(let ((inhibit-read-only t)
- (before (< (point) (mark 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) (point) (mark t))
(funcall (or yank-undo-function 'delete-region) (mark t) (point)))
(setq yank-undo-function nil)
@end group
@end group
@group
(if before
- ;; This is like exchange-point-and-mark,
+ ;; 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)
+ ;; 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)
The function is interactive with a small @samp{p} so the prefix
argument is processed and passed to the function. The command can
only be used after a previous yank; otherwise an error message is
-sent. This check uses the variable @code{last-command} which is
-set by @code{yank} and is discussed elsewhere. (@xref{copy-region-as-kill}.)
+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
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::
+* Compute a Remainder::
+* Y Axis Element::
+* Y-axis-column::
+* print-Y-axis Penultimate::
+@end menu
+
+@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
+@ifnottex
+@unnumberedsubsec The @code{print-Y-axis} Function in Detail
+@end ifnottex
+
It is easy enough to see in the figure what the Y axis label should
look like; but to say in words, and then to write a function
definition to do the job is another matter. It is not quite true to
the fifth line from the bottom and on every line that is a multiple of
five.
-@menu
-* Height of label::
-* Compute a Remainder::
-* Y Axis Element::
-* Y-axis-column::
-* print-Y-axis Penultimate::
-@end menu
-
-@node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
+@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis
@ifnottex
@unnumberedsubsec What height should the label be?
@end ifnottex
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
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
@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}:
@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}}
HCoop / bpt / emacs.git / blobdiff