/[emacs]/emacs/man/custom.texi
ViewVC logotype

Diff of /emacs/man/custom.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.93 by cyd, Sun Oct 30 03:56:16 2005 UTC revision 1.94 by teirllm, Fri Dec 9 00:30:08 2005 UTC
# Line 7  Line 7 
7  @cindex customization  @cindex customization
8    
9    This chapter talks about various topics relevant to adapting the    This chapter talks about various topics relevant to adapting the
10  behavior of Emacs in minor ways.  See @cite{The Emacs Lisp Reference  behavior of Emacs in minor ways.
11  Manual} for how to make more far-reaching changes.  @xref{X Resources},  @iftex
12    See @cite{The Emacs Lisp Reference Manual}
13    @end iftex
14    @ifnottex
15    @xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
16    Reference Manual},
17    @end ifnottex
18    for how to make more far-reaching changes.  @xref{X Resources},
19  for information on using X resources to customize Emacs.  for information on using X resources to customize Emacs.
20    
21    Customization that you do within Emacs normally affects only the    Customization that you do within Emacs normally affects only the
# Line 52  line when they are on; for example, @sam Line 59  line when they are on; for example, @sam
59  that Auto Fill mode is on.  that Auto Fill mode is on.
60    
61    Append @code{-mode} to the name of a minor mode to get the name of a    Append @code{-mode} to the name of a minor mode to get the name of a
62  command function that turns the mode on or off.  Thus, the command to  command that turns the mode on or off.  Thus, the command to
63  enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These  enable or disable Auto Fill mode is called @code{auto-fill-mode}.  These
64  commands are usually invoked with @kbd{M-x}, but you can bind keys to them  commands are usually invoked with @kbd{M-x}, but you can bind keys to them
65  if you wish.  With no argument, the function turns the mode on if it was  if you wish.  With no argument, the function turns the mode on if it was
66  off and off if it was on.  This is known as @dfn{toggling}.  A positive  off and off if it was on.  This is known as @dfn{toggling}.  A positive
# Line 66  buffer-local; they apply only to the cur Line 73  buffer-local; they apply only to the cur
73  the mode in certain buffers and not others.  the mode in certain buffers and not others.
74    
75    For most minor modes, the command name is also the name of a    For most minor modes, the command name is also the name of a
76  variable which directly controls the mode.  The mode is enabled  variable.  The variable's value is non-@code{nil} if the mode is
77  whenever this variable's value is non-@code{nil}, and the minor-mode  enabled and @code{nil} if it is disabled.  Some minor-mode commands
78  command works by setting the variable.  For example, the command  work by just setting the variable.  For example, the command
79  @code{outline-minor-mode} works by setting the value of  @code{abbrev-mode} works by setting the value of @code{abbrev-mode} as
80  @code{outline-minor-mode} as a variable; it is this variable that  a variable; it is this variable that directly turns Abbrev mode on and
81  directly turns Outline minor mode on and off.  To check whether a  off.  You can directly set the variable's value instead of calling the
82  given minor mode works this way, use @kbd{C-h v} to ask for  mode function.  For other minor modes, you need to either set the
83  documentation on the variable name.  variable through the Customize interface or call the mode function to
84    correctly enable or disable the mode.  To check which of these two
85    These minor-mode variables provide a good way for Lisp programs to  possibilities applies to a given minor mode, use @kbd{C-h v} to ask
86  turn minor modes on and off; they are also useful in a file's local  for documentation on the variable name.
87  variables list (@pxref{File Variables}).  But please think twice  
88  before setting minor modes with a local variables list, because most    For minor mode commands that work by just setting the minor mode
89  minor modes are a matter of user preference---other users editing the  variable, that variable provides a good way for Lisp programs to turn
90  same file might not want the same minor modes you prefer.  minor modes on and off; it is also useful in a file's local variables
91    list (@pxref{File Variables}).  But please think twice before setting
92    minor modes with a local variables list, because most minor modes are
93    a matter of user preference---other users editing the same file might
94    not want the same minor modes you prefer.
95    
96    The most useful buffer-local minor modes include Abbrev mode, Auto    The most useful buffer-local minor modes include Abbrev mode, Auto
97  Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents  Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents
# Line 144  In Binary Overwrite mode, digits after @ Line 155  In Binary Overwrite mode, digits after @
155  octal character code, as usual.  octal character code, as usual.
156    
157    Here are some useful minor modes that normally apply to all buffers    Here are some useful minor modes that normally apply to all buffers
158  at once.  Since each is enabled or disabled by the value of a  at once.  Since Line Number mode and Transient Mark mode can be
159    enabled or disabled just by setting the value of the minor mode
160  variable, you @emph{can} set them differently for particular buffers,  variable, you @emph{can} set them differently for particular buffers,
161  by explicitly making the corresponding variables local in those  by explicitly making the corresponding variable local in those
162  buffers.  @xref{Locals}.  buffers.  @xref{Locals}.
163    
164    Icomplete mode displays an indication of available completions when    Icomplete mode displays an indication of available completions when
# Line 166  these modes are enabled by default when Line 178  these modes are enabled by default when
178  will get an error.  This means you must either set the mark, or  will get an error.  This means you must either set the mark, or
179  explicitly ``reactivate'' it, before each command that uses the region.  explicitly ``reactivate'' it, before each command that uses the region.
180  The advantage of Transient Mark mode is that Emacs can display the  The advantage of Transient Mark mode is that Emacs can display the
181  region highlighted (currently only when using X).  @xref{Mark}.  region highlighted.  @xref{Mark}.
182    
183  @node Easy Customization  @node Easy Customization
184  @section Easy Customization Interface  @section Easy Customization Interface
# Line 274  variables and faces), and their structur Line 286  variables and faces), and their structur
286  @samp{[-]}; invoking that hides the group contents.  @samp{[-]}; invoking that hides the group contents.
287    
288    Each group, variable, or face name in this buffer has an active field    Each group, variable, or face name in this buffer has an active field
289  which says @samp{[Group]}, @samp{[Variable]} or @samp{[Face]}.  Invoking  which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}.  Invoking
290  that active field creates an ordinary customization buffer showing just  that active field creates an ordinary customization buffer showing just
291  that group and its contents, just that variable, or just that face.  that group and its contents, just that variable, or just that face.
292  This is the way to set values in it.  This is the way to set values in it.
# Line 286  This is the way to set values in it. Line 298  This is the way to set values in it.
298  customization buffer:  customization buffer:
299    
300  @smallexample  @smallexample
301  Kill Ring Max: [Hide] 60  Kill Ring Max: [Hide Value] 60
302     [State]: this variable is unchanged from its standard setting.     [State]: STANDARD.
303  Maximum length of kill ring before oldest elements are thrown away.  Maximum length of kill ring before oldest elements are thrown away.
304  @end smallexample  @end smallexample
305    
306    The text following @samp{[Hide]}, @samp{60} in this case, indicates    The text following @samp{[Hide Value]}, @samp{60} in this case, indicates
307  the current value of the variable.  If you see @samp{[Show]} instead of  the current value of the variable.  If you see @samp{[Show Value]} instead of
308  @samp{[Hide]}, it means that the value is hidden; the customization  @samp{[Hide Value]}, it means that the value is hidden; the customization
309  buffer initially hides values that take up several lines.  Invoke  buffer initially hides values that take up several lines.  Invoke
310  @samp{[Show]} to show the value.  @samp{[Show Value]} to show the value.
311    
312    The line after the option name indicates the @dfn{customization state}    The line after the option name indicates the @dfn{customization state}
313  of the variable: in the example above, it says you have not changed the  of the variable: in the example above, it says you have not changed the
# Line 317  another number. Line 329  another number.
329  change to say that you have edited the value:  change to say that you have edited the value:
330    
331  @smallexample  @smallexample
332  [State]: you have edited the value as text, but not set the variable.  [State]: EDITED, shown value does not take effect until you set or @r{@dots{}}
333                                                               save it.
334  @end smallexample  @end smallexample
335    
336  @cindex setting option value  @cindex setting option value
# Line 328  that, you must @dfn{set} it.  To do this Line 341  that, you must @dfn{set} it.  To do this
341    The state of the variable changes visibly when you set it:    The state of the variable changes visibly when you set it:
342    
343  @smallexample  @smallexample
344  [State]: you have set this variable, but not saved it for future sessions.  [State]: SET for current session only.
345  @end smallexample  @end smallexample
346    
347     You don't have to worry about specifying a value that is not valid;     You don't have to worry about specifying a value that is not valid;
# Line 355  value of @code{file-coding-system-alist} Line 368  value of @code{file-coding-system-alist}
368  is how it appears in the customization buffer:  is how it appears in the customization buffer:
369    
370  @smallexample  @smallexample
371  File Coding System Alist: [Hide]  File Coding System Alist: [Hide Value]
372  [INS] [DEL] File regexp: \.elc\'  [INS] [DEL] File regexp: \.elc\'
373              Choice: [Value Menu] Encoding/decoding pair:              Choice: [Value Menu] Encoding/decoding pair:
374              Decoding: emacs-mule              Decoding: emacs-mule
# Line 373  File Coding System Alist: [Hide] Line 386  File Coding System Alist: [Hide]
386              Decoding: undecided              Decoding: undecided
387              Encoding: nil              Encoding: nil
388  [INS]  [INS]
389     [State]: this variable is unchanged from its standard setting.     [State]: STANDARD.
390  Alist to decide a coding system to use for a file I/O operation. [Hide]  Alist to decide a coding system to use for a file I/O @r{@dots{}}
391                                    operation. [Hide Rest]
392  The format is ((PATTERN . VAL) ...),  The format is ((PATTERN . VAL) ...),
393  where PATTERN is a regular expression matching a file name,  where PATTERN is a regular expression matching a file name,
394  @r{[@dots{}more lines of documentation@dots{}]}  @r{[@dots{}more lines of documentation@dots{}]}
# Line 420  Customizations}). Line 434  Customizations}).
434    
435    You can also restore the variable to its standard value by invoking    You can also restore the variable to its standard value by invoking
436  @samp{[State]} and selecting the @samp{Erase Customization} operation.  @samp{[State]} and selecting the @samp{Erase Customization} operation.
437  There are actually three reset operations:  There are actually four reset operations:
438    
439  @table @samp  @table @samp
440  @item Reset  @item Reset to Current
441  If you have made some modifications and not yet set the variable,  If you have made some modifications and not yet set the variable,
442  this restores the text in the customization buffer to match  this restores the text in the customization buffer to match
443  the actual value.  the actual value.
# Line 452  comment you enter will be saved, and dis Line 466  comment you enter will be saved, and dis
466  the same variable in a customization buffer, even in another session.  the same variable in a customization buffer, even in another session.
467    
468    The state of a group indicates whether anything in that group has been    The state of a group indicates whether anything in that group has been
469  edited, set or saved.  You can select @samp{Set for Current Session},  edited, set or saved.
 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}  
 operation for the group; these operations on the group apply to all  
 options in the group and its subgroups.  
