Merge from emacs-24, up to 2012-04-10T02:06:19Z!larsi@gnus.org

25 files changed, 360 insertions, 159 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b5bdba1296f..6b3aba6d799 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,40 @@
+2012-04-14  Chong Yidong  <cyd@gnu.org>
+
+	* customize.texi (Applying Customizations):
+	(Custom Themes): New nodes.
+
+	* display.texi (Defining Faces): Reference custom-set-faces.
+
+	* modes.texi (Defining Minor Modes, Defining Minor Modes):
+	* os.texi (Startup Summary): Copyedits.
+
+2012-04-14  Glenn Morris  <rgm@gnu.org>
+
+	* loading.texi (Loading Non-ASCII): "unibyte:" can also be at the end.
+
+	* strings.texi (Case Tables):
+	* objects.texi (General Escape Syntax):
+	* keymaps.texi (Key Sequences): Use @acronym with "ASCII".
+
+	* buffers.texi, compile.texi, customize.texi, debugging.texi:
+	* display.texi, edebug.texi, eval.texi, help.texi, intro.texi:
+	* keymaps.texi, minibuf.texi, modes.texi, os.texi, processes.texi:
+	* text.texi: Use @file for buffers, per the Texinfo manual.
+
+	* compile.texi (Compiler Errors): Add missing space in buffer name.
+
+2012-04-14  Chong Yidong  <cyd@gnu.org>
+
+	* processes.texi (Query Before Exit): Remove obsolete function
+	process-kill-without-query (Bug#11190).
+
+2012-04-14  Glenn Morris  <rgm@gnu.org>
+
+	* files.texi, frames.texi, loading.texi, os.texi, processes.texi:
+	Use @env for environment variables.
+
+	* Makefile.in: Replace non-portable use of $< in ordinary rules.
+
 2012-04-12  Jari Aalto  <jari.aalto@cante.net>
 
 	* processes.texi (Synchronous Processes): Mention
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 5094a3f8ab6..10ec236eaee 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -106,21 +106,22 @@ html: elisp.html
 pdf: elisp.pdf
 ps: elisp.ps
 
+## Note: "<" is not portable in ordinary make rules.
 $(infodir)/elisp: $(srcs)
 	$(mkinfodir)
-	$(MAKEINFO) $(MAKEINFO_OPTS) -o $@ $<
+	$(MAKEINFO) $(MAKEINFO_OPTS) -o $@ $(srcdir)/elisp.texi
 
 elisp.dvi: $(srcs)
-	$(ENVADD) $(TEXI2DVI) $<
+	$(ENVADD) $(TEXI2DVI) $(srcdir)/elisp.texi
 
 elisp.html: $(srcs)
-	$(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ $<
+	$(MAKEINFO) $(MAKEINFO_OPTS) --html -o $@ $(srcdir)/elisp.texi
 
 elisp.ps: elisp.dvi
-	$(DVIPS) -o $@ $<
+	$(DVIPS) -o $@ elisp.dvi
 
 elisp.pdf: $(srcs)
-	$(ENVADD) $(TEXI2PDF) $<
+	$(ENVADD) $(TEXI2PDF) $(srcdir)/elisp.texi
 
 .PHONY: mostlyclean clean distclean maintainer-clean infoclean
 
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 125a886ecb2..433663b4260 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -863,7 +863,7 @@ a buffer visible in any window on any visible frame, except as a last
 resort.  If @var{visible-ok} is non-@code{nil}, then it does not matter
 whether a buffer is displayed somewhere or not.
 
-If no suitable buffer exists, the buffer @samp{*scratch*} is returned
+If no suitable buffer exists, the buffer @file{*scratch*} is returned
 (and created, if necessary).
 @end defun
 
@@ -874,7 +874,7 @@ selected frame's buffer list.
 
 The argument @var{visible-ok} is handled as with @code{other-buffer},
 see above.  If no suitable buffer can be found, the buffer
-@samp{*scratch*} is returned.
+@file{*scratch*} is returned.
 @end defun
 
 @deffn Command bury-buffer &optional buffer-or-name
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 90d038c29d6..093c91f02b0 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -92,7 +92,7 @@ the @code{byte-compile} function.  You can compile a whole file with
 
   Sometimes, the byte compiler produces warning and/or error messages
 (@pxref{Compiler Errors}, for details).  These messages are recorded
-in a buffer called @samp{*Compile-Log*}, which uses Compilation mode.
+in a buffer called @file{*Compile-Log*}, which uses Compilation mode.
 @xref{Compilation Mode,,,emacs, The GNU Emacs Manual}.
 
 @cindex macro compilation
@@ -443,14 +443,14 @@ to what @code{eval-when-compile} does.
 @cindex compiler errors
 
   Byte compilation outputs all errors and warnings into the buffer
-@samp{*Compile-Log*}.  The messages include file names and line
+@file{*Compile-Log*}.  The messages include file names and line
 numbers that identify the location of the problem.  The usual Emacs
 commands for operating on compiler diagnostics work properly on these
 messages.
 
   When an error is due to invalid syntax in the program, the byte
 compiler might get confused about the errors' exact location.  One way
-to investigate is to switch to the buffer @w{@samp{*Compiler Input*}}.
+to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}.
 (This buffer name starts with a space, so it does not show up in
 @kbd{M-x list-buffers}.)  This buffer contains the program being
 compiled, and point shows how far the byte compiler was able to read;
@@ -602,7 +602,7 @@ the stack.
 @deffn Command disassemble object &optional buffer-or-name
 This command displays the disassembled code for @var{object}.  In
 interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
-the output goes in a buffer named @samp{*Disassemble*}.  If
+the output goes in a buffer named @file{*Disassemble*}.  If
 @var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
 name of an existing buffer.  Then the output goes there, at point, and
 point is left before the output.
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index d86aea24fbc..ea84afdd408 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -4,20 +4,25 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/customize
 @node Customization, Loading, Macros, Top
-@chapter Writing Customization Definitions
+@chapter Customization Settings
 
-@cindex customization definitions
-  This chapter describes how to declare user options for customization,
-and also customization groups for classifying them.  We use the term
-@dfn{customization item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
+@cindex customization item
+  This chapter describes how to declare customizable variables and
+customization groups for classifying them.  We use the term
+@dfn{customization item} to include customizable variables,
+customization groups, as well as faces.
+
+  @xref{Defining Faces}, for the @code{defface} macro, which is used
+for declaring customizable faces.
 
 @menu
-* Common Keywords::      Common keyword arguments for all kinds of
-                           customization declarations.
-* Group Definitions::    Writing customization group definitions.
-* Variable Definitions:: Declaring user options.
-* Customization Types::  Specifying the type of a user option.
+* Common Keywords::         Common keyword arguments for all kinds of
+                             customization declarations.
+* Group Definitions::       Writing customization group definitions.
+* Variable Definitions::    Declaring user options.
+* Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 @end menu
 
 @node Common Keywords
@@ -306,7 +311,7 @@ individual types for a description of how to use @code{:options}.
 @item :set @var{setfunction}
 @kindex set@r{, @code{defcustom} keyword}
 Specify @var{setfunction} as the way to change the value of this
-option when using the Customize user interface.  The function
+option when using the Customize interface.  The function
 @var{setfunction} should take two arguments, a symbol (the option
 name) and the new value, and should do whatever is necessary to update
 the value properly for this option (which may not mean simply setting
@@ -588,7 +593,7 @@ The value must be a coding-system name, and you can do completion with
 @item color
 The value must be a valid color name.  The widget provides completion
 for color names, as well as a sample and a button for selecting a
-color name from a list of color names shown in a @samp{*Colors*}
+color name from a list of color names shown in a @file{*Colors*}
 buffer.
 @end table
 
@@ -1242,3 +1247,168 @@ the inferior widgets will convert @emph{their} inferior widgets.  If
 the data structure is itself recursive, this conversion is an infinite
 recursion.  The @code{lazy} widget prevents the recursion: it convert
 its @code{:type} argument only when needed.
+
+@node Applying Customizations
+@section Applying Customizations
+
+The following functions are responsible for installing the user's
+customization settings for variables and faces, respectively.  When
+the user invokes @samp{Save for future sessions} in the Customize
+interface, that takes effect by writing a @code{custom-set-variables}
+and/or a @code{custom-set-faces} form into the custom file, to be
+evaluated the next time Emacs starts up.
+
+@defun custom-set-variables &rest args
+This function installs the variable customizations specified by
+@var{args}.  Each argument in @var{args} should have the form
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+@var{var} is a variable name (a symbol), and @var{expression} is an
+expression which evaluates to the desired customized value.
+
+If the @code{defcustom} form for @var{var} has been evaluated prior to
+this @code{custom-set-variables} call, @var{expression} is immediately
+evaluated, and the variable's value is set to the result.  Otherwise,
+@var{expression} is stored into the variable's @code{saved-value}
+property, to be evaluated when the relevant @code{defcustom} is called
+(usually when the library defining that variable is loaded into
+Emacs).
+
+The @var{now}, @var{request}, and @var{comment} entries are for
+internal use only, and may be omitted.  @var{now}, if non-@code{nil},
+means to set the variable's value now, even if the variable's
+@code{defcustom} form has not been evaluated.  @var{request} is a list
+of features to be loaded immediately (@pxref{Named Features}).
+@var{comment} is a string describing the customization.
+@end defun
+
+@defun custom-set-faces &rest args
+This function installs the face customizations specified by
+@var{args}.  Each argument in @var{args} should have the form
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+@var{face} is a face name (a symbol), and @var{spec} is the customized
+face specification for that face (@pxref{Defining Faces}).
+
+The @var{now} and @var{comment} entries are for internal use only, and
+may be omitted.  @var{now}, if non-@code{nil}, means to install the
+face specification now, even if the @code{defface} form has not been
+evaluated.  @var{comment} is a string describing the customization.
+@end defun
+
+@node Custom Themes
+@section Custom Themes
+
+  @dfn{Custom themes} are collections of settings that can be enabled
+or disabled as a unit.  @xref{Custom Themes,,, emacs, The GNU Emacs
+Manual}.  Each Custom theme is defined by an Emacs Lisp source file,
+which should follow the conventions described in this section.
+(Instead of writing a Custom theme by hand, you can also create one
+using a Customize-like interface; @pxref{Creating Custom Themes,,,
+emacs, The GNU Emacs Manual}.)
+
+  A Custom theme file should be named @file{@var{foo}-theme.el}, where
+@var{foo} is the theme name.  The first Lisp form in the file should
+be a call to @code{deftheme}, and the last form should be a call to
+@code{provide-theme}.
+
+@defmac deftheme theme &optional doc
+This macro declares @var{theme} (a symbol) as the name of a Custom
+theme.  The optional argument @var{doc} should be a string describing
+the theme; this is the description shown when the user invokes the
+@code{describe-theme} command or types @kbd{?} in the @samp{*Custom
+Themes*} buffer.
+
+Two special theme names are disallowed: @code{user} is a ``dummy''
+theme which stores the user's direct customization settings, and
+@code{changed} is a ``dummy'' theme which stores changes made outside
+of the Customize system.  If you specify either of these as the
+@var{theme} argument, @code{deftheme} signals an error.
+@end defmac
+
+@defmac provide-theme theme
+This macro declares that the theme named @var{theme} has been fully
+specified.
+@end defmac
+
+  In between @code{deftheme} and @code{provide-theme} are Lisp forms
+specifying the theme settings: usually a call to
+@code{custom-theme-set-variables} and/or a call to
+@code{custom-theme-set-faces}.
+
+@defun custom-theme-set-variables theme &rest args
+This function specifies the Custom theme @var{theme}'s variable
+settings.  @var{theme} should be a symbol.  Each argument in
+@var{args} should be a list of the form
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-variables}.  @xref{Applying Customizations}.
+@end defun
+
+@defun custom-theme-set-faces theme &rest args
+This function specifies the Custom theme @var{theme}'s face settings.
+@var{theme} should be a symbol.  Each argument in @var{args} should be
+a list of the form
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-faces}.  @xref{Applying Customizations}.
+@end defun
+
+  In theory, a theme file can also contain other Lisp forms, which
+would be evaluated when loading the theme, but that is ``bad form''.
+To protect against loading themes containing malicious code, Emacs
+displays the source file and asks for confirmation from the user
+before loading any non-built-in theme for the first time.
+
+  The following functions are useful for programmatically enabling and
+disabling Custom themes:
+
+@defun custom-theme-p theme
+This function return a non-@code{nil} value if @var{theme} (a symbol)
+is the name of a Custom theme (i.e.@: a Custom theme which has been
+loaded into Emacs, whether or not the theme is enabled).  Otherwise,
+it returns @code{nil}.
+@end defun
+
+@deffn Command load-theme theme &optional no-confirm no-enable
+This function loads the Custom theme named @var{theme} from its source
+file, looking for the source file in the directories specified by the
+variable @code{custom-theme-load-path}.  @xref{Custom Themes,,, emacs,
+The GNU Emacs Manual}.  It also @dfn{enables} the theme, causing its
+variable and face settings to take effect.
+
+If the optional argument @var{no-confirm} is non-@code{nil}, this
+skips prompting the user for confirmation before loading the theme.
+
+If the optional argument @var{no-enable} is non-@code{nil}, the theme
+is loaded but not enabled.
+@end deffn
+
+@deffn Command enable-theme theme
+This function enables the Custom theme named @var{theme}.  It signals
+an error if no such theme has been loaded.
+@end deffn
+
+@deffn Command disable-theme theme
+This function disables the Custom theme named @var{theme}.  The theme
+remains loaded, so that a subsequent call to @code{enable-theme} will
+re-enable it.
+@end deffn
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 6e7d0078e07..115d8ff42de 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -303,7 +303,7 @@ an implicit @code{progn} (@pxref{Sequencing}).
 @subsection Using the Debugger
 
   When the debugger is entered, it displays the previously selected
-buffer in one window and a buffer named @samp{*Backtrace*} in another
+buffer in one window and a buffer named @file{*Backtrace*} in another
 window.  The backtrace buffer contains one line for each level of Lisp
 function execution currently going on.  At the beginning of this buffer
 is a message describing the reason that the debugger was invoked (such
@@ -412,7 +412,7 @@ the variable values within the debugger.
 
 @item R
 Like @kbd{e}, but also save the result of evaluation in the
-buffer @samp{*Debugger-record*}.
+buffer @file{*Debugger-record*}.
 
 @item q
 Terminate the program being debugged; return to top-level Emacs
@@ -450,7 +450,7 @@ to invoke the debugger.
 
 @defun debug &rest debugger-args
 This function enters the debugger.  It switches buffers to a buffer
-named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
+named @file{*Backtrace*} (or @file{*Backtrace*<2>} if it is the second
 recursive entry to the debugger, etc.), and fills it with information
 about the stack of Lisp function calls.  It then enters a recursive
 edit, showing the backtrace buffer in Debugger mode.
@@ -461,7 +461,7 @@ buffer and returns to whatever called @code{debug}.  This is the only
 way the function @code{debug} can return to its caller.
 
 The use of the @var{debugger-args} is that @code{debug} displays the
-rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
+rest of its arguments at the top of the @file{*Backtrace*} buffer, so
 that the user can see them.  Except as described below, this is the
 @emph{only} way these arguments are used.
 
@@ -560,7 +560,7 @@ of @code{debug} (@pxref{Invoking the Debugger}).
 @cindex call stack
 This function prints a trace of Lisp function calls currently active.
 This is the function used by @code{debug} to fill up the
-@samp{*Backtrace*} buffer.  It is written in C, since it must have access
+@file{*Backtrace*} buffer.  It is written in C, since it must have access
 to the stack to determine which function calls are active.  The return
 value is always @code{nil}.
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 8382c2a1555..cc48133113f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -268,7 +268,7 @@ objects for its format specifications, like in the @code{format}
 function (@pxref{Formatting Strings}).  The resulting formatted string
 is displayed in the echo area; if it contains @code{face} text
 properties, it is displayed with the specified faces (@pxref{Faces}).
-The string is also added to the @samp{*Messages*} buffer, but without
+The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
 In batch mode, the message is printed to the standard error stream,
@@ -341,7 +341,7 @@ buffer is used, the window used to display it.
 
 If @var{message} is a string, then the optional argument
 @var{buffer-name} is the name of the buffer used to display it when a
-pop-up buffer is used, defaulting to @samp{*Message*}.  In the case
+pop-up buffer is used, defaulting to @file{*Message*}.  In the case
 where @var{message} is a string and displayed in the echo area, it is
 not specified whether the contents are inserted into the buffer anyway.
 
@@ -474,16 +474,16 @@ this macro this way:
 @end defmac
 
 @node Logging Messages
-@subsection Logging Messages in @samp{*Messages*}
+@subsection Logging Messages in @file{*Messages*}
 @cindex logging echo-area messages
 
   Almost all the messages displayed in the echo area are also recorded
-in the @samp{*Messages*} buffer so that the user can refer back to
+in the @file{*Messages*} buffer so that the user can refer back to
 them.  This includes all the messages that are output with
 @code{message}.
 
 @defopt message-log-max
-This variable specifies how many lines to keep in the @samp{*Messages*}
+This variable specifies how many lines to keep in the @file{*Messages*}
 buffer.  The value @code{t} means there is no limit on how many lines to
 keep.  The value @code{nil} disables message logging entirely.  Here's
 how to display a message and prevent it from being logged:
@@ -494,7 +494,7 @@ how to display a message and prevent it from being logged:
 @end example
 @end defopt
 
-  To make @samp{*Messages*} more convenient for the user, the logging
+  To make @file{*Messages*} more convenient for the user, the logging
 facility combines successive identical messages.  It also combines
 successive related messages for the sake of two cases: question
 followed by answer, and a series of progress messages.
@@ -624,7 +624,7 @@ and @var{type} as the warning type.  @var{level} should be the
 severity level, with @code{:warning} being the default.
 
 @var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
-for logging the warning.  By default, it is @samp{*Warnings*}.
+for logging the warning.  By default, it is @file{*Warnings*}.
 @end defun
 
 @defun lwarn type level message &rest args
@@ -1885,7 +1885,7 @@ in all frames.  But you can also assign a face name a special set of
 attributes in one frame (@pxref{Attribute Functions}).
 
 @menu
-* Defining Faces::      How to define a face with @code{defface}.
+* Defining Faces::      How to define a face.
 * Face Attributes::     What is in a face?
 * Attribute Functions::  Functions to examine and set face attributes.
 * Displaying Faces::     How Emacs combines the faces specified for a character.
@@ -1904,22 +1904,17 @@ attributes in one frame (@pxref{Attribute Functions}).
 @node Defining Faces
 @subsection Defining Faces
 
-  The way to define a new face is with @code{defface}.  This creates a
-kind of customization item which the user can customize using the
-Customization buffer (@pxref{Customization}).
-
-  People are sometimes tempted to create variables whose values specify
-which faces to use (for example, Font-Lock does this).  In the vast
-majority of cases, this is not necessary, and simply using faces
-directly is preferable.
+  The @code{defface} macro defines a face and specifies its default
+appearance.  The user can subsequently customize the face using the
+Customize interface (@pxref{Customization}).
 
 @defmac defface face spec doc [keyword value]@dots{}
-This declares @var{face} as a customizable face whose default
+This macro declares @var{face} as a customizable face whose default
 attributes are given by @var{spec}.  You should not quote the symbol
 @var{face}, and it should not end in @samp{-face} (that would be
-redundant).  The argument @var{doc} specifies the face documentation.
-The keywords you can use in @code{defface} are the same as in
-@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+redundant).  The argument @var{doc} is a documentation string for the
+face.  The additional @var{keyword} arguments have the same meanings
+as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
 
 When @code{defface} executes, it defines the face according to
 @var{spec}, then uses any customizations that were read from the
@@ -1930,12 +1925,14 @@ Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
 overrides any customizations of the face.  This way, the face reflects
 exactly what the @code{defface} says.
 
-The purpose of @var{spec} is to specify how the face should appear on
-different kinds of terminals.  It should be an alist whose elements
-have the form @code{(@var{display} @var{atts})}.  @var{display}
-specifies a class of terminals (see below), while @var{atts} is a
-property list of face attributes and their values, specifying the
-appearance of the face on matching terminals
+@cindex face specification
+The @var{spec} argument is a @dfn{face specification}, which states
+how the face should appear on different kinds of terminals.  It should
+be an alist whose elements each have the form @code{(@var{display}
+@var{atts})}.  @var{display} specifies a class of terminals (see
+below), while @var{atts} is a property list of face attributes and
+their values, specifying the appearance of the face on matching
+terminals
 @iftex
 (see the next section for details about face attributes).
 @end iftex
@@ -2022,14 +2019,22 @@ frame must match one of the @var{value}s specified for it in
   :group 'basic-faces)
 @end example
 
-  Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the specified face attributes.  The
-attributes saved by the user with the customization buffer are
-recorded in the symbol property @code{saved-face}; the attributes
-customized by the user for the current session, but not saved, are
-recorded in the symbol property @code{customized-face}.  The
-documentation string is recorded in the symbol property
-@code{face-documentation}.
+  Internally, Emacs stores the face's default specification in its
+@code{face-defface-spec} symbol property (@pxref{Property Lists}).
+The @code{saved-face} property stores the face specification saved by
+the user, using the customization buffer; the @code{customized-face}
+property stores the face specification customized for the current
+session, but not saved; and the @code{theme-face} property stores an
+alist associating the active customization settings and Custom themes
+with their specifications for that face.  The face's documentation
+string is stored in the @code{face-documentation} property.  But
+normally you should not try to set any of these properties directly.
+@xref{Applying Customizations}, for the @code{custom-set-faces}
+function, which is used to apply customized face settings.
+
+  People are sometimes tempted to create variables whose values
+specify a face to use.  In the vast majority of cases, this is not
+necessary; it is preferable to simply use faces directly.
 
 @defopt frame-background-mode
 This option, if non-@code{nil}, specifies the background type to use for
@@ -2752,7 +2757,7 @@ For text matching a search command.
 @itemx warning
 @itemx success
 For text concerning errors, warnings, or successes.  For example,
-these are used for messages in @samp{*Compilation*} buffers.
+these are used for messages in @file{*Compilation*} buffers.
 @end table
 
 @node Font Selection
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 245aaf94c6d..9d50f5fb31f 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -622,7 +622,7 @@ back to the stop point in the source code buffer from any buffer using
 saved outside window configuration---so that even if you turn saving
 back @emph{on}, the current window configuration remains unchanged when
 you next exit Edebug (by continuing the program).  However, the
-automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
+automatic redisplay of @file{*edebug*} and @file{*edebug-trace*} may
 conflict with the buffers you wish to see unless you have enough windows
 open.
 
@@ -661,18 +661,18 @@ lexically bound symbols created by the following constructs in
 @node Eval List
 @subsection Evaluation List Buffer
 
-  You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+  You can use the @dfn{evaluation list buffer}, called @file{*edebug*}, to
 evaluate expressions interactively.  You can also set up the
 @dfn{evaluation list} of expressions to be evaluated automatically each
 time Edebug updates the display.
 
 @table @kbd
 @item E
-Switch to the evaluation list buffer @samp{*edebug*}
+Switch to the evaluation list buffer @file{*edebug*}
 (@code{edebug-visit-eval-list}).
 @end table
 
-  In the @samp{*edebug*} buffer you can use the commands of Lisp
+  In the @file{*edebug*} buffer you can use the commands of Lisp
 Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
 Manual}) as well as these special commands:
 
