Merge from trunk.

16 files changed, 619 insertions, 869 deletions

diff --git a/ChangeLog b/ChangeLog
index fb342cffec9..e33acde4239 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2012-01-16  Juanma Barranquero  <lekktu@gmail.com>
+
+        * .bzrignore: Ignore etc/__pycache__.
+
 2011-12-17  Paul Eggert  <eggert@cs.ucla.edu>
 
         Port HAVE_PTHREAD configuration to MirBSD 10 (Bug#10201).
diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 0c75181aa03..daf8e33d041 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -144,7 +144,7 @@ emacs-xtra.texi
 emerge-xtra.texi
 entering.texi     cyd
 files.texi        cyd
-fixit.texi        
+fixit.texi        cyd
 fortran-xtra.texi 
 frames.texi       cyd
 glossary.texi
@@ -175,7 +175,7 @@ trouble.texi      cyd
 vc-xtra.texi      cyd
 vc1-xtra.texi     cyd
 windows.texi      cyd
-xresources.texi   
+xresources.texi   cyd
 
 ** Check the Lisp manual.
 
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index ab8c822ffcf..90a7f69ea72 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,7 +1,31 @@
+2012-01-16  Volker Sobek  <reklov@live.com>  (tiny change)
+
+        * programs.texi (Comment Commands): Typo (bug#10514).
+
+2012-01-15  Chong Yidong  <cyd@gnu.org>
+
+        * xresources.texi (X Resources): Describe GTK+ case first.
+        (Resources): Don't use borderWidth as an example, since it doesn't
+        work with GTK+.
+        (Table of Resources): Clarify role of several resources, including
+        the Emacs 24 behavior of cursorBlink etc.
+        (Face Resources): Node deleted.  Recommend using Customize
+        instead.  Add paragraph to `Table of Resources' node summarizing
+        how to use X resources for changing faces.
+        (Lucid Resources): Rewrite, omitting description of font names,
+        referring to the Fonts node instead.
+        (LessTif Resources): Copyedits.
+        (GTK resources): Rewrite, describing the difference between gtk2
+        and gtk3.
+        (GTK Resource Basics): New node.
+        (GTK Widget Names, GTK Names in Emacs): Rewrite.
+        (GTK styles): Just refer to Fonts node for GTK font format.
+
+        * display.texi (Faces): Document the cursor face.
+
 2012-01-14  Chong Yidong  <cyd@gnu.org>
 
-        * cmdargs.texi (Action Arguments): No need to mention
-        EMACSLOADPATH.
+        * cmdargs.texi (Action Arguments): No need to mention EMACSLOADPATH.
         (General Variables): Add xref to Lisp Libraries.
         (Initial Options): Copyedits.
         (Resume Arguments): Node deleted; emacs.bash/csh are obsolete.
@@ -8826,7 +8850,7 @@
 ;; coding: utf-8
 ;; End:
 
-  Copyright (C) 1993-1999, 2001-2011  Free Software Foundation, Inc.
+  Copyright (C) 1993-1999, 2001-2012  Free Software Foundation, Inc.
 
   This file is part of GNU Emacs.
 
diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi
index 68f617d2cfd..d9f17c91f5e 100644
--- a/doc/emacs/anti.texi
+++ b/doc/emacs/anti.texi
@@ -3,135 +3,19 @@
 @c See file emacs.texi for copying conditions.
 
 @node Antinews, Mac OS / GNUstep, X Resources, Top
-@appendix Emacs 22 Antinews
+@appendix Emacs 23 Antinews
 @c Update the emacs.texi Antinews menu entry with the above version number.
 
   For those users who live backwards in time, here is information
-about downgrading to Emacs version 22.3.  We hope you will enjoy the
+about downgrading to Emacs version 23.4.  We hope you will enjoy the
 greater simplicity that results from the absence of many Emacs
 @value{EMACSVER} features.
 
 @itemize @bullet
-
-@item
-We have switched to a character representation specially designed for
-Emacs.  Rather than forcing all the widely used scripts into artificial
-alignment, as Unicode does, Emacs treats them all equally, giving
-each one a place in the space of character codes.  We have eliminated
-the confusing practice, in Emacs 23, whereby one character can belong
-to multiple character sets.  Now each script has its own variant, and
-they all are different as far as Emacs is concerned.  For example,
-there's a Latin-1 c-cedilla character, and there's a Latin-2
-c-cedilla; searching a buffer for the Latin-1 variant only finds that
-variant, but not the others.
-
-@item
-Emacs now uses its own special internal encoding for non-@acronym{ASCII}
-characters, known as @samp{emacs-mule}.  This was imperative to
-support several different variants of the same character, each one
-belonging to its own script: @samp{emacs-mule} marks each character
-with its script, to better discern them from one another.
-
-@item
-For simplicity, the functions @code{encode-coding-region} and
-@code{decode-coding-region} no longer accept an argument saying where
-to store the result of their conversions.  The result always replaces
-the original, so there's no need to look for it elsewhere.
-
-@item
-Emacs no longer performs font anti-aliasing.  If your fonts look ugly,
-try choosing a larger font and increasing the screen resolution.
-Admittedly, this becomes difficult as you go further back in time,
-since available screen resolutions will decrease.
-
-@item
-The Fontconfig font library is no longer supported.  To specify a
-font, you must use an XLFD (X Logical Font Descriptor).  The other
-ways of specifying fonts---so-called ``Fontconfig'' and ``GTK'' font
-names---are redundant, so they have been removed.
-
-@item
-Transient Mark mode is now disabled by default.  Furthermore, some
-commands that operate specifically on the region when it is active and
-Transient Mark mode is enabled (such as @code{fill-paragraph}
-@code{ispell-word}, and @code{indent-for-tab-command}), no longer do
-so.
-
-@item
-Holding @key{shift} while typing a motion command no longer creates a
-temporarily active region, since that's inconsistent with how Emacs
-normally handles keybindings.  The variable @code{shift-select-mode}
-has been deleted.  You can, however, still create temporarily active
-regions by dragging the mouse.
-
-@item
-The line motion commands, @kbd{C-n} and @kbd{C-p}, now move by logical
-text lines, not screen lines.  Even if a long text line is continued
-over multiple screen lines, @kbd{C-n} and @kbd{C-p} treat it as a
-single line, because that's ultimately what it is.
-
-@item
-Visual Line mode, which provides ``word wrap'' functionality, has been
-removed.  You can still use Long Lines mode to gain an approximation
-of word wrapping, though this has some drawbacks---for instance,
-syntax highlighting often doesn't work well on wrapped lines.
-
-@item
-@kbd{C-l} now runs @code{recenter} instead of
-@code{recenter-top-bottom}.  This always sets the current line at the
-center of the window, instead of cycling through the center, top, and
-bottom of the window on successive invocations.  This lets you type
-@kbd{C-l C-l C-l C-l} to be @emph{absolutely sure} that you have
-recentered the line.
-
-@item
-The way Emacs generates possible minibuffer completions is now much
-simpler to understand.  It matches alternatives to the text before
-point, ignoring the text after point; it also does not attempt to
-perform partial completion if the first completion attempt fails.
-
-@item
-Typing @kbd{M-n} at the start of the minibuffer history list no longer
-attempts to generate guesses of possible minibuffer input.  It instead
-does the straightforward thing, by issuing the message @samp{End of
-history; no default available}.
-
-@item
-Individual buffers can no longer display faces specially.  The text
-scaling commands @kbd{C-x C-+}, @kbd{C-x C--}, and @kbd{C-x C-0} have
-been removed, and so has the buffer face menu bound to
-@kbd{S-down-mouse-1}.
-
-@item
-VC no longer supports fileset-based operations on distributed version
-control systems (DVCSs) such as Arch, Bazaar, Subversion, Mercurial,
-and Git.  For instance, multi-file commits will be performed by
-committing one file at a time.  As you go further back in time, we
-will remove DVCS support entirely, so you should migrate your projects
-to CVS.
-
-@item
-Rmail now uses a special file format, Babyl format, specifically designed
-for storing and editing mail.  When you visit a file in Rmail, or get new
-mail, Rmail converts it automatically to Babyl format.
-
-@item
-Emacs can no longer display frames on X windows and text terminals
-(ttys) simultaneously.  If you start Emacs as an X application, it
-can only create X frames; if you start Emacs on a tty, it can only use
-that tty.  No more confusion about which type of frame
-@command{emacsclient} will use in any given Emacs session!
-
-@item
-Emacs can no longer be started as a daemon.  You can be sure that if
-you don't see Emacs, then it's not running.
-
 @item
-Emacs has added support for many soon-to-be-non-obsolete platforms,
-including VMS, DECstation, SCO Unix, and systems lacking alloca.
-Support for Sun windows has been added.
+FIXME
 
 @item
 To keep up with decreasing computer memory capacity and disk space, many
-other functions and files have been eliminated in Emacs 22.3.
+other functions and files have been eliminated in Emacs 23.4.
 @end itemize
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index e7d58c32290..67feb791fe1 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -489,10 +489,20 @@ support a limited range of colors.
 changes for future Emacs sessions.  @xref{Face Customization}.  A face
 does not have to specify every single attribute; often it inherits
 most attributes from another face.  Any ultimately unspecified
-attribute is taken from a face named @code{default}, whose attributes
-are all specified.  The @code{default} face is the default for
-displaying text, and its background color is also used as the frame's
-background color.
+attribute is taken from the face named @code{default}.
+
+  The @code{default} face is the default for displaying text, and all
+of its attributes are specified.  Its background color is also used as
+the frame's background color.
+
+@cindex cursor face
+  Another special face is the @code{cursor} face.  On graphical
+displays, the background color of this face is used to draw the text
+cursor.  None of the other attributes of this face have any effect;
+the foreground color for text under the cursor is taken from the
+background color of the underlying text.  On text terminals, the
+appearance of the text cursor is determined by the terminal, not by
+the @code{cursor} face.
 
   You can also use X resources to specify attributes of any particular
 face.  @xref{Resources}.
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index b00625facbf..1f7fecb8b6a 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -210,7 +210,7 @@ Appendices
 * GNU Free Documentation License:: The license for this documentation.
 * Emacs Invocation::    Hairy startup options.
 * X Resources::         X resources for customizing Emacs.
-* Antinews::            Information about Emacs version 22.
+* Antinews::            Information about Emacs version 23.
 * Mac OS / GNUstep::    Using Emacs under Mac OS and GNUstep.
 * Microsoft Windows::   Using Emacs on Microsoft Windows and MS-DOS.
 * Manifesto::           What's GNU?  Gnu's Not Unix!
@@ -1124,15 +1124,15 @@ X Options and Resources
 
 * Resources::           Using X resources with Emacs (in general).
 * Table of Resources::  Table of specific X resources that affect Emacs.
-* Face Resources::      X resources for customizing faces.
 * Lucid Resources::     X resources for Lucid menus.
 * LessTif Resources::   X resources for LessTif and Motif menus.
 * GTK resources::       Resources for GTK widgets.
 
 GTK resources
 
-* GTK widget names::      How widgets in GTK are named in general.
-* GTK Names in Emacs::    GTK widget names in Emacs.
+* GTK Resource Basics::   Basic usage of GTK+ resources.
+* GTK Widget Names::      How GTK+ widgets are named.
+* GTK Names in Emacs::    GTK+ widgets used by Emacs.
 * GTK styles::            What can be customized in a GTK widget.
 
 Emacs and Mac OS / GNUstep
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 7fef7fb1e22..8ba9b78603a 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -952,7 +952,7 @@ comment text.
 comment on the current line, along with the whitespace before it.
 Since the comment is saved to the kill ring, you can reinsert it on
 another line by moving to the end of that line, doing @kbd{C-y}, and
-then @kbd{M-;} to realign the command.  You can achieve the same
+then @kbd{M-;} to realign the comment.  You can achieve the same
 effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
 (@code{comment-dwim} actually calls @code{comment-kill} as a
 subroutine when it is given a prefix argument).
diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi
index 7a4e4798061..66281d6dbbb 100644
--- a/doc/emacs/xresources.texi
+++ b/doc/emacs/xresources.texi
@@ -6,31 +6,26 @@
 @appendix X Options and Resources
 
   You can customize some X-related aspects of Emacs behavior using X
-resources, as is usual for programs that use X.  On MS-Windows, you
-can customize some of the same aspects using the system registry.
-@xref{MS-Windows Registry}.
-
-  When Emacs is built using an ``X toolkit'', such as Lucid or
-LessTif, you need to use X resources to customize the appearance of
-the widgets, including the menu-bar, scroll-bar, and dialog boxes.
-This is because the libraries that implement these don't provide for
-customization through Emacs.  GTK+ widgets use a separate system of
+resources, as is usual for programs that use X.
+
+  When Emacs is compiled with GTK+ support, the appearance of various
+graphical widgets, such as the menu-bar, scroll-bar, and dialog boxes,
+is determined by
 @ifnottex
 ``GTK resources'', which we will also describe.
 @end ifnottex
 @iftex
-``GTK resources.''  In this chapter we describe the most commonly used
-resource specifications.  For full documentation, see the online
-manual.
-
-@c Add xref for LessTif/Motif menu resources.
+``GTK resources''.
 @end iftex
+When Emacs is built without GTK+ support, the appearance of these
+widgets is determined by additional X resources.
 
+  On MS-Windows, you can customize some of the same aspects using the
+system registry (@pxref{MS-Windows Registry}).
 
 @menu
 * Resources::           Using X resources with Emacs (in general).
 * Table of Resources::  Table of specific X resources that affect Emacs.
-* Face Resources::      X resources for customizing faces.
 * Lucid Resources::     X resources for Lucid menus.
 * LessTif Resources::   X resources for LessTif and Motif menus.
 * GTK resources::       Resources for GTK widgets.
@@ -63,60 +58,41 @@ settings in the Display Control Panel.  You can also set resources
 using the @samp{-xrm} command line option, as explained below.)
 
   Each line in the X resource file specifies a value for one option or
-for a collection of related options.  Each resource specification
+for a collection of related options.  The order in which the lines
+appear in the file does not matter.  Each resource specification
 consists of a @dfn{program name} and a @dfn{resource name}.  Case
 distinctions are significant in each of these names.  Here is an
 example:
 
 @example
-emacs.borderWidth: 2
+emacs.cursorColor: dark green
 @end example
 
-@ifnottex
   The program name is the name of the executable file to which the
 resource applies.  For Emacs, this is normally @samp{emacs}.  To
 specify a definition that applies to all instances of Emacs,
 regardless of the name of the Emacs executable, use @samp{Emacs}.
 
   The resource name is the name of a program setting.  For instance,
-Emacs recognizes a @samp{borderWidth} resource that controls the width
-of the external border for graphical frames.
+Emacs recognizes a @samp{cursorColor} resource that controls the color
+of the text cursor.
 
   Resources are grouped into named classes.  For instance, the
-@samp{BorderWidth} class contains both the @samp{borderWidth} resource
-(which we just described), as well as the @samp{internalBorder}
-resource, which controls the width of the internal border for
-graphical frames.  Instead of using a resource name, you can use a
-class name to specify the same value for all resources in that class.
-Here's an example:
-
-@example
-emacs.BorderWidth: 2
-@end example
-
-  If you specify a value for a class, it becomes the default for all
-resources in that class.  You can specify values for individual
-resources as well; these override the class value, for those
-particular resources.  The following example specifies 2 as the
-default width for all borders, but overrides this value with 4 for the
-external border:
+@samp{Foreground} class contains the @samp{cursorColor},
+@samp{foreground} and @samp{pointerColor} resources (@pxref{Table of
+Resources}).  Instead of using a resource name, you can use a class
+name to specify the default value for all resources in that class,
+like this:
 
 @example
-emacs.BorderWidth: 2
-emacs.borderWidth: 4
+emacs.Foreground: dark green
 @end example
-@end ifnottex
-
-  The order in which the lines appear in the file does not matter.
-One way to experiment with the effect of different resource settings
-is to use the @code{editres} program.  See the @code{editres} man page
-for more details.
 
   Emacs does not process X resources at all if you set the variable
-@code{inhibit-x-resources} to a non-@code{nil} value, or if you
-specify the @samp{-Q} (or @samp{--quick}) command-line argument
-(@pxref{Initial Options}).  (The @samp{-Q} argument automatically sets
-@code{inhibit-x-resources} to @code{t}.)
+@code{inhibit-x-resources} to a non-@code{nil} value.  If you invoke
+Emacs with the @samp{-Q} (or @samp{--quick}) command-line option,
+@code{inhibit-x-resources} is automatically set to @code{t}
+(@pxref{Initial Options}).
 
 @ifnottex
   In addition, you can use the following command-line options to
@@ -162,98 +138,93 @@ other resource specifications.
 @node Table of Resources
 @appendixsec Table of X Resources for Emacs
 
-  This table lists the resource names that designate options for
-Emacs, not counting those for the appearance of the menu bar, each
-with the class that it belongs to:
+  This table lists the X resource names that Emacs recognizes,
+excluding those that control the appearance of graphical widgets like
+the menu bar:
 
 @table @asis
 @item @code{background} (class @code{Background})
-Background color name.
+Background color (@pxref{Colors}).
 
 @item @code{bitmapIcon} (class @code{BitmapIcon})
 Tell the window manager to display the Emacs icon if @samp{on}; don't
-do so if @samp{off}.  (The icon is usually shown in the ``taskbar'' on
-a graphical desktop.)
+do so if @samp{off}.  @xref{Icons X}, for a description of the icon.
 
+@ifnottex
 @item @code{borderColor} (class @code{BorderColor})
-Color name for the external border.
+Color of the frame's external border.  This has no effect if Emacs is
+compiled with GTK+ support.
 
-@ifnottex
 @item @code{borderWidth} (class @code{BorderWidth})
-Width in pixels of the external border.
+Width of the frame's external border, in pixels.  This has no effect
+if Emacs is compiled with GTK+ support.
 @end ifnottex
 
 @item @code{cursorColor} (class @code{Foreground})
-Color name for text cursor (point).
+Text cursor color.  If this resource is specified when Emacs starts
+up, Emacs sets its value as the background color of the @code{cursor}
+face (@pxref{Faces}).
 
-@ifnottex
 @item @code{cursorBlink} (class @code{CursorBlink})
-Specifies whether to make the cursor blink. The default is @samp{on}.  Use
-@samp{off} or @samp{false} to turn cursor blinking off.
-@end ifnottex
+If the value of this resource is @samp{off} or @samp{false} or
+@samp{0} at startup, Emacs disables Blink Cursor mode (@pxref{Cursor
+Display}).
 
 @item @code{font} (class @code{Font})
-Font name for the @code{default} font.  @xref{Fonts}.  You can also
+Font name for the @code{default} face (@pxref{Fonts}).  You can also
 specify a fontset name (@pxref{Fontsets}).
 
 @item @code{fontBackend} (class @code{FontBackend})
-The backend(s) to use for drawing fonts; if multiple backends are
-specified, they must be comma-delimited and given in order of
-precedence.  On X, for instance, the value @samp{x,xft} tells Emacs to
+Comma-delimited list of backend(s) to use for drawing fonts, in order
+of precedence.  For instance, the value @samp{x,xft} tells Emacs to
 draw fonts using the X core font driver, falling back on the Xft font
-driver if that fails.  Normally, you can leave this resource unset, in
-which case Emacs tries using all font backends available on your
-graphical device.
+driver if that fails.  Normally, you should leave this resource unset,
+in which case Emacs tries using all available font backends.
 
 @item @code{foreground} (class @code{Foreground})
-Color name for text.
+Default foreground color for text.
 
 @item @code{geometry} (class @code{Geometry})
-Window size and position.  Be careful not to specify this resource as
-@samp{emacs*geometry}, because that may affect individual menus as well
-as the Emacs frame itself.
+Window size and position.  The value should be a size and position
+specification, of the same form as in the @samp{-g} or
+@samp{--geometry} command-line option (@pxref{Window Size X}).
 
-If this resource specifies a position, that position applies only to the
-initial Emacs frame (or, in the case of a resource for a specific frame
-name, only that frame).  However, the size, if specified here, applies to
-all frames.
+The size applies to all frames in the Emacs session, but the position
+applies only to the initial Emacs frame (or, in the case of a resource
+for a specific frame name, only that frame).
+
+
+Be careful not to specify this resource as @samp{emacs*geometry}, as
+that may affect individual menus as well as the main Emacs frame.
 
-@ifnottex
 @item @code{fullscreen} (class @code{Fullscreen})
 The desired fullscreen size.  The value can be one of @code{fullboth},
-@code{maximized}, @code{fullwidth} or @code{fullheight}, which correspond to
-the command-line options @samp{-fs}, @samp{-mm}, @samp{-fw}, and @samp{-fh}
-(@pxref{Window Size X}).
-
-Note that this applies to the initial frame only.
-@end ifnottex
+@code{maximized}, @code{fullwidth} or @code{fullheight}, which
+correspond to the command-line options @samp{-fs}, @samp{-mm},
+@samp{-fw}, and @samp{-fh} (@pxref{Window Size X}).  Note that this
+applies to the initial frame only.
 
+@ifnottex
 @item @code{iconName} (class @code{Title})
 Name to display in the icon.
 
 @item @code{internalBorder} (class @code{BorderWidth})
-Width in pixels of the internal border.
+Width of the internal frame border, in pixels.
+@end ifnottex
 
 @item @code{lineSpacing} (class @code{LineSpacing})
 @cindex line spacing
-@cindex leading
-Additional space (@dfn{leading}) between lines, in pixels.
+Additional space between lines, in pixels.
 
 @item @code{menuBar} (class @code{MenuBar})
 @cindex menu bar
-Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
-@ifnottex
-@xref{Lucid Resources}, and @ref{LessTif Resources},
-@end ifnottex
-@iftex
-@xref{Lucid Resources},
-@end iftex
-for how to control the appearance of the menu bar if you have one.
+If the value of this resource is @samp{off} or @samp{false} or
+@samp{0}, Emacs disables Menu Bar mode at startup (@pxref{Menu Bars}).
 
 @ifnottex
 @item @code{minibuffer} (class @code{Minibuffer})
-If @samp{none}, don't make a minibuffer in this frame.
-It will use a separate minibuffer frame instead.
+If @samp{none}, Emacs will not make a minibuffer in this frame; it
+will use a separate minibuffer frame instead.
 
 @item @code{paneFont} (class @code{Font})
 @cindex font for menus
@@ -261,7 +232,9 @@ Font name for menu pane titles, in non-toolkit versions of Emacs.
 @end ifnottex
 
 @item @code{pointerColor} (class @code{Foreground})
-Color of the mouse cursor.
+Color of the mouse cursor.  This has no effect in many graphical
+desktop environments, as they do not let Emacs change the mouse cursor
+this way.
 
 @ifnottex
 @item @code{privateColormap} (class @code{PrivateColormap})
@@ -271,7 +244,6 @@ visual'' of class PseudoColor and Emacs is using it.
 @item @code{reverseVideo} (class @code{ReverseVideo})
 Switch foreground and background default colors if @samp{on}, use colors as
 specified if @samp{off}.
-@end ifnottex
 
 @item @code{screenGamma} (class @code{ScreenGamma})
 @cindex gamma correction
@@ -281,7 +253,9 @@ Gamma correction for colors, equivalent to the frame parameter
 @item @code{scrollBarWidth} (class @code{ScrollBarWidth})
 @cindex scrollbar width
 The scroll bar width in pixels, equivalent to the frame parameter
-@code{scroll-bar-width}.
+@code{scroll-bar-width}.  Do not set this resource if Emacs is
+compiled with GTK+ support.
+@end ifnottex
 
 @ifnottex
 @item @code{selectionFont} (class @code{SelectionFont})
@@ -306,24 +280,16 @@ Name to display in the title bar of the initial Emacs frame.
 
 @item @code{toolBar} (class @code{ToolBar})
 @cindex tool bar
-Number of lines to reserve for the tool bar.  A zero value suppresses
-the tool bar.  For the Emacs tool bar (i.e.@: not Gtk+), if the value
-is non-zero and @code{auto-resize-tool-bars} is non-@code{nil}, the
-tool bar's size will be changed automatically so that all tool bar
-items are visible.  If the value of @code{auto-resize-tool-bars} is
-@code{grow-only}, the tool bar expands automatically, but does not
-contract automatically.  To contract the tool bar, you must redraw the
-frame by entering @kbd{C-l}.  For the Gtk+ tool bar, any non-zero
-value means on and @code{auto-resize-tool-bars} has no effect.
+If the value of this resource is @samp{off} or @samp{false} or
+@samp{0}, Emacs disables Tool Bar mode at startup (@pxref{Tool Bars}).
 
 @item @code{useXIM} (class @code{UseXIM})
 @cindex XIM
 @cindex X input methods
 @cindex input methods, X
-Turn off use of X input methods (XIM) if @samp{false} or @samp{off}.
-This is only relevant if your Emacs is actually built with XIM
-support.  It is potentially useful to turn off XIM for efficiency,
-especially slow X client/server links.
+Disable use of X input methods (XIM) if @samp{false} or @samp{off}.
+This is only relevant if your Emacs is built with XIM support.  It
+might be useful to turn off XIM on slow X client/server links.
 
 @item @code{verticalScrollBars} (class @code{ScrollBars})
 Give frames scroll bars if @samp{on}; don't have scroll bars if
@@ -331,143 +297,51 @@ Give frames scroll bars if @samp{on}; don't have scroll bars if
 
 @ifnottex
 @item @code{visualClass} (class @code{VisualClass})
-Specify the ``visual'' that X should use.  This tells X how to handle
-colors.
-
-The value should start with one of @samp{TrueColor},
-@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor},
-@samp{GrayScale}, and @samp{StaticGray}, followed by
-@samp{-@var{depth}}, where @var{depth} is the number of color planes.
-Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo}
-program outputs information saying which ones.
+The @dfn{visual class} for X color display.  If specified, the value
+should start with one of @samp{TrueColor}, @samp{PseudoColor},
+@samp{DirectColor}, @samp{StaticColor}, @samp{GrayScale}, and
+@samp{StaticGray}, followed by @samp{-@var{depth}}, where @var{depth}
+is the number of color planes.
 @end ifnottex
 @end table
 
-@node Face Resources
-@appendixsec X Resources for Faces
-
-  You can use resources to customize the appearance of particular
-faces (@pxref{Faces}):
-
-@table @code
-@item @var{face}.attributeForeground
-Foreground color for face @var{face}.
-@item @var{face}.attributeBackground
-Background color for face @var{face}.
-@item @var{face}.attributeUnderline
-Underline flag for face @var{face}.  Use @samp{on} or @samp{true} for
-yes.
-@item @var{face}.attributeStrikeThrough
-@itemx @var{face}.attributeOverline
-@itemx @var{face}.attributeBox
-@itemx @var{face}.attributeInverse
-Likewise, for other boolean font attributes.
-@item @var{face}.attributeStipple
-The name of a pixmap data file to use for the stipple pattern, or
-@code{false} to not use stipple for the face @var{face}.
-@item @var{face}.attributeBackgroundPixmap
-The background pixmap for the face @var{face}.  Should be a name of a
-pixmap file or @code{false}.
-@item @var{face}.attributeFont
-Font name (full XFD name or valid X abbreviation) for face @var{face}.
-Instead of this, you can specify the font through separate attributes.
-@end table
-
-  Instead of using @code{attributeFont} to specify a font name, you can
-select a font through these separate attributes:
-
-@table @code
-@item @var{face}.attributeFamily
-Font family for face @var{face}.
-@item @var{face}.attributeHeight
-Height of the font to use for face @var{face}: either an integer
-specifying the height in units of 1/10@dmn{pt}, or a floating point
-number that specifies a scale factor to scale the underlying face's
-default font, or a function to be called with the default height which
-will return a new height.
-@item @var{face}.attributeWidth
-@itemx @var{face}.attributeWeight
-@itemx @var{face}.attributeSlant
-Each of these resources corresponds to a like-named font attribute,
-and you write the resource value the same as the symbol you would use
-for the font attribute value.
-@item @var{face}.attributeBold
-Bold flag for face @var{face}---instead of @code{attributeWeight}.  Use @samp{on} or @samp{true} for
-yes.
-@item @var{face}.attributeItalic
-Italic flag for face @var{face}---instead of @code{attributeSlant}.
-@end table
+  You can also use X resources to customize individual Emacs faces
+(@pxref{Faces}).  For example, setting the resource
+@samp{@var{face}.attributeForeground} is equivalent to customizing the
+@samp{foreground} attribute of the face @var{face}.  However, we
+recommend customizing faces from within Emacs, instead of using X
+resources.  @xref{Face Customization}.
 
+@ifnottex
 @node Lucid Resources
 @appendixsec Lucid Menu And Dialog X Resources
 @cindex Menu X Resources (Lucid widgets)
 @cindex Dialog X Resources (Lucid widgets)
 @cindex Lucid Widget X Resources
 
-@ifnottex
-  If the Emacs installed at your site was built to use the X toolkit
-with the Lucid menu widgets, then the menu bar is a separate widget and
-has its own resources.  The resource names contain @samp{pane.menubar}
-(following, as always, the name of the Emacs invocation, or @samp{Emacs},
-which stands for all Emacs invocations).  Specify them like this:
-
-@example
-Emacs.pane.menubar.@var{resource}:  @var{value}
-@end example
-
-@noindent
-For example, to specify the font @samp{Courier-12} for the menu-bar items,
-write this:
-@end ifnottex
-@iftex
-   If the Emacs installed at your site was built to use the X toolkit
-with the Lucid menu widgets, then the menu bar is a separate widget
-and has its own resources.  The resource specifications start with
-@samp{Emacs.pane.menubar}---for instance, to specify the font
-@samp{Courier-12} for the menu-bar items, write this:
-@end iftex
+  If Emacs is compiled with the X toolkit support using Lucid widgets,
+you can use X resources to customize the appearance of the menu bar,
+pop-up menus, and dialog boxes.  The resources for the menu bar fall
+in the @samp{pane.menubar} class (following, as always, either the
+name of the Emacs executable or @samp{Emacs} for all Emacs
+invocations).  The resources for the pop-up menu are in the
+@samp{menu*} class.  The resources for dialog boxes are in the
+@samp{dialog*} class.
 
-@example
-Emacs.pane.menubar.font:  Courier-12
-@end example
-
-@noindent
-To specify a font, use fontconfig font names as values to the @code{font}
-resource, or old style names:
+  For example, to display menu bar entries with the @samp{Courier-12}
+font (@pxref{Fonts}), write this:
 
 @example
-Emacs.pane.menubar.font: lucidasanstypewriter-10
+Emacs.pane.menubar.font: Courier-12
 @end example
 
 @noindent
-Emacs first tries to open the font as an old style font, and if that fails
-as an fontconfig font.  In rare cases, Emacs might do the wrong thing.
-
-@noindent
-The Lucid menus can display multilingual text in your locale with old style
-fonts.  For more information about fontsets see the man page for
-@code{XCreateFontSet}.  To enable multilingual menu text you specify a
-@code{fontSet} resource instead of the font resource.  If both
-@code{font} and @code{fontSet} resources are specified, the
-@code{fontSet} resource is used.
+Lucid widgets can display multilingual text in your locale.  To enable
+this, specify a @code{fontSet} resource instead of a @code{font}
+resource.  @xref{Fontsets}.  If both @code{font} and @code{fontSet}
+resources are specified, the @code{fontSet} resource is used.
 
-@noindent
-Resources for @emph{non-menubar} toolkit pop-up menus have
-@samp{menu*} instead of @samp{pane.menubar}.  For example, to specify
-the font @samp{8x16} for the pop-up menu items, write this:
-
-@example
-Emacs.menu*.font:       8x16
-@end example
-
-@noindent
-For dialog boxes, use @samp{dialog*}:
-
-@example
-Emacs.dialog*.font: Sans-12
-@end example
-
-  Here is a list of the specific resources for menu bars and pop-up menus:
+Here is a list of resources for menu bars, pop-up menus, and dialogs:
 
 @table @code
 @item font
@@ -475,11 +349,11 @@ Font for menu item text.
 @item fontSet
 Fontset for menu item text.
 @item foreground
-Color of the foreground.
+Foreground color.
 @item background
-Color of the background.
+Background color.
 @item buttonForeground
-In the menu bar, the color of the foreground for a selected item.
+Foreground color for a selected item.
 @ifnottex
 @item horizontalSpacing
 Horizontal spacing in pixels between items.  Default is 3.
@@ -489,59 +363,51 @@ Vertical spacing in pixels between items.  Default is 2.
 Horizontal spacing between the arrow (which indicates a submenu) and
 the associated text.  Default is 10.
 @item shadowThickness
-Thickness of shadow line around the widget.  Default is 1.
-
-Also determines the thickness of shadow lines around other objects,
-for instance 3D buttons and arrows.  If you have the impression that
-the arrows in the menus do not stand out clearly enough or that the
-difference between ``in'' and ``out'' buttons is difficult to see, set
-this to 2.  If you have no problems with visibility, the default
-probably looks better.  The background color may also have some effect
-on the contrast.
+Thickness of shadow lines for 3D buttons, arrows, and other graphical
+elements.  Default is 1.
 @end ifnottex
 @item margin
-The margin of the menu bar, in characters.  Default is 1.
+Margin of the menu bar, in characters.  Default is 1.
 @end table
 
-@ifnottex
 @node LessTif Resources
 @appendixsec LessTif Menu X Resources
 @cindex Menu X Resources (LessTif widgets)
 @cindex LessTif Widget X Resources
 
-  If the Emacs installed at your site was built to use the X toolkit
-with the LessTif or Motif widgets, then the menu bar, the dialog
-boxes, the pop-up menus, and the file-selection box are separate
-widgets and have their own resources.
+  If Emacs is compiled with the X toolkit support using LessTif or
+Motif widgets, you can use X resources to customize the appearance of
+the menu bar, pop-up menus, and dialog boxes.  However, the resources
+are organized differently from Lucid widgets.
 
-  The resource names for the menu bar contain @samp{pane.menubar}
-(following, as always, the name of the Emacs invocation, or
-@samp{Emacs}, which stands for all Emacs invocations).  Specify them
-like this:
+  The resource names for the menu bar are in the @samp{pane.menubar}
+class, and they must be specified in this form:
 
 @smallexample
 Emacs.pane.menubar.@var{subwidget}.@var{resource}:  @var{value}
 @end smallexample
 
-  Each individual string in the menu bar is a subwidget; the subwidget's
-name is the same as the menu item string.  For example, the word
-@samp{File} in the menu bar is part of a subwidget named
-@samp{emacs.pane.menubar.File}.  Most likely, you want to specify the
-same resources for the whole menu bar.  To do this, use @samp{*} instead
-of a specific subwidget name.  For example, to specify the font
-@samp{8x16} for the menu-bar items, write this:
+@noindent
+For pop-up menus, the resources are in the @samp{menu*} class, instead
+of @samp{pane.menubar}.  For dialog boxes, they are in @samp{dialog}.
+In each case, each individual menu string is a subwidget; the
+subwidget's name is the same as the menu item string.  For example,
+the @samp{File} menu in the menu bar is a subwidget named
+@samp{emacs.pane.menubar.File}.
+
+  Typically, you want to specify the same resources for the whole menu
+bar.  To do this, use @samp{*} instead of a specific subwidget name.
+For example, to specify the font @samp{8x16} for all menu bar items,
+including submenus, write this:
 
 @smallexample
 Emacs.pane.menubar.*.fontList:  8x16
 @end smallexample
 
-@noindent
-This also specifies the resource value for submenus.
-
-  Each item in a submenu in the menu bar also has its own name for X
-resources; for example, the @samp{File} submenu has an item named
-@samp{Save (current buffer)}.  A resource specification for a submenu
-item looks like this:
+  Each item in a submenu also has its own name for X resources; for
+example, the @samp{File} submenu has an item named @samp{Save (current
+buffer)}.  A resource specification for a submenu item looks like
+this:
 
 @smallexample
 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
@@ -574,46 +440,23 @@ Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value}
 @noindent
 (This should be one long line.)
 
-  It's impossible to specify a resource for all the menu-bar items
-without also specifying it for the submenus as well.  So if you want the
-submenu items to look different from the menu bar itself, you must ask
-for that in two steps.  First, specify the resource for all of them;
-then, override the value for submenus alone.  Here is an example:
+  If you want the submenu items to look different from the menu bar
+itself, you must first specify the resource for all of them, then
+override the value for submenus alone.  Here is an example:
 
 @smallexample
 Emacs.pane.menubar.*.fontList:  8x16
 Emacs.pane.menubar.popup_*.fontList: 8x16
 @end smallexample
 
-@noindent
-For LessTif pop-up menus, use @samp{menu*} instead of
-@samp{pane.menubar}.  For example, to specify the font @samp{8x16} for
-the pop-up menu items, write this:
-
-@smallexample
-Emacs.menu*.fontList:  8x16
-@end smallexample
-
-@noindent
-For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}:
-
-@example
-Emacs.dialog*.fontList: 8x16
-Emacs.dialog*.foreground: hotpink
-@end example
-
-To specify resources for the LessTif file-selection box, use
+  To specify resources for the LessTif file-selection box, use
 @samp{fsb*}, like this:
 
 @example
 Emacs.fsb*.fontList: 8x16
 @end example
 
-@iftex
-@medbreak
-@end iftex
-  Here is a list of the specific resources for LessTif menu bars and
-pop-up menus:
+  Here is a list of resources for LessTif menu bars and pop-up menus:
 
 @table @code
 @item armColor
@@ -638,128 +481,92 @@ The color for the border shadow, on the top and the left.
 @end table
 @end ifnottex
 
-
 @node GTK resources
 @appendixsec GTK resources
-@iftex
-  The most common way to customize the GTK widgets Emacs uses (menus,
-dialogs tool bars and scroll bars) is by choosing an appropriate
-theme, for example with the GNOME theme selector.
-
-You can also do Emacs specific customization by inserting GTK style
-directives in the file @file{~/.emacs.d/gtkrc}, but only if you have a
-Gtk+ version earlier than 3 (i.e.@: 2).  Some GTK themes ignore
-customizations in @file{~/.emacs.d/gtkrc} so not everything works with
-all themes.  To customize Emacs font, background, faces, etc., use the
-normal X resources (@pxref{Resources}).  We will present some examples
-of customizations here, but for a more detailed description, see the
-online manual
-
-  The first example is just one line.  It changes the font on all GTK widgets
-to courier with size 12:
-
-@smallexample
-gtk-font-name = "courier 12"
-@end smallexample
-
-  The thing to note is that the font name is not an X font name, but a
-Pango font name.  A Pango font name is basically of the format "family
-style size", where the style is optional as in the case above.  A name
-with a style could be for example:
+@cindex GTK+ resources
+@cindex resource files for GTK
+@cindex @file{~/.gtkrc-2.0} file
+@cindex @file{~/.emacs.d/gtkrc} file
 
-@smallexample
-gtk-font-name = "helvetica bold 10"
-@end smallexample
+  If Emacs is compiled with GTK+ toolkit support, the simplest way to
+customize its GTK+ widgets (e.g.@: menus, dialogs, tool bars and
+scroll bars) is to choose an appropriate GTK+ theme, for example with
+the GNOME theme selector.
+
+  In GTK+ version 2, you can also use @dfn{GTK+ resources} to
+customize the appearance of GTK+ widgets used by Emacs.  These
+resources are specified in either the file @file{~/.emacs.d/gtkrc}
+(for Emacs-specific GTK+ resources), or @file{~/.gtkrc-2.0} (for
+general GTK+ resources).  We recommend using @file{~/.emacs.d/gtkrc},
+since GTK+ seems to ignore @file{~/.gtkrc-2.0} when running GConf with
+GNOME.  Note, however, that some GTK themes may override
+customizations in @file{~/.emacs.d/gtkrc}; there is nothing we can do
+about this.  GTK+ resources do not affect aspects of Emacs unrelated
+to GTK+ widgets, such as fonts and colors in the main Emacs window;
+those are governed by normal X resources (@pxref{Resources}).
+
+  The following sections describe how to customize GTK+ resources for
+Emacs.  For details about GTK+ resources, see the GTK+ API document at
+@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
 
-  To customize widgets you first define a style and then apply the style to
-the widgets.  Here is an example that sets the font for menus, but not
-for other widgets:
+  In GTK+ version 3, GTK+ resources have been replaced by a completely
+different system.  The appearance of GTK+ widgets is now determined by
+CSS-like style files: @file{gtk-3.0/gtk.css} in the GTK+ installation
+directory, and @file{~/.themes/@var{theme}/gtk-3.0/gtk.css} for local
+style settings (where @var{theme} is the name of the current GTK+
+theme).  Therefore, the description of GTK+ resources in this section
+does not apply to GTK+ 3.  For details about the GTK+ 3 styling
+system, see
+@uref{http://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}.
 
-@smallexample
-# @r{Define the style @samp{menufont}.}
-style "menufont"
-@{
-  font_name = "helvetica bold 14"  # This is a Pango font name
-@}
+@menu
+* GTK Resource Basics::   Basic usage of GTK+ resources.
+* GTK Widget Names::      How GTK+ widgets are named.
+* GTK Names in Emacs::    GTK widgets used by Emacs.
+* GTK styles::            What can be customized in a GTK widget.
+@end menu
 
-# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
-widget "*emacs-menuitem*" style "menufont"
-@end smallexample
+@node GTK Resource Basics
+@appendixsubsec GTK Resource Basics
 
-The widget name in this example contains wildcards, so the style will be
-applied to all widgets that match "*emacs-menuitem*".  The widgets are
-named by the way they are contained, from the outer widget to the inner widget.
-So to apply the style "my_style" (not shown) with the full, absolute name, for
-the menubar and the scroll bar in Emacs we use:
+  In a GTK+ 2 resource file (usually @file{~/.emacs.d/gtkrc}), the
+simplest kinds of resource settings simply assign a value to a
+variable.  For example, putting the following line in the resource
+file changes the font on all GTK+ widgets to @samp{courier-12}:
 
 @smallexample
-widget "Emacs.pane.menubar" style "my_style"
-widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
+gtk-font-name = "courier 12"
 @end smallexample
 
-But to avoid having to type it all, wildcards are often used.  @samp{*}
-matches zero or more characters and @samp{?} matches one character.  So "*"
-matches all widgets.
+@noindent
+Note that in this case the font name must be supplied as a GTK font
+pattern (also called a @dfn{Pango font name}), not as a
+Fontconfig-style font name or XLFD.  @xref{Fonts}.
 
-  Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem).
-You can assign styles by name or by class.  In this example we have used the
-class:
+  To customize widgets you first define a @dfn{style}, and then apply
+the style to the widgets.  Here is an example that sets the font for
+menus (@samp{#} characters indicate comments):
 
 @smallexample
-style "menufont"
+# @r{Define the style @samp{my_style}.}
+style "my_style"
 @{
   font_name = "helvetica bold 14"
 @}
 
-widget_class "*GtkMenuBar" style "menufont"
+# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{my_style}.}
+widget "*emacs-menuitem*" style "my_style"
 @end smallexample
 
 @noindent
-The names and classes for the GTK widgets Emacs uses are:
-
-@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
-@item @code{emacs-filedialog}
-@tab @code{GtkFileSelection}
-@item @code{emacs-dialog}
-@tab @code{GtkDialog}
-@item @code{Emacs}
-@tab @code{GtkWindow}
-@item @code{pane}
-@tab @code{GtkVHbox}
-@item @code{emacs}
-@tab @code{GtkFixed}
-@item @code{verticalScrollBar}
-@tab @code{GtkVScrollbar}
-@item @code{emacs-toolbar}
-@tab @code{GtkToolbar}
-@item @code{menubar}
-@tab @code{GtkMenuBar}
-@item @code{emacs-menuitem}
-@tab anything in menus
-@end multitable
-
-  GTK absolute names are quite strange when it comes to menus
-and dialogs.  The names do not start with @samp{Emacs}, as they are
-free-standing windows and not contained (in the GTK sense) by the
-Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:
-
-@smallexample
-widget "*emacs-dialog*" style "my_dialog_style"
-widget "*emacs-filedialog* style "my_file_style"
-widget "*emacs-menuitem* style "my_menu_style"
-@end smallexample
-
-  If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
-automatically applies only to Emacs, since other programs don't read
-that file.  For example, the drop down menu in the file dialog can not
-be customized by any absolute widget name, only by an absolute class
-name.  This is because the widgets in the drop down menu do not
-have names and the menu is not contained in the Emacs GtkWindow.  To
-have all menus in Emacs look the same, use this in
-@file{~/.emacs.d/gtkrc}:
+The widget name in this example contains wildcards, so the style is
+applied to all widgets matching @samp{*emacs-menuitem*}.  The widgets
+are named by the way they are contained, from the outer widget to the
+inner widget.  Here is another example that applies @samp{my_style}
+specifically to the Emacs menu bar:
 
 @smallexample
-widget_class "*Menu*" style "my_menu_style"
+widget "Emacs.pane.menubar.*" style "my_style"
 @end smallexample
 
   Here is a more elaborate example, showing how to change the parts of
@@ -768,97 +575,24 @@ the scroll bar:
 @smallexample
 style "scroll"
 @{
-  fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
-  bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
-  bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
-  bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
+  fg[NORMAL] = "red"@ @ @ @ @ # @r{Arrow color.}
+  bg[NORMAL] = "yellow"@ @ # @r{Thumb and background around arrow.}
+  bg[ACTIVE] = "blue"@ @ @ @ # @r{Trough color.}
+  bg[PRELIGHT] = "white"@ # @r{Thumb color when the mouse is over it.}
 @}
 
 widget "*verticalScrollBar*" style "scroll"
 @end smallexample
-@end iftex
-
-@ifnottex
-@cindex GTK resources and customization
-@cindex resource files for GTK
-@cindex @file{~/.gtkrc-2.0} file
-@cindex @file{~/.emacs.d/gtkrc} file
-
-  If Emacs was built to use the GTK widget set, then the menu bar, tool bar,
-scroll bar and the dialogs are customized with the standard GTK
-customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific
-file @file{~/.emacs.d/gtkrc}.  We recommend that you use
-@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0}
-seems to be ignored when running GConf with GNOME.  These files apply
-only to GTK widget features.  To customize Emacs font, background,
-faces, etc., use the normal X resources (@pxref{Resources}).
-
-  Some GTK themes override these mechanisms, which means that using
-these mechanisms will not work to customize them.
-
-  In these files you first define a style and say what it means; then
-you specify to apply the style to various widget types (@pxref{GTK
-widget names}).  Here is an example of how to change the font for
-Emacs menus:
-
-@smallexample
-# @r{Define the style @samp{menufont}.}
-style "menufont"
-@{
-  font_name = "helvetica bold 14"  # This is a Pango font name
-@}
-
-# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
-widget "*emacs-menuitem*" style "menufont"
-@end smallexample
-
-  Here is a more elaborate example, showing how to change the parts of
-the scroll bar:
-
-@smallexample
-style "scroll"
-@{
-  fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
-  bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
-  bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
-  bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
-@}
 
-widget "*verticalScrollBar*" style "scroll"
-@end smallexample
-
-  There are also parameters that affect GTK as a whole.  For example,
-the property @code{gtk-font-name} sets the default font for GTK.  You
-must use Pango font names (@pxref{GTK styles}).  A GTK resources file
-that just sets a default font looks like this:
-
-@smallexample
-gtk-font-name = "courier 12"
-@end smallexample
-
-  The GTK resources file is fully described in the GTK API document.
-This can be found in
-@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html},
-where @file{prefix} is the directory in which the GTK libraries were
-installed (usually @file{/usr} or @file{/usr/local}).  You can also
-find the document online, at
-@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
-
-@menu
-* GTK widget names::      How widgets in GTK are named in general.
-* GTK Names in Emacs::    GTK widget names in Emacs.
-* GTK styles::            What can be customized in a GTK widget.
-@end menu
-
-@node GTK widget names
+@node GTK Widget Names
 @appendixsubsec GTK widget names
 @cindex GTK widget names
 
-  A GTK widget is specified by its @dfn{widget class} and
-@dfn{widget name}.  The widget class is the type of the widget: for
-example, @code{GtkMenuBar}.  The widget name is the name given to a
-specific widget.  A widget always has a class, but need not have a
-name.
+  A GTK+ widget is specified by a @dfn{widget name} and a @dfn{widget
+class}.  The widget name refers to a specific widget
+(e.g.@: @samp{emacs-menuitem}), while the widget class refers to a
+collection of similar widgets (e.g.@: @samp{GtkMenuItem}).  A widget
+always has a class, but need not have a name.
 
   @dfn{Absolute names} are sequences of widget names or widget
 classes, corresponding to hierarchies of widgets embedded within
@@ -868,55 +602,31 @@ a @code{GtkMenuBar} called @code{menubar}, the absolute class name
 of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and
 its absolute widget name is @code{top.box.menubar}.
 
-  When assigning a style to a widget, you can use the absolute class
-name or the absolute widget name.
-
-  There are two commands to specify changes for widgets:
+  GTK+ resource files can contain two types of commands for specifying
+widget appearances:
 
-@table @asis
-@item @code{widget_class}
-specifies a style for widgets based on the absolute class name.
+@table @code
+@item widget
+specifies a style for widgets based on the class name, or just the
+class.
 
-@item @code{widget}
-specifies a style for widgets based on the absolute class name,
-or just the class.
+@item widget_class
+specifies a style for widgets based on the class name.
 @end table
 
 @noindent
-You must specify the class and the style in double-quotes, and put
-these commands at the top level in the GTK customization file, like
-this:
+See the previous subsection for examples of using the @code{widget}
+command; the @code{widget_class} command is used similarly.  Note that
+the widget name/class and the style must be enclosed in double-quotes,
+and these commands must be at the top level in the GTK+ resource file.
 
-@smallexample
-style "menufont"
-@{
-  font_name = "helvetica bold 14"
-@}
-
-widget "top.box.menubar" style "menufont"
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont"
-@end smallexample
-
-  Matching of absolute names uses shell wildcard syntax: @samp{*}
-matches zero or more characters and @samp{?} matches one character.
-This example assigns @code{base_style} to all widgets:
+  As previously noted, you may specify a widget name or class with
+shell wildcard syntax: @samp{*} matches zero or more characters and
+@samp{?} matches one character.  This example assigns a style to all
+widgets:
 
 @smallexample
-widget "*" style "base_style"
-@end smallexample
-
-  Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar}
-and the corresponding absolute widget name @code{top.box.menubar}, all
-these examples specify @code{my_style} for the menu bar:
-
-@smallexample
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
-widget_class "GtkWindow.*.GtkMenuBar" style "my_style"
-widget_class "*GtkMenuBar" style "my_style"
-widget "top.box.menubar" style "my_style"
-widget "*box*menubar" style "my_style"
-widget "*menubar" style "my_style"
-widget "*menu*" style "my_style"
+widget "*" style "my_style"
 @end smallexample
 
 @node GTK Names in Emacs
@@ -924,68 +634,52 @@ widget "*menu*" style "my_style"
 @cindex GTK widget names
 @cindex GTK widget classes
 
-  In Emacs, the top level widget for a frame is a @code{GtkWindow}
-that contains a @code{GtkVBox}.  The @code{GtkVBox} contains the
-@code{GtkMenuBar} and a @code{GtkFixed} widget.  The vertical scroll
-bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed}
-widget.  The text you write in Emacs is drawn in the @code{GtkFixed}
-widget.
+  The GTK+ widgets used by an Emacs frame are listed below:
 
-  Dialogs in Emacs are @code{GtkDialog} widgets.  The file dialog is a
-@code{GtkFileSelection} widget.
+@table @asis
+@item @code{Emacs} (class @code{GtkWindow})
+@table @asis
+@item @code{pane} (class @code{GtkVBox})
+@table @asis
+@item @code{menubar} (class @code{GtkMenuBar})
+@table @asis
+@item [menu item widgets]
+@end table
+@item [unnamed widget] (class @code{GtkHandleBox})
+@table @asis
+@item @code{emacs-toolbar} (class @code{GtkToolbar})
+@table @asis
+@item [tool bar item widgets]
+@end table
+@end table
+@item @code{emacs} (class @code{GtkFixed})
+@table @asis
+@item @code{verticalScrollBar} (class @code{GtkVScrollbar})
+@end table
+@end table
+@end table
+@end table
 
 @noindent
-To set a style for the menu bar using the absolute class name, use:
+The contents of Emacs windows are drawn in the @code{emacs} widget.
+Note that even if there are multiple Emacs windows, each scroll bar
+widget is named @code{verticalScrollBar}.
 
-@smallexample
-widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
-@end smallexample
-
-@noindent
-For the scroll bar, the absolute class name is:
+  For example, here are two different ways to set the menu bar style:
 
 @smallexample
-widget_class
-  "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar"
-     style "my_style"
+widget "Emacs.pane.menubar.*" style "my_style"
+widget_class "GtkWindow.GtkVBox.GtkMenuBar.*" style "my_style"
 @end smallexample
 
-@noindent
-The names for the emacs widgets, and their classes, are:
-
-@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
-@item @code{emacs-filedialog}
-@tab @code{GtkFileSelection}
-@item @code{emacs-dialog}
-@tab @code{GtkDialog}
-@item @code{Emacs}
-@tab @code{GtkWindow}
-@item @code{pane}
-@tab @code{GtkVHbox}
-@item @code{emacs}
-@tab @code{GtkFixed}
-@item @code{verticalScrollBar}
-@tab @code{GtkVScrollbar}
-@item @code{emacs-toolbar}
-@tab @code{GtkToolbar}
-@item @code{menubar}
-@tab @code{GtkMenuBar}
-@item @code{emacs-menuitem}
-@tab anything in menus
-@end multitable
-
-@noindent
-Thus, for Emacs you can write the two examples above as:
-
-@smallexample
-widget "Emacs.pane.menubar" style "my_style"
-widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
-@end smallexample
+  For GTK+ dialogs, Emacs uses a widget named @code{emacs-dialog}, of
+class @code{GtkDialog}.  For file selection, Emacs uses a widget named
+@code{emacs-filedialog}, of class @code{GtkFileSelection}.
 
-  GTK absolute names are quite strange when it comes to menus
-and dialogs.  The names do not start with @samp{Emacs}, as they are
-free-standing windows and not contained (in the GTK sense) by the
-Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:
+  Because the widgets for pop-up menus and dialogs are free-standing
+windows and not ``contained'' in the @code{Emacs} widget, their GTK+
+absolute names do not start with @samp{Emacs}.  To customize these
+widgets, use wildcards like this:
 
 @smallexample
 widget "*emacs-dialog*" style "my_dialog_style"
@@ -993,14 +687,7 @@ widget "*emacs-filedialog* style "my_file_style"
 widget "*emacs-menuitem* style "my_menu_style"
 @end smallexample
 
-  If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
-automatically applies only to Emacs, since other programs don't read
-that file.  For example, the drop down menu in the file dialog can not
-be customized by any absolute widget name, only by an absolute class
-name.  This is because the widgets in the drop down menu do not
-have names and the menu is not contained in the Emacs GtkWindow.  To
-have all menus in Emacs look the same, use this in
-@file{~/.emacs.d/gtkrc}:
+  If you want to apply a style to all menus in Emacs, use this:
 
 @smallexample
 widget_class "*Menu*" style "my_menu_style"
@@ -1010,15 +697,7 @@ widget_class "*Menu*" style "my_menu_style"
 @appendixsubsec GTK styles
 @cindex GTK styles
 
-  In a GTK style you specify the appearance widgets shall have.  You
-can specify foreground and background color, background pixmap and
-font.  The edit widget (where you edit the text) in Emacs is a GTK
-widget, but trying to specify a style for the edit widget will have no
-effect.  This is so that Emacs compiled for GTK is compatible with
-Emacs compiled for other X toolkits.  The settings for foreground,
-background and font for the edit widget is taken from the X resources;
-@pxref{Resources}.  Here is an example of two style declarations,
-@samp{default} and @samp{ruler}:
+  Here is an example of two GTK+ style declarations:
 
 @smallexample
 pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps"
@@ -1128,9 +807,8 @@ text fields in the file dialog.
 
 @item font_name = "@var{font}"
 This specifies the font for text in the widget.  @var{font} is a
-Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica
-Bold 12}, @samp{Courier 14}, @samp{Times 18}.  See below for exact
-syntax.  The names are case insensitive.
+GTK-style (or Pango) font name, like @samp{Sans Italic 10}.
+@xref{Fonts}.  The names are case insensitive.
 @end table
 
   There are three ways to specify a color: a color name, an RGB
@@ -1138,60 +816,6 @@ triplet, or a GTK-style RGB triplet.  @xref{Colors}, for a description
 of color names and RGB triplets.  Color names should be enclosed with
 double quotes, e.g.@: @samp{"red"}.  RGB triplets should be written
 without double quotes, e.g.@: @samp{#ff0000}.  GTK-style RGB triplets
-have the form
-
-@smallexample
-@code{@{ @var{r}, @var{g}, @var{b} @}}
-@end smallexample
-
-@noindent
-where @var{r}, @var{g} and @var{b} are either integers in the range
-0-65535 or floats in the range 0.0-1.0.
-
-  Pango font names have the form ``@var{family-list} @var{style-options}
-@var{size}.''
-@cindex Pango font name
-@noindent
-@var{family-list} is a comma separated list of font families optionally
-terminated by a comma.  This way you can specify several families and the
-first one found will be used.  @var{family} corresponds to the second part in
-an X font name, for example in
-
-@smallexample
--adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1
-@end smallexample
-
-@noindent
-the family name is @samp{times}.
-
-@noindent
-@var{style-options} is a whitespace separated list of words where each word
-is a style, variant, weight, or stretch.  The default value for all of
-these is @code{normal}.
-
-@noindent
-A `style' corresponds to the fourth part of an X font name.  In X font
-names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango
-font names the corresponding values are @code{normal}, @code{italic},
-or @code{oblique}.
-
-@noindent
-A `variant' is either @code{normal} or @code{small-caps}.
-Small caps is a font with the lower case characters replaced by
-smaller variants of the capital characters.
-
-@noindent
-Weight describes the ``boldness'' of a font.  It corresponds to the third
-part of an X font name.  It is one of @code{ultra-light}, @code{light},
-@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
-
-@noindent
-Stretch gives the width of the font relative to other designs within a
-family.  It corresponds to the fifth part of an X font name.  It is one of
-@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
-@code{semi-condensed}, @code{normal}, @code{semi-expanded},
-@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
-
-@noindent
-@var{size} is a decimal number that describes the font size in points.
-@end ifnottex
+have the form @w{@code{@{ @var{r}, @var{g}, @var{b} @}}}, where
+@var{r}, @var{g} and @var{b} are either integers in the range 0-65535
+or floats in the range 0.0-1.0.
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f69eeeaadd4..4b9531c0e6c 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+2012-01-16  Juanma Barranquero  <lekktu@gmail.com>
+
+        * windows.texi (Window Parameters): Use @pxref.
+
+2012-01-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Window Configurations, Window Parameters):
+        Describe persistent window parameters.
+
 2011-12-27  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * variables.texi (Creating Buffer-Local): Warn against misuses of
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 85e1b9340fc..1bff30e45e1 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3104,7 +3104,9 @@ window configuration; see @ref{Frame Configurations}.
 @defun current-window-configuration &optional frame
 This function returns a new object representing @var{frame}'s current
 window configuration.  The default for @var{frame} is the selected
-frame.
+frame.  This function saves copies of window parameters listed by the
+variable @code{window-persistent-parameters}, see @ref{Window
+Parameters} for details.
 @end defun
 
 @defun set-window-configuration configuration
@@ -3206,24 +3208,30 @@ configurations.
 
   The objects returned by @code{current-window-configuration} die
 together with the Emacs process.  In order to store a window
-configuration on disk and read it back in another Emacs session the
-following two functions can be used.
+configuration on disk and read it back in another Emacs session, the
+functions described next can be used.  These functions are also useful
+to clone the state of a frame into an arbitrary live window
+(@code{set-window-configuration} effectively clones the windows of a
+frame into the root window of that very frame only).
 
-@defun window-state-get &optional window markers
+@defun window-state-get &optional window ignore
 This function returns the state of @var{window} as a Lisp object.  The
 argument @var{window} can be any window and defaults to the root window
 of the selected frame.
 
-The optional argument @var{markers} non-@code{nil} means to use markers
-for sampling positions like @code{window-point} or @code{window-start}.
-This argument should be non-@code{nil} only if the value is used for
-putting the state back in the same session since markers slow down
-processing.
+If the optional argument @var{ignore} is non-@code{nil}, this means to
+not use markers for sampling positions like @code{window-point} or
+@code{window-start}.  This argument should be non-@code{nil} when the
+state shall be written on disk and read back in another session.
+
+The variable @code{window-persistent-parameters} specifies whether and
+which window parameters are saved by this function, see @ref{Window
+Parameters} for details.
 @end defun
 
-The value returned by @code{window-state-get} can be converted by using
+The value returned by @code{window-state-get} can be converted, using
 one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
-Mode}) to an object that can be written to a file.  Such objects can be
+Mode}), to an object that can be written to a file.  Such objects can be
 read back and converted to a Lisp object representing the state of the
 window.  That Lisp object can be used as argument for the following
 function in order to restore the state window in another window.
@@ -3268,6 +3276,51 @@ This function sets @var{window}'s value of @var{parameter} to
 is the selected window.
 @end defun
 
+By default, functions saving and restoring window configurations or the
+states of windows (@pxref{Window Configurations}) do not care about
+window parameters.  This means, that when you change the value of a
+parameter within the body of a @code{save-window-excursion}, the
+previous value is not restored upon exit of that macro.  It also means
+that when you clone via @code{window-state-put} a window state saved
+earlier by @code{window-state-get}, the cloned windows come up with no
+parameters at all.  The following variable allows to override the
+standard behavior.
+
+@defvar window-persistent-parameters
+This variable is an alist specifying which parameters get saved by
+@code{current-window-configuration} and @code{window-state-get} and
+subsequently restored by @code{set-window-configuration} and
+@code{window-state-put}, see @ref{Window Configurations}.
+
+The @sc{car} of each entry of this alist is the symbol specifying the
+parameter.  The @sc{cdr} must be one of the following:
+
+@table @asis
+@item @code{state}
+This value means the parameter is saved by @code{window-state-get}
+provided its @var{ignore} argument is @code{nil}.  The function
+@code{current-window-configuration} does not save this parameter.
+
+@item @code{nil}
+This value specifies that the parameter is saved by
+@code{current-window-configuration} and, provided its @var{ignore}
+argument is @code{nil}, by @code{window-state-get}.
+
+@item @code{t}
+This means that the parameter is saved unconditionally by both
+@code{current-window-configuration} and @code{window-state-get}.  This
+value should not be used for parameters whose values do not have a read
+syntax.  Otherwise, invoking @code{window-state-put} in another session
+may fail with an @code{invalid-read-syntax} error.
+@end table
+
+Parameters that have been saved are restored to their previous values by
+@code{set-window-configuration} respectively are installed by
+@code{window-state-put}.  Parameters that have not been saved are left
+alone by @code{set-window-configuration} respectively are not installed
+by @code{window-state-put}.
+@end defvar
+
 Some functions, notably @code{delete-window},
 @code{delete-other-windows} and @code{split-window} may behave specially
 when their @var{window} argument has a parameter set.  You can override
@@ -3287,7 +3340,7 @@ windows when exiting that function.
 @end defvar
 
 The following parameters are currently used by the window management
-code.
+code:
 
 @table @asis
 @item @code{delete-window}
@@ -3309,14 +3362,20 @@ This parameter affects the execution of @code{other-window}
 @item @code{no-other-window}
 This parameter marks the window as not selectable by @code{other-window}
 (@pxref{Cyclic Window Ordering}).
+
+@item @code{clone-of}
+This parameter specifies the window this one has been cloned from and is
+installed by @code{window-state-get}, see @ref{Window Configurations}.
+
+@item @code{quit-restore}
+This parameter tells how to proceed with a window when the buffer it
+shows is no more needed.  It is installed by the buffer display
+functions (@pxref{Choosing Window}) and consulted by the function
+@code{quit-window} (@pxref{Quitting Windows}).
 @end table
 
 In addition, the parameters @code{window-atom} and @code{window-side}
-are reserved and should not be used by applications.  The
-@code{quit-restore} parameter tells how to proceed with a window when
-the buffer it shows is no more needed.  This parameter is installed by
-the buffer display functions (@pxref{Choosing Window}) and consulted by
-the function @code{quit-window} (@pxref{Quitting Windows}).
+are reserved and should not be used by applications.
 
 
 @node Window Hooks
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 76728fdbc5b..2813d80d9ff 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,20 @@
+2012-01-16  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * minibuffer.el (completion--replace): Strip properties (bug#10062).
+
+2012-01-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * window.el (window-state-ignored-parameters): Remove variable.
+        (window--state-get-1): Rename argument MARKERS to IGNORE.
+        Handle persistent window parameters.  Make copy of clone-of
+        parameter only if requested.  (Bug#10348)
+        (window--state-put-2): Install a window parameter only if it has
+        a non-nil value or an existing parameter shall be overwritten.
+
+2012-01-15  Michael Albinus  <michael.albinus@gmx.de>
+
+        * net/tramp-sh.el (tramp-remote-path): Set tramp-autoload cookie.
+
 2012-01-14  Eli Zaretskii  <eliz@gnu.org>
 
         * info.el (Info-toc-build): If the Info file has no "Up" pointer,
@@ -34,7 +51,7 @@
 
         Fix Emacs bug #10463 - put `widen's around the critical spots.
 
-        * progmodes/cc-engine.el (c-in-literal, c-literal-limits): put a
+        * progmodes/cc-engine.el (c-in-literal, c-literal-limits): Put a
         widen around each invocation of c-state-pp-to-literal.  Remove an
         unused let variable.
 
@@ -45,8 +62,8 @@
 
 2012-01-10  Chong Yidong  <cyd@gnu.org>
 
-        * net/network-stream.el (network-stream-open-starttls): Avoid
-        emitting a confusing error message when the server gives a bad
+        * net/network-stream.el (network-stream-open-starttls):
+        Avoid emitting a confusing error message when the server gives a bad
         response to the capability command.
 
 2012-01-10  Glenn Morris  <rgm@gnu.org>
@@ -139,8 +156,8 @@
 
         * custom.el (enable-theme): Don't set custom-safe-themes.
 
-        * cus-theme.el (custom-theme-merge-theme): Ignore
-        custom-enabled-themes and custom-safe-themes.
+        * cus-theme.el (custom-theme-merge-theme):
+        Ignore custom-enabled-themes and custom-safe-themes.
 
 2012-01-05  Michael R. Mauger  <mmaug@yahoo.com>
 
@@ -163,8 +180,8 @@
 
 2012-01-03  Chong Yidong  <cyd@gnu.org>
 
-        * shell.el (shell-dynamic-complete-functions): Put
-        pcomplete-completions-at-point, so as to try
+        * shell.el (shell-dynamic-complete-functions):
+        Put pcomplete-completions-at-point, so as to try
         comint-filename-completion first (Bug#10417).
 
 2012-01-02  Richard Stallman  <rms@gnu.org>
@@ -189,8 +206,8 @@
 
 2012-01-01  Eli Zaretskii  <eliz@gnu.org>
 
-        * term/w32-win.el (dynamic-library-alist) <gnutls>: Load
-        libgnutls-28.dll, from GnuTLS version 3.x, in preference to
+        * term/w32-win.el (dynamic-library-alist) <gnutls>:
+        Load libgnutls-28.dll, from GnuTLS version 3.x, in preference to
         libgnutls-26.dll.
 
 2011-12-31  Andreas Schwab  <schwab@linux-m68k.org>
@@ -242,11 +259,10 @@
 2011-12-24  Alan Mackenzie  <acm@muc.de>
 
         Introduce a mechanism to widen the region used in context font
-        locking.  Use this to protect declarations from losing their
-        contexts.
+        locking.  Use this to protect declarations from losing their contexts.
 
-        * progmodes/cc-langs.el (c-before-font-lock-functions): Replace
-        c-set-fl-decl-start with c-change-set-fl-decl-start (Renaming).
+        * progmodes/cc-langs.el (c-before-font-lock-functions):
+        Replace c-set-fl-decl-start with c-change-set-fl-decl-start (Renaming).
         (c-before-context-fontification-functions): New defvar, a list of
         functions to be run just before context (etc.) font locking.
 
@@ -398,22 +414,19 @@
 
         * progmodes/cc-langs (c-label-kwds): Let AWK take the same
         expression as the rest.
-        (c-nonlabel-token-key): Allow string literals for AWK.  Refactor
-        for the other modes.
+        (c-nonlabel-token-key): Allow string literals for AWK.
+        Refactor for the other modes.
 
         Large brace-block initialisation makes CC Mode slow: Fix.
-        Tidy up and accelerate c-in-literal, etc. by using the
-        c-parse-state
+        Tidy up and accelerate c-in-literal, etc. by using the c-parse-state
         routines.  Limit backward searching in c-font-lock-enclosing.decl.
 
         * progmodes/cc-engine.el (c-state-pp-to-literal): Return the
         pp-state and literal type in addition to the limits.
-        (c-state-safe-place): New defun, extracted from
-        c-state-literal-at.
+        (c-state-safe-place): New defun, extracted from c-state-literal-at.
         (c-state-literal-at): Use the above new defun.
-        (c-slow-in-literal, c-fast-in-literal): Removed.
-        (c-in-literal, c-literal-limits): Amended to use
-        c-state-pp-to-literal.
+        (c-slow-in-literal, c-fast-in-literal): Remove.
+        (c-in-literal, c-literal-limits): Amend to use c-state-pp-to-literal.
 
         * progmodes/cc-fonts.el (c-font-lock-enclosing-decls): Check for
         being in a literal.  Add a limit for backward searching.
@@ -487,8 +500,8 @@
 2011-12-10  Eli Zaretskii  <eliz@gnu.org>
 
         * mail/rmailsum.el (rmail-header-summary): RFC2047 decode the
-        `from' or `to' address before taking its substring.  Fixes
-        incorrect display in Rmail summary buffer whereby an RFC2047
+        `from' or `to' address before taking its substring.
+        Fixes incorrect display in Rmail summary buffer whereby an RFC2047
         encoded name is chopped in the middle of the encoded string, and
         thus displayed encoded.
 
@@ -707,8 +720,8 @@
         (verilog-uvm-statement-re): Support UVM indentation and
         highlighting, with old OVM keywords only.
         (verilog-auto-tieoff, verilog-auto-tieoff-declaration):
-        Support AUTOTIEOFF creating non-wire data types.  Suggested by Jonathan
-        Greenlaw.
+        Support AUTOTIEOFF creating non-wire data types.
+        Suggested by Jonathan Greenlaw.
         (verilog-auto-insert-lisp, verilog-delete-to-paren)
         (verilog-forward-sexp-cmt, verilog-forward-sexp-ign-cmt)
         (verilog-inject-sense, verilog-read-inst-pins)
@@ -794,11 +807,11 @@
         Andrew Drake.
         (verilog-auto-star-safe, verilog-delete-auto-star-implicit)
         (verilog-inst-comment-re): Fix not deleting Interfaced comment
-        when expanding .* in interfaces, bug320.  Reported by Pierre-David
-        Pfister.
+        when expanding .* in interfaces, bug320.
+        Reported by Pierre-David Pfister.
         (verilog-read-module-name): Fix import statements between module
-        name and open parenthesis, bug317.  Reported by Pierre-David
-        Pfister.
+        name and open parenthesis, bug317.
+        Reported by Pierre-David Pfister.
         (verilog-simplify-range-expression): Fix simplification of
         multiplications inside AUTOWIRE connections, bug303.
         (verilog-auto-inst-port): Support parameter expansion in
@@ -1052,8 +1065,7 @@
 
 2011-11-19  Andreas Schwab  <schwab@linux-m68k.org>
 
-        * progmodes/sh-script.el (sh-assignment-regexp): Add entry for
-        bash.
+        * progmodes/sh-script.el (sh-assignment-regexp): Add entry for bash.
 
 2011-11-19  Juri Linkov  <juri@jurta.org>
 
@@ -1178,8 +1190,7 @@
 
         * window.el (window-resize, delete-window, split-window):
         Replace window-splits by window-combination-resize.
-        * cus-start.el (window-splits): Replace by
-        window-combination-resize.
+        * cus-start.el (window-splits): Replace by window-combination-resize.
 
 2011-11-17  Glenn Morris  <rgm@gnu.org>
 
@@ -1244,8 +1255,7 @@
         * window.el (split-window, window-state-get-1)
         (window-state-put-1, window-state-put-2): Rename occurrences of
         window-nest to window-combination-limit.
-        * cus-start.el (window-nest): Rename to
-        window-combination-limit.
+        * cus-start.el (window-nest): Rename to window-combination-limit.
 
 2011-11-16  Chong Yidong  <cyd@gnu.org>
 
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 756010160d2..3d9b30bcbb3 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -571,6 +571,10 @@ in the last `cdr'."
 (defun completion--replace (beg end newtext)
   "Replace the buffer text between BEG and END with NEWTEXT.
 Moves point to the end of the new text."
+  ;; The properties on `newtext' include things like
+  ;; completions-first-difference, which we don't want to include
+  ;; upon insertion.
+  (set-text-properties 0 (length newtext) nil newtext)
   ;; Maybe this should be in subr.el.
   ;; You'd think this is trivial to do, but details matter if you want
   ;; to keep markers "at the right place" and be robust in the face of
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index 02f933be367..2478253841f 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -512,6 +512,7 @@ detected as prompt when being sent on echoing hosts, therefore.")
 ;; GNU/Linux (Debian, Suse): /bin:/usr/bin
 ;; FreeBSD: /usr/bin:/bin:/usr/sbin:/sbin: - beware trailing ":"!
 ;; IRIX64: /usr/bin
+;;;###tramp-autoload
 (defcustom tramp-remote-path
   '(tramp-default-remote-path "/bin" "/usr/bin" "/usr/sbin" "/usr/local/bin"
     "/local/bin" "/local/freeware/bin" "/local/gnu/bin"
diff --git a/lisp/window.el b/lisp/window.el
index 8eb0ac3575b..54e5ec9c74c 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -3568,10 +3568,7 @@ specific buffers."
     ))
 
 ;;; Window states, how to get them and how to put them in a window.
-(defvar window-state-ignored-parameters '(quit-restore)
-  "List of window parameters ignored by `window-state-get'.")
-
-(defun window--state-get-1 (window &optional markers)
+(defun window--state-get-1 (window &optional ignore)
   "Helper function for `window-state-get'."
   (let* ((type
           (cond
@@ -3589,12 +3586,27 @@ specific buffers."
             (normal-width . ,(window-normal-size window t))
             (combination-limit . ,(window-combination-limit window))
             ,@(let (list)
-                (dolist (parameter (window-parameters window))
-                  (unless (memq (car parameter)
-                                window-state-ignored-parameters)
-                    (setq list (cons parameter list))))
-                (unless (window-parameter window 'clone-of)
-                  ;; Make a clone-of parameter.
+                ;; Make copies of persistent window parameters whose cdr
+                ;; is either t or, when IGNORE is non-nil, is either nil
+                ;; or `state'.
+                (dolist (pers window-persistent-parameters)
+                  (when (and (consp pers)
+                             (or (eq (cdr pers) t)
+                                 (and (memq (cdr pers) '(state nil))
+                                      (not ignore))))
+                    (let ((par (assq (car pers) (window-parameters window))))
+                      (setq list (cons (cons (car pers) (when par (cdr par)))
+                                       list)))))
+                ;; Save `clone-of' parameter unless IGNORE or
+                ;; `window-persistent-parameters' prevail.
+                (when (and (not (assq 'clone-of (window-parameters window)))
+                           (let ((clone-of
+                                  (assq 'clone-of
+                                        window-persistent-parameters)))
+                             (when clone-of
+                               (if ignore
+                                   (eq (cdr clone-of) t)
+                                 (memq (cdr clone-of) '(state nil))))))
                   (setq list (cons (cons 'clone-of window) list)))
                 (when list
                   `((parameters . ,list))))
@@ -3616,30 +3628,31 @@ specific buffers."
                        (scroll-bars . ,(window-scroll-bars window))
                        (vscroll . ,(window-vscroll window))
                        (dedicated . ,(window-dedicated-p window))
-                       (point . ,(if markers (copy-marker point) point))
-                       (start . ,(if markers (copy-marker start) start))
+                       (point . ,(if ignore point (copy-marker point)))
+                       (start . ,(if ignore start (copy-marker start)))
                        ,@(when mark
-                           `((mark . ,(if markers
-                                          (copy-marker mark) mark)))))))))))
+                           `((mark . ,(if ignore
+                                          mark (copy-marker mark))))))))))))
          (tail
           (when (memq type '(vc hc))
             (let (list)
               (setq window (window-child window))
               (while window
-                (setq list (cons (window--state-get-1 window markers) list))
+                (setq list (cons (window--state-get-1 window ignore) list))
                 (setq window (window-right window)))
               (nreverse list)))))
     (append head tail)))
 