470    
471    Near the top of the customization buffer there are two lines    Near the top of the customization buffer there are two lines
472  containing several active fields:  containing several active fields:
473    
474  @smallexample  @smallexample
475   [Set for Current Session] [Save for Future Sessions]   [Set for Current Session] [Save for Future Sessions]
476   [Reset] [Reset to Saved] [Erase Customization]   [Finish]   [Reset to Current] [Reset to Saved] [Erase Customization]   [Finish]
477  @end smallexample  @end smallexample
478    
479  @vindex custom-buffer-done-function  @vindex custom-buffer-done-function
480  @noindent  @noindent
481  Invoking @samp{[Finish]} either buries or kills this customization  Invoking @samp{[Finish]} either buries or kills this customization
482  buffer according to the setting of the option  buffer according to the setting of the option
483  @code{custom-buffer-done-function}; the default is to bury the buffer.  @code{custom-buffer-done-kill}; the default is to bury the buffer.
484  Each of the other fields performs an operation---set, save or  Each of the other fields performs an operation---set, save or
485  reset---on each of the options in the buffer that could meaningfully  reset---on each of the options in the buffer that could meaningfully
486  be set, saved or reset.  They do not operate on options whose values  be set, saved or reset.  They do not operate on options whose values
487  are hidden.  are hidden, nor on subgroups.
488    
489  @node Saving Customizations  @node Saving Customizations
490  @subsection Saving Customizations  @subsection Saving Customizations
# Line 529  the faces in the group appear in the cus Line 540  the faces in the group appear in the cus
540  example of how a face looks:  example of how a face looks:
541    
542  @smallexample  @smallexample
543  Custom Changed Face:(sample) [Hide]  Custom Changed Face:(sample) [Hide Face]
544     [State]: this face is unchanged from its standard setting.     [State]: STANDARD.
545  Face used when the customize item has been changed.  Face used when the customize item has been changed.
546  Parent groups: => Custom Magic Faces  Parent groups: [Custom Magic Faces]
547  Attributes: [ ] Font Family: *  Attributes: [ ] Font Family: *
548              [ ] Width: *              [ ] Width: *
549              [ ] Height: *              [ ] Height: *
# Line 556  attribute by invoking that field.  When Line 567  attribute by invoking that field.  When
567  can change the attribute value in the usual ways.  can change the attribute value in the usual ways.
568    
569    For the colors, you can specify a color name (use @kbd{M-x    For the colors, you can specify a color name (use @kbd{M-x
570  list-colors-display}) for a list of them) or a hexadecimal color  list-colors-display} for a list of them) or a hexadecimal color
571  specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.  specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
572  (@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is  (@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
573  green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.)  On a  green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.)  On a
# Line 627  on the character after point. Line 638  on the character after point.
638    You can also set up the customization buffer with a specific group,    You can also set up the customization buffer with a specific group,
639  using @kbd{M-x customize-group}.  The immediate contents of the chosen  using @kbd{M-x customize-group}.  The immediate contents of the chosen
640  group, including user options, faces, and other groups, all appear  group, including user options, faces, and other groups, all appear
641  as well.  However, these subgroups' own contents start out hidden.  You  as well.  However, these subgroups' own contents are not included.
 can show their contents in the usual way, by invoking @samp{[Show]}.  