@@ -699,7 +699,7 @@ Switch back to the source code buffer at the current stop point
 @end table
 
   You can evaluate expressions in the evaluation list window with
-@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @file{*scratch*};
 but they are evaluated in the context outside of Edebug.
 
   The expressions you enter interactively (and their results) are lost
@@ -758,8 +758,8 @@ the expression at a suitable place, insert a new comment line, then type
 @kbd{C-c C-u}.  You need not insert dashes in the comment line---its
 contents don't matter.
 
-After selecting @samp{*edebug*}, you can return to the source code
-buffer with @kbd{C-c C-w}.  The @samp{*edebug*} buffer is killed when
+After selecting @file{*edebug*}, you can return to the source code
+buffer with @kbd{C-c C-w}.  The @file{*edebug*} buffer is killed when
 you continue execution, and recreated next time it is needed.
 
 @node Printing in Edebug
@@ -819,7 +819,7 @@ for details.
 @cindex trace buffer
 
   Edebug can record an execution trace, storing it in a buffer named
-@samp{*edebug-trace*}.  This is a log of function calls and returns,
+@file{*edebug-trace*}.  This is a log of function calls and returns,
 showing the function names and their arguments and values.  To enable
 trace recording, set @code{edebug-trace} to a non-@code{nil} value.
 
