Doc updates related to tty-setup-hook
[bpt/emacs.git] / doc / emacs / custom.texi
index 6bc96bd..deaeb91 100644 (file)
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
+@c Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Customization
 @chapter Customization
@@ -79,7 +79,7 @@ top-level @code{Emacs} group.  It looks like this, in part:
 
 @c we want the buffer example to all be on one page, but unfortunately
 @c that's quite a bit of text, so force all space to the bottom.
-@page
+@c @page
 @smallexample
 @group
 To apply changes, use the Save or Set buttons.
@@ -345,7 +345,7 @@ hidden, nor on subgroups that are hidden or not visible in the buffer.
 @kindex C-x C-c @r{(customization buffer)}
 @findex Custom-set
 @findex Custom-save
-  The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent using to
+  The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent to using
 the @samp{[Set for Current Session]} button.  The command @kbd{C-x
 C-s} (@code{Custom-save}) is like using the @samp{[Save for Future
 Sessions]} button.
@@ -450,11 +450,14 @@ attribute; an empty checkbox, @samp{[ ]}, means that the face does not
 specify any special value for the attribute.  You can activate a
 checkbox to specify or unspecify its attribute.
 
-  Most faces only specify a few attributes (in the above example,
-@code{font-lock-comment-face} only specifies the foreground color).
-Emacs has a special face, @code{default}, whose attributes are all
-specified; it determines the attributes left unspecified by other
-faces.
+  A face does not have to specify every single attribute; in fact,
+most faces only specify a few attributes.  In the above example,
+@code{font-lock-comment-face} only specifies the foreground color.
+Any unspecified attribute is taken from the special face named
+@code{default}, whose attributes are all specified.  The
+@code{default} face is the face used to display any text that does not
+have an explicitly-assigned face; furthermore, its background color
+attribute serves as the background color of the frame.
 
   The @samp{Hide Unused Attributes} button, at the end of the
 attribute list, hides the unspecified attributes of the face.  When
@@ -552,7 +555,7 @@ or disabled as a unit.  You can use Custom themes to switch easily
 between various collections of settings, and to transfer such
 collections from one computer to another.
 
-  A Custom theme is stored an Emacs Lisp source file.  If the name of
+  A Custom theme is stored as an Emacs Lisp source file.  If the name of
 the Custom theme is @var{name}, the theme file is named
 @file{@var{name}-theme.el}.  @xref{Creating Custom Themes}, for the
 format of a theme file and how to make one.
@@ -607,10 +610,10 @@ always considered safe.
 @vindex custom-enabled-themes
   Setting or saving Custom themes actually works by customizing the
 variable @code{custom-enabled-themes}.  The value of this variable is
-a list of Custom theme names (as Lisp symbols, e.g.@: @code{tango}).
+a list of Custom theme names (as Lisp symbols, e.g., @code{tango}).
 Instead of using the @file{*Custom Themes*} buffer to set
 @code{custom-enabled-themes}, you can customize the variable using the
-usual customization interface, e.g.@: with @kbd{M-x customize-option}.
+usual customization interface, e.g., with @kbd{M-x customize-option}.
 Note that Custom themes are not allowed to set
 @code{custom-enabled-themes} themselves.
 
@@ -628,7 +631,7 @@ theme, its @samp{State} display shows @samp{THEMED} instead of
 @findex disable-theme
   You can enable a specific Custom theme in the current Emacs session
 by typing @kbd{M-x load-theme}.  This prompts for a theme name, loads
-the theme from the theme file, and enables the theme.  If a theme file
+the theme from the theme file, and enables it.  If a theme file
 has been loaded before, you can enable the theme without loading its
 file by typing @kbd{M-x enable-theme}.  To disable a Custom theme,
 type @kbd{M-x disable-theme}.
@@ -636,7 +639,7 @@ type @kbd{M-x disable-theme}.
 @findex describe-theme
   To see a description of a Custom theme, type @kbd{?} on its line in
 the @file{*Custom Themes*} buffer; or type @kbd{M-x describe-theme}
-anywhere in Emacs and enter the theme name in the minibuffer.
+anywhere in Emacs and enter the theme name.
 
 @node Creating Custom Themes
 @subsection Creating Custom Themes
