Mercurial > emacs
comparison man/custom.texi @ 58763:25b217a7d2af
(Easy Customization): Move up to section level,
before Variables. Avoid using the term "variable"; say "option".
New initial explanation.
(Variables): In initial explanation, connect "variable" to the
already-explained "user option".
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 05 Dec 2004 14:14:50 +0000 |
parents | a322009ca3d0 |
children | 515e4fdf4cac |
comparison
equal
deleted
inserted
replaced
58762:770cf3ce5391 | 58763:25b217a7d2af |
---|---|
25 replay sequences of keys. | 25 replay sequences of keys. |
26 | 26 |
27 @menu | 27 @menu |
28 * Minor Modes:: Each minor mode is one feature you can turn on | 28 * Minor Modes:: Each minor mode is one feature you can turn on |
29 independently of any others. | 29 independently of any others. |
30 * Easy Customization:: | |
31 Convenient way to browse and change user options. | |
30 * Variables:: Many Emacs commands examine Emacs variables | 32 * Variables:: Many Emacs commands examine Emacs variables |
31 to decide what to do; by setting variables, | 33 to decide what to do; by setting variables, |
32 you can control their functioning. | 34 you can control their functioning. |
33 * Key Bindings:: The keymaps say what command each key runs. | 35 * Key Bindings:: The keymaps say what command each key runs. |
34 By changing them, you can "redefine keys". | 36 By changing them, you can "redefine keys". |
169 will get an error. This means you must either set the mark, or | 171 will get an error. This means you must either set the mark, or |
170 explicitly ``reactivate'' it, before each command that uses the region. | 172 explicitly ``reactivate'' it, before each command that uses the region. |
171 The advantage of Transient Mark mode is that Emacs can display the | 173 The advantage of Transient Mark mode is that Emacs can display the |
172 region highlighted (currently only when using X). @xref{Mark}. | 174 region highlighted (currently only when using X). @xref{Mark}. |
173 | 175 |
174 @node Variables | 176 @node Easy Customization |
175 @section Variables | 177 @section Easy Customization Interface |
176 @cindex variable | 178 |
177 @cindex option, user | |
178 @cindex user option | 179 @cindex user option |
179 | 180 Emacs has many @dfn{user options} which have values that you can set |
180 A @dfn{variable} is a Lisp symbol which has a value. The symbol's | 181 in order to customize various commands. Most user options are |
181 name is also called the name of the variable. A variable name can | 182 documented in this manual. Each user option is actually a Lisp |
182 contain any characters that can appear in a file, but conventionally | 183 variable (@pxref{Variables}), so their names appear in the Variable |
183 variable names consist of words separated by hyphens. A variable can | 184 Index (@pxref{Variable Index}). |
184 have a documentation string which describes what kind of value it should | |
185 have and how the value will be used. | |
186 | |
187 Lisp allows any variable to have any kind of value, but most variables | |
188 that Emacs uses require a value of a certain type. Often the value should | |
189 always be a string, or should always be a number. Sometimes we say that a | |
190 certain feature is turned on if a variable is ``non-@code{nil},'' meaning | |
191 that if the variable's value is @code{nil}, the feature is off, but the | |
192 feature is on for @emph{any} other value. The conventional value to use to | |
193 turn on the feature---since you have to pick one particular value when you | |
194 set the variable---is @code{t}. | |
195 | |
196 Emacs uses many Lisp variables for internal record keeping, as any | |
197 Lisp program must, but the most interesting variables for you are the | |
198 ones that exist for the sake of customization. Emacs does not (usually) | |
199 change the values of these variables; instead, you set the values, and | |
200 thereby alter and control the behavior of certain Emacs commands. These | |
201 variables are called @dfn{user options}. Most user options are | |
202 documented in this manual, and appear in the Variable Index | |
203 (@pxref{Variable Index}). | |
204 | |
205 One example of a variable which is a user option is @code{fill-column}, which | |
206 specifies the position of the right margin (as a number of characters from | |
207 the left margin) to be used by the fill commands (@pxref{Filling}). | |
208 | |
209 @menu | |
210 * Examining:: Examining or setting one variable's value. | |
211 * Easy Customization:: | |
212 Convenient and easy customization of variables. | |
213 * Hooks:: Hook variables let you specify programs for parts | |
214 of Emacs to run on particular occasions. | |
215 * Locals:: Per-buffer values of variables. | |
216 * File Variables:: How files can specify variable values. | |
217 @end menu | |
218 | |
219 @node Examining | |
220 @subsection Examining and Setting Variables | |
221 @cindex setting variables | |
222 | |
223 @table @kbd | |
224 @item C-h v @var{var} @key{RET} | |
225 Display the value and documentation of variable @var{var} | |
226 (@code{describe-variable}). | |
227 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} | |
228 Change the value of variable @var{var} to @var{value}. | |
229 @end table | |
230 | |
231 To examine the value of a single variable, use @kbd{C-h v} | |
232 (@code{describe-variable}), which reads a variable name using the | |
233 minibuffer, with completion. It displays both the value and the | |
234 documentation of the variable. For example, | |
235 | |
236 @example | |
237 C-h v fill-column @key{RET} | |
238 @end example | |
239 | |
240 @noindent | |
241 displays something like this: | |
242 | |
243 @smallexample | |
244 fill-column's value is 70 | |
245 | |
246 Documentation: | |
247 *Column beyond which automatic line-wrapping should happen. | |
248 Automatically becomes buffer-local when set in any fashion. | |
249 @end smallexample | |
250 | |
251 @noindent | |
252 The star at the beginning of the documentation indicates that this | |
253 variable is a user option. @kbd{C-h v} is not restricted to user | |
254 options; it allows any variable name. | |
255 | |
256 @findex set-variable | |
257 The most convenient way to set a specific user option is with @kbd{M-x | |
258 set-variable}. This reads the variable name with the minibuffer (with | |
259 completion), and then reads a Lisp expression for the new value using | |
260 the minibuffer a second time. For example, | |
261 | |
262 @example | |
263 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
264 @end example | |
265 | |
266 @noindent | |
267 sets @code{fill-column} to 75. | |
268 | |
269 @kbd{M-x set-variable} is limited to user option variables, but you can | |
270 set any variable with a Lisp expression, using the function @code{setq}. | |
271 Here is a @code{setq} expression to set @code{fill-column}: | |
272 | |
273 @example | |
274 (setq fill-column 75) | |
275 @end example | |
276 | |
277 To execute an expression like this one, go to the @samp{*scratch*} | |
278 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp | |
279 Interaction}. | |
280 | |
281 Setting variables, like all means of customizing Emacs except where | |
282 otherwise stated, affects only the current Emacs session. | |
283 | |
284 @node Easy Customization | |
285 @subsection Easy Customization Interface | |
286 | 185 |
287 @findex customize | 186 @findex customize |
288 @cindex customization buffer | 187 @cindex customization buffer |
289 A convenient way to find the user option variables that you want to | 188 You can browse interactively through the the user options and change |
290 change, and then change them, is with @kbd{M-x customize}. This | 189 some of them using @kbd{M-x customize}. This command creates a |
291 command creates a @dfn{customization buffer} with which you can browse | 190 @dfn{customization buffer}, which offers commands to navigate through |
292 through the Emacs user options in a logically organized structure, | 191 a logically organized structure of the Emacs user options; you can |
293 then edit and set their values. You can also use the customization | 192 also use it to edit and set their values, and to save settings |
294 buffer to save settings permanently in your @file{~/.emacs} file | 193 permanently in your @file{~/.emacs} file (@pxref{Init File}). |
295 (@pxref{Init File}). | 194 |
296 | 195 The appearance of the example buffers in this section is typically |
297 The appearance of the example buffers in the following is typically | 196 different under a window system, since faces are then used to indicate |
298 different under a window system where faces can be used to indicate the | 197 the active fields and other features. |
299 active fields and other features. | |
300 | 198 |
301 @menu | 199 @menu |
302 * Groups: Customization Groups. | 200 * Groups: Customization Groups. |
303 How options are classified in a structure. | 201 How options are classified in a structure. |
304 * Changing an Option:: How to edit a value and set an option. | 202 * Changing an Option:: How to edit a value and set an option. |
307 * Specific Customization:: Making a customization buffer for specific | 205 * Specific Customization:: Making a customization buffer for specific |
308 options, faces, or groups. | 206 options, faces, or groups. |
309 @end menu | 207 @end menu |
310 | 208 |
311 @node Customization Groups | 209 @node Customization Groups |
312 @subsubsection Customization Groups | 210 @subsection Customization Groups |
313 @cindex customization groups | 211 @cindex customization groups |
314 | 212 |
315 For customization purposes, user options are organized into | 213 For customization purposes, user options are organized into |
316 @dfn{groups} to help you find them. Groups are collected into bigger | 214 @dfn{groups} to help you find them. Groups are collected into bigger |
317 groups, all the way up to a master group called @code{Emacs}. | 215 groups, all the way up to a master group called @code{Emacs}. |
387 that active field creates an ordinary customization buffer showing just | 285 that active field creates an ordinary customization buffer showing just |
388 that group and its contents, just that option, or just that face. | 286 that group and its contents, just that option, or just that face. |
389 This is the way to set values in it. | 287 This is the way to set values in it. |
390 | 288 |
391 @node Changing an Option | 289 @node Changing an Option |
392 @subsubsection Changing an Option | 290 @subsection Changing an Option |
393 | 291 |
394 Here is an example of what a user option looks like in the | 292 Here is an example of what a user option looks like in the |
395 customization buffer: | 293 customization buffer: |
396 | 294 |
397 @smallexample | 295 @smallexample |
409 The line after the option name indicates the @dfn{customization state} | 307 The line after the option name indicates the @dfn{customization state} |
410 of the option: in the example above, it says you have not changed the | 308 of the option: in the example above, it says you have not changed the |
411 option yet. The word @samp{[State]} at the beginning of this line is | 309 option yet. The word @samp{[State]} at the beginning of this line is |
412 active; you can get a menu of various operations by invoking it with | 310 active; you can get a menu of various operations by invoking it with |
413 @kbd{Mouse-1} or @key{RET}. These operations are essential for | 311 @kbd{Mouse-1} or @key{RET}. These operations are essential for |
414 customizing the variable. | 312 customizing the user option. |
415 | 313 |
416 The line after the @samp{[State]} line displays the beginning of the | 314 The line after the @samp{[State]} line displays the beginning of the |
417 option's documentation string. If there are more lines of | 315 option's documentation string. If there are more lines of |
418 documentation, this line ends with @samp{[More]}; invoke this to show | 316 documentation, this line ends with @samp{[More]}; invoke this to show |
419 the full documentation string. | 317 the full documentation string. |
428 @smallexample | 326 @smallexample |
429 [State]: you have edited the value as text, but not set the option. | 327 [State]: you have edited the value as text, but not set the option. |
430 @end smallexample | 328 @end smallexample |
431 | 329 |
432 @cindex setting option value | 330 @cindex setting option value |
433 Editing the value does not actually set the option variable. To do | 331 Editing the value does not actually set the option. To do |
434 that, you must @dfn{set} the option. To do this, invoke the word | 332 that, you must @dfn{set} the option. To do this, invoke the word |
435 @samp{[State]} and choose @samp{Set for Current Session}. | 333 @samp{[State]} and choose @samp{Set for Current Session}. |
436 | 334 |
437 The state of the option changes visibly when you set it: | 335 The state of the option changes visibly when you set it: |
438 | 336 |
521 @cindex customized options, saving | 419 @cindex customized options, saving |
522 Setting the option changes its value in the current Emacs session; | 420 Setting the option changes its value in the current Emacs session; |
523 @dfn{saving} the value changes it for future sessions as well. To | 421 @dfn{saving} the value changes it for future sessions as well. To |
524 save the option, invoke @samp{[State]} and select the @samp{Save for | 422 save the option, invoke @samp{[State]} and select the @samp{Save for |
525 Future Sessions} operation. This works by writing code so as to set | 423 Future Sessions} operation. This works by writing code so as to set |
526 the option variable again each time you start Emacs (@pxref{Saving | 424 the option again, each time you start Emacs (@pxref{Saving |
527 Customizations}). | 425 Customizations}). |
528 | 426 |
529 You can also restore the option to its standard value by invoking | 427 You can also restore the option to its standard value by invoking |
530 @samp{[State]} and selecting the @samp{Erase Customization} operation. | 428 @samp{[State]} and selecting the @samp{Erase Customization} operation. |
531 There are actually three reset operations: | 429 There are actually three reset operations: |
545 accordingly. This also eliminates any saved value for the option, | 443 accordingly. This also eliminates any saved value for the option, |
546 so that you will get the standard value in future Emacs sessions. | 444 so that you will get the standard value in future Emacs sessions. |
547 | 445 |
548 @item Use Backup Value | 446 @item Use Backup Value |
549 This sets the option to a previous value that was set in the | 447 This sets the option to a previous value that was set in the |
550 customization buffer in this session. If you customize a variable | 448 customization buffer in this session. If you customize an option |
551 and then reset the variable, which discards the customized value, | 449 and then reset it, which discards the customized value, |
552 you can get the customized value back again with this operation. | 450 you can get the customized value back again with this operation. |
553 @end table | 451 @end table |
554 | 452 |
555 @cindex comments on customized options | 453 @cindex comments on customized options |
556 Sometimes it is useful to record a comment about a specific | 454 Sometimes it is useful to record a comment about a specific |
581 Each of the other fields performs an operation---set, save or | 479 Each of the other fields performs an operation---set, save or |
582 reset---on each of the items in the buffer that could meaningfully be | 480 reset---on each of the items in the buffer that could meaningfully be |
583 set, saved or reset. | 481 set, saved or reset. |
584 | 482 |
585 @node Saving Customizations | 483 @node Saving Customizations |
586 @subsubsection Saving Customizations | 484 @subsection Saving Customizations |
587 | 485 |
588 @vindex custom-file | 486 @vindex custom-file |
589 The customization buffer normally saves customizations in | 487 The customization buffer normally saves customizations in |
590 @file{~/.emacs}. If you wish, you can save customizations in another | 488 @file{~/.emacs}. If you wish, you can save customizations in another |
591 file instead. To make this work, your @file{~/.emacs} should set | 489 file instead. To make this work, your @file{~/.emacs} should set |
613 customizations in your @file{~/.emacs} init file. This is because | 511 customizations in your @file{~/.emacs} init file. This is because |
614 saving customizations from such a session would wipe out all the other | 512 saving customizations from such a session would wipe out all the other |
615 customizations you might have on your init file. | 513 customizations you might have on your init file. |
616 | 514 |
617 @node Face Customization | 515 @node Face Customization |
618 @subsubsection Customizing Faces | 516 @subsection Customizing Faces |
619 @cindex customizing faces | 517 @cindex customizing faces |
620 @cindex bold font | 518 @cindex bold font |
621 @cindex italic font | 519 @cindex italic font |
622 @cindex fonts and faces | 520 @cindex fonts and faces |
623 | 521 |
674 the attribute's current value is the default---type just @key{RET} if | 572 the attribute's current value is the default---type just @key{RET} if |
675 you don't want to change that attribute. Type @samp{none} if you want | 573 you don't want to change that attribute. Type @samp{none} if you want |
676 to clear out the attribute. | 574 to clear out the attribute. |
677 | 575 |
678 @node Specific Customization | 576 @node Specific Customization |
679 @subsubsection Customizing Specific Items | 577 @subsection Customizing Specific Items |
680 | 578 |
681 Instead of finding the options you want to change by moving down | 579 Instead of finding the options you want to change by moving down |
682 through the structure of groups, you can specify the particular option, | 580 through the structure of groups, you can specify the particular option, |
683 face or group that you want to customize. | 581 face or group that you want to customize. |
684 | 582 |
702 Set up a customization buffer containing all options and faces that you | 600 Set up a customization buffer containing all options and faces that you |
703 have customized but not saved. | 601 have customized but not saved. |
704 @end table | 602 @end table |
705 | 603 |
706 @findex customize-option | 604 @findex customize-option |
707 If you want to alter a particular user option variable with the | 605 If you want to alter a particular user option with the |
708 customization buffer, and you know its name, you can use the command | 606 customization buffer, and you know its name, you can use the command |
709 @kbd{M-x customize-option} and specify the option name. This sets up | 607 @kbd{M-x customize-option} and specify the option name. This sets up |
710 the customization buffer with just one option---the one that you asked | 608 the customization buffer with just one option---the one that you asked |
711 for. Editing, setting and saving the value work as described above, but | 609 for. Editing, setting and saving the value work as described above, but |
712 only for the specified option. | 610 only for the specified option. |
717 on the character after point. | 615 on the character after point. |
718 | 616 |
719 @findex customize-group | 617 @findex customize-group |
720 You can also set up the customization buffer with a specific group, | 618 You can also set up the customization buffer with a specific group, |
721 using @kbd{M-x customize-group}. The immediate contents of the chosen | 619 using @kbd{M-x customize-group}. The immediate contents of the chosen |
722 group, including option variables, faces, and other groups, all appear | 620 group, including user options, faces, and other groups, all appear |
723 as well. However, these subgroups' own contents start out hidden. You | 621 as well. However, these subgroups' own contents start out hidden. You |
724 can show their contents in the usual way, by invoking @samp{[Show]}. | 622 can show their contents in the usual way, by invoking @samp{[Show]}. |
725 | 623 |
726 @findex customize-apropos | 624 @findex customize-apropos |
727 To control more precisely what to customize, you can use @kbd{M-x | 625 To control more precisely what to customize, you can use @kbd{M-x |
744 If you change option values and then decide the change was a mistake, | 642 If you change option values and then decide the change was a mistake, |
745 you can use two special commands to revisit your previous changes. Use | 643 you can use two special commands to revisit your previous changes. Use |
746 @kbd{M-x customize-saved} to look at the options and faces that you have | 644 @kbd{M-x customize-saved} to look at the options and faces that you have |
747 saved. Use @kbd{M-x customize-customized} to look at the options and | 645 saved. Use @kbd{M-x customize-customized} to look at the options and |
748 faces that you have set but not saved. | 646 faces that you have set but not saved. |
647 | |
648 @node Variables | |
649 @section Variables | |
650 @cindex variable | |
651 @cindex option, user | |
652 @cindex user option | |
653 | |
654 A @dfn{variable} is a Lisp symbol which has a value. The symbol's | |
655 name is also called the name of the variable. A variable name can | |
656 contain any characters that can appear in a file, but conventionally | |
657 variable names consist of words separated by hyphens. A variable can | |
658 have a documentation string which describes what kind of value it should | |
659 have and how the value will be used. | |
660 | |
661 Lisp allows any variable to have any kind of value, but most variables | |
662 that Emacs uses need a value of a certain type. Often the value should | |
663 always be a string, or should always be a number. Sometimes we say that a | |
664 certain feature is turned on if a variable is ``non-@code{nil},'' meaning | |
665 that if the variable's value is @code{nil}, the feature is off, but the | |
666 feature is on for @emph{any} other value. The conventional value to use to | |
667 turn on the feature---since you have to pick one particular value when you | |
668 set the variable---is @code{t}. | |
669 | |
670 Emacs uses many Lisp variables for internal record keeping, but the | |
671 most interesting variables for a non-programmer user are the @dfn{user | |
672 options}, the variables that are meant for users to change. Each user | |
673 option that you can set with the customization buffera is, in fact, a | |
674 Lisp variable. Emacs does not (usually) change the values of these | |
675 variables; instead, you set the values, and thereby alter and control | |
676 the behavior of certain Emacs commands. Use of the customization | |
677 buffer is explained above; here we describe other aspects of Emacs | |
678 variables. | |
679 | |
680 @menu | |
681 * Examining:: Examining or setting one variable's value. | |
682 * Hooks:: Hook variables let you specify programs for parts | |
683 of Emacs to run on particular occasions. | |
684 * Locals:: Per-buffer values of variables. | |
685 * File Variables:: How files can specify variable values. | |
686 @end menu | |
687 | |
688 @node Examining | |
689 @subsection Examining and Setting Variables | |
690 @cindex setting variables | |
691 | |
692 @table @kbd | |
693 @item C-h v @var{var} @key{RET} | |
694 Display the value and documentation of variable @var{var} | |
695 (@code{describe-variable}). | |
696 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} | |
697 Change the value of variable @var{var} to @var{value}. | |
698 @end table | |
699 | |
700 To examine the value of a single variable, use @kbd{C-h v} | |
701 (@code{describe-variable}), which reads a variable name using the | |
702 minibuffer, with completion. It displays both the value and the | |
703 documentation of the variable. For example, | |
704 | |
705 @example | |
706 C-h v fill-column @key{RET} | |
707 @end example | |
708 | |
709 @noindent | |
710 displays something like this: | |
711 | |
712 @smallexample | |
713 fill-column's value is 70 | |
714 | |
715 Documentation: | |
716 *Column beyond which automatic line-wrapping should happen. | |
717 Automatically becomes buffer-local when set in any fashion. | |
718 @end smallexample | |
719 | |
720 @noindent | |
721 The star at the beginning of the documentation indicates that this | |
722 variable is a user option. @kbd{C-h v} is not restricted to user | |
723 options; it allows any variable name. | |
724 | |
725 @findex set-variable | |
726 The most convenient way to set a specific user option is with @kbd{M-x | |
727 set-variable}. This reads the variable name with the minibuffer (with | |
728 completion), and then reads a Lisp expression for the new value using | |
729 the minibuffer a second time. For example, | |
730 | |
731 @example | |
732 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} | |
733 @end example | |
734 | |
735 @noindent | |
736 sets @code{fill-column} to 75. | |
737 | |
738 @kbd{M-x set-variable} is limited to user option variables, but you can | |
739 set any variable with a Lisp expression, using the function @code{setq}. | |
740 Here is a @code{setq} expression to set @code{fill-column}: | |
741 | |
742 @example | |
743 (setq fill-column 75) | |
744 @end example | |
745 | |
746 To execute an expression like this one, go to the @samp{*scratch*} | |
747 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp | |
748 Interaction}. | |
749 | |
750 Setting variables, like all means of customizing Emacs except where | |
751 otherwise stated, affects only the current Emacs session. | |
749 | 752 |
750 @node Hooks | 753 @node Hooks |
751 @subsection Hooks | 754 @subsection Hooks |
752 @cindex hook | 755 @cindex hook |
753 @cindex running a hook | 756 @cindex running a hook |