@@ -1567,7 +1567,7 @@ The default value is @code{step}.
 
 @defopt edebug-trace
 If this is non-@code{nil}, trace each function entry and exit.
-Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
+Tracing output is displayed in a buffer named @file{*edebug-trace*}, one
 function entry or exit per line, indented by the recursion level.
 
 Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index dc835347235..76397556b01 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -123,7 +123,7 @@ Cover art by Etienne Suvasa.
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -500,6 +500,8 @@ Writing Customization Definitions
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1295,7 +1297,7 @@ Overlays
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 429d999a2c8..7f25b33eb43 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -807,7 +807,7 @@ The value of this variable is a list of the values returned by all the
 expressions that were read, evaluated, and printed from buffers
 (including the minibuffer) by the standard Emacs commands which do
 this.  (Note that this does @emph{not} include evaluation in
-@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
+@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in
 @code{lisp-interaction-mode}.)  The elements are ordered most recent
 first.
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index b49e56158ad..3e96a448963 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2154,7 +2154,7 @@ double all @samp{$} characters to prevent subsequent incorrect
 results.
 
 @c Wordy to avoid overfull hbox.  --rjc 15mar92
-Here we assume that the environment variable @code{HOME}, which holds
+Here we assume that the environment variable @env{HOME}, which holds
 the user's home directory name, has value @samp{/xcssun/users/rms}.
 
 @example
