More minor changes.

Center images for TeX output.
(kill-new function):  Remove indentation for sentence talking about
momentarily skipping code.
(cons & search-fwd Review):  Document @code{funcall}.  Document
@code{re-search-forward} with existing @code{search-forward}.
Reference chapter on regular expression searches.
(Recursion with list): Specify a more recent version as being Emacs.
(Recursion with list, Every, recursive-graph-body-print):  Change
`if ... progn' expression to `when'.
(Recursive triangle function): For printing in small book, ensure
section name is not last on bottom of preceding page.
(Keep): Remove extraneous space in function definition example.
(sentence-end): Specify `in English' for glyphs that end a sentence.
Note that in GNU Emacs 22, the name refers to both a variable and a
function.
(fwd-sentence while loops): Write a function as one, not as a form
(fwd-para let): Add `which' to sentence with `parstart' and `parsep'.
(etags): Move sentences involving `find-tag' and sources.  State
location of Emacs `src' directory.
(Design count-words-region):  Better explain two backslashes in a row.
(Find a File): Fix grammar; add a `to' and write `to visit'.  Change
`named' to `selected'.
(lengths-list-file): Remove extraneous parenthesis from reference.
(lengths-list-many-files): Explain `expand-file-name' better.
(Files List): Rephrase sentence regarding Lisp sources directory

2 files changed, 109 insertions, 72 deletions

diff --git a/lispintro/ChangeLog b/lispintro/ChangeLog
index 84d6cee96da..4784cfde92b 100644
--- a/lispintro/ChangeLog
+++ b/lispintro/ChangeLog
@@ -1,3 +1,32 @@
+2006-11-05  Robert J. Chassell  <bob@rattlesnake.com>
+
+        * emacs-lisp-intro.texi: More minor changes.
+        Center images for TeX output.
+        (kill-new function):  Remove indentation for sentence talking about
+        momentarily skipping code.
+        (cons & search-fwd Review):  Document @code{funcall}.  Document
+        @code{re-search-forward} with existing @code{search-forward}.
+        Reference chapter on regular expression searches.
+        (Recursion with list): Specify a more recent version as being Emacs.
+        (Recursion with list, Every, recursive-graph-body-print):  Change
+        `if ... progn' expression to `when'.
+        (Recursive triangle function): For printing in small book, ensure
+        section name is not last on bottom of preceding page.
+        (Keep): Remove extraneous space in function definition example.
+        (sentence-end): Specify `in English' for glyphs that end a sentence.
+        Note that in GNU Emacs 22, the name refers to both a variable and a
+        function.
+        (fwd-sentence while loops): Write a function as one, not as a form
+        (fwd-para let): Add `which' to sentence with `parstart' and `parsep'.
+        (etags): Move sentences involving `find-tag' and sources.  State
+        location of Emacs `src' directory.
+        (Design count-words-region):  Better explain two backslashes in a row.
+        (Find a File): Fix grammar; add a `to' and write `to visit'.  Change
+        `named' to `selected'.
+        (lengths-list-file): Remove extraneous parenthesis from reference.
+        (lengths-list-many-files): Explain `expand-file-name' better.
+        (Files List): Rephrase sentence regarding Lisp sources directory
+
 2006-11-04  Robert J. Chassell  <bob@rattlesnake.com>
 
         * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100.
diff --git a/lispintro/emacs-lisp-intro.texi b/lispintro/emacs-lisp-intro.texi
index 3d954f6f942..621dd038693 100644
--- a/lispintro/emacs-lisp-intro.texi
+++ b/lispintro/emacs-lisp-intro.texi
@@ -8800,6 +8800,7 @@ Make STRING the latest kill in the kill ring.
 @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.
@@ -9486,6 +9487,10 @@ For example:
 @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
@@ -9550,15 +9555,19 @@ Record whatever narrowing is in effect in the current buffer, if any,
 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.
@@ -9665,7 +9674,7 @@ This sounds more complicated than it is and is easier seen in a diagram:
 @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}}
@@ -9728,7 +9737,7 @@ bouquet
 @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}}
@@ -9777,7 +9786,7 @@ bouquet
 @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}}
@@ -9844,7 +9853,7 @@ bouquet        flowers
 @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}}
@@ -9916,7 +9925,7 @@ bouquet                       flowers
 @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}}
@@ -10033,7 +10042,7 @@ Here is a fanciful representation:
 @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}}
@@ -10214,7 +10223,7 @@ kill-ring     kill-ring-yank-pointer
 @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}}
@@ -11446,7 +11455,7 @@ Also, place your cursor immediately after the last closing parenthesis
 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 @@ expression directly in Info.
 (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 @@ Put in yet another way, if the list is not empty, the first robot
 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 @@ works on a shorter 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
@@ -11522,6 +11530,7 @@ nil
 @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
@@ -11881,11 +11890,10 @@ The @code{print-elements-recursively} function looks like this:
 (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 @@ The pattern for @code{print-elements-recursively} is:
 
 @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),
@@ -12017,7 +12025,7 @@ Here is an example that uses @code{cond}:
 
    ;; 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
@@ -12379,9 +12387,9 @@ The symbol @code{sentence-end} is bound to the pattern that marks the
 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 @@ sentence-end
 
 @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 @@ end of the paragraph, @code{(point)} returns the value of point, and then
 @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 @@ Otherwise, the variable will be set to @code{nil}.
 
 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*}
@@ -13524,11 +13534,14 @@ a car with his eyes shut!)
 @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
@@ -13537,10 +13550,6 @@ sources.)
 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 @@ M-x compile RET etags *.el RET
 @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 @@ of which I load 12---you can create a @file{TAGS} file for the Emacs
 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
@@ -13592,10 +13600,11 @@ to see a list of the options accepted by @code{etags} as well as a
 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 @@ visit-tags-table}.
 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
@@ -13921,9 +13930,9 @@ single backslash has special meaning to the Emacs Lisp interpreter.
 It indicates that the following character is interpreted differently
 than usual.  For example, the two characters, @samp{\n}, stand for
 @samp{newline}, rather than for a backslash followed by @samp{n}.  Two
-backslashes in a row stand for an ordinary, `unspecial' backslash,
-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 @@ creating one if none already exists."
 
 @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 @@ suppress warning messages.  These optional arguments are irrelevant.)
 
 However, the @code{find-file-noselect} function does not select the
 buffer in which it puts the file.  Emacs does not switch its attention
-(or yours if you are using @code{find-file-noselect}) to the 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 @@ and symbols in a function definition should change the buffer.
 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 @@ version, you may have to evaluate the following:
 @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 @@ These considerations lead us directly to the function itself:
 @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 @@ Thus, on my system,
 @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
@@ -16821,7 +16830,7 @@ The numbers-list consists of the Y-axis values."
 
 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 @@ Used within recursive-graph-body-print function."
 @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 @@ Used within recursive-graph-body-print function."
         (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 @@ If we want to multiply 3 by 7, we can write:
 @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}}
@@ -21081,7 +21089,7 @@ Similarly, we can write:
 @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}}
@@ -21120,7 +21128,7 @@ If we want to divide 100 by 50, we can write:
 @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}}