642    
643  @findex customize-apropos  @findex customize-apropos
644    To control more precisely what to customize, you can use @kbd{M-x    To control more precisely what to customize, you can use @kbd{M-x
645  customize-apropos}.  You specify a regular expression as argument; then  customize-apropos}.  You specify a regular expression as argument; then
646  all options, faces and groups whose names match this regular expression  all options, faces and groups whose names match this regular expression
647  are set up in the customization buffer.  If you specify an empty regular  are set up in the customization buffer.  If you specify an empty regular
648  expression, this includes @emph{all} groups, options and faces in the  expression, this includes @emph{all} groups, options and faces (but
649  customization buffer (but that takes a long time).  that takes a long time).
650    
651  @findex customize-changed-options  @findex customize-changed-options
652    When you upgrade to a new Emacs version, you might want to customize    When you upgrade to a new Emacs version, you might want to customize
# Line 1688  word: Line 1698  word:
1698  @cindex keypad  @cindex keypad
1699    Many keyboards have a ``numeric keypad'' on the right hand side.    Many keyboards have a ``numeric keypad'' on the right hand side.
1700  The numeric keys in the keypad double up as cursor motion keys,  The numeric keys in the keypad double up as cursor motion keys,
1701  toggled by a key labelled @samp{Num Lock}.  By default, Emacs  toggled by a key labeled @samp{Num Lock}.  By default, Emacs
1702  translates these keys to the corresponding keys in the main keyboard.  translates these keys to the corresponding keys in the main keyboard.
1703  For example, when @samp{Num Lock} is on, the key labelled @samp{8} on  For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
1704  the numeric keypad produces @code{kp-8}, which is translated to  the numeric keypad produces @code{kp-8}, which is translated to
1705  @kbd{8}; when @samp{Num Lock} is off, the same key produces  @kbd{8}; when @samp{Num Lock} is off, the same key produces
1706  @code{kp-up}, which is translated to @key{UP}.  If you rebind a key  @code{kp-up}, which is translated to @key{UP}.  If you rebind a key
# Line 1825  twice. Line 1835  twice.
1835    Emacs also supports triple-click events whose names start with    Emacs also supports triple-click events whose names start with
1836  @samp{triple-}.  Emacs does not distinguish quadruple clicks as event  @samp{triple-}.  Emacs does not distinguish quadruple clicks as event
1837  types; clicks beyond the third generate additional triple-click events.  types; clicks beyond the third generate additional triple-click events.
1838  However, the full number of clicks is recorded in the event list, so you  However, the full number of clicks is recorded in the event list, so
1839  can distinguish if you really want to.  We don't recommend distinct  if you know Emacs Lisp you can distinguish if you really want to
1840  meanings for more than three clicks, but sometimes it is useful for  (@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}).
1841  subsequent clicks to cycle through the same set of three meanings, so  We don't recommend distinct meanings for more than three clicks, but
1842  that four clicks are equivalent to one click, five are equivalent to  sometimes it is useful for subsequent clicks to cycle through the same
1843  two, and six are equivalent to three.  set of three meanings, so that four clicks are equivalent to one
1844    click, five are equivalent to two, and six are equivalent to three.
1845    
1846    Emacs also records multiple presses in drag and button-down events.    Emacs also records multiple presses in drag and button-down events.
1847  For example, when you press a button twice, then move the mouse while  For example, when you press a button twice, then move the mouse while
# Line 1848  click.  Its value is in units of millise Line 1859  click.  Its value is in units of millise
1859    
1860  @vindex double-click-fuzz  @vindex double-click-fuzz
1861    The variable @code{double-click-fuzz} specifies how much the mouse    The variable @code{double-click-fuzz} specifies how much the mouse
1862  can move between clicks still allow them to be grouped as a multiple  can move between clicks and still allow them to be grouped as a multiple
1863  click.  Its value is in units of pixels on windowed displays and in  click.  Its value is in units of pixels on windowed displays and in
1864  units of 1/8 of a character cell on text-mode terminals; the default is  units of 1/8 of a character cell on text-mode terminals; the default is
1865  3.  3.
# Line 1882  you use scroll bars, they appear in plac Line 1893  you use scroll bars, they appear in plac
1893  @item vertical-scroll-bar  @item vertical-scroll-bar
1894  The mouse was in a vertical scroll bar.  (This is the only kind of  The mouse was in a vertical scroll bar.  (This is the only kind of
1895  scroll bar Emacs currently supports.)  scroll bar Emacs currently supports.)
1896    @item menu-bar
1897    The mouse was in the menu bar.
1898    @item header-line
1899    The mouse was in a header line.
1900  @ignore  @ignore
1901  @item horizontal-scroll-bar  @item horizontal-scroll-bar
1902  The mouse was in a horizontal scroll bar.  Horizontal scroll bars do  The mouse was in a horizontal scroll bar.  Horizontal scroll bars do
# Line 2397  library.  @xref{Hooks}. Line 2412  library.  @xref{Hooks}.
2412  @subsection How Emacs Finds Your Init File  @subsection How Emacs Finds Your Init File
2413    
2414    Normally Emacs uses the environment variable @env{HOME} to find    Normally Emacs uses the environment variable @env{HOME} to find
2415  @file{.emacs}; that's what @samp{~} means in a file name.  If @file{.emacs}  @file{.emacs}; that's what @samp{~} means in a file name.  If
2416  is not found directly inside @file{~/}, Emacs looks for it in  @file{.emacs} is not found inside @file{~/} (nor @file{.emacs.el}),
2417  @file{~/.emacs.d/}.  Emacs looks for @file{~/.emacs.d/init.el} (which, like
2418    @file{~/.emacs.el}, can be byte-compiled).
2419    
2420    However, if you run Emacs from a shell started by @code{su}, Emacs    However, if you run Emacs from a shell started by @code{su}, Emacs
2421  tries to find your own @file{.emacs}, not that of the user you are  tries to find your own @file{.emacs}, not that of the user you are

Legend:
Removed from v.1.93  
changed lines
  Added in v.1.94

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26