@@ -2239,9 +2239,9 @@ non-@code{nil}.  To use it, you should expand the prefix against
 the proper directory before calling @code{make-temp-file}.
 
 @defopt temporary-file-directory
-@cindex @code{TMPDIR} environment variable
-@cindex @code{TMP} environment variable
-@cindex @code{TEMP} environment variable
+@cindex @env{TMPDIR} environment variable
+@cindex @env{TMP} environment variable
+@cindex @env{TEMP} environment variable
 This variable specifies the directory name for creating temporary files.
 Its value should be a directory name (@pxref{Directory Names}), but it
 is good for Lisp programs to cope if the value is a directory's file
@@ -2249,7 +2249,7 @@ name instead.  Using the value as the second argument to
 @code{expand-file-name} is a good way to achieve that.
 
 The default value is determined in a reasonable way for your operating
-system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
+system; it is based on the @env{TMPDIR}, @env{TMP} and @env{TEMP}
 environment variables, with a fall-back to a system-dependent name if
 none of these variables is defined.
 
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 125d6071cab..1bd4cf4854b 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -488,7 +488,7 @@ frame.  @code{title} and @code{name} are meaningful on all terminals.
 @item display
 The display on which to open this frame.  It should be a string of the
 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@code{DISPLAY} environment variable.
