Merge from emacs--rel--22

Revision: emacs@sv.gnu.org/emacs--devo--0--patch-966

8 files changed, 132 insertions, 69 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 9c4d874e139..e950d152a80 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,24 @@
+2007-12-27  Richard Stallman  <rms@gnu.org>
+
+        * text.texi (Formatted Text): Improve menu tag.
+        (Editing Format Info): In Info, add duplicate menu of nodes
+        about the submenus.
+        (Format Faces): Say where Faces menu is found.  Mention Other.
+        (Format Colors): Say where these submenus are found.
+        (Format Indentation, Format Justification): Likewise.
+        (Format Properties): Likewise.
+
+2007-12-22  Richard Stallman  <rms@gnu.org>
+
+        * search.texi (Query Replace): Make exp of query-replace more
+        self-contained, and clarify.
+ 
+        * cc-mode.texi (Getting Started): Change @ref to @pxref.
+
+2007-12-15  Richard Stallman  <rms@gnu.org>
+
+        * files.texi (Auto Save): Clarify definition of auto-saving.
+
 2007-11-26  Richard Stallman  <rms@gnu.org>
 
         * help.texi (Help Echo): Cleanups.
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 8e2cb879754..8e33dc5aa8c 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -997,10 +997,11 @@ visit files under version control.
 @cindex mode, Auto Save
 @cindex crashes
 
-  Emacs saves all the visited files from time to time (based on counting
-your keystrokes) without being asked.  This is called @dfn{auto-saving}.
-It prevents you from losing more than a limited amount of work if the
-system crashes.
+  Emacs saves all the visited files from time to time (based on
+counting your keystrokes) without being asked, in separate files so as
+not to alter the files you actually use.  This is called
+@dfn{auto-saving}.  It prevents you from losing more than a limited
+amount of work if the system crashes.
 
   When Emacs determines that it is time for auto-saving, it considers
 each buffer, and each is auto-saved if auto-saving is enabled for it
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index af1b877e6a4..7b77046e2f3 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1152,13 +1152,12 @@ Replace some matches for @var{regexp} with @var{newstring}.
 @kindex M-%
 @findex query-replace
   If you want to change only some of the occurrences of @samp{foo} to
-@samp{bar}, not all of them, then you cannot use an ordinary
-@code{replace-string}.  Instead, use @kbd{M-%} (@code{query-replace}).
+@samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}).
 This command finds occurrences of @samp{foo} one by one, displays each
 occurrence and asks you whether to replace it.  Aside from querying,
-@code{query-replace} works just like @code{replace-string}.  It
-preserves case, like @code{replace-string}, provided
-@code{case-replace} is non-@code{nil}, as it normally is
+@code{query-replace} works just like @code{replace-string}
+(@pxref{Unconditional Replace}).  In particular, it preserves case
+provided @code{case-replace} is non-@code{nil}, as it normally is
 (@pxref{Replacement and Case}).  A numeric argument means consider
 only occurrences that are bounded by word-delimiter characters.
 
diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index c151c75e8bb..4b3bc8df0f0 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1951,7 +1951,7 @@ contains a list of ideas for future enhancements.
 * Justification: Format Justification.
                                 Centering, setting text flush with the
                                   left or right margin, etc.
-* Other: Format Properties.     The "special" text properties submenu.
+* Special: Format Properties.   The "special" text properties submenu.
 * Forcing Enriched Mode::       How to force use of Enriched mode.
 @end menu
 
@@ -2037,9 +2037,7 @@ or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle
 mouse button).  There are also keyboard commands described in the
 following section.
 
-  Most of the items in the Text Properties menu lead to other submenus.
-These are described in the sections that follow.  Some items run
-commands directly:
+  These items in the Text Properties menu run commands directly:
 
 @table @code
 @findex facemenu-remove-face-props
@@ -2068,14 +2066,35 @@ Display a list of all the defined faces (@code{list-faces-display}).
 Display a list of all the defined colors (@code{list-colors-display}).
 @end table
 
+@ifinfo
+  Other items in the Text Properties menu lead to submenus:
+
+@menu
+* Faces: Format Faces.          Bold, italic, underline, etc.
+* Color: Format Colors.         Changing the color of text.
+* Indent: Format Indentation.   Changing the left and right margins.
+* Justification: Format Justification.
+                                Centering, setting text flush with the
+                                  left or right margin, etc.
+* Special: Format Properties.   The "special" text properties submenu.
+@end menu
+@end ifinfo
+@ifnotinfo
+  The rest lead to submenus which are described in the following sections.
+@end ifnotinfo
+
 @node Format Faces
 @subsection Faces in Formatted Text
 
