[Emacs-diffs] Changes to emacs/lispintro/emacs-lisp-intro.texi,v

[Robert J. Chassell]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Robert J. Chassell <bob>        06/11/05 16:19:48

Index: emacs-lisp-intro.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispintro/emacs-lisp-intro.texi,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -b -r1.51 -r1.52
--- emacs-lisp-intro.texi       4 Nov 2006 19:08:35 -0000       1.51
+++ emacs-lisp-intro.texi       5 Nov 2006 16:19:47 -0000       1.52
@@ -8800,6 +8800,7 @@
 @noindent
 Let's skip over the rest of the documentation for the moment.
 
address@hidden
 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.
@@ -9486,6 +9487,10 @@
 @end group
 @end smallexample
 
address@hidden funcall
address@hidden 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
@@ -9550,15 +9555,19 @@
 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:
address@hidden 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.
@@ -9665,7 +9674,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -9728,7 +9737,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -9777,7 +9786,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -9844,7 +9853,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -9916,7 +9925,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -10033,7 +10042,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -10214,7 +10223,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -11446,7 +11455,7 @@
 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
@@ -11457,11 +11466,10 @@
 (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
@@ -11483,7 +11491,7 @@
 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
@@ -11502,7 +11510,7 @@
 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
address@hidden, the @code{if} expression tests false so the then-part is
address@hidden, the @code{when} expression tests false so the then-part is
 not evaluated.  The function as a whole then returns @code{nil}.
 
 @need 1200
@@ -11522,6 +11530,7 @@
 @end group
 @end smallexample
 
address@hidden 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
@@ -11881,11 +11890,10 @@
 (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
@@ -11896,9 +11904,9 @@
 
 @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),
@@ -12379,9 +12387,9 @@
 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
 [.?!]
@@ -12466,9 +12474,11 @@
 
 @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
@@ -12817,7 +12827,7 @@
 @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
@@ -13210,8 +13220,8 @@
 
 The next two local variables in the @code{let*} expression are
 designed to remove instances of @samp{^} from @code{parstart} and
address@hidden, the local variables indicate the paragraph start and
-the paragraph separator.  The next expression sets @code{parsep}
address@hidden, 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*}
@@ -13526,9 +13536,12 @@
 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.  This will take you directly to the source.  If the
address@hidden 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
address@hidden 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
@@ -13537,10 +13550,6 @@
 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.
@@ -13562,7 +13571,7 @@
 @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,
@@ -13570,11 +13579,10 @@
 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
address@hidden@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
address@hidden file, type @address@hidden *.el ../elisp/*.el}}, where
address@hidden/elisp/} is the second directory:
 
 @smallexample
 M-x compile RET etags *.el ../elisp/*.el RET
@@ -13592,10 +13600,11 @@
 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
@@ -13625,8 +13634,8 @@
 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
address@hidden/} 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
@@ -13921,9 +13930,9 @@
 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
@@ -15115,7 +15124,7 @@
 
 @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}).)
@@ -15158,7 +15167,7 @@
 
 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
@@ -15235,10 +15244,10 @@
 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
@@ -15290,7 +15299,7 @@
 @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
@@ -15402,8 +15411,8 @@
 @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.1.100 lisp sources location here
 @need 1500
@@ -15895,8 +15904,8 @@
 @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
address@hidden files.
 
 @code{files-in-below-directory} returns a list in reverse alphabetical
 order.  An expression to sort the list in alphabetical order looks
@@ -16821,7 +16830,7 @@
 
 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
@@ -16838,8 +16847,7 @@
 @end group
 
 @group
-  (if numbers-list
-      (progn
+  (when numbers-list
         (setq from-position (point))
         (insert-rectangle
          (column-of-graph height (car numbers-list)))
@@ -16849,7 +16857,7 @@
         (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
 
@@ -21039,7 +21047,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -21081,7 +21089,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}
@@ -21120,7 +21128,7 @@
 @ifset print-postscript-figures
 @sp 1
 @tex
address@hidden
address@hidden @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}}