Tweaks to lisp manual to remove over/underflows in printed version.

* help.texi (Accessing Documentation):
* display.texi (Pixel Specification):
* processes.texi (Serial Ports, Serial Ports):
* nonascii.texi (Character Properties, Default Coding Systems):
* text.texi (Changing Properties, Special Properties):
* windows.texi (Window Start and End):
* modes.texi (SMIE Indentation Example, SMIE Tricks):
* keymaps.texi (Searching Keymaps, Tool Bar):
* minibuf.texi (Basic Completion):
* compile.texi (Eval During Compile):
* strings.texi (Formatting Strings): Tweaks to avoid overflowing
7x9 paper in printed manual.

* lists.texi (Sets And Lists): Fix misplaced text.

15 files changed, 115 insertions, 108 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index c8a45ffc4d3..fd8a9945cf9 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,20 @@
+2011-05-29  Chong Yidong  <cyd@stupidchicken.com>
+
+        * help.texi (Accessing Documentation):
+        * display.texi (Pixel Specification):
+        * processes.texi (Serial Ports, Serial Ports):
+        * nonascii.texi (Character Properties, Default Coding Systems):
+        * text.texi (Changing Properties, Special Properties):
+        * windows.texi (Window Start and End):
+        * modes.texi (SMIE Indentation Example, SMIE Tricks):
+        * keymaps.texi (Searching Keymaps, Tool Bar):
+        * minibuf.texi (Basic Completion):
+        * compile.texi (Eval During Compile):
+        * strings.texi (Formatting Strings): Tweaks to avoid overflowing
+        7x9 paper in printed manual.
+
+        * lists.texi (Sets And Lists): Fix misplaced text.
+
 2011-05-06  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * modes.texi (Region to Refontify): Rename from "Region to Fontify".
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 928955b0239..b91e1626233 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -452,7 +452,7 @@ used to load it for compiling, but not executing.  For example,
 
 @lisp
 (eval-when-compile
-  (require 'my-macro-package))  ;; only macros needed from this
+  (require 'my-macro-package))
 @end lisp
 
 The same sort of thing goes for macros and @code{defsubst} functions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8a884401546..4a647ef15a2 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1443,9 +1443,9 @@ specify a particular attribute for certain text.  @xref{Face
 Attributes}.
 
 @item
-A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
-@code{(background-color . @var{color-name})}.  These elements specify
-just the foreground color or just the background color.
+A cons cell, either of the form @code{(fg-color . @var{color-name})}
+or @code{(bg-color . @var{color-name})}.  These elements specify just
+the foreground color or just the background color.
 
 @code{(foreground-color . @var{color-name})} has the same effect as
 @code{(:foreground @var{color-name})}; likewise for the background.
@@ -3821,9 +3821,10 @@ pixels per inch, millimeter, and centimeter, respectively.  The
 and height of the current face.  An image specification @code{image}
 corresponds to the width or height of the image.
 
-  The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
-@code{right-margin}, @code{scroll-bar}, and @code{text} elements
-specify to the width of the corresponding area of the window.
+  The elements @code{left-fringe}, @code{right-fringe},
+@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
+@code{text} specify to the width of the corresponding area of the
+window.
 
   The @code{left}, @code{center}, and @code{right} positions can be
 used with @code{:align-to} to specify a position relative to the left
@@ -4613,16 +4614,14 @@ If @var{no-error} is non-@code{nil} and a suitable path can't be
 found, don't signal an error.  Instead, return a list of directories as
 before, except that @code{nil} appears in place of the image directory.
 
-Here is an example that uses a common idiom to provide compatibility
-with versions of Emacs that lack the variable @code{image-load-path}:
+Here is an example of using @code{image-load-path-for-library}:
 
 @example
 (defvar image-load-path) ; shush compiler
 (let* ((load-path (image-load-path-for-library
-                        "mh-e" "mh-logo.xpm"))
+                    "mh-e" "mh-logo.xpm"))
        (image-load-path (cons (car load-path)
-                              (when (boundp 'image-load-path)
-                                image-load-path))))
+                              image-load-path)))
   (mh-tool-bar-folder-buttons-init))
 @end example
 @end defun