+@env{DISPLAY} environment variable.
 
 @vindex display-type, a frame parameter
 @item display-type
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index c703e7810f8..42de3f1e358 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -180,7 +180,7 @@ face.
 @c Wordy to prevent overfull hboxes.  --rjc 15mar92
 Here is an example of using the two functions, @code{documentation} and
 @code{documentation-property}, to display the documentation strings for
-several symbols in a @samp{*Help*} buffer.
+several symbols in a @file{*Help*} buffer.
 
 @anchor{describe-symbols example}
 @smallexample
@@ -535,7 +535,7 @@ seems to be as a match.  Each of the remaining elements is a
 documentation string, or @code{nil}, for @var{symbol} as a function,
 variable, etc.
 
-It also displays the symbols in a buffer named @samp{*Apropos*}, each
+It also displays the symbols in a buffer named @file{*Apropos*}, each
 with a one-line description taken from the beginning of its
 documentation string.
 
@@ -648,7 +648,7 @@ certain documentation and text files that come with Emacs.
 
 @defun help-buffer
 This function returns the name of the help buffer, which is normally
-@samp{*Help*}; if such a buffer does not exist, it is first created.
+@file{*Help*}; if such a buffer does not exist, it is first created.
 @end defun
 
 @defmac with-help-window buffer-name body@dots{}
@@ -662,16 +662,16 @@ scroll the help window.
 @end defmac
 
 @defun help-setup-xref item interactive-p
-This function updates the cross reference data in the @samp{*Help*}
+This function updates the cross reference data in the @file{*Help*}
 buffer, which is used to regenerate the help information when the user
 clicks on the @samp{Back} or @samp{Forward} buttons.  Most commands
-that use the @samp{*Help*} buffer should invoke this function before
+that use the @file{*Help*} buffer should invoke this function before
 clearing the buffer.  The @var{item} argument should have the form
 @code{(@var{function} . @var{args})}, where @var{function} is a function
 to call, with argument list @var{args}, to regenerate the help buffer.
 The @var{interactive-p} argument is non-@code{nil} if the calling
 command was invoked interactively; in that case, the stack of items
-for the @samp{*Help*} buffer's @samp{Back} buttons is cleared.
+for the @file{*Help*} buffer's @samp{Back} buttons is cleared.
 @end defun
 
 @xref{describe-symbols example}, for an example of using
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 365c5f3122e..c963ba03545 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -247,7 +247,7 @@ indicated with @samp{@equiv{}}.
 
   Many of the examples in this manual print text when they are
 evaluated.  If you execute example code in a Lisp Interaction buffer