-  The Faces submenu lists various Emacs faces including @code{bold},
-@code{italic}, and @code{underline} (@pxref{Faces}).  These menu items
-operate on the region if it is active and nonempty.  Otherwise, they
-specify to use that face for an immediately following self-inserting
-character.  Instead of the menu, you can use these keyboard commands:
+  The Faces submenu under Text Properties lists various Emacs faces
+including @code{bold}, @code{italic}, and @code{underline}
+(@pxref{Faces}).  These menu items operate on the region if it is
+active and nonempty.  Otherwise, they specify to use that face for an
+immediately following self-inserting character.  There is also an item
+@samp{Other} with which you can enter a face name through the
+minibuffer (@pxref{Standard Faces}).
+
+  Instead of the Faces submenu, you can use these keyboard commands:
 
 @table @kbd
 @kindex M-o d @r{(Enriched mode)}
@@ -2158,20 +2177,22 @@ them.
 @subsection Colors in Formatted Text
 
   You can specify foreground and background colors for portions of the
-text.  There is a menu for specifying the foreground color and a menu
-for specifying the background color.  Each color menu lists all the
-colors that you have used in Enriched mode in the current Emacs session.
+text.  Under Text Properties there is a submenu for specifying the
+foreground color, and a submenu for specifying the background color.
+Each one lists all the colors that you have used in Enriched mode in
+the current Emacs session.
 
   If you specify a color with a prefix argument---or, in Transient
 Mark mode, if the region is not active---then it applies to any
 immediately following self-inserting input.  Otherwise, the command
 applies to the region.
 
-  Each color menu contains one additional item: @samp{Other}.  You can use
-this item to specify a color that is not listed in the menu; it reads
-the color name with the minibuffer.  To display a list of available colors
-and their names, use the @samp{Display Colors} menu item in the Text
-Properties menu (@pxref{Editing Format Info}).
+  Each of the two color submenus contains one additional item:
+@samp{Other}.  You can use this item to specify a color that is not
+listed in the menu; it reads the color name with the minibuffer.  To
+display a list of available colors and their names, use the
+@samp{Display Colors} menu item in the Text Properties menu
+(@pxref{Editing Format Info}).
 
   Any color that you specify in this way, or that is mentioned in a
 formatted text file that you read in, is added to the corresponding
@@ -2192,8 +2213,9 @@ indentation for the right or left margin of an entire paragraph or a
 part of a paragraph.  The margins you specify automatically affect the
 Emacs fill commands (@pxref{Filling}) and line-breaking commands.
 
-  The Indentation submenu provides a convenient interface for specifying
-these properties.  The submenu contains four items:
+  The Indentation submenu of Text Properties provides a convenient
+interface for specifying these properties.  The submenu contains four
+items:
 
 @table @code
 @kindex C-x TAB @r{(Enriched mode)}
@@ -2266,8 +2288,8 @@ Prefix}.
 justification for a paragraph.  The style you specify automatically
 affects the Emacs fill commands.
 
-  The Justification submenu provides a convenient interface for specifying
-the style.  The submenu contains five items:
+  The Justification submenu of Text Properties provides a convenient
+interface for specifying the style.  The submenu contains five items:
 
 @table @code
 @item Left
@@ -2341,11 +2363,12 @@ sets (as always) the default value for buffers that do not override it.
 @node Format Properties
 @subsection Setting Other Text Properties
 