@@ -5351,8 +5350,10 @@ value) in various ways.
                         (aref colorcomp-data 2)))
           (samp " (sample text) "))
       (insert "Color\t: "
-              (propertize samp 'face `(foreground-color . ,cstr))
-              (propertize samp 'face `(background-color . ,cstr))
+              (propertize samp 'face
+                          `(foreground-color . ,cstr))
+              (propertize samp 'face
+                          `(background-color . ,cstr))
               "\n"))))
 
 (defun colorcomp (color)
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 93a8acdff0c..b140a1343dc 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -14,7 +14,7 @@
 @c in general, keep the following line commented out, unless doing a
 @c copy of this manual that will be published.  The manual should go
 @c onto the distribution in the full, 8.5 x 11" size.
-@c set smallbook
+@c @smallbook
 
 @ifset smallbook
 @smallbook
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 496ad6226f4..f1db33582ff 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -144,9 +144,9 @@ unless @var{verbatim} is non-@code{nil}.
 @end defun
 
 @defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}.
-@code{documentation} handles macros, named keyboard macros, and
-special forms, as well as ordinary functions.
+This function returns the documentation string of @var{function}.  It
+handles macros, named keyboard macros, and special forms, as well as
+ordinary functions.
 
 If @var{function} is a symbol, this function first looks for the
 @code{function-documentation} property of that symbol; if that has a
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 1d485ab67ba..b1f02d6b26e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -720,17 +720,18 @@ pseudo-Lisp description of the order and conditions for searching
 them:
 
 @lisp