@@ -684,9 +687,8 @@ the @samp{[Merge Theme]} button and specifying the special theme named
   A theme file is simply an Emacs Lisp source file, and loading the
 Custom theme works by loading the Lisp file.  Therefore, you can edit
 a theme file directly instead of using the @file{*Custom Theme*}
-buffer.
-@c Add link to the relevant Emacs Lisp Reference manual node, once
-@c that is written.
+buffer.  @xref{Custom Themes,,, elisp, The Emacs Lisp Reference
+Manual}, for details.
 
 @node Variables
 @section Variables
@@ -763,22 +765,20 @@ C-h v fill-column @key{RET}
 @noindent
 displays something like this:
 
-@smallexample
+@example
 fill-column is a variable defined in `C source code'.
 fill-column's value is 70
-Local in buffer custom.texi; global value is 70
-Automatically becomes buffer-local when set in any fashion.
 
-  Automatically becomes buffer-local when set in any fashion.
-  This variable is safe as a file local variable if its value
-  satisfies the predicate `integerp'.
+Automatically becomes buffer-local when set.
+This variable is safe as a file local variable if its value
+satisfies the predicate `integerp'.
 
 Documentation:
-*Column beyond which automatic line-wrapping should happen.
-Interactively, you can set the buffer local value using C-x f.
+Column beyond which automatic line-wrapping should happen.
+Interactively, you can set the local value with C-x f.
 
 You can customize this variable.
-@end smallexample
+@end example
 
 @noindent
 The line that says ``You can customize the variable'' indicates that
@@ -838,7 +838,8 @@ is a normal hook.
 
 @cindex abnormal hook
   A few hooks are @dfn{abnormal hooks}.  Their names end in
-@samp{-hooks} or @samp{-functions}, instead of @samp{-hook}.  What
+@samp{-functions}, instead of @samp{-hook} (some old code may also use
+the deprecated suffix @samp{-hooks}).  What
 makes these hooks abnormal is the way its functions are
 called---perhaps they are given arguments, or perhaps the values they
 return are used in some way.  For example,
@@ -867,7 +868,7 @@ other modes based on Text mode:
 @noindent
 This works by calling @code{auto-fill-mode}, which enables the minor
 mode when no argument is supplied (@pxref{Minor Modes}).  Next,
-suppose you don't want Auto Fill mode turned on in La@TeX{} mode,
+suppose you don't want Auto Fill mode turned on in @LaTeX{} mode,
 which is one of the modes based on Text mode.  You can do this with
 the following additional line:
 
@@ -879,7 +880,7 @@ the following additional line:
 Here we have used the special macro @code{lambda} to construct an
 anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp
 Reference Manual}), which calls @code{auto-fill-mode} with an argument
-of @code{-1} to disable the minor mode.  Because La@TeX{} mode runs
+of @code{-1} to disable the minor mode.  Because @LaTeX{} mode runs
 @code{latex-mode-hook} after running @code{text-mode-hook}, the result
 leaves Auto Fill mode disabled.
 
@@ -1055,13 +1056,14 @@ pair with a colon and semicolon.  The special variable/value pair
 @findex add-file-local-variable-prop-line
 @findex delete-file-local-variable-prop-line
 @findex copy-dir-locals-to-file-locals-prop-line
-  Instead of adding variable/value pairs by hand, you can use the
-command @kbd{M-x add-file-local-variable-prop-line}.  This prompts for
-a variable and value, and adds them to the first line in the
-appropriate way.  @kbd{M-x delete-file-local-variable-prop-line}
-prompts for a variable, and deletes its entry from the line.  @kbd{M-x
-copy-dir-locals-to-file-locals-prop-line} copies directory-local
-variables to the first line (@pxref{Directory Variables}).
+  You can use @kbd{M-x add-file-local-variable-prop-line} instead of
+adding entries by hand.  This command prompts for a variable and
+value, and adds them to the first line in the appropriate way.
+@kbd{M-x delete-file-local-variable-prop-line} prompts for a variable,
+and deletes its entry from the line.  The command @kbd{M-x
+copy-dir-locals-to-file-locals-prop-line} copies the current
+directory-local variables to the first line (@pxref{Directory
+Variables}).
 
   Here is an example first line that specifies Lisp mode and sets two
 variables with numeric values:
@@ -1164,7 +1166,10 @@ conversion of this file.  @xref{Coding Systems}.
 
 @item
 @code{unibyte} says to load or compile a file of Emacs Lisp in unibyte
-mode, if the value is @code{t}.  @xref{Disabling Multibyte}.
+mode, if the value is @code{t}.  @xref{Disabling Multibyte, ,
+Disabling Multibyte Characters, elisp, GNU Emacs Lisp Reference
+Manual}.
+
 @end itemize
 
 @noindent
@@ -1284,7 +1289,9 @@ specified in @file{.dir-locals.el}, as though they had been defined as
 file-local variables for that file (@pxref{File Variables}).  Emacs
 searches for @file{.dir-locals.el} starting in the directory of the
 visited file, and moving up the directory tree.  To avoid slowdown,
-this search is skipped for remote files.
+this search is skipped for remote files.  If needed, the search can be
+extended for remote files by setting the variable
+@code{enable-remote-dir-locals} to @code{t}.
 
   The @file{.dir-locals.el} file should hold a specially-constructed
 list, which maps major mode names (symbols) to alists
@@ -1301,7 +1308,7 @@ files in that subdirectory.
 @example
 ((nil . ((indent-tabs-mode . t)
          (fill-column . 80)))
- (c-mode . ((c-file-style . "BSD")))
+ (c-mode . ((c-file-style . "BSD")
             (subdirs . nil)))
  ("src/imported"
   . ((nil . ((change-log-default-name
@@ -1523,7 +1530,7 @@ circumstances.
 @vindex minibuffer-local-completion-map
 @vindex minibuffer-local-must-match-map
 @vindex minibuffer-local-filename-completion-map
-@vindex minibuffer-local-must-match-filename-map
+@vindex minibuffer-local-filename-must-match-map
   The minibuffer has its own set of local keymaps; they contain various
 completion and exit commands.
 
@@ -1540,7 +1547,7 @@ just like @key{RET}.
 for cautious completion.
 @item
 @code{minibuffer-local-filename-completion-map} and
-@code{minibuffer-local-must-match-filename-map} are like the two
+@code{minibuffer-local-filename-must-match-map} are like the two
 previous ones, but they are specifically for file name completion.
 They do not bind @key{SPC}.
 @end itemize
@@ -1644,7 +1651,7 @@ you can specify them in your initialization file by writing Lisp code.
 
 @findex kbd
   There are several ways to write a key binding using Lisp.  The
-simplest is to use the @code{kbd} macro, which converts a textual
+simplest is to use the @code{kbd} function, which converts a textual
 representation of a key sequence---similar to how we have written key
 sequences in this manual---into a form that can be passed as an
 argument to @code{global-set-key}.  For example, here's how to bind
@@ -1672,11 +1679,11 @@ and mouse events:
 (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
 @end example
 
-  Instead of using the @code{kbd} macro, you can use a Lisp string or
-vector to specify the key sequence.  Using a string is simpler, but
-only works for @acronym{ASCII} characters and Meta-modified
-@acronym{ASCII} characters.  For example, here's how to bind @kbd{C-x
-M-l} to @code{make-symbolic-link} (@pxref{Misc File Ops}):
+  Instead of using @code{kbd}, you can use a Lisp string or vector to
+specify the key sequence.  Using a string is simpler, but only works
+for @acronym{ASCII} characters and Meta-modified @acronym{ASCII}
+characters.  For example, here's how to bind @kbd{C-x M-l} to
+@code{make-symbolic-link} (@pxref{Misc File Ops}):
 
 @example
 (global-set-key "\C-x\M-l" 'make-symbolic-link)
@@ -1732,11 +1739,11 @@ and @kbd{C-c p} in Texinfo mode:
 
 @example
 (add-hook 'texinfo-mode-hook
-          '(lambda ()
-             (define-key texinfo-mode-map "\C-cp"
-                         'backward-paragraph)
-             (define-key texinfo-mode-map "\C-cn"
-                         'forward-paragraph)))
+          (lambda ()
+            (define-key texinfo-mode-map "\C-cp"
+                        'backward-paragraph)
+            (define-key texinfo-mode-map "\C-cn"
+                        'forward-paragraph)))
 @end example
 
 @node Modifier Keys
@@ -1923,7 +1930,7 @@ single click definition has run when the first click was received.
   This constrains what you can do with double clicks, but user interface
 designers say that this constraint ought to be followed in any case.  A
 double click should do something similar to the single click, only
-``more so.''  The command for the double-click event should perform the
+``more so''.  The command for the double-click event should perform the
 extra work for the double click.
 
   If a double-click event has no binding, it changes to the
@@ -1971,7 +1978,7 @@ or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
   A frame includes areas that don't show text from the buffer, such as
 the mode line and the scroll bar.  You can tell whether a mouse button
 comes from a special area of the screen by means of dummy ``prefix
-keys.''  For example, if you click the mouse in the mode line, you get
+keys''.  For example, if you click the mouse in the mode line, you get
 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
 Thus, here is how to define the command for clicking the first button in
 a mode line to run @code{scroll-up-command}:
@@ -2103,11 +2110,12 @@ loading of this library, use the option @samp{--no-site-file}.
 better to put them in @file{default.el}, so that users can more easily
 override them.
 
+@cindex site-lisp directories
   You can place @file{default.el} and @file{site-start.el} in any of
 the directories which Emacs searches for Lisp libraries.  The variable
 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
-Many sites put these files in the @file{site-lisp} subdirectory of the
-Emacs installation directory, typically
+Many sites put these files in a subdirectory named @file{site-lisp} in
+the Emacs installation directory, such as
 @file{/usr/local/share/emacs/site-lisp}.
 
   Byte-compiling your init file is not recommended (@pxref{Byte
@@ -2180,7 +2188,7 @@ sequences are mandatory.
 @samp{\C-} can be used as a prefix for a control character, as in
 @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
-@kbd{Control-Meta-A}.@refill
+@kbd{Control-Meta-A}.
 
 @xref{Init Non-ASCII}, for information about including
 non-@acronym{ASCII} in your init file.
@@ -2324,7 +2332,7 @@ Here a full file name is used, so no searching is done.
 @cindex loading Lisp libraries automatically
 @cindex autoload Lisp libraries
 Tell Emacs to find the definition for the function @code{myfunction}
-by loading a Lisp library named @file{mypackage} (i.e.@: a file
+by loading a Lisp library named @file{mypackage} (i.e., a file
 @file{mypackage.elc} or @file{mypackage.el}):
 
 @example
@@ -2443,7 +2451,7 @@ it is run on that type of terminal.  For a terminal type named
 found by searching the directories @code{load-path} as usual and trying the
 suffixes @samp{.elc} and @samp{.el}.  Normally it appears in the
 subdirectory @file{term} of the directory where most Emacs libraries are
-kept.@refill
+kept.
 
   The usual purpose of the terminal-specific library is to map the
 escape sequences used by the terminal's function keys onto more
@@ -2458,7 +2466,7 @@ function keys that Termcap does not specify.
 before the first hyphen is significant in choosing the library name.
 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
 the library @file{term/aaa}.  The code in the library can use
-@code{(getenv "TERM")} to find the full terminal type name.@refill
+@code{(getenv "TERM")} to find the full terminal type name.
 
 @vindex term-file-prefix
   The library's name is constructed by concatenating the value of the
@@ -2466,8 +2474,8 @@ variable @code{term-file-prefix} and the terminal type.  Your @file{.emacs}
 file can prevent the loading of the terminal-specific library by setting
 @code{term-file-prefix} to @code{nil}.
 
-@vindex term-setup-hook
-  Emacs runs the hook @code{term-setup-hook} at the end of
+@vindex tty-setup-hook
+  Emacs runs the hook @code{tty-setup-hook} at the end of
 initialization, after both your @file{.emacs} file and any
 terminal-specific library have been read in.  Add hook functions to this
 hook if you wish to override part of any of the terminal-specific
@@ -2491,7 +2499,7 @@ editor customizations even if you are running as the super user.
 
   More precisely, Emacs first determines which user's init file to use.
 It gets your user name from the environment variables @env{LOGNAME} and
-@env{USER}; if neither of those exists, it uses effective user-ID.
+@env{USER}; if neither of those exists, it uses effective user-ID@.
 If that user name matches the real user-ID, then Emacs uses @env{HOME};
 otherwise, it looks up the home directory corresponding to that user
 name in the system's data base of users.