From 5552d5a425bfeef0b89fe43b0cda03554ee3bd98 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Fri, 23 Dec 2005 01:46:33 +0000 Subject: [PATCH] (Easy Customization and subnodes): Replace "active field" with "button". Use "user option" only for variables. Use "setting" for variable-or-face. --- man/custom.texi | 323 ++++++++++++++++++++++++------------------------ 1 file changed, 160 insertions(+), 163 deletions(-) diff --git a/man/custom.texi b/man/custom.texi index c1442ca2f3c..2180fcdd04a 100644 --- a/man/custom.texi +++ b/man/custom.texi @@ -34,7 +34,7 @@ replay sequences of keys. @menu * Minor Modes:: Each minor mode is one feature you can turn on independently of any others. -* Easy Customization:: Convenient way to browse and change user options. +* Easy Customization:: Convenient way to browse and change settings. * Variables:: Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning. @@ -183,31 +183,31 @@ region highlighted. @xref{Mark}. @node Easy Customization @section Easy Customization Interface -@cindex user option - Emacs has many @dfn{user options} which have values that you can set -in order to customize various commands. Many user options are -documented in this manual. Most user options are actually Lisp -variables (@pxref{Variables}), so their names appear in the Variable -Index (@pxref{Variable Index}). The rest are faces and their -attributes (@pxref{Faces}). +@cindex settings + Emacs has many @dfn{settings} which have values that you can specify +in order to customize various commands. Many are documented in this +manual. Most settings are @dfn{user options}---that is to say, Lisp +variables (@pxref{Variables})---so their names appear in the Variable +Index (@pxref{Variable Index}). The other settings are faces and +their attributes (@pxref{Faces}). @findex customize @cindex customization buffer - You can browse interactively through the user options and change -some of them using @kbd{M-x customize}. This command creates a -@dfn{customization buffer}, which offers commands to navigate through -a logically organized structure of the Emacs user options; you can -also use it to edit and set their values, and to save settings -permanently in your @file{~/.emacs} file (@pxref{Init File}). + You can browse interactively through settings and change them using +@kbd{M-x customize}. This command creates a @dfn{customization +buffer}, which offers commands to navigate through a logically +organized structure of the Emacs settings; you can also use it to edit +and set their values, and to save settings permanently in your +@file{~/.emacs} file (@pxref{Init File}). The appearance of the example buffers in this section is typically different under a window system, since faces are then used to indicate -the active fields and other features. +buttons and editable fields. @menu -* Groups: Customization Groups. How options are classified in a structure. -* Browsing: Browsing Custom. Browsing and searching for options and faces. -* Changing a Variable:: How to edit a value and set an option. +* Groups: Customization Groups. How settings are classified in a structure. +* Browsing: Browsing Custom. Browsing and searching for settings. +* Changing a Variable:: How to edit an option's value and set the option. * Saving Customizations:: Specifying the file for saving customizations. * Face Customization:: How to edit the attributes of a face. * Specific Customization:: Making a customization buffer for specific @@ -220,9 +220,9 @@ the active fields and other features. @subsection Customization Groups @cindex customization groups - For customization purposes, user options are organized into -@dfn{groups} to help you find them. Groups are collected into bigger -groups, all the way up to a master group called @code{Emacs}. + For customization purposes, settings are organized into @dfn{groups} +to help you find them. Groups are collected into bigger groups, all +the way up to a master group called @code{Emacs}. @kbd{M-x customize} creates a customization buffer that shows the top-level @code{Emacs} group and the second-level groups immediately @@ -255,59 +255,57 @@ documentation string; the @code{Emacs} group also has a @samp{[State]} line. @cindex editable fields (customization buffer) -@cindex active fields (customization buffer) +@cindex buttons (customization buffer) Most of the text in the customization buffer is read-only, but it -typically includes some @dfn{editable fields} that you can edit. There -are also @dfn{active fields}; this means a field that does something -when you @dfn{invoke} it. To invoke an active field, either click on it -with @kbd{Mouse-1}, or move point to it and type @key{RET}. +typically includes some @dfn{editable fields} that you can edit. +There are also @dfn{buttons}, which do something when you @dfn{invoke} +them. To invoke a button, either click on it with @kbd{Mouse-1}, or +move point to it and type @key{RET}. For example, the phrase @samp{[Go to Group]} that appears in a -second-level group is an active field. Invoking the @samp{[Go to -Group]} field for a group creates a new customization buffer, which -shows that group and its contents. This field is a kind of hypertext -link to another group. +second-level group is a button. Invoking it creates a new +customization buffer, which shows that group and its contents. This +is a kind of hypertext link to another group. - The @code{Emacs} group includes a few user options itself, but -mainly it contains other groups, which contain more groups, which -contain the user options. By browsing the hierarchy of groups, you -will eventually find the feature you are interested in customizing. -Then you can use the customization buffer to set the options -pertaining to that feature. You can also go straight to a particular -group by name, using the command @kbd{M-x customize-group}. + The @code{Emacs} group includes a few settings, but mainly it +contains other groups, which contain more groups, which contain the +settings. By browsing the hierarchy of groups, you will eventually +find the feature you are interested in customizing. Then you can use +the customization buffer to set that feature's settings. You can also +go straight to a particular group by name, using the command @kbd{M-x +customize-group}. @node Browsing Custom @subsection Browsing and Searching for Options and Faces @findex customize-browse -You can use @kbd{M-x customize} to browse the groups and options, but -often @kbd{M-x customize-browse} is a more efficient alternative. -That is because it lets you view the structure of customization groups -on a larger scale. This command creates a special kind of -customization buffer which shows only the names of the groups (and -variables and faces), and their structure. + + @kbd{M-x customize-browse} is another way to browse the available +settings. This command creates a special customization buffer which +shows only the names of groups and settings, and puts them in a +structure. In this buffer, you can show the contents of a group by invoking @samp{[+]}. When the group contents are visible, this button changes to @samp{[-]}; invoking that hides the group contents. - Each group, variable, or face name in this buffer has an active field -which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking -that active field creates an ordinary customization buffer showing just -that group and its contents, just that variable, or just that face. -This is the way to set values in it. + Each setting in this buffer has a button which says @samp{[Group]}, +@samp{[Option]} or @samp{[Face]}. Invoking this button creates an +ordinary customization buffer showing just that group and its +contents, just that user option, or just that face. This is the way +to change settings that you find with @kbd{M-x customize-browse}. - If you can guess part of the name of the options you are interested -in, then sometimes @kbd{M-x customize-apropos} can be another useful -way to search for options. However, unlike @code{customize} and -@code{customize-browse}, @code{customize-apropos} can only find -options that are loaded in the current Emacs session. @xref{Specific -Customization,, Customizing Specific Items}. + If you can guess part of the name of the settings you are interested +in, @kbd{M-x customize-apropos} is another way to search for settings. +However, unlike @code{customize} and @code{customize-browse}, +@code{customize-apropos} can only find groups and settings that are +loaded in the current Emacs session. @xref{Specific Customization,, +Customizing Specific Items}. @node Changing a Variable @subsection Changing a Variable - Here is an example of what a variable looks like in the -customization buffer: + Here is an example of what a variable (a user option) looks like in +the customization buffer: @smallexample Kill Ring Max: [Hide Value] 60 @@ -321,34 +319,32 @@ the current value of the variable. If you see @samp{[Show Value]} instead of buffer initially hides values that take up several lines. Invoke @samp{[Show Value]} to show the value. - The line after the option name indicates the @dfn{customization state} -of the variable: in the example above, it says you have not changed the -option yet. The word @samp{[State]} at the beginning of this line is -active; you can get a menu of various operations by invoking it with -@kbd{Mouse-1} or @key{RET}. These operations are essential for -customizing the variable. + The line after the variable name indicates the @dfn{customization +state} of the variable: in the example above, it says you have not +changed the option yet. The @samp{[State]} button at the beginning of +this line gives you a menu of various operations for customizing the +variable. The line after the @samp{[State]} line displays the beginning of the variable's documentation string. If there are more lines of -documentation, this line ends with @samp{[More]}; invoke this to show -the full documentation string. +documentation, this line ends with a @samp{[More]} button; invoke that +to show the full documentation string. - To enter a new value for @samp{Kill Ring Max}, move point to the value -and edit it textually. For example, you can type @kbd{M-d}, then insert -another number. - - When you begin to alter the text, you will see the @samp{[State]} line -change to say that you have edited the value: + To enter a new value for @samp{Kill Ring Max}, move point to the +value and edit it textually. For example, you can type @kbd{M-d}, +then insert another number. As you begin to alter the text, you will +see the @samp{[State]} line change to say that you have edited the +value: @smallexample [State]: EDITED, shown value does not take effect until you set or @r{@dots{}} save it. @end smallexample -@cindex setting option value - Editing the value does not actually set the variable. To do -that, you must @dfn{set} it. To do this, invoke the word -@samp{[State]} and choose @samp{Set for Current Session}. +@cindex settings, how to set + Editing the value does not actually set the variable. To do that, +you must @dfn{set} the variable. To do this, invoke the +@samp{[State]} button and choose @samp{Set for Current Session}. The state of the variable changes visibly when you set it: @@ -357,23 +353,24 @@ that, you must @dfn{set} it. To do this, invoke the word @end smallexample You don't have to worry about specifying a value that is not valid; -setting the variable checks for validity and will not really install an -unacceptable value. +the @samp{Set for Current Session} operation checks for validity and +will not install an unacceptable value. @kindex M-TAB @r{(customization buffer)} @findex widget-complete - While editing a value or field that is a file name, directory name, + While editing a field that is a file name, directory name, command name, or anything else for which completion is defined, you can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. (@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) Some variables have a small fixed set of possible legitimate values. -These variables don't let you edit the value textually. Instead, an -active field @samp{[Value Menu]} appears before the value; invoke this -field to edit the value. For a boolean ``on or off'' value, the active -field says @samp{[Toggle]}, and it changes to the other value. -@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes -take effect when you use the @samp{Set for Current Session} operation. +These variables don't let you edit the value textually. Instead, a +@samp{[Value Menu]} button appears before the value; invoke this +button to change the value. For a boolean ``on or off'' value, the +button says @samp{[Toggle]}, and it changes to the other value. +@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the +changes take real effect when you use the @samp{Set for Current +Session} operation. Some variables have values with complex structure. For example, the value of @code{file-coding-system-alist} is an association list. Here @@ -408,10 +405,10 @@ where PATTERN is a regular expression matching a file name, @noindent Each association in the list appears on four lines, with several -editable or ``active'' fields. You can edit the regexps and coding +editable fields and/or buttons. You can edit the regexps and coding systems using ordinary editing commands. You can also invoke -@samp{[Value Menu]} to switch to a kind of value---for instance, to -specify a function instead of a pair of coding systems. +@samp{[Value Menu]} to switch to a different kind of value---for +instance, to specify a function instead of a pair of coding systems. To delete an association from the list, invoke the @samp{[DEL]} button for that item. To add an association, invoke @samp{[INS]} at the @@ -424,19 +421,19 @@ list. @kindex S-TAB @r{(customization buffer)} @findex widget-forward @findex widget-backward - Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for -moving through the customization buffer. @key{TAB} -(@code{widget-forward}) moves forward to the next active or editable -field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the -previous active or editable field. + Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful +for moving through the customization buffer. @key{TAB} +(@code{widget-forward}) moves forward to the next button or editable +field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to +the previous button or editable field. Typing @key{RET} on an editable field also moves forward, just like @key{TAB}. We set it up this way because people often type @key{RET} when they are finished editing a field. To insert a newline within an editable field, use @kbd{C-o} or @kbd{C-q C-j}. -@cindex saving variable value -@cindex customized variables, saving +@cindex saving a setting +@cindex settings, how to save Setting the variable changes its value in the current Emacs session; @dfn{saving} the value changes it for future sessions as well. To save the variable, invoke @samp{[State]} and select the @samp{Save for @@ -460,7 +457,7 @@ and updates the text accordingly. @item Erase Customization This sets the variable to its standard value, and updates the text -accordingly. This also eliminates any saved value for the option, +accordingly. This also eliminates any saved value for the variable, so that you will get the standard value in future Emacs sessions. @item Use Backup Value @@ -480,8 +477,7 @@ the same variable in a customization buffer, even in another session. The state of a group indicates whether anything in that group has been edited, set or saved. - Near the top of the customization buffer there are two lines -containing several active fields: + Near the top of the customization buffer there are two lines of buttons: @smallexample [Set for Current Session] [Save for Future Sessions] @@ -493,10 +489,10 @@ containing several active fields: Invoking @samp{[Finish]} either buries or kills this customization buffer according to the setting of the option @code{custom-buffer-done-kill}; the default is to bury the buffer. -Each of the other fields performs an operation---set, save or -reset---on each of the options in the buffer that could meaningfully -be set, saved or reset. They do not operate on options whose values -are hidden, nor on subgroups. +Each of the other buttons performs an operation---set, save or +reset---on each of the settings in the buffer that could meaningfully +be set, saved or reset. They do not operate on settings whose values +are hidden, nor on subgroups not visible in the buffer. @node Saving Customizations @subsection Saving Customizations @@ -572,11 +568,12 @@ Attributes: [ ] Font Family: * [ ] Inherit: * @end smallexample - Each face attribute has its own line. The @samp{[@var{x}]} field + Each face attribute has its own line. The @samp{[@var{x}]} button before the attribute name indicates whether the attribute is -@dfn{enabled}; @samp{X} means that it is. You can enable or disable the -attribute by invoking that field. When the attribute is enabled, you -can change the attribute value in the usual ways. +@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} +means that it's disabled. You can enable or disable the attribute by +clicking that button. When the attribute is enabled, you can change +the attribute value in the usual ways. For the colors, you can specify a color name (use @kbd{M-x list-colors-display} for a list of them) or a hexadecimal color @@ -608,9 +605,9 @@ to clear out the attribute. @node Specific Customization @subsection Customizing Specific Items - Instead of finding the options you want to change by moving down -through the structure of groups, you can specify the particular variable, -face, or group that you want to customize. + Instead of finding the setting you want to change by navigating the +structure of groups, here are other ways to specify the settings that +you want to customize. @table @kbd @item M-x customize-variable @key{RET} @var{variable} @key{RET} @@ -620,17 +617,17 @@ Set up a customization buffer with just one face, @var{face}. @item M-x customize-group @key{RET} @var{group} @key{RET} Set up a customization buffer with just one group, @var{group}. @item M-x customize-apropos @key{RET} @var{regexp} @key{RET} -Set up a customization buffer with all the variables, faces and groups -that match @var{regexp}. +Set up a customization buffer with all the settings and groups that +match @var{regexp}. @item M-x customize-changed-options @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the variables, faces and groups +Set up a customization buffer with all the settings and groups whose meaning has changed since Emacs version @var{version}. @item M-x customize-saved -Set up a customization buffer containing all variables and faces that you +Set up a customization buffer containing all settings that you have saved with customization buffers. @item M-x customize-customized -Set up a customization buffer containing all variables and faces that you -have customized but not saved. +Set up a customization buffer containing all settings that you have +customized but not saved. @end table @findex customize-variable @@ -639,8 +636,8 @@ buffer, and you know its name, you can use the command @kbd{M-x customize-variable} and specify the variable name. This sets up the customization buffer with just one variable---the one that you asked for. Editing, setting and saving the value work as described above, -but only for the specified variable. Minibuffer completion is very -handy if you only know part of the name. However, it only finds +but only for the specified variable. Minibuffer completion is handy +if you only know part of the name. However, this command can only see options that have been loaded in the current Emacs session. @findex customize-face @@ -651,57 +648,56 @@ on the character after point. @findex customize-group You can also set up the customization buffer with a specific group, using @kbd{M-x customize-group}. The immediate contents of the chosen -group, including user options, faces, and other groups, all appear +group, including variables, faces, and other groups, all appear as well (even if not already loaded). However, the subgroups' own contents are not included. @findex customize-apropos To control more precisely what to customize, you can use @kbd{M-x -customize-apropos}. You specify a regular expression as argument; then -all @emph{loaded} options, faces and groups whose names match this +customize-apropos}. You specify a regular expression as argument; +then all @emph{loaded} settings and groups whose names match this regular expression are set up in the customization buffer. If you -specify an empty regular expression, this includes @emph{all} groups, -options and faces (but that takes a long time). +specify an empty regular expression, this includes @emph{all} loaded +groups and settings---which takes a long time to set up. -@findex customize-changed-options +@findex customize-changed When you upgrade to a new Emacs version, you might want to customize -new options and options whose meanings or default values have changed. -To do this, use @kbd{M-x customize-changed-options} and specify a -previous Emacs version number using the minibuffer. It creates a -customization buffer which shows all the options (and groups) whose -definitions have been changed since the specified version. (Not just -those that are already loaded.) +new settings and settings whose meanings or default values have +changed. To do this, use @kbd{M-x customize-changed} and +specify a previous Emacs version number using the minibuffer. It +creates a customization buffer which shows all the settings and groups +whose definitions have been changed since the specified version, loading +them if necessary. @findex customize-saved @findex customize-customized - If you change option values and then decide the change was a -mistake, you can use two special commands to revisit your previous -changes. Use @kbd{M-x customize-saved} to look at the options that -you have saved. Use @kbd{M-x customize-customized} to look at the -options that you have set but not saved. + If you change settings and then decide the change was a mistake, you +can use two special commands to revisit your previous changes. Use +@kbd{M-x customize-saved} to look at the settings that you have saved. +Use @kbd{M-x customize-customized} to look at the settings that you +have set but not saved. @node Custom Themes @subsection Customization Themes @cindex custom themes -@dfn{Custom themes} are collections of customized options that can be -enabled or disabled as a unit. You can use Custom themes to switch -quickly and easily between various collections of settings, and to -transfer such collections from one computer to another. + @dfn{Custom themes} are collections of settings that can be enabled +or disabled as a unit. You can use Custom themes to switch quickly +and easily between various collections of settings, and to transfer +such collections from one computer to another. @findex customize-create-theme -To define a Custom theme, use the command -@kbd{M-x customize-create-theme}, which brings up a buffer named -@samp{*New Custom Theme*}. At the top of the buffer is an editable -field where you can specify the name of the theme. To add a -customization option to the theme, click on the @samp{INS} button to -open up a field where you can insert the name of the option. The -current value of that option is applied to the theme. After adding as -many options as you like, click on @samp{Done} to save the Custom -theme. + To define a Custom theme, use the command @kbd{M-x +customize-create-theme}, which brings up a buffer named @samp{*New +Custom Theme*}. At the top of the buffer is an editable field where +you can specify the name of the theme. To add a customization option +to the theme, click on the @samp{INS} button to open up a field where +you can insert the name of the option. The current value of that +option is applied to the theme. After adding as many options as you +like, click on @samp{Done} to save the Custom theme. @vindex custom-theme-directory -Saving a Custom theme named @var{foo} writes its definition into the + Saving a Custom theme named @var{foo} writes its definition into the file @file{@var{foo}-theme.el}, in the directory @file{~/.emacs.d/} (you can specify the directory by setting @code{custom-theme-directory}). @@ -747,25 +743,26 @@ variable names consist of words separated by hyphens. A variable can have a documentation string which describes what kind of value it should have and how the value will be used. - Lisp allows any variable to have any kind of value, but most variables -that Emacs uses need a value of a certain type. Often the value should -always be a string, or should always be a number. Sometimes we say that a -certain feature is turned on if a variable is ``non-@code{nil},'' meaning -that if the variable's value is @code{nil}, the feature is off, but the -feature is on for @emph{any} other value. The conventional value to use to -turn on the feature---since you have to pick one particular value when you -set the variable---is @code{t}. + Emacs Lisp allows any variable (with a few exceptions) to have any +kind of value, but most variables that Emacs uses need a value of a +certain type. Often the value should always be a string, or should +always be a number. Sometimes we say that a certain feature is turned +on if a variable is ``non-@code{nil},'' meaning that if the variable's +value is @code{nil}, the feature is off, but the feature is on for +@emph{any} other value. The conventional value to use to turn on the +feature---since you have to pick one particular value when you set the +variable---is @code{t}. Emacs uses many Lisp variables for internal record keeping, but the -most interesting variables for a non-programmer user are those that -are also @dfn{user options}, the variables that are meant for users to -change. Each user option that you can set with the customization -buffer is (if it is not a face) in fact a Lisp variable. Emacs does -not (usually) change the values of these variables; instead, you set -the values, and thereby alter and control the behavior of certain -Emacs commands. Use of the customization buffer is explained above -(@pxref{Easy Customization}); here we describe other aspects of Emacs -variables. +most interesting variables for a non-programmer user are those meant +for users to change---the @dfn{user options}. + + Each user option that you can set with the customization buffer is +in fact a Lisp variable. Emacs does not (usually) change the values +of these variables; instead, you set the values, and thereby alter and +control the behavior of certain Emacs commands. Use of the +customization buffer is explained above (@pxref{Easy Customization}); +here we describe other aspects of Emacs variables. @menu * Examining:: Examining or setting one variable's value.