-(or (if overriding-terminal-local-map
-        (@var{find-in} overriding-terminal-local-map)
-      (if overriding-local-map
-          (@var{find-in} overriding-local-map)
-        (or (@var{find-in} (get-char-property (point) 'keymap))
-            (@var{find-in-any} emulation-mode-map-alists)
-            (@var{find-in-any} minor-mode-overriding-map-alist)
-            (@var{find-in-any} minor-mode-map-alist)
-            (if (get-text-property (point) 'local-map)
-                (@var{find-in} (get-char-property (point) 'local-map))
-              (@var{find-in} (current-local-map))))))
+(or (cond
+     (overriding-terminal-local-map
+      (@var{find-in} overriding-terminal-local-map))
+     (overriding-local-map
+      (@var{find-in} overriding-local-map))
+     (or (@var{find-in} (get-char-property (point) 'keymap))
+         (@var{find-in-any} emulation-mode-map-alists)
+         (@var{find-in-any} minor-mode-overriding-map-alist)
+         (@var{find-in-any} minor-mode-map-alist)
+         (if (get-text-property (point) 'local-map)
+             (@var{find-in} (get-char-property (point) 'local-map))
+           (@var{find-in} (current-local-map)))))
     (@var{find-in} (current-global-map)))
 @end lisp
 
@@ -2661,8 +2662,8 @@ using an indirection through @code{tool-bar-map}.
 By default, the global map binds @code{[tool-bar]} as follows:
 @example
 (global-set-key [tool-bar]
-                '(menu-item "tool bar" ignore
-                            :filter (lambda (ignore) tool-bar-map)))
+  '(menu-item "tool bar" ignore
+              :filter (lambda (ignore) tool-bar-map)))
 @end example
 @noindent
 Thus the tool bar map is derived dynamically from the value of variable
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 4435af43c8c..b45277acfb3 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1356,10 +1356,10 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
 (delq '(4) sample-list)
      @result{} (a c (4))
 @end group
+@end example
 
 If you want to delete elements that are @code{equal} to a given value,
 use @code{delete} (see below).
-@end example
 
 @defun remq object list
 This function returns a copy of @var{list}, with all elements removed
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 9b09a304bd0..b2ffc5fede7 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -839,12 +839,13 @@ variable as ``risky'' with a non-@code{nil}
 @code{risky-local-variable} property.  @xref{File Local Variables}.
 
 @defvar completion-ignore-case
-If the value of this variable is non-@code{nil}, Emacs does not
-consider case significant in completion.  Note, however, that this
-variable is overridden by @code{read-file-name-completion-ignore-case}
-within @code{read-file-name} (@pxref{Reading File Names}), and by
-@code{read-buffer-completion-ignore-case} within @code{read-buffer}
-(@pxref{High-Level Completion}).
+If the value of this variable is non-@code{nil}, case is not
+considered significant in completion.  Within @code{read-file-name},
+this variable is overridden by
+@code{read-file-name-completion-ignore-case} (@pxref{Reading File
+Names}); within @code{read-buffer}, it is overridden by
+@code{read-buffer-completion-ignore-case} (@pxref{High-Level
+Completion}).
 @end defvar
 
 @defvar completion-regexp-list
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 1c72619c833..3f3eb2cd1f6 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1024,8 +1024,8 @@ Turning on text-mode runs the hook `text-mode-hook'."
 @end group
 @group
   ;; @r{These four lines are absent from the current version}
-  ;; @r{not because this is done some other way, but rather}
-  ;; @r{because nowadays Text mode uses the normal definition of paragraphs.}
+  ;; @r{not because this is done some other way, but because}
+  ;; @r{nowadays Text mode uses the normal definition of paragraphs.}
   (set (make-local-variable 'paragraph-start)
        (concat "[ \t]*$\\|" page-delimiter))
   (set (make-local-variable 'paragraph-separate) paragraph-start)
@@ -1117,12 +1117,15 @@ modes should understand the Lisp conventions for comments.  The rest of
 
 @smallexample
 @group
-  (set (make-local-variable 'paragraph-start) (concat page-delimiter "\\|$" ))
-  (set (make-local-variable 'paragraph-separate) paragraph-start)
+  (set (make-local-variable 'paragraph-start)
+       (concat page-delimiter "\\|$" ))
+  (set (make-local-variable 'paragraph-separate)
+       paragraph-start)
   @dots{}
 @end group
 @group
-  (set (make-local-variable 'comment-indent-function) 'lisp-comment-indent))
+  (set (make-local-variable 'comment-indent-function)
+       'lisp-comment-indent))
   @dots{}
 @end group
 @end smallexample
@@ -3590,7 +3593,9 @@ natural to have a BNF grammar that looks like this:
   (inst ("IF" exp "THEN" insts "ELSE" insts "END")
         ("CASE" exp "OF" cases "END")
         ...)
-  (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts))
+  (cases (cases "|" cases)
+         (caselabel ":" insts)
+         ("ELSE" insts))
   ...
 @end example
 
@@ -3791,7 +3796,9 @@ block).
 Here is an example of an indentation function:
 
 @example
-(eval-when-compile (require 'cl))       ;For the `case' macro.
+;; For the `case' macro.
+(eval-when-compile (require 'cl))
+
 (defun sample-smie-rules (kind token)
   (case kind
     (:elem (case token
@@ -3872,9 +3879,10 @@ and is always at the beginning of a line, we can use a more efficient
 rule:
 @example
 ((equal token "if")
- (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
+ (and (not (smie-rule-bolp))
+      (smie-rule-prev-p "else")
       (save-excursion
-        (sample-smie-backward-token)  ;Jump before the "else".
+        (sample-smie-backward-token)
         (cons 'column (current-column)))))
 @end example
 
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 3093613ccaa..b66a5446e45 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -378,17 +378,17 @@ properties that Emacs knows about:
 
 @table @code
 @item name
-This property corresponds to the Unicode @code{Name} property.  The
-value is a string consisting of upper-case Latin letters A to Z,
-digits, spaces, and hyphen @samp{-} characters.
+Corresponds to the @code{Name} Unicode property.  The value is a
+string consisting of upper-case Latin letters A to Z, digits, spaces,
+and hyphen @samp{-} characters.
 
 @item general-category
-This property corresponds to the Unicode @code{General_Category}
-property.  The value is a symbol whose name is a 2-letter abbreviation
-of the character's classification.
+Corresponds to the @code{General_Category} Unicode property.  The
+value is a symbol whose name is a 2-letter abbreviation of the
+character's classification.
 
 @item canonical-combining-class
-Corresponds to the Unicode @code{Canonical_Combining_Class} property.
+Corresponds to the @code{Canonical_Combining_Class} Unicode property.
 The value is an integer number.
 
 @item bidi-class
@@ -469,15 +469,18 @@ This function returns the value of @var{char}'s @var{propname} property.
      @result{} Nd
 @end group
 @group
-(get-char-code-property ?\u2084 'digit-value) ; subscript 4
+;; subscript 4
+(get-char-code-property ?\u2084 'digit-value)
      @result{} 4
 @end group
 @group
-(get-char-code-property ?\u2155 'numeric-value) ; one fifth
+;; one fifth
+(get-char-code-property ?\u2155 'numeric-value)
      @result{} 1/5
 @end group
 @group
-(get-char-code-property ?\u2163 'numeric-value) ; Roman IV
+;; Roman IV
+(get-char-code-property ?\u2163 'numeric-value)
      @result{} \4
 @end group
 @end example
@@ -1447,11 +1450,11 @@ for decoding (in case @var{operation} does decoding), and
 @var{encoding-system} is the coding system for encoding (in case
 @var{operation} does encoding).
 
-The argument @var{operation} is a symbol, one of @code{write-region},
-@code{start-process}, @code{call-process}, @code{call-process-region},
-@code{insert-file-contents}, or @code{open-network-stream}.  These are
-the names of the Emacs I/O primitives that can do character code and
-eol conversion.
+The argument @var{operation} is a symbol; it should be one of
+@code{write-region}, @code{start-process}, @code{call-process},
+@code{call-process-region}, @code{insert-file-contents}, or
+@code{open-network-stream}.  These are the names of the Emacs I/O
+primitives that can do character code and eol conversion.
 
 The remaining arguments should be the same arguments that might be given
 to the corresponding I/O primitive.  Depending on the primitive, one
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index d5598f55388..f3f68a79471 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1795,9 +1795,9 @@ nice values get scheduled more favorably.)
 The number of threads in the process.
 
 @item start
-The time the process was started, in the @w{@code{(@var{high}
-@var{low} @var{microsec})}} format used by @code{current-time} and
-@code{file-attributes}.
+The time when the process was started, in the same
+@w{@code{(@var{high} @var{low} @var{microsec})}} format used by
+@code{current-time} and @code{file-attributes}.
 
 @item etime
 The time elapsed since the process started, in the @w{@code{(@var{high}
@@ -2483,25 +2483,17 @@ Install @var{plist} as the initial plist of the process.
 @itemx :parity
 @itemx :stopbits
 @itemx :flowcontrol
-These arguments are handled by @code{serial-process-configure}, which
-is called by @code{make-serial-process}.
+These are handled by @code{serial-process-configure}, which is called
+by @code{make-serial-process}.
 @end table
 
 The original argument list, possibly modified by later configuration,
 is available via the function @code{process-contact}.
 
-Examples:
+Here is an example:
 
 @example
 (make-serial-process :port "/dev/ttyS0" :speed 9600)
-
-(make-serial-process :port "COM1" :speed 115200 :stopbits 2)
-
-(make-serial-process :port "\\\\.\\COM13" :speed 1200
-                     :bytesize 7 :parity 'odd)
-
-(make-serial-process :port "/dev/tty.BlueConsole-SPP-1"
-                     :speed nil)
 @end example
 @end defun
 
@@ -2561,19 +2553,9 @@ flow control).  If @var{flowcontrol} is not given, it defaults to no
 flow control.
 @end table
 
-@code{serial-process-configure} is called by @code{make-serial-process} for the
-initial configuration of the serial port.
-
-Examples:
-
-@example
-(serial-process-configure :process "/dev/ttyS0" :speed 1200)
-
-(serial-process-configure :buffer "COM1" :stopbits 1
-                          :parity 'odd :flowcontrol 'hw)
-
-(serial-process-configure :port "\\\\.\\COM13" :bytesize 7)
-@end example
+@code{serial-process-configure} is called by
+@code{make-serial-process} for the initial configuration of the serial
+port.
 @end defun
 
 @node Byte Packing
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 925c92050e4..87b9f4368fb 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -829,12 +829,12 @@ is not truncated.
 
 @example
 @group
-(format "The word `%7s' actually has %d letters in it."
+(format "The word `%7s' has %d letters in it."
         "foo" (length "foo"))
-     @result{} "The word `    foo' actually has 3 letters in it."
-(format "The word `%7s' actually has %d letters in it."
+     @result{} "The word `    foo' has 3 letters in it."
+(format "The word `%7s' has %d letters in it."
         "specification" (length "specification"))
-     @result{} "The word `specification' actually has 13 letters in it."
+     @result{} "The word `specification' has 13 letters in it."
 @end group
 @end example
 
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index e11913e9931..f4dce6a1bc6 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2810,9 +2810,9 @@ construct each part with @code{propertize} and then combine them with
 @end smallexample
 @end defun
 
-  See also the function @code{buffer-substring-no-properties}
-(@pxref{Buffer Contents}) which copies text from the buffer
-but does not copy its properties.
+  @xref{Buffer Contents}, for the function
+@code{buffer-substring-no-properties}, which copies text from the
+buffer but does not copy its properties.
 
 @node Property Search
 @subsection Text Property Search Functions
@@ -2996,13 +2996,6 @@ face attribute name and @var{value} is a meaningful value for that
 attribute.  With this feature, you do not need to create a face each
 time you want to specify a particular attribute for certain text.
 @xref{Face Attributes}.
-
-@item
-A cons cell with the form @code{(foreground-color . @var{color-name})}
-or @code{(background-color . @var{color-name})}.  These are old,
-deprecated equivalents for @code{(:foreground @var{color-name})} and
-@code{(:background @var{color-name})}.  Please convert code that uses
-them.
 @end itemize
 
 It works to use the latter two forms directly as the value
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 5dd845efbdb..9be6c061bf1 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -256,7 +256,8 @@ file if you distribute copies.  Use a notice like this one:
 ;; GNU General Public License for more details.
 
 ;; You should have received a copy of the GNU General Public License
-;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+;; along with this program.  If not, see
+;; <http://www.gnu.org/licenses/>.
 @end smallexample
 
 If you have signed papers to assign the copyright to the Foundation,
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f17fc3c718b..ee9d1a8374e 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1463,10 +1463,10 @@ to the current position of point in @var{window}; @var{window}, to the
 selected window.  If @var{position} is @code{t}, that means to check the
 last visible position in @var{window}.
 
-The @code{pos-visible-in-window-p} function considers only vertical
-scrolling.  If @var{position} is out of view only because @var{window}
-has been scrolled horizontally, @code{pos-visible-in-window-p} returns
-non-@code{nil} anyway.  @xref{Horizontal Scrolling}.
+This function considers only vertical scrolling.  If @var{position} is
+out of view only because @var{window} has been scrolled horizontally,
+@code{pos-visible-in-window-p} returns non-@code{nil} anyway.
+@xref{Horizontal Scrolling}.
 
 If @var{position} is visible, @code{pos-visible-in-window-p} returns
 @code{t} if @var{partially} is @code{nil}; if @var{partially} is