-  The Special Properties menu lets you add or remove three other useful text
-properties: @code{read-only}, @code{invisible} and @code{intangible}.
-The @code{intangible} property disallows moving point within the text,
-the @code{invisible} text property hides text from display, and the
-@code{read-only} property disallows alteration of the text.
+  The Special Properties submenu of Text Properties can add or remove
+three other useful text properties: @code{read-only}, @code{invisible}
+and @code{intangible}.  The @code{intangible} property disallows
+moving point within the text, the @code{invisible} text property hides
+text from display, and the @code{read-only} property disallows
+alteration of the text.
 
   Each of these special properties has a menu item to add it to the
 region.  The last menu item, @samp{Remove Special}, removes all of these
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bfeb88f7830..50399b0120e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2007-12-28  Richard Stallman  <rms@gnu.org>
+
+        * frames.texi (Size Parameters): Fix typo.
+        (Basic Parameters): For `title', refer to title bar.
+        (Size and Position): Explain meaning of frame pixel width and height.
+
+2007-12-23  Richard Stallman  <rms@gnu.org>
+
+        * customize.texi (Type Keywords): Uncomment :validate and clarify it.
+        Improve some of the commented-out keywords' text too.
+
 2007-12-14  Martin Rudalics  <rudalics@gmx.at>
 
         * nonascii.texi (Encoding and I/O): Reword to avoid saying
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index b97ce20fc22..d971d5b6db2 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -1121,6 +1121,16 @@ corresponding value, @var{function}, should be a function that accepts
 two arguments, a widget and a value; it should return non-@code{nil} if
 the value is acceptable.
 
+@item :validate @var{function}
+Specify a validation function for input.  @var{function} takes a
+widget as an argument, and should return @code{nil} if the widget's
+current value is valid for the widget.  Otherwise, it should return
+the widget containing the invalid data, and set that widget's
+@code{:error} property to a string explaining the error.
+
+In many cases you can use the function @code{widget-children-validate}
+for this job; it tests that all children of @var{widget} are valid.
+
 @ignore
 @item :indent @var{columns}
 Indent this item by @var{columns} columns.  The indentation is used for
@@ -1128,23 +1138,24 @@ Indent this item by @var{columns} columns.  The indentation is used for
 buttons, and for editable lists.  It affects the whole of the
 item except for the first line.
 
-@item :offset @var{columns}
-An integer indicating how many extra spaces to indent the subitems of
-this item.  By default, subitems are indented the same as their parent.
+@item :offset @var{extra}
+Indent the subitems of this item @var{extra} columns more than this
+item itself.  By default, subitems are indented the same as their
+parent.
 
-@item :extra-offset
-An integer indicating how many extra spaces to add to this item's
-indentation, compared to its parent.
+@item :extra-offset @var{n}
+Add @var{n} extra spaces to this item's indentation, compared to its
+parent's indentation.
 
-@item :notify
-A function called each time the item or a subitem is changed.  The
-function is called with two or three arguments.  The first argument is
-the item itself, the second argument is the item that was changed, and
-the third argument is the event leading to the change, if any.
+@item :notify @var{function}
+Call @var{function} each time the item or a subitem is changed.  The
+function gets two or three arguments.  The first argument is the item
+itself, the second argument is the item that was changed, and the
+third argument is the event leading to the change, if any.
 
-@item :menu-tag
-A tag used in the menu when the widget is used as an option in a
-@code{menu-choice} widget.
+@item :menu-tag @var{tag-string}
+Use @var{tag-string} in the menu when the widget is used as an option
+in a @code{menu-choice} widget.
 
 @item :menu-tag-get
 A function used for finding the tag when the widget is used as an option
@@ -1152,15 +1163,6 @@ in a @code{menu-choice} widget.  By default, the tag used will be either the
 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
 representation of the @code{:value} property if not.
 
-@item :validate
-A function which takes a widget as an argument, and return @code{nil}
-if the widget's current value is valid for the widget.  Otherwise, it
-should return the widget containing the invalid data, and set that
-widget's @code{:error} property to a string explaining the error.
-
-You can use the function @code{widget-children-validate} for this job;
-it tests that all children of @var{widget} are valid.
-
 @item :tab-order
 Specify the order in which widgets are traversed with
 @code{widget-forward} or @code{widget-backward}.  This is only partially
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index cd29d44ab76..ab9a6e8291c 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -362,12 +362,12 @@ in this frame.  Its value is @code{color}, @code{grayscale} or
 @code{mono}.
 
 @item title
-If a frame has a non-@code{nil} title, it appears in the window system's
-border for the frame, and also in the mode line of windows in that frame
-if @code{mode-line-frame-identification} uses @samp{%F}
-(@pxref{%-Constructs}).  This is normally the case when Emacs is not
-using a window system, and can only display one frame at a time.
-@xref{Frame Titles}.
+If a frame has a non-@code{nil} title, it appears in the window
+system's title bar at the top of the frame, and also in the mode line
+of windows in that frame if @code{mode-line-frame-identification} uses
+@samp{%F} (@pxref{%-Constructs}).  This is normally the case when
+Emacs is not using a window system, and can only display one frame at
+a time.  @xref{Frame Titles}.
 
 @item name
 The name of the frame.  The frame name serves as a default for the frame
@@ -463,7 +463,7 @@ The height of the frame contents, in characters.  (To get the height in
 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
 
 @item width
-The width of the frame contents, in characters.  (To get the height in
+The width of the frame contents, in characters.  (To get the width in
 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
 
 @item user-size
@@ -808,8 +808,14 @@ of the frame is normally the same as the size of the terminal screen.
 
 @defun frame-pixel-height &optional frame
 @defunx frame-pixel-width &optional frame
-These functions return the height and width of @var{frame}, measured in
-pixels.  If you don't supply @var{frame}, they use the selected frame.
+These functions return the height and width of the main display area
+of @var{frame}, measured in pixels.  If you don't supply @var{frame},
+they use the selected frame.
+
+These values include the internal borders, and windows' scroll bars
+and fringes (which belong to individual windows, not to the frame
+itself), but do not include menu bars or tool bars (except when using
+X without an X toolkit).
 @end defun
 
 @defun frame-char-height &optional frame
diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi
index 7c9a2ac1f1b..80c9332996a 100644
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -487,8 +487,8 @@ work just fine right out of the box.  Note however that you might not
 have the latest @ccmode{} release and might want to upgrade your copy
 (see below).
 
-You should probably start by skimming through the entire chapter
-@ref{Commands} to get an overview of @ccmode{}'s capabilities.
+You should probably start by skimming through the entire Commands chapter
+(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities.
 
 After trying out some commands, you may dislike some aspects of
 @ccmode{}'s default configuration.  Here is an outline of how to