# HG changeset patch # User Richard M. Stallman # Date 1102256090 0 # Node ID 25b217a7d2af7f6e04c9b5b0ed667e2061a60b38 # Parent 770cf3ce5391e1b16a866b9352f24f88db88ba27 (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". diff -r 770cf3ce5391 -r 25b217a7d2af man/custom.texi --- a/man/custom.texi Sun Dec 05 14:03:06 2004 +0000 +++ b/man/custom.texi Sun Dec 05 14:14:50 2004 +0000 @@ -27,6 +27,8 @@ @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. * Variables:: Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning. @@ -171,132 +173,28 @@ The advantage of Transient Mark mode is that Emacs can display the region highlighted (currently only when using X). @xref{Mark}. -@node Variables -@section Variables -@cindex variable -@cindex option, user -@cindex user option - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the name of the variable. A variable name can -contain any characters that can appear in a file, but conventionally -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 require 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, as any -Lisp program must, but the most interesting variables for you are the -ones that exist for the sake of customization. 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. These -variables are called @dfn{user options}. Most user options are -documented in this manual, and appear in the Variable Index -(@pxref{Variable Index}). - - One example of a variable which is a user option is @code{fill-column}, which -specifies the position of the right margin (as a number of characters from -the left margin) to be used by the fill commands (@pxref{Filling}). - -@menu -* Examining:: Examining or setting one variable's value. -* Easy Customization:: - Convenient and easy customization of variables. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables +@node Easy Customization +@section Easy Customization Interface -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a single variable, use @kbd{C-h v} -(@code{describe-variable}), which reads a variable name using the -minibuffer, with completion. It displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@smallexample -fill-column's value is 70 - -Documentation: -*Column beyond which automatic line-wrapping should happen. -Automatically becomes buffer-local when set in any fashion. -@end smallexample - -@noindent -The star at the beginning of the documentation indicates that this -variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows any variable name. - -@findex set-variable - The most convenient way to set a specific user option is with @kbd{M-x -set-variable}. This reads the variable name with the minibuffer (with -completion), and then reads a Lisp expression for the new value using -the minibuffer a second time. For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to user option variables, but you can -set any variable with a Lisp expression, using the function @code{setq}. -Here is a @code{setq} expression to set @code{fill-column}: - -@example -(setq fill-column 75) -@end example - - To execute an expression like this one, go to the @samp{*scratch*} -buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp -Interaction}. - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. - -@node Easy Customization -@subsection 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. Most user options are +documented in this manual. Each user option is actually a Lisp +variable (@pxref{Variables}), so their names appear in the Variable +Index (@pxref{Variable Index}). @findex customize @cindex customization buffer - A convenient way to find the user option variables that you want to -change, and then change them, is with @kbd{M-x customize}. This -command creates a @dfn{customization buffer} with which you can browse -through the Emacs user options in a logically organized structure, -then edit and set their values. You can also use the customization -buffer to save settings permanently in your @file{~/.emacs} file -(@pxref{Init File}). + You can browse interactively through the 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}). -The appearance of the example buffers in the following is typically -different under a window system where faces can be used to indicate the -active fields and other features. + 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. @menu * Groups: Customization Groups. @@ -309,7 +207,7 @@ @end menu @node Customization Groups -@subsubsection Customization Groups +@subsection Customization Groups @cindex customization groups For customization purposes, user options are organized into @@ -389,7 +287,7 @@ This is the way to set values in it. @node Changing an Option -@subsubsection Changing an Option +@subsection Changing an Option Here is an example of what a user option looks like in the customization buffer: @@ -411,7 +309,7 @@ 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. +customizing the user option. The line after the @samp{[State]} line displays the beginning of the option's documentation string. If there are more lines of @@ -430,7 +328,7 @@ @end smallexample @cindex setting option value - Editing the value does not actually set the option variable. To do + Editing the value does not actually set the option. To do that, you must @dfn{set} the option. To do this, invoke the word @samp{[State]} and choose @samp{Set for Current Session}. @@ -523,7 +421,7 @@ @dfn{saving} the value changes it for future sessions as well. To save the option, invoke @samp{[State]} and select the @samp{Save for Future Sessions} operation. This works by writing code so as to set -the option variable again each time you start Emacs (@pxref{Saving +the option again, each time you start Emacs (@pxref{Saving Customizations}). You can also restore the option to its standard value by invoking @@ -547,8 +445,8 @@ @item Use Backup Value This sets the option to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset the variable, which discards the customized value, +customization buffer in this session. If you customize an option +and then reset it, which discards the customized value, you can get the customized value back again with this operation. @end table @@ -583,7 +481,7 @@ set, saved or reset. @node Saving Customizations -@subsubsection Saving Customizations +@subsection Saving Customizations @vindex custom-file The customization buffer normally saves customizations in @@ -615,7 +513,7 @@ customizations you might have on your init file. @node Face Customization -@subsubsection Customizing Faces +@subsection Customizing Faces @cindex customizing faces @cindex bold font @cindex italic font @@ -676,7 +574,7 @@ to clear out the attribute. @node Specific Customization -@subsubsection Customizing Specific Items +@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 option, @@ -704,7 +602,7 @@ @end table @findex customize-option - If you want to alter a particular user option variable with the + If you want to alter a particular user option with the customization buffer, and you know its name, you can use the command @kbd{M-x customize-option} and specify the option name. This sets up the customization buffer with just one option---the one that you asked @@ -719,7 +617,7 @@ @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 option variables, faces, and other groups, all appear +group, including user options, faces, and other groups, all appear as well. However, these subgroups' own contents start out hidden. You can show their contents in the usual way, by invoking @samp{[Show]}. @@ -747,6 +645,111 @@ saved. Use @kbd{M-x customize-customized} to look at the options and faces that you have set but not saved. +@node Variables +@section Variables +@cindex variable +@cindex option, user +@cindex user option + + A @dfn{variable} is a Lisp symbol which has a value. The symbol's +name is also called the name of the variable. A variable name can +contain any characters that can appear in a file, but conventionally +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 uses many Lisp variables for internal record keeping, but the +most interesting variables for a non-programmer user are the @dfn{user +options}, the variables that are meant for users to change. Each user +option that you can set with the customization buffera 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; here we describe other aspects of Emacs +variables. + +@menu +* Examining:: Examining or setting one variable's value. +* Hooks:: Hook variables let you specify programs for parts + of Emacs to run on particular occasions. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. +@end menu + +@node Examining +@subsection Examining and Setting Variables +@cindex setting variables + +@table @kbd +@item C-h v @var{var} @key{RET} +Display the value and documentation of variable @var{var} +(@code{describe-variable}). +@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} +Change the value of variable @var{var} to @var{value}. +@end table + + To examine the value of a single variable, use @kbd{C-h v} +(@code{describe-variable}), which reads a variable name using the +minibuffer, with completion. It displays both the value and the +documentation of the variable. For example, + +@example +C-h v fill-column @key{RET} +@end example + +@noindent +displays something like this: + +@smallexample +fill-column's value is 70 + +Documentation: +*Column beyond which automatic line-wrapping should happen. +Automatically becomes buffer-local when set in any fashion. +@end smallexample + +@noindent +The star at the beginning of the documentation indicates that this +variable is a user option. @kbd{C-h v} is not restricted to user +options; it allows any variable name. + +@findex set-variable + The most convenient way to set a specific user option is with @kbd{M-x +set-variable}. This reads the variable name with the minibuffer (with +completion), and then reads a Lisp expression for the new value using +the minibuffer a second time. For example, + +@example +M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} +@end example + +@noindent +sets @code{fill-column} to 75. + + @kbd{M-x set-variable} is limited to user option variables, but you can +set any variable with a Lisp expression, using the function @code{setq}. +Here is a @code{setq} expression to set @code{fill-column}: + +@example +(setq fill-column 75) +@end example + + To execute an expression like this one, go to the @samp{*scratch*} +buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp +Interaction}. + + Setting variables, like all means of customizing Emacs except where +otherwise stated, affects only the current Emacs session. + @node Hooks @subsection Hooks @cindex hook