-(such as the buffer @samp{*scratch*}), the printed text is inserted into
+(such as the buffer @file{*scratch*}), the printed text is inserted into
 the buffer.  If you execute the example by other means (such as by
 evaluating the function @code{eval-region}), the printed text is
 displayed in the echo area.
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 5dd57ccb4ac..65666217e16 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -64,7 +64,7 @@ constituent events; thus, @code{"\C-xl"} represents the key sequence
 @kbd{C-x l}.
 
   Key sequences containing function keys, mouse button events, or
-non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be
 represented as strings; they have to be represented as vectors.
 
   In the vector representation, each element of the vector represents
@@ -808,7 +808,7 @@ bindings.
 @defun current-local-map
 This function returns the current buffer's local keymap, or @code{nil}
 if it has none.  In the following example, the keymap for the
-@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
+@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
 in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
 keymap.
 
@@ -1922,7 +1922,7 @@ other command.  However, if @var{no-remap} is non-@code{nil}.
 
 @deffn Command describe-bindings &optional prefix buffer-or-name
 This function creates a listing of all current key bindings, and
-displays it in a buffer named @samp{*Help*}.  The text is grouped by
+displays it in a buffer named @file{*Help*}.  The text is grouped by
 modes---minor modes first, then the major mode, then global bindings.
 
 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 47a2a39ed63..0c02f338c7b 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -235,7 +235,7 @@ it skips the latter group.
 in a list of directories specified by the variable @code{load-path}.
 
 @defvar load-path