-(defun window-state-get (&optional window markers)
+(defun window-state-get (&optional window ignore)
   "Return state of WINDOW as a Lisp object.
 WINDOW can be any window and defaults to the root window of the
 selected frame.
 
-Optional argument MARKERS non-nil means use markers for sampling
-positions like `window-point' or `window-start'.  MARKERS should
-be non-nil only if the value is used for putting the state back
-in the same session (note that markers slow down processing).
+Optional argument IGNORE non-nil means do not use markers for
+sampling positions like `window-point' or `window-start' and do
+not record parameters unless `window-persistent-parameters'
+requests it.  IGNORE should be non-nil when the return value
+shall be written to a file and read back in another session.
 
 The return value can be used as argument for `window-state-put'
 to put the state recorded here into an arbitrary window.  The
@@ -3665,7 +3678,7 @@ value can be also stored on disk and read back in a new session."
      ;; These are probably not needed.
      ,@(when (window-size-fixed-p window) `((fixed-height . t)))
      ,@(when (window-size-fixed-p window t) `((fixed-width . t))))
-   (window--state-get-1 window markers)))
+   (window--state-get-1 window ignore)))
 
 (defvar window-state-put-list nil
   "Helper variable for `window-state-put'.")
@@ -3744,10 +3757,15 @@ value can be also stored on disk and read back in a new session."
           (state (cdr (assq 'buffer item))))
       (when combination-limit
         (set-window-combination-limit window combination-limit))
-      ;; Process parameters.
+      ;; Assign saved window parameters.  If a parameter's value is nil,
+      ;; don't assign it unless the new window has it set already (which
+      ;; shouldn't happen unless some `window-configuration-change-hook'
+      ;; function installed it).
       (when parameters
         (dolist (parameter parameters)
-          (set-window-parameter window (car parameter) (cdr parameter))))
+          (when (or (cdr parameter)
+                    (window-parameter window (car parameter)))
+            (set-window-parameter window (car parameter) (cdr parameter)))))
       ;; Process buffer related state.
       (when state
         ;; We don't want to raise an error here so we create a buffer if
diff --git a/src/ChangeLog b/src/ChangeLog
index a989246335d..c27b4c69bb5 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,4 +1,4 @@
-2012-01-15  Paul Eggert  <eggert@cs.ucla.edu>
+2012-01-17  Paul Eggert  <eggert@cs.ucla.edu>
 
         Fix integer width and related bugs (Bug#9874).
         * alloc.c (pure_bytes_used_lisp, pure_bytes_used_non_lisp):
@@ -788,6 +788,12 @@
         rather than rolling our own approximation.
         (SCROLL_BAR_VEC_SIZE): Remove; not used.
 
+2012-01-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * window.c (Vwindow_persistent_parameters): New variable.
+        (Fset_window_configuration, save_window_save): Handle persistent
+        window parameters.
+
 2012-01-14  Eli Zaretskii  <eliz@gnu.org>
 
         * w32fns.c (signal_user_input): Don't do a QUIT, to avoid
diff --git a/src/window.c b/src/window.c
index 27e4914ad1a..edf60cd8ff3 100644
--- a/src/window.c
+++ b/src/window.c
@@ -57,7 +57,7 @@ static Lisp_Object Qreplace_buffer_in_windows, Qget_mru_window;
 static Lisp_Object Qwindow_resize_root_window, Qwindow_resize_root_window_vertically;
 static Lisp_Object Qscroll_up, Qscroll_down, Qscroll_command;
 static Lisp_Object Qsafe, Qabove, Qbelow;
-static Lisp_Object Qauto_buffer_name;
+static Lisp_Object Qauto_buffer_name, Qclone_of, Qstate;
 
 static int displayed_window_lines (struct window *);
 static struct window *decode_window (Lisp_Object);
@@ -5412,6 +5412,7 @@ the return value is nil.  Otherwise the value is t.  */)
     {
       Lisp_Object window;
       Lisp_Object dead_windows = Qnil;
+      register Lisp_Object tem, par, pers;
       register struct window *w;
       register struct saved_window *p;
       struct window *root_window;
@@ -5545,7 +5546,28 @@ the return value is nil.  Otherwise the value is t.  */)
           w->vertical_scroll_bar_type = p->vertical_scroll_bar_type;
           w->dedicated = p->dedicated;
           w->combination_limit = p->combination_limit;
-          w->window_parameters = p->window_parameters;
+          /* Restore any window parameters that have been saved.
+             Parameters that have not been saved are left alone.  */
+          for (tem = p->window_parameters; CONSP (tem); tem = XCDR (tem))
+            {
+              pers = XCAR (tem);
+              if (CONSP (pers))
+                {
+                  if (NILP (XCDR (pers)))
+                    {
+                      par = Fassq (XCAR (pers), w->window_parameters);
+                      if (CONSP (par) && !NILP (XCDR (par)))
+                        /* Reset a parameter to nil if and only if it
+                           has a non-nil association.  Don't make new
+                           associations.  */
+                        Fsetcdr (par, Qnil);
+                    }
+                  else
+                    /* Always restore a non-nil value.  */
+                    Fset_window_parameter (window, XCAR (pers), XCDR (pers));
+                }
+            }
+
           XSETFASTINT (w->last_modified, 0);
           XSETFASTINT (w->last_overlay_modified, 0);
 
@@ -5812,7 +5834,7 @@ save_window_save (Lisp_Object window, struct Lisp_Vector *vector, int i)
 {
   register struct saved_window *p;
   register struct window *w;
-  register Lisp_Object tem;
+  register Lisp_Object tem, pers, par;
 
   for (;!NILP (window); window = w->next)
     {
@@ -5840,12 +5862,60 @@ save_window_save (Lisp_Object window, struct Lisp_Vector *vector, int i)
       p->vertical_scroll_bar_type = w->vertical_scroll_bar_type;
       p->dedicated = w->dedicated;
       p->combination_limit = w->combination_limit;
-      p->window_parameters = w->window_parameters;
+      p->window_parameters = Qnil;
+
+      if (!NILP (Vwindow_persistent_parameters))
+        {
+          /* Run cycle detection on Vwindow_persistent_parameters.  */
+          Lisp_Object tortoise, hare;
+
+          hare = tortoise = Vwindow_persistent_parameters;
+          while (CONSP (hare))
+            {
+              hare = XCDR (hare);
+              if (!CONSP (hare))
+                break;
+
+              hare = XCDR (hare);
+              tortoise = XCDR (tortoise);
+
+              if (EQ (hare, tortoise))
+                /* Reset Vwindow_persistent_parameters to Qnil.  */
+                {
+                  Vwindow_persistent_parameters = Qnil;
+                  break;
+                }
+            }
+
+          for (tem = Vwindow_persistent_parameters; CONSP (tem);
+               tem = XCDR (tem))
+            {
+              pers = XCAR (tem);
+              /* Save values for persistent window parameters whose cdr
+                 is either nil or t.  */
+              if (CONSP (pers) && (NILP (XCDR (pers)) || EQ (XCDR (pers), Qt)))
+                {
+                  par = Fassq (XCAR (pers), w->window_parameters);
+                  if (NILP (par))
+                    /* If the window has no value for the parameter,
+                       make one.  */
+                    p->window_parameters = Fcons (Fcons (XCAR (pers), Qnil),
+                                                  p->window_parameters);
+                  else
+                    /* If the window has a value for the parameter,
+                       save it.  */
+                    p->window_parameters = Fcons (Fcons (XCAR (par),
+                                                         XCDR (par)),
+                                                  p->window_parameters);
+                }
+            }
+        }
+
       if (!NILP (w->buffer))
         {
-          /* Save w's value of point in the window configuration.
-             If w is the selected window, then get the value of point
-             from the buffer; pointm is garbage in the selected window.  */
+          /* Save w's value of point in the window configuration.  If w
+             is the selected window, then get the value of point from
+             the buffer; pointm is garbage in the selected window.  */
           if (EQ (window, selected_window))
             {
               p->pointm = Fmake_marker ();
@@ -6435,6 +6505,8 @@ syms_of_window (void)
   DEFSYM (Qabove, "above");
   DEFSYM (Qbelow, "below");
   DEFSYM (Qauto_buffer_name, "auto-buffer-name");
+  DEFSYM (Qclone_of, "clone-of");
+  DEFSYM (Qstate, "state");
 
   staticpro (&Vwindow_list);
 
@@ -6544,6 +6616,31 @@ retrieved via the function `window-combination-limit' and altered by the
 function `set-window-combination-limit'.  */);
   Vwindow_combination_limit = Qnil;
 
+  DEFVAR_LISP ("window-persistent-parameters", Vwindow_persistent_parameters,
+               doc: /* Alist of persistent window parameters.
+Parameters in this list are saved by `current-window-configuration' and
+`window-state-get' and subsequently restored to their previous values by
+`set-window-configuration' and `window-state-put'.
+
+The car of each entry of this alist is the symbol specifying the
+parameter.  The cdr is one of the following:
+
+The symbol `state' means the parameter is saved by `window-state-get'
+provided its IGNORE argument is nil.  `current-window-configuration'
+does not save this parameter.
+
+nil means the parameter is saved by `current-window-configuration' and,
+provided its IGNORE argument is nil, by `window-state-get'.
+
+t means the parameter is saved unconditionally by both
+`current-window-configuration' and `window-state-get'.  Parameters
+without read syntax (like windows or frames) should not use that.
+
+Parameters not saved by `current-window-configuration' or
+`window-state-get' are left alone by `set-window-configuration'
+respectively are not installed by `window-state-put'.  */);
+  Vwindow_persistent_parameters = list1 (Fcons (Qclone_of, Qstate));
+
   defsubr (&Sselected_window);
   defsubr (&Sminibuffer_window);
   defsubr (&Swindow_minibuffer_p);