-@cindex @code{EMACSLOADPATH} environment variable
+@cindex @env{EMACSLOADPATH} environment variable
 The value of this variable is a list of directories to search when
 loading files with @code{load}.  Each element is a string (which must be
 a directory name) or @code{nil} (which stands for the current working
@@ -375,7 +375,7 @@ strings are multibyte strings should not be noticeable, since
 inserting them in unibyte buffers converts them to unibyte
 automatically.  However, if this does make a difference, you can force
 a particular Lisp file to be interpreted as unibyte by writing
-@samp{-*-unibyte: t;-*-} in a comment on the file's first line.  With
+@samp{unibyte: t} in a local variables section.  With
 that designator, the file will unconditionally be interpreted as
 unibyte, even in an ordinary multibyte Emacs session.  This can matter
 when making keybindings to non-@acronym{ASCII} characters written as
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 437a2daa8e3..247e052784a 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1062,7 +1062,7 @@ using the value of the variable @code{minibuffer-completion-table} as
 the @var{collection} argument, and the value of
 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
 The list of completions is displayed as text in a buffer named
-@samp{*Completions*}.
+@file{*Completions*}.
 @end deffn
 
 @defun display-completion-list completions &optional common-substring
@@ -1756,7 +1756,7 @@ completion behavior is overridden.  @xref{Completion Variables}.
 The value should be a function for @dfn{annotating} completions.  The
 function should take one argument, @var{string}, which is a possible
 completion.  It should return a string, which is displayed after the
-completion @var{string} in the @samp{*Completions*} buffer.
+completion @var{string} in the @file{*Completions*} buffer.
 
 @item display-sort-function
 The value should be a function for sorting completions.  The function
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 946dcb91317..83fbd02b16c 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -628,7 +628,7 @@ have set.
 This function sets the major mode of @var{buffer} to the default value of
 @code{major-mode}; if that is @code{nil}, it uses the
 current buffer's major mode (if that is suitable).  As an exception,
-if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to
+if @var{buffer}'s name is @file{*scratch*}, it sets the mode to
 @code{initial-major-mode}.
 
 The low-level primitives for creating buffers do not use this function,
@@ -637,9 +637,9 @@ but medium-level commands such as @code{switch-to-buffer} and
 @end defun
 
 @defopt initial-major-mode
-@cindex @samp{*scratch*}
+@cindex @file{*scratch*}
 The value of this variable determines the major mode of the initial
-@samp{*scratch*} buffer.  The value should be a symbol that is a major
+@file{*scratch*} buffer.  The value should be a symbol that is a major
 mode command.  The default value is @code{lisp-interaction-mode}.
 @end defopt
 
@@ -908,7 +908,7 @@ common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
 (@pxref{Reverting}).
 
 An example of a major mode derived from Special mode is Buffer Menu
-mode, which is used by the @samp{*Buffer List*} buffer.  @xref{List
+mode, which is used by the @file{*Buffer List*} buffer.  @xref{List
 Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
 @end deffn
 
@@ -1571,8 +1571,8 @@ rather than buffer-local.  It defaults to @code{nil}.
 
 One of the effects of making a minor mode global is that the
 @var{mode} variable becomes a customization variable.  Toggling it
-through the Custom interface turns the mode on and off, and its value
-can be saved for future Emacs sessions (@pxref{Saving
+through the Customize interface turns the mode on and off, and its
+value can be saved for future Emacs sessions (@pxref{Saving
 Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
 variable to work, you should ensure that the @code{define-minor-mode}
 form is evaluated each time Emacs starts; for packages that are not
@@ -1691,7 +1691,7 @@ Fundamental mode; but it does not detect the creation of a new buffer
 in Fundamental mode.
 
 This defines the customization option @var{global-mode} (@pxref{Customization}),
-which can be toggled in the Custom interface to turn the minor mode on
+which can be toggled in the Customize interface to turn the minor mode on
 and off.  As with @code{define-minor-mode}, you should ensure that the
 @code{define-globalized-minor-mode} form is evaluated each time Emacs
 starts, for example by providing a @code{:require} keyword.
@@ -2016,7 +2016,7 @@ identify the mode name in the mode line, use @code{format-mode-line}
 This buffer-local variable contains the mode line information on process
 status in modes used for communicating with subprocesses.  It is
 displayed immediately following the major mode name, with no intervening
-space.  For example, its value in the @samp{*shell*} buffer is
+space.  For example, its value in the @file{*shell*} buffer is
 @code{(":%s")}, which allows the shell to display its status along
 with the major mode as: @samp{(Shell:run)}.  Normally this variable
 is @code{nil}.
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index ba4803c73f2..7901f27c4f5 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -352,7 +352,7 @@ following text.)
 
   In addition to the specific escape sequences for special important
 control characters, Emacs provides several types of escape syntax that
-you can use to specify non-ASCII text characters.
+you can use to specify non-@acronym{ASCII} text characters.
 
 @cindex unicode character escape
   You can specify characters by their Unicode values.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 8a57ed2c1f0..35ac7c20384 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -89,7 +89,7 @@ that Emacs is being initialized.
 @c set-locale-environment
 @item
 It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
+if requested by environment variables such as @env{LANG}.
 
 @item
 It does some basic parsing of the command-line arguments.
@@ -170,7 +170,7 @@ measurement of how long it took.
 It runs the normal hook @code{after-init-hook}.
 
 @item
-If the buffer @samp{*scratch*} exists and is still in Fundamental mode
+If the buffer @file{*scratch*} exists and is still in Fundamental mode
 (as it should be by default), it sets its major mode according to
 @code{initial-major-mode}.
 
@@ -196,7 +196,7 @@ It now exits if the option @code{--batch} was specified.
 
 @item
 If @code{initial-buffer-choice} is a string, it visits the file with
-that name.  If the @samp{*scratch*} buffer exists and is
+that name.  If the @file{*scratch*} buffer exists and is
 empty, it inserts @code{initial-scratch-message} into that buffer.
 
 @c To make things nice and confusing, the next three items can be
@@ -254,7 +254,7 @@ The following options affect some aspects of the startup sequence.
 
 @defopt inhibit-startup-screen
 This variable, if non-@code{nil}, inhibits the startup screen.  In
-that case, Emacs typically displays the @samp{*scratch*} buffer; but
+that case, Emacs typically displays the @file{*scratch*} buffer; but
 see @code{initial-buffer-choice}, below.
 
 Do not set this variable in the init file of a new user, or in a way
@@ -274,7 +274,7 @@ startup screen.
 @ignore
 @c I do not think this should be mentioned.  AFAICS it is just a dodge
 @c around inhibit-startup-screen not being settable on a site-wide basis.
-If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.
+If its value is @code{t}, Emacs displays the @file{*scratch*} buffer.
 @end ignore
 @end defopt
 
@@ -290,17 +290,17 @@ form to your init file:
 
 Emacs explicitly checks for an expression as shown above in your init
 file; your login name must appear in the expression as a Lisp string
-constant.  You can also use the Custom interface.  Other methods of setting
-@code{inhibit-startup-echo-area-message} to the same value do not
-inhibit the startup message.  This way, you can easily inhibit the
+constant.  You can also use the Customize interface.  Other methods of
+setting @code{inhibit-startup-echo-area-message} to the same value do
+not inhibit the startup message.  This way, you can easily inhibit the
 message for yourself if you wish, but thoughtless copying of your init
 file will not inhibit the message for someone else.
 @end defopt
 
 @defopt initial-scratch-message
 This variable, if non-@code{nil}, should be a string, which is
-inserted into the @samp{*scratch*} buffer when Emacs starts up.  If it
-is @code{nil}, the @samp{*scratch*} buffer is empty.
+inserted into the @file{*scratch*} buffer when Emacs starts up.  If it
+is @code{nil}, the @file{*scratch*} buffer is empty.
 @end defopt
 
 @noindent
@@ -352,8 +352,8 @@ control whether and where to find the init file; @samp{-q} (and the
 stronger @samp{-Q}) says not to load an init file, while @samp{-u
 @var{user}} says to load @var{user}'s init file instead of yours.
 @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}.  If neither
-option is specified, Emacs uses the @code{LOGNAME} environment
-variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
+option is specified, Emacs uses the @env{LOGNAME} environment
+variable, or the @env{USER} (most systems) or @env{USERNAME} (MS
 systems) variable, to find your home directory and thus your init
 file; this way, even if you have su'd, Emacs still loads your own init
 file.  If those environment variables are absent, though, Emacs uses
@@ -430,7 +430,7 @@ This variable holds the name of the @file{.emacs.d} directory.  It is
   Each terminal type can have its own Lisp library that Emacs loads when
 run on that type of terminal.  The library's name is constructed by
 concatenating the value of the variable @code{term-file-prefix} and the
-terminal type (specified by the environment variable @code{TERM}).
+terminal type (specified by the environment variable @env{TERM}).
 Normally, @code{term-file-prefix} has the value
 @code{"term/"}; changing this is not recommended.  Emacs finds the file
 in the normal manner, by searching the @code{load-path} directories, and
@@ -468,7 +468,7 @@ use this hook to define initializations for terminals that do not
 have their own libraries.  @xref{Hooks}.
 
 @defvar term-file-prefix
-@cindex @code{TERM} environment variable
+@cindex @env{TERM} environment variable
 If the value of this variable is non-@code{nil}, Emacs loads a
 terminal-specific initialization file as follows:
 
@@ -481,7 +481,7 @@ You may set the @code{term-file-prefix} variable to @code{nil} in your
 init file if you do not wish to load the
 terminal-initialization file.
 
-On MS-DOS, Emacs sets the @code{TERM} environment variable to @samp{internal}.
+On MS-DOS, Emacs sets the @env{TERM} environment variable to @samp{internal}.
 @end defvar
 
 @defvar term-setup-hook
@@ -1010,7 +1010,7 @@ value is @code{":"} for Unix and GNU systems, and @code{";"} for MS systems.
 
 @defun parse-colon-path path
 This function takes a search path string such as the value of
-the @code{PATH} environment variable, and splits it at the separators,
+the @env{PATH} environment variable, and splits it at the separators,
 returning a list of directory names.  @code{nil} in this list means
 the current directory.  Although the function's name says
 ``colon'', it actually uses the value of @code{path-separator}.
@@ -1113,7 +1113,7 @@ want to use the default value.
 
 @defun user-login-name &optional uid
 This function returns the name under which the user is logged in.
-It uses the environment variables @code{LOGNAME} or @code{USER} if
+It uses the environment variables @env{LOGNAME} or @env{USER} if
 either is set.  Otherwise, the value is based on the effective
 @acronym{UID}, not the real @acronym{UID}.
 
@@ -1124,12 +1124,12 @@ corresponds to @var{uid}, or @code{nil} if there is no such user.
 @defun user-real-login-name
 This function returns the user name corresponding to Emacs's real
 @acronym{UID}.  This ignores the effective @acronym{UID}, and the
-environment variables @code{LOGNAME} and @code{USER}.
+environment variables @env{LOGNAME} and @env{USER}.
 @end defun
 
 @defun user-full-name &optional uid
 This function returns the full name of the logged-in user---or the value
-of the environment variable @code{NAME}, if that is set.
+of the environment variable @env{NAME}, if that is set.
 
 If the Emacs process's user-id does not correspond to any known user (and
 provided @code{NAME} is not set), the result is @code{"unknown"}.
@@ -1249,9 +1249,9 @@ The argument @var{time-value}, if given, specifies a time (represented
 as a list of integers) to analyze instead of the current time.
 @end defun
 
-The current time zone is determined by the @samp{TZ} environment
+The current time zone is determined by the @env{TZ} environment
 variable.  @xref{System Environment}.  For example, you can tell Emacs
-to use universal time with @code{(setenv "TZ" "UTC0")}.  If @samp{TZ}
+to use universal time with @code{(setenv "TZ" "UTC0")}.  If @env{TZ}
 is not in the environment, Emacs uses a platform-dependent default
 time zone.
 
@@ -1325,7 +1325,7 @@ yourself before you call @code{encode-time}.
 The optional argument @var{zone} defaults to the current time zone and
 its daylight saving time rules.  If specified, it can be either a list
 (as you would get from @code{current-time-zone}), a string as in the
-@code{TZ} environment variable, @code{t} for Universal Time, or an
+@env{TZ} environment variable, @code{t} for Universal Time, or an
 integer (as you would get from @code{decode-time}).  The specified
 zone is used without any further alteration for daylight saving time.
 
@@ -2233,7 +2233,7 @@ non-@code{nil}, Emacs tells the session manager to cancel the
 shutdown.
 @end defvar
 
-Here is an example that just inserts some text into @samp{*scratch*} when
+Here is an example that just inserts some text into @file{*scratch*} when
 Emacs is restarted by the session manager.
 
 @example
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 39b146e3017..ab35dceb1ff 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -77,14 +77,14 @@ sections.  Since the three functions are all called in a similar
 fashion, their common arguments are described here.
 
 @cindex execute program
-@cindex @code{PATH} environment variable
-@cindex @code{HOME} environment variable
+@cindex @env{PATH} environment variable
+@cindex @env{HOME} environment variable
   In all cases, the function's @var{program} argument specifies the
 program to be run.  An error is signaled if the file is not found or
 cannot be executed.  If the file name is relative, the variable
 @code{exec-path} contains a list of directories to search.  Emacs
 initializes @code{exec-path} when it starts up, based on the value of
-the environment variable @code{PATH}.  The standard file name
+the environment variable @env{PATH}.  The standard file name
 constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as
 usual in @code{exec-path}, but environment variable substitutions
 (@samp{$HOME}, etc.) are not recognized; use
@@ -717,7 +717,7 @@ This command displays a listing of all living processes.  In addition,
 it finally deletes any process whose status was @samp{Exited} or
 @samp{Signaled}.  It returns @code{nil}.
 
-The processes are shown in a buffer named @samp{*Process List*}, whose
+The processes are shown in a buffer named @file{*Process List*}, whose
 major mode is named Process Menu mode.
 
 If @var{query-only} is non-@code{nil} then it lists only processes
@@ -1632,35 +1632,17 @@ This returns the query flag of @var{process}.
 This function sets the query flag of @var{process} to @var{flag}.  It
 returns @var{flag}.
 
+Here is an example of using @code{set-process-query-on-exit-flag} on a
+shell process to avoid querying:
+
 @smallexample
 @group
-;; @r{Don't query about the shell process}
 (set-process-query-on-exit-flag (get-process "shell") nil)
      @result{} t
 @end group
 @end smallexample
 @end defun
 
-@defun process-kill-without-query process &optional do-query
-This function clears the query flag of @var{process}, so that
-Emacs will not query the user on account of that process.
-
-Actually, the function does more than that: it returns the old value of
-the process's query flag, and sets the query flag to @var{do-query}.
-Please don't use this function to do those things any more---please
-use the newer, cleaner functions @code{process-query-on-exit-flag} and
-@code{set-process-query-on-exit-flag} in all but the simplest cases.
-The only way you should use @code{process-kill-without-query} nowadays
-is like this:
-
-@smallexample
-@group
-;; @r{Don't query about the shell process}
-(process-kill-without-query (get-process "shell"))
-@end group
-@end smallexample
-@end defun
-
 @node System Processes
 @section Accessing Other Processes
 @cindex system processes
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 7813283ade5..3b8c62af313 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -1117,7 +1117,7 @@ Exits}).
 @acronym{ASCII} characters; for example, in the Turkish language
 environment, the @acronym{ASCII} character @samp{I} is downcased into
 a Turkish ``dotless i''.  This can interfere with code that requires
-ordinary ASCII case conversion, such as implementations of
+ordinary @acronym{ASCII} case conversion, such as implementations of
 @acronym{ASCII}-based network protocols.  In that case, use the
 @code{with-case-table} macro with the variable @var{ascii-case-table},
 which stores the unmodified case table for the @acronym{ASCII}
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 770dd5b5777..bae145c1694 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4345,7 +4345,7 @@ changed text, its length is simply the difference between the first two
 arguments.
 @end defvar
 
-  Output of messages into the @samp{*Messages*} buffer does not
+  Output of messages into the @file{*Messages*} buffer does not
 call these functions.
 
 @defmac combine-after-change-calls body@dots{}
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index df269868e09..45a0dee3b1c 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -141,7 +141,7 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -520,6 +520,8 @@ Writing Customization Definitions
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1317,7 +1319,7 @@ Overlays
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 2a2578158bf..01a3e3c129e 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -140,7 +140,7 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -519,6 +519,8 @@ Writing Customization Definitions
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1316,7 +1318,7 @@ Overlays
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for