xemacs-beta: man/xemacs/custom.texi comparison

comparison man/xemacs/custom.texi @ 428:3ecd8885ac67 r21-2-22

Import from CVS: tag r21-2-22

author	cvs
date	Mon, 13 Aug 2007 11:28:15 +0200
parents
children	84b14dcb0985

comparison

equal deleted inserted replaced

-:0a0253eac470
+:3ecd8885ac67
+@node Customization, Quitting, Emulation, Top
+@chapter Customization
+@cindex customization
+This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways.
+All kinds of customization affect only the particular Emacs job that you
+do them in.  They are completely lost when you kill the Emacs job, and have
+no effect on other Emacs jobs you may run at the same time or later.  The
+only way an Emacs job can affect anything outside of it is by writing a
+file; in particular, the only way to make a customization `permanent' is to
+put something in your @file{.emacs} file or other appropriate file to do the
+customization in each session.  @xref{Init File}.
+@menu
+* Minor Modes::     Each minor mode is one feature you can turn on
+independently of any others.
+* Variables::       Many Emacs commands examine Emacs variables
+to decide what to do; by setting variables,
+you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
+to be replayed with a single command.
+* Key Bindings::    The keymaps say what command each key runs.
+By changing them, you can "redefine keys".
+* Syntax::          The syntax table controls how words and expressions
+are parsed.
+* Init File::       How to write common customizations in the @file{.emacs}
+file.
+* Audible Bell::    Changing how Emacs sounds the bell.
+* Faces::           Changing the fonts and colors of a region of text.
+* X Resources::	    X resources controlling various aspects of the
+behavior of XEmacs.
+@end menu
+@node Minor Modes
+@section Minor Modes
+@cindex minor modes
+@cindex mode line
+Minor modes are options which you can use or not.  For example, Auto
+Fill mode is a minor mode in which @key{SPC} breaks lines between words
+as you type.  All the minor modes are independent of each other and of
+the selected major mode.  Most minor modes inform you in the mode line
+when they are on; for example, @samp{Fill} in the mode line means that
+Auto Fill mode is on.
+Append @code{-mode} to the name of a minor mode to get the name of a
+command function that turns the mode on or off.  Thus, the command to
+enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These
+commands are usually invoked with @kbd{M-x}, but you can bind keys to them
+if you wish.  With no argument, the function turns the mode on if it was
+off and off if it was on.  This is known as @dfn{toggling}.  A positive
+argument always turns the mode on, and an explicit zero argument or a
+negative argument always turns it off.
+@cindex Auto Fill mode
+@findex auto-fill-mode
+Auto Fill mode allows you to enter filled text without breaking lines
+explicitly.  Emacs inserts newlines as necessary to prevent lines from
+becoming too long.  @xref{Filling}.
+@cindex Overwrite mode
+@findex overwrite-mode
+Overwrite mode causes ordinary printing characters to replace existing
+text instead of moving it to the right.  For example, if point is in
+front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite
+mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill
+@cindex Abbrev mode
+@findex abbrev-mode
+Abbrev mode allows you to define abbreviations that automatically expand
+as you type them.  For example, @samp{amd} might expand to @samp{abbrev
+mode}.  @xref{Abbrevs}, for full information.
+@node Variables
+@section Variables
+@cindex variable
+@cindex option
+A @dfn{variable} is a Lisp symbol which has a value.  Variable names
+can contain any characters, but by convention they are words separated
+by hyphens.  A variable can also 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 has
+to be a string or 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 @i{any} other value.  The conventional value 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 recordkeeping, 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{options}.  Most options are documented in this manual and
+appear in the Variable Index (@pxref{Variable Index}).
+One example of a variable which is an 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.
+* Edit Options::        Examining or editing list of all variables' values.
+* 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
+@itemx M-x describe-variable
+Print the value and documentation of a variable.
+@findex set-variable
+@item M-x set-variable
+Change the value of a variable.
+@end table
+@kindex C-h v
+@findex describe-variable
+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 prints both the value and the
+documentation of the variable.
+@example
+C-h v fill-column @key{RET}
+@end example
+@noindent
+prints something like:
+@smallexample
+fill-column's value is 75
+Documentation:
+*Column beyond which automatic line-wrapping should happen.
+Automatically becomes local when set in any fashion.
+@end smallexample
+@cindex option
+@noindent
+The star at the beginning of the documentation indicates that this variable
+is an option.  @kbd{C-h v} is not restricted to options; it allows any
+variable name.
+@findex set-variable
+If you know which option you want to set, you can use @kbd{M-x
+set-variable} to set it.  This prompts for the variable name in the
+minibuffer (with completion), and then prompts for 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, as if you had executed the Lisp expression
+@code{(setq fill-column 75)}.
+Setting variables in this way, like all means of customizing Emacs
+except where explicitly stated, affects only the current Emacs session.
+@node Easy Customization
+@subsection Easy Customization Interface
+@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.  (Not all Emacs user options are included in this
+structure as of yet, but we are adding the rest.)
+@menu
+* Groups: Customization Groups.
+How options are classified in a structure.
+* Changing an Option::       How to edit a value and set an option.
+* Face Customization::       How to edit the attributes of a face.
+* Specific Customization::   Making a customization buffer for specific
+options, faces, or groups.
+@end menu
+@node Customization Groups
+@subsubsection 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}.
+@kbd{M-x customize} creates a customization buffer that shows the
+top-level @code{Emacs} group and the second-level groups immediately
+under it.  It looks like this, in part:
+@smallexample
+/- Emacs group: ---------------------------------------------------\
+[State]: visible group members are all at standard settings.
+Customization of the One True Editor.
+See also [Manual].
+[Open] Editing group
+Basic text editing facilities.
+[Open] External group
+Interfacing to external utilities.
+@var{more second-level groups}
+\- Emacs group end ------------------------------------------------/
+@end smallexample
+@noindent
+This says that the buffer displays the contents of the @code{Emacs}
+group.  The other groups are listed because they are its contents.  But
+they are listed differently, without indentation and dashes, because
+@emph{their} contents are not included.  Each group has a single-line
+documentation string; the @code{Emacs} group also has a @samp{[State]}
+line.
+@cindex editable fields (customization buffer)
+@cindex active fields (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}.
+For example, the phrase @samp{[Open]} that appears in a second-level
+group is an active field.  Invoking the @samp{[Open]} field for a group
+opens up a new customization buffer, which shows that group and its
+contents.  This field is a kind of hypertext link to another group.
+The @code{Emacs} group does not include any user options itself, but
+other groups do.  By examining various groups, you will eventually find
+the options and faces that belong to the feature you are interested in
+customizing.  Then you can use the customization buffer to set them.
+@findex customize-browse
+You can view the structure of customization groups on a larger scale
+with @kbd{M-x customize-browse}.  This command creates a special kind of
+customization buffer which shows only the names of the groups (and
+options and faces), and their 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, option 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 option, or just that face.
+This is the way to set values in it.
+@node Changing an Option
+@subsubsection Changing an Option
+Here is an example of what a user option looks like in the
+customization buffer:
+@smallexample
+Kill Ring Max: [Hide] 30
+[State]: this option is unchanged from its standard setting.
+Maximum length of kill ring before oldest elements are thrown away.
+@end smallexample
+The text following @samp{[Hide]}, @samp{30} in this case, indicates
+the current value of the option.  If you see @samp{[Show]} instead of
+@samp{[Hide]}, it means that the value is hidden; the customization
+buffer initially hides values that take up several lines.  Invoke
+@samp{[Show]} to show the value.
+The line after the option name indicates the @dfn{customization state}
+of the option: 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 @samp{[State]} line displays the beginning of the
+option's documentation string.  If there are more lines of
+documentation, this line ends with @samp{[More]}; invoke this 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:
+@smallexample
+[State]: you have edited the value as text, but not set the option.
+@end smallexample
+@cindex setting option value
+Editing the value does not actually set the option variable.  To do
+that, you must @dfn{set} the option.  To do this, invoke the word
+@samp{[State]} and choose @samp{Set for Current Session}.
+The state of the option changes visibly when you set it:
+@smallexample
+[State]: you have set this option, but not saved it for future sessions.
+@end smallexample
+You don't have to worry about specifying a value that is not valid;
+setting the option checks for validity and will not really 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,
+command name, or anything else for which completion is defined, you can
+type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
+Some options have a small fixed set of possible legitimate values.
+These options 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.
+Some options have values with complex structure.  For example, the
+value of @code{load-path} is a list of directories.  Here is how it
+appears in the customization buffer:
+@smallexample
+Load Path:
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
+[INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
+[INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
+[INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
+[INS]
+[State]: this item has been changed outside the customization buffer.
+List of directories to search for files to load....
+@end smallexample
+@noindent
+Each directory in the list appears on a separate line, and each line has
+several editable or active fields.
+You can edit any of the directory names.  To delete a directory from
+the list, invoke @samp{[DEL]} on that line.  To insert a new directory in
+the list, invoke @samp{[INS]} at the point where you want to insert it.
+You can also invoke @samp{[Current dir?]} to switch between including
+a specific named directory in the path, and including @code{nil} in the
+path.  (@code{nil} in a search path means ``try the current
+directory.'')
+@kindex TAB @r{(customization buffer)}
+@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.
+Typing @key{RET} on an editable field also moves forward, just like
+@key{TAB}.  The reason for this is that people have a tendency to type
+@key{RET} when they are finished editing a field.  If you have occasion
+to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
+C-j},
+@cindex saving option value
+Setting the option changes its value in the current Emacs session;
+@dfn{saving} the value changes it for future sessions as well.  This
+works by writing code into your @file{~/.emacs} file so as to set the
+option variable again each time you start Emacs.  To save the option,
+invoke @samp{[State]} and select the @samp{Save for Future Sessions}
+operation.
+You can also restore the option to its standard value by invoking
+@samp{[State]} and selecting the @samp{Reset} operation.  There are
+actually three reset operations:
+@table @samp
+@item Reset to Current
+If you have made some modifications and not yet set the option,
+this restores the text in the customization buffer to match
+the actual value.
+@item Reset to Saved
+This restores the value of the option to the last saved value,
+and updates the text accordingly.
+@item Reset to Standard Settings
+This sets the option to its standard value, and updates the text
+accordingly.  This also eliminates any saved value for the option,
+so that you will get the standard value in future Emacs sessions.
+@end table
+The state of a group indicates whether anything in that group has been
+edited, set or saved.  You can select @samp{Set for Current Session},
+@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.
+Near the top of the customization buffer there are two lines
+containing several active fields:
+@smallexample
+[Set] [Save] [Reset]  [Done]
+@end smallexample
+@noindent
+Invoking @samp{[Done]} buries this customization buffer.  Each of the
+other fields performs an operation---set, save or reset---on each of the
+items in the buffer that could meaningfully be set, saved or reset.
+@node Face Customization
+@subsubsection Customizing Faces
+@cindex customizing faces
+@cindex bold font
+@cindex italic font
+@cindex fonts and faces
+In addition to user options, some customization groups also include
+faces.  When you show the contents of a group, both the user options and
+the faces in the group appear in the customization buffer.  Here is an
+example of how a face looks:
+@smallexample
+Custom Changed Face: (sample)
+[State]: this face is unchanged from its standard setting.
+Face used when the customize item has been changed.
+Parent groups: [Custom Magic Faces]
+Attributes: [ ] Bold: [Toggle]  off (nil)
+[ ] Italic: [Toggle]  off (nil)
+[ ] Underline: [Toggle]  off (nil)
+[ ] Foreground: white       (sample)
+[ ] Background: blue        (sample)
+[ ] Inverse: [Toggle]  off (nil)
+[ ] Stipple:
+[ ] Font Family:
+[ ] Size:
+[ ] Strikethru: off
+@end smallexample
+Each face attribute has its own line.  The @samp{[@var{x}]} field
+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.
+@c Is this true for XEmacs?
+@c  On a black-and-white display, the colors you can use for the
+@c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
+@c and @samp{gray3}.  Emacs supports these shades of gray by using
+@c background stipple patterns instead of a color.
+@c
+Setting, saving and resetting a face work like the same operations for
+options (@pxref{Changing an Option}).
+A face can specify different appearances for different types of
+display.  For example, a face can make text red on a color display, but
+use a bold font on a monochrome display.  To specify multiple
+appearances for a face, select @samp{Show Display Types} in the menu you
+get from invoking @samp{[State]}.
+@c It would be cool to implement this
+@c @findex modify-face
+@c   Another more basic way to set the attributes of a specific face is
+@c with @kbd{M-x modify-face}.  This command reads the name of a face, then
+@c reads the attributes one by one.  For the color and stipple attributes,
+@c the attribute's current value is the default---type just @key{RET} if
+@c you don't want to change that attribute.  Type @samp{none} if you want
+@c to clear out the attribute.
+@node Specific Customization
+@subsubsection 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,
+face or group that you want to customize.
+@table @kbd
+@item M-x customize-option @key{RET} @var{option} @key{RET}
+Set up a customization buffer with just one option, @var{option}.
+@item M-x customize-face @key{RET} @var{face} @key{RET}
+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 options, faces and groups
+that match @var{regexp}.
+@item M-x customize-saved
+Set up a customization buffer containing all options and faces that you
+have saved with customization buffers.
+@item M-x customize-customized
+Set up a customization buffer containing all options and faces that you
+have customized but not saved.
+@end table
+@findex customize-option
+If you want to alter a particular user option variable 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
+for.  Editing, setting and saving the value work as described above, but
+only for the specified option.
+@findex customize-face
+Likewise, you can modify a specific face, chosen by name, using
+@kbd{M-x customize-face}.
+@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
+as well.  However, these subgroups' own contents start out hidden.  You
+can show their contents in the usual way, by invoking @samp{[Show]}.
+@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 options, faces 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 in the
+customization buffer (but that takes a long time).
+@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{customize-saved} to look at the options and faces that you have
+saved.  Use @kbd{M-x customize-customized} to look at the options and
+faces that you have set but not saved.
+@node Edit Options
+@subsection Editing Variable Values
+@table @kbd
+@item M-x list-options
+Display a buffer listing names, values, and documentation of all options.
+@item M-x edit-options
+Change option values by editing a list of options.
+@end table
+@findex list-options
+@kbd{M-x list-options} displays a list of all Emacs option variables in
+an Emacs buffer named @samp{*List Options*}.  Each option is shown with its
+documentation and its current value.  Here is what a portion of it might
+look like:
+@smallexample
+;; exec-path:
+("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
+*List of directories to search programs to run in subprocesses.
+Each element is a string (directory name)
+or nil (try the default directory).
+;;
+;; fill-column:
+75
+*Column beyond which automatic line-wrapping should happen.
+Automatically becomes local when set in any fashion.
+;;
+@end smallexample
+@findex edit-options
+@kbd{M-x edit-options} goes one step further and immediately selects the
+@samp{*List Options*} buffer; this buffer uses the major mode Options mode,
+which provides commands that allow you to point at an option and change its
+value:
+@table @kbd
+@item s
+Set the variable point is in or near to a new value read using the
+minibuffer.
+@item x
+Toggle the variable point is in or near: if the value was @code{nil},
+it becomes @code{t}; otherwise it becomes @code{nil}.
+@item 1
+Set the variable point is in or near to @code{t}.
+@item 0
+Set the variable point is in or near to @code{nil}.
+@item n
+@itemx p
+Move to the next or previous variable.
+@end table
+@node Locals
+@subsection Local Variables
+@table @kbd
+@item M-x make-local-variable
+Make a variable have a local value in the current buffer.
+@item M-x kill-local-variable
+Make a variable use its global value in the current buffer.
+@item M-x make-variable-buffer-local
+Mark a variable so that setting it will make it local to the
+buffer that is current at that time.
+@end table
+@cindex local variables
+You can make any variable @dfn{local} to a specific Emacs buffer.
+This means that the variable's value in that buffer is independent of
+its value in other buffers.  A few variables are always local in every
+buffer.  All other Emacs variables have a @dfn{global} value which is in
+effect in all buffers that have not made the variable local.
+Major modes always make the variables they set local to the buffer.
+This is why changing major modes in one buffer has no effect on other
+buffers.
+@findex make-local-variable
+@kbd{M-x make-local-variable} reads the name of a variable and makes it
+local to the current buffer.  Further changes in this buffer will not
+affect others, and changes in the global value will not affect this
+buffer.
+@findex make-variable-buffer-local
+@cindex per-buffer variables
+@kbd{M-x make-variable-buffer-local} reads the name of a variable and
+changes the future behavior of the variable so that it automatically
+becomes local when it is set.  More precisely, once you have marked a
+variable in this way, the usual ways of setting the
+variable will automatically invoke @code{make-local-variable} first.  We
+call such variables @dfn{per-buffer} variables.
+Some important variables have been marked per-buffer already.  They
+include @code{abbrev-mode}, @code{auto-fill-function},
+@code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
+@code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
+@code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode},
+@code{selective-display-ellipses}, @*@code{selective-display},
+@code{tab-width}, and @code{truncate-lines}.  Some other variables are
+always local in every buffer, but they are used for internal
+purposes.@refill
+Note: the variable @code{auto-fill-function} was formerly named
+@code{auto-fill-hook}.
+@findex kill-local-variable
+If you want a variable to cease to be local to the current buffer,
+call @kbd{M-x kill-local-variable} and provide the name of a variable to
+the prompt.  The global value of the variable
+is again in effect in this buffer.  Setting the major mode kills all
+the local variables of the buffer.
+@findex setq-default
+To set the global value of a variable, regardless of whether the
+variable has a local value in the current buffer, you can use the
+Lisp function @code{setq-default}.  It works like @code{setq}.
+If there is a local value in the current buffer, the local value is
+not affected by @code{setq-default}; thus, the new global value may
+not be visible until you switch to another buffer, as in the case of:
+@example
+(setq-default fill-column 75)
+@end example
+@noindent
+@code{setq-default} is the only way to set the global value of a variable
+that has been marked with @code{make-variable-buffer-local}.
+@findex default-value
+Programs can look at a variable's default value with @code{default-value}.
+This function takes a symbol as an argument and returns its default value.
+The argument is evaluated; usually you must quote it explicitly, as in
+the case of:
+@example
+(default-value 'fill-column)
+@end example
+@node File Variables
+@subsection Local Variables in Files
+@cindex local variables in files
+A file can contain a @dfn{local variables list}, which specifies the
+values to use for certain Emacs variables when that file is edited.
+Visiting the file checks for a local variables list and makes each variable
+in the list local to the buffer in which the file is visited, with the
+value specified in the file.
+A local variables list goes near the end of the file, in the last page.
+(It is often best to put it on a page by itself.)  The local variables list
+starts with a line containing the string @samp{Local Variables:}, and ends
+with a line containing the string @samp{End:}.  In between come the
+variable names and values, one set per line, as @samp{@var{variable}:@:
+@var{value}}.  The @var{value}s are not evaluated; they are used literally.
+The line which starts the local variables list does not have to say
+just @samp{Local Variables:}.  If there is other text before @samp{Local
+Variables:}, that text is called the @dfn{prefix}, and if there is other
+text after, that is called the @dfn{suffix}.  If a prefix or suffix are
+present, each entry in the local variables list should have the prefix
+before it and the suffix after it.  This includes the @samp{End:} line.
+The prefix and suffix are included to disguise the local variables list
+as a comment so the compiler or text formatter  will ignore it.
+If you do not need to disguise the local variables list as a comment in
+this way, there is no need to include a prefix or a suffix.@refill
+Two ``variable'' names are special in a local variables list: a value
+for the variable @code{mode} sets the major mode, and a value for the
+variable @code{eval} is simply evaluated as an expression and the value
+is ignored.  These are not real variables; setting them in any other
+context does not have the same effect.  If @code{mode} is used in a
+local variables list, it should be the first entry in the list.
+Here is an example of a local variables list:
+@example
+;;; Local Variables: ***
+;;; mode:lisp ***
+;;; comment-column:0 ***
+;;; comment-start: ";;; "  ***
+;;; comment-end:"***" ***
+;;; End: ***
+@end example
+Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.
+Note also that comments in the file begin with and end with the same
+strings.  Presumably the file contains code in a language which is
+enough like Lisp for Lisp mode to be useful but in which comments
+start and end differently.  The prefix and suffix are used in the local
+variables list to make the list look like several lines of comments when
+the compiler or interpreter for that language reads the file.
+The start of the local variables list must be no more than 3000
+characters from the end of the file, and must be in the last page if the
+file is divided into pages.  Otherwise, Emacs will not notice it is
+there.  The purpose is twofold: a stray @samp{Local Variables:}@: not in
+the last page does not confuse Emacs, and Emacs never needs to search a
+long file that contains no page markers and has no local variables list.
+You may be tempted to turn on Auto Fill mode with a local variable
+list.  That is inappropriate.  Whether you use Auto Fill mode or not is
+a matter of personal taste, not a matter of the contents of particular
+files.  If you want to use Auto Fill, set up major mode hooks with your
+@file{.emacs} file to turn it on (when appropriate) for you alone
+(@pxref{Init File}).  Don't try to use a local variable list that would
+impose your taste on everyone working with the file.
+XEmacs allows you to specify local variables in the first line
+of a file, in addition to specifying them in the @code{Local Variables}
+section at the end of a file.
+If the first line of a file contains two occurrences of @code{`-*-'},
+XEmacs uses the information between them to determine what the major
+mode and variable settings should be.  For example, these are all legal:
+@example
+	;;; -*- mode: emacs-lisp -*-
+	;;; -*- mode: postscript; version-control: never -*-
+	;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
+@end example
+For historical reasons, the syntax @code{`-*- modename -*-'} is allowed
+as well; for example, you can use:
+@example
+	;;; -*- emacs-lisp -*-
+@end example
+@vindex enable-local-variables
+The variable @code{enable-local-variables} controls the use of local
+variables lists in files you visit.  The value can be @code{t},
+@code{nil}, or something else.  A value of @code{t} means local variables
+lists are obeyed; @code{nil} means they are ignored; anything else means
+query.
+The command @code{M-x normal-mode} always obeys local variables lists
+and ignores this variable.
+@node Keyboard Macros
+@section Keyboard Macros
+@cindex keyboard macros
+A @dfn{keyboard macro} is a command defined by the user to abbreviate a
+sequence of keys.  For example, if you discover that you are about to type
+@kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
+macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty.
+@c widecommands
+@table @kbd
+@item C-x (
+Start defining a keyboard macro (@code{start-kbd-macro}).
+@item C-x )
+End the definition of a keyboard macro (@code{end-kbd-macro}).
+@item C-x e
+Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
+@item C-u C-x (
+Re-execute last keyboard macro, then add more keys to its definition.
+@item C-x q
+When this point is reached during macro execution, ask for confirmation
+(@code{kbd-macro-query}).
+@item M-x name-last-kbd-macro
+Give a command name (for the duration of the session) to the most
+recently defined keyboard macro.
+@item M-x insert-kbd-macro
+Insert in the buffer a keyboard macro's definition, as Lisp code.
+@end table
+Keyboard macros differ from other Emacs commands in that they are
+written in the Emacs command language rather than in Lisp.  This makes it
+easier for the novice to write them and makes them more convenient as
+temporary hacks.  However, the Emacs command language is not powerful
+enough as a programming language to be useful for writing anything
+general or complex.  For such things, Lisp must be used.
+You define a keyboard macro by executing the commands which are its
+definition.  Put differently, as you are defining a keyboard macro, the
+definition is being executed for the first time.  This way, you see
+what the effects of your commands are, and don't have to figure
+them out in your head.  When you are finished, the keyboard macro is
+defined and also has been executed once.  You can then execute the same
+set of commands again by invoking the macro.
+@menu
+* Basic Kbd Macro::     Defining and running keyboard macros.
+* Save Kbd Macro::      Giving keyboard macros names; saving them in files.
+* Kbd Macro Query::     Keyboard macros that do different things each use.
+@end menu
+@node Basic Kbd Macro
+@subsection Basic Use
+@kindex C-x (
+@kindex C-x )
+@kindex C-x e
+@findex start-kbd-macro
+@findex end-kbd-macro
+@findex call-last-kbd-macro
+To start defining a keyboard macro, type @kbd{C-x (}
+(@code{start-kbd-macro}).  From then on, anything you type continues to be
+executed, but also becomes part of the definition of the macro.  @samp{Def}
+appears in the mode line to remind you of what is going on.  When you are
+finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
+definition, without becoming part of it.
+For example,
+@example
+C-x ( M-f foo C-x )
+@end example
+@noindent
+defines a macro to move forward a word and then insert @samp{foo}.
+You can give @kbd{C-x )} a repeat count as an argument, in which case it
+repeats the macro that many times right after defining it, but defining
+the macro counts as the first repetition (since it is executed as you
+define it).  If you give @kbd{C-x )} an argument of 4, it executes the
+macro immediately 3 additional times.  An argument of zero to @kbd{C-x
+e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an
+error or you type @kbd{C-g}).
+Once you have defined a macro, you can invoke it again with the
+@kbd{C-x e} command (@code{call-last-kbd-macro}).  You can give the
+command a repeat count numeric argument to execute the macro many times.
+To repeat an operation at regularly spaced places in the
+text, define a macro and include as part of the macro the commands to move
+to the next place you want to use it.  For example, if you want to change
+each line, you should position point at the start of a line, and define a
+macro to change that line and leave point at the start of the next line.
+Repeating the macro will then operate on successive lines.
+After you have terminated the definition of a keyboard macro, you can add
+to the end of its definition by typing @kbd{C-u C-x (}.  This is equivalent
+to plain @kbd{C-x (} followed by retyping the whole definition so far.  As
+a consequence it re-executes the macro as previously defined.
+@node Save Kbd Macro
+@subsection Naming and Saving Keyboard Macros
+@findex name-last-kbd-macro
+To save a keyboard macro for longer than until you define the
+next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
+This reads a name as an argument using the minibuffer and defines that name
+to execute the macro.  The macro name is a Lisp symbol, and defining it in
+this way makes it a valid command name for calling with @kbd{M-x} or for
+binding a key to with @code{global-set-key} (@pxref{Keymaps}).  If you
+specify a name that has a prior definition other than another keyboard
+macro, Emacs prints an error message and nothing is changed.
+@findex insert-kbd-macro
+Once a macro has a command name, you can save its definition in a file.
+You can then use it in another editing session.  First visit the file
+you want to save the definition in.  Then use the command:
+@example
+M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
+@end example
+@noindent
+This inserts some Lisp code that, when executed later, will define the same
+macro with the same definition it has now.  You need not understand Lisp
+code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
+Then save the file.  You can load the file with @code{load-file}
+(@pxref{Lisp Libraries}).  If the file you save in is your initialization file
+@file{~/.emacs} (@pxref{Init File}), then the macro will be defined each
+time you run Emacs.
+If you give @code{insert-kbd-macro} a prefix argument, it creates
+additional Lisp code to record the keys (if any) that you have bound to the
+keyboard macro, so that the macro is reassigned the same keys when you
+load the file.
+@node Kbd Macro Query
+@subsection Executing Macros With Variations
+@kindex C-x q
+@findex kbd-macro-query
+You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar
+to that of @code{query-replace}.  The macro asks you  each time
+whether to make a change.  When you are defining the macro, type @kbd{C-x
+q} at the point where you want the query to occur.  During macro
+definition, the @kbd{C-x q} does nothing, but when you invoke the macro,
+@kbd{C-x q} reads a character from the terminal to decide whether to
+continue.
+The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL},
+@kbd{C-d}, @kbd{C-l}, and @kbd{C-r}.  Any other character terminates
+execution of the keyboard macro and is then read as a command.
+@key{SPC} means to continue.  @key{DEL} means to skip the remainder of
+this repetition of the macro, starting again from the beginning in the
+next repetition.  @kbd{C-d} means to skip the remainder of this
+repetition and cancel further repetition.  @kbd{C-l} redraws the frame
+and asks you again for a character to specify what to do.  @kbd{C-r} enters
+a recursive editing level, in which you can perform editing that is not
+part of the macro.  When you exit the recursive edit using @kbd{C-M-c},
+you are asked again how to continue with the keyboard macro.  If you
+type a @key{SPC} at this time, the rest of the macro definition is
+executed.  It is up to you to leave point and the text in a state such
+that the rest of the macro will do what you want.@refill
+@kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
+different function.  It enters a recursive edit reading input from the
+keyboard, both when you type it during the definition of the macro and
+when it is executed from the macro.  During definition, the editing you do
+inside the recursive edit does not become part of the macro.  During macro
+execution, the recursive edit gives you a chance to do some particularized
+editing.  @xref{Recursive Edit}.
+@node Key Bindings
+@section Customizing Key Bindings
+This section deals with the @dfn{keymaps} that define the bindings
+between keys and functions, and shows how you can customize these bindings.
+@cindex command
+@cindex function
+@cindex command name
+A command is a Lisp function whose definition provides for interactive
+use.  Like every Lisp function, a command has a function name, which is
+a Lisp symbol whose name usually consists of lower case letters and
+hyphens.
+@menu
+* Keymaps::    Definition of the keymap data structure.
+Names of Emacs's standard keymaps.
+* Rebinding::  How to redefine one key's meaning conveniently.
+* Disabling::  Disabling a command means confirmation is required
+before it can be executed.  This is done to protect
+beginners from surprises.
+@end menu
+@node Keymaps
+@subsection Keymaps
+@cindex keymap
+@cindex global keymap
+@vindex global-map
+The bindings between characters and command functions are recorded in
+data structures called @dfn{keymaps}.  Emacs has many of these.  One, the
+@dfn{global} keymap, defines the meanings of the single-character keys that
+are defined regardless of major mode.  It is the value of the variable
+@code{global-map}.
+@cindex local keymap
+@vindex c-mode-map
+@vindex lisp-mode-map
+Each major mode has another keymap, its @dfn{local keymap}, which
+contains overriding definitions for the single-character keys that are
+redefined in that mode.  Each buffer records which local keymap is
+installed for it at any time, and the current buffer's local keymap is
+the only one that directly affects command execution.  The local keymaps
+for Lisp mode, C mode, and many other major modes always exist even when
+not in use.  They are the values of the variables @code{lisp-mode-map},
+@code{c-mode-map}, and so on.  For less frequently used major modes, the
+local keymap is sometimes constructed only when the mode is used for the
+first time in a session, to save space.
+@cindex minibuffer
+@vindex minibuffer-local-map
+@vindex minibuffer-local-ns-map
+@vindex minibuffer-local-completion-map
+@vindex minibuffer-local-must-match-map
+@vindex repeat-complex-command-map
+@vindex isearch-mode-map
+There are local keymaps for the minibuffer, too; they contain various
+completion and exit commands.
+@itemize @bullet
+@item
+@code{minibuffer-local-map} is used for ordinary input (no completion).
+@item
+@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
+just like @key{RET}.  This is used mainly for Mocklisp compatibility.
+@item
+@code{minibuffer-local-completion-map} is for permissive completion.
+@item
+@code{minibuffer-local-must-match-map} is for strict completion and
+for cautious completion.
+@item
+@code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
+@item
+@code{isearch-mode-map} contains the bindings of the special keys which
+are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}.
+@end itemize
+@vindex ctl-x-map
+@vindex help-map
+@vindex esc-map
+Finally, each prefix key has a keymap which defines the key sequences
+that start with it.  For example, @code{ctl-x-map} is the keymap used for
+characters following a @kbd{C-x}.
+@itemize @bullet
+@item
+@code{ctl-x-map} is the variable name for the map used for characters that
+follow @kbd{C-x}.
+@item
+@code{help-map} is used for characters that follow @kbd{C-h}.
+@item
+@code{esc-map} is for characters that follow @key{ESC}. All Meta
+characters are actually defined by this map.
+@item
+@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
+@item
+@code{mode-specific-map} is for characters that follow @kbd{C-c}.
+@end itemize
+The definition of a prefix key is the keymap to use for looking up
+the following character.  Sometimes the definition is actually a Lisp
+symbol whose function definition is the following character keymap.  The
+effect is the same, but it provides a command name for the prefix key that
+you can use as a description of what the prefix key is for.  Thus the
+binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
+definition is the keymap for @kbd{C-x} commands, the value of
+@code{ctl-x-map}.@refill
+Prefix key definitions can appear in either the global
+map or a local map.  The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
+and @key{ESC} as prefix keys appear in the global map, so these prefix
+keys are always available.  Major modes can locally redefine a key as a
+prefix by putting a prefix key definition for it in the local
+map.@refill
+A mode can also put a prefix definition of a global prefix character such
+as @kbd{C-x} into its local map.  This is how major modes override the
+definitions of certain keys that start with @kbd{C-x}.  This case is
+special, because the local definition does not entirely replace the global
+one.  When both the global and local definitions of a key are other
+keymaps, the next character is looked up in both keymaps, with the local
+definition overriding the global one.  The character after the
+@kbd{C-x} is looked up in both the major mode's own keymap for redefined
+@kbd{C-x} commands and in @code{ctl-x-map}.  If the major mode's own keymap
+for @kbd{C-x} commands contains @code{nil}, the definition from the global
+keymap for @kbd{C-x} commands is used.@refill
+@node Rebinding
+@subsection Changing Key Bindings
+@cindex key rebinding, this session
+@cindex rebinding keys, this session
+You can redefine an Emacs key by changing its entry in a keymap.
+You can change the global keymap, in which case the change is effective in
+all major modes except those that have their own overriding local
+definitions for the same key.  Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+@menu
+* Interactive Rebinding::     Changing Key Bindings Interactively
+* Programmatic Rebinding::    Changing Key Bindings Programmatically
+* Key Bindings Using Strings::Using Strings for Changing Key Bindings
+@end menu
+@node Interactive Rebinding
+@subsubsection Changing Key Bindings Interactively
+@findex global-set-key
+@findex local-set-key
+@findex local-unset-key
+@table @kbd
+@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
+Defines @var{key} globally to run @var{cmd}.
+@item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET}
+Defines @var{key} locally (in the major mode now in effect) to run
+@var{cmd}.
+@item M-x local-unset-key @key{RET} @var{keys} @key{RET}
+Removes the local binding of @var{key}.
+@end table
+@var{cmd} is a symbol naming an interactively-callable function.
+When called interactively, @var{key} is the next complete key sequence
+that you type.  When called as a function, @var{key} is a string, a
+vector of events, or a vector of key-description lists as described in
+the @code{define-key} function description.  The binding goes in
+the current buffer's local map, which is shared with other buffers in
+the same major mode.
+The following example:
+@example
+M-x global-set-key @key{RET} C-f next-line @key{RET}
+@end example
+@noindent
+redefines @kbd{C-f} to move down a line.  The fact that @var{cmd} is
+read second makes it serve as a kind of confirmation for @var{key}.
+These functions offer no way to specify a particular prefix keymap as
+the one to redefine in, but that is not necessary, as you can include
+prefixes in @var{key}.  @var{key} is read by reading characters one by
+one until they amount to a complete key (that is, not a prefix key).
+Thus, if you type @kbd{C-f} for @var{key}, Emacs enters
+the minibuffer immediately to read @var{cmd}.  But if you type
+@kbd{C-x}, another character is read; if that character is @kbd{4},
+another character is read, and so on.  For example,@refill
+@example
+M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
+@end example
+@noindent
+redefines @kbd{C-x 4 $} to run the (fictitious) command
+@code{spell-other-window}.
+@findex define-key
+@findex substitute-key-definition
+The most general way to modify a keymap is the function
+@code{define-key}, used in Lisp code (such as your @file{.emacs} file).
+@code{define-key} takes three arguments: the keymap, the key to modify
+in it, and the new definition.  @xref{Init File}, for an example.
+@code{substitute-key-definition} is used similarly; it takes three
+arguments, an old definition, a new definition, and a keymap, and
+redefines in that keymap all keys that were previously defined with the
+old definition to have the new definition instead.
+@node Programmatic Rebinding
+@subsubsection Changing Key Bindings Programmatically
+You can use the functions @code{global-set-key} and @code{define-key}
+to rebind keys under program control.
+@findex define-key
+@findex global-set-key
+@table @kbd
+@item  @code{(global-set-key @var{keys} @var{cmd})}
+Defines @var{keys} globally to run @var{cmd}.
+@item @code{(define-key @var{keymap} @var{keys} @var{def})}
+Defines @var{keys} to run @var{def} in the keymap @var{keymap}.
+@end table
+@var{keymap} is a keymap object.
+@var{keys} is the sequence of keystrokes to bind.
+@var{def} is anything that can be a key's definition:
+@itemize @bullet
+@item
+@code{nil}, meaning key is undefined in this keymap
+@item
+A command, that is, a Lisp function suitable for interactive calling
+@item
+A string or key sequence vector, which is treated as a keyboard macro
+@item
+A keymap to define a prefix key
+@item
+A symbol so that when the key is looked up, the symbol stands for its
+function definition, which should at that time be one of the above,
+or another symbol whose function definition is used, and so on
+@item
+A cons, @code{(string . defn)}, meaning that @var{defn} is the definition
+(@var{defn} should be a valid definition in its own right)
+@item
+A cons, @code{(keymap . char)}, meaning use the definition of
+@var{char} in map @var{keymap}
+@end itemize
+For backward compatibility, XEmacs allows you to specify key
+sequences as strings.  However, the preferred method is to use the
+representations of key sequences as vectors of keystrokes.
+@xref{Keystrokes}, for more information about the rules for constructing
+key sequences.
+Emacs allows you to abbreviate representations for key sequences in
+most places where there is no ambiguity.
+Here are some rules for abbreviation:
+@itemize @bullet
+@item
+The keysym by itself is equivalent to a list of just that keysym, i.e.,
+@code{f1} is equivalent to @code{(f1)}.
+@item
+A keystroke by itself is equivalent to a vector containing just that
+keystroke, i.e.,  @code{(control a)} is equivalent to @code{[(control a)]}.
+@item
+You can use ASCII codes for keysyms that have them. i.e.,
+@code{65} is equivalent to @code{A}. (This is not so much an
+abbreviation as an alternate representation.)
+@end itemize
+Here are some examples of programmatically binding keys:
+@example
+;;;  Bind @code{my-command} to @key{f1}
+(global-set-key 'f1 'my-command)
+;;;  Bind @code{my-command} to @kbd{Shift-f1}
+(global-set-key '(shift f1) 'my-command)
+;;; Bind @code{my-command} to @kbd{C-c Shift-f1}
+(global-set-key '[(control c) (shift f1)] 'my-command)
+;;; Bind @code{my-command} to the middle mouse button.
+(global-set-key 'button2 'my-command)
+;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}}
+;;; in the keymap that is in force when you are running @code{dired}.
+(define-key dired-mode-map '(meta control button3) 'my-command)
+@end example
+@comment ;; note that these next four lines are not synonymous:
+@comment ;;
+@comment (global-set-key '(meta control delete) 'my-command)
+@comment (global-set-key '(meta control backspace) 'my-command)
+@comment (global-set-key '(meta control h) 'my-command)
+@comment (global-set-key '(meta control H) 'my-command)
+@comment
+@comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''.
+@comment ;;
+@comment (global-set-key "\^J" 'my-command)
+@node Key Bindings Using Strings
+@subsubsection Using Strings for Changing Key Bindings
+For backward compatibility, you can still use strings to represent
+key sequences.  Thus you can use commands like the following:
+@example
+;;; Bind @code{end-of-line} to @kbd{C-f}
+(global-set-key "\C-f" 'end-of-line)
+@end example
+Note, however, that in some cases you may be binding more than one
+key sequence by using a single command.  This situation can
+arise because in ASCII, @kbd{C-i} and @key{TAB} have
+the same representation.  Therefore, when Emacs sees:
+@example
+(global-set-key "\C-i" 'end-of-line)
+@end example
+it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}.
+The solution XEmacs adopts is to bind both of these key
+sequences.
+@cindex redefining keys
+After binding a command to two key sequences with a form like:
+@example
+	(define-key global-map "\^X\^I" 'command-1)
+@end example
+it is possible to redefine only one of those sequences like so:
+@example
+	(define-key global-map [(control x) (control i)] 'command-2)
+	(define-key global-map [(control x) tab] 'command-3)
+@end example
+This applies only when running under a window system.  If you are
+talking to Emacs through an ASCII-only channel, you do not get any of
+these features.
+Here is a table of pairs of key sequences that behave in a
+similar fashion:
+@example
+control h      backspace
+control l      clear
+control i      tab
+control m      return
+control j      linefeed
+control [      escape
+control @@      control space
+@end example
+@node Disabling
+@subsection Disabling Commands
+@cindex disabled command
+Disabling a command marks it as requiring confirmation before it
+can be executed.  The purpose of disabling a command is to prevent
+beginning users from executing it by accident and being confused.
+The direct mechanism for disabling a command is to have a non-@code{nil}
+@code{disabled} property on the Lisp symbol for the command.  These
+properties are normally set by the user's @file{.emacs} file with
+Lisp expressions such as:
+@example
+(put 'delete-region 'disabled t)
+@end example
+If the value of the @code{disabled} property is a string, that string
+is included in the message printed when the command is used:
+@example
+(put 'delete-region 'disabled
+"Text deleted this way cannot be yanked back!\n")
+@end example
+@findex disable-command
+@findex enable-command
+You can disable a command either by editing the @file{.emacs} file
+directly or with the command @kbd{M-x disable-command}, which edits the
+@file{.emacs} file for you.  @xref{Init File}.
+When you attempt to invoke a disabled command interactively in Emacs,
+a window is displayed containing the command's name, its
+documentation, and some instructions on what to do next; then
+Emacs asks for input saying whether to execute the command as requested,
+enable it and execute, or cancel it.  If you decide to enable the
+command, you are asked whether to do this permanently or just for the
+current session.  Enabling permanently works by automatically editing
+your @file{.emacs} file.  You can use @kbd{M-x enable-command} at any
+time to enable any command permanently.
+Whether a command is disabled is independent of what key is used to
+invoke it; it also applies if the command is invoked using @kbd{M-x}.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+@node Syntax
+@section The Syntax Table
+@cindex syntax table
+All the Emacs commands which parse words or balance parentheses are
+controlled by the @dfn{syntax table}.  The syntax table specifies which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on.  Actually, each major mode has its own syntax
+table (though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode.  The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it ``the'' syntax table.  A syntax table is a Lisp object, a vector of
+length 256 whose elements are numbers.
+@menu
+* Entry: Syntax Entry.    What the syntax table records for each character.
+* Change: Syntax Change.  How to change the information.
+@end menu
+@node Syntax Entry
+@subsection Information About Each Character
+The syntax table entry for a character is a number that encodes six
+pieces of information:
+@itemize @bullet
+@item
+The syntactic class of the character, represented as a small integer
+@item
+The matching delimiter, for delimiter characters only
+(the matching delimiter of @samp{(} is @samp{)}, and vice versa)
+@item
+A flag saying whether the character is the first character of a
+two-character comment starting sequence
+@item
+A flag saying whether the character is the second character of a
+two-character comment starting sequence
+@item
+A flag saying whether the character is the first character of a
+two-character comment ending sequence
+@item
+A flag saying whether the character is the second character of a
+two-character comment ending sequence
+@end itemize
+The syntactic classes are stored internally as small integers, but are
+usually described to or by the user with characters.  For example, @samp{(}
+is used to specify the syntactic class of opening delimiters.  Here is a
+table of syntactic classes, with the characters that specify them.
+@table @samp
+@item @w{ }
+The class of whitespace characters.
+@item w
+The class of word-constituent characters.
+@item _
+The class of characters that are part of symbol names but not words.
+This class is represented by @samp{_} because the character @samp{_}
+has this class in both C and Lisp.
+@item .
+The class of punctuation characters that do not fit into any other
+special class.
+@item (
+The class of opening delimiters.
+@item )
+The class of closing delimiters.
+@item '
+The class of expression-adhering characters.  These characters are
+part of a symbol if found within or adjacent to one, and are part
+of a following expression if immediately preceding one, but are like
+whitespace if surrounded by whitespace.
+@item "
+The class of string-quote characters.  They match each other in pairs,
+and the characters within the pair all lose their syntactic
+significance except for the @samp{\} and @samp{/} classes of escape
+characters, which can be used to include a string-quote inside the
+string.
+@item $
+The class of self-matching delimiters.  This is intended for @TeX{}'s
+@samp{$}, which is used both to enter and leave math mode.  Thus,
+a pair of matching @samp{$} characters surround each piece of math mode
+@TeX{} input.  A pair of adjacent @samp{$} characters act like a single
+one for purposes of matching.
+@item /
+The class of escape characters that always just deny the following
+character its special syntactic significance.  The character after one
+of these escapes is always treated as alphabetic.
+@item \
+The class of C-style escape characters.  In practice, these are
+treated just like @samp{/}-class characters, because the extra
+possibilities for C escapes (such as being followed by digits) have no
+effect on where the containing expression ends.
+@item <
+The class of comment-starting characters.  Only single-character
+comment starters (such as @samp{;} in Lisp mode) are represented this
+way.
+@item >
+The class of comment-ending characters.  Newline has this syntax in
+Lisp mode.
+@end table
+@vindex parse-sexp-ignore-comments
+The characters flagged as part of two-character comment delimiters can
+have other syntactic functions most of the time.  For example, @samp{/} and
+@samp{*} in C code, when found separately, have nothing to do with
+comments.  The comment-delimiter significance overrides when the pair of
+characters occur together in the proper order.  Only the list and sexp
+commands use the syntax table to find comments; the commands specifically
+for comments have other variables that tell them where to find comments.
+Moreover, the list and sexp commands notice comments only if
+@code{parse-sexp-ignore-comments} is non-@code{nil}.  This variable is set
+to @code{nil} in modes where comment-terminator sequences are liable to
+appear where there is no comment, for example, in Lisp mode where the
+comment terminator is a newline but not every newline ends a comment.
+@node Syntax Change
+@subsection Altering Syntax Information
+It is possible to alter a character's syntax table entry by storing a new
+number in the appropriate element of the syntax table, but it would be hard
+to determine what number to use.  Emacs therefore provides a command that
+allows you to specify the syntactic properties of a character in a
+convenient way.
+@findex modify-syntax-entry
+@kbd{M-x modify-syntax-entry} is the command to change a character's
+syntax.  It can be used interactively and is also used by major
+modes to initialize their own syntax tables.  Its first argument is the
+character to change.  The second argument is a string that specifies the
+new syntax.  When called from Lisp code, there is a third, optional
+argument, which specifies the syntax table in which to make the change.  If
+not supplied, or if this command is called interactively, the third
+argument defaults to the current buffer's syntax table.
+@enumerate
+@item
+The first character in the string specifies the syntactic class.  It
+is one of the characters in the previous table (@pxref{Syntax Entry}).
+@item
+The second character is the matching delimiter.  For a character that
+is not an opening or closing delimiter, this should be a space, and may
+be omitted if no following characters are needed.
+@item
+The remaining characters are flags.  The flag characters allowed are:
+@table @samp
+@item 1
+Flag this character as the first of a two-character comment starting sequence.
+@item 2
+Flag this character as the second of a two-character comment starting sequence.
+@item 3
+Flag this character as the first of a two-character comment ending sequence.
+@item 4
+Flag this character as the second of a two-character comment ending sequence.
+@end table
+@end enumerate
+@kindex C-h s
+@findex describe-syntax
+Use @kbd{C-h s} (@code{describe-syntax}) to display a description of
+the contents of the current syntax table.  The description of each
+character includes both the string you have to pass to
+@code{modify-syntax-entry} to set up that character's current syntax,
+and some English to explain that string if necessary.
+@node Init File
+@section The Init File, .emacs
+@cindex init file
+@cindex Emacs initialization file
+@cindex key rebinding, permanent
+@cindex rebinding keys, permanently
+When you start Emacs, it normally loads the file @file{.emacs} in your
+home directory.  This file, if it exists, should contain Lisp code.  It
+is called your initialization file or @dfn{init file}.  Use the command
+line switch @samp{-q} to tell Emacs whether to load an
+init file (@pxref{Entering Emacs}).  Use the command line switch
+@samp{-user-init-file} (@pxref{Command Switches}) to tell Emacs to load
+a different file instead of @file{~/.emacs}.
+When the @file{.emacs} file is read, the variable @code{user-init-file}
+says which init file was loaded.
+At some sites there is a @dfn{default init file}, which is the
+library named @file{default.el}, found via the standard search path for
+libraries.  The Emacs distribution contains no such library; your site
+may create one for local customizations.  If this library exists, it is
+loaded whenever you start Emacs.  But your init file, if any, is loaded
+first; if it sets @code{inhibit-default-init} non-@code{nil}, then
+@file{default} is not loaded.
+If you have a large amount of code in your @file{.emacs} file, you
+should move it into another file named @file{@var{something}.el},
+byte-compile it (@pxref{Lisp Libraries}), and load that file from your
+@file{.emacs} file using @code{load}.
+@menu
+* Init Syntax::     Syntax of constants in Emacs Lisp.
+* Init Examples::   How to do some things with an init file.
+* Terminal Init::   Each terminal type can have an init file.
+@end menu
+@node Init Syntax
+@subsection Init File Syntax
+The @file{.emacs} file contains one or more Lisp function call
+expressions.  Each consists of a function name followed by
+arguments, all surrounded by parentheses.  For example, @code{(setq
+fill-column 60)} represents a call to the function @code{setq} which is
+used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
+The second argument to @code{setq} is an expression for the new value
+of the variable.  This can be a constant, a variable, or a function call
+expression.  In @file{.emacs}, constants are used most of the time.
+They can be:
+@table @asis
+@item Numbers
+Integers are written in decimal, with an optional initial minus sign.
+If a sequence of digits is followed by a period and another sequence
+of digits, it is interpreted as a floating point number.
+The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to
+represent numbers in binary, octal, and hexadecimal notation (or radix).
+@item Strings
+Lisp string syntax is the same as C string syntax with a few extra
+features.  Use a double-quote character to begin and end a string constant.
+Newlines and special characters may be present literally in strings.  They
+can also be represented as backslash sequences: @samp{\n} for newline,
+@samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab,
+@samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
+backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
+character whose octal code is @var{ooo}.  Backslash and double-quote are
+the only characters for which backslash sequences are mandatory.
+You can use @samp{\C-} as a prefix for a control character, as in
+@samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for
+a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
+Control-Meta-A.@refill
+@item Characters
+Lisp character constant syntax consists of a @samp{?} followed by
+either a character or an escape sequence starting with @samp{\}.
+Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
+strings and characters are not interchangeable in Lisp; some contexts
+require one and some contexts require the other.
+@item True
+@code{t} stands for `true'.
+@item False
+@code{nil} stands for `false'.
+@item Other Lisp objects
+Write a single-quote (') followed by the Lisp object you want.
+@end table
+@node Init Examples
+@subsection Init File Examples
+Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+@itemize @bullet
+@item
+Make @key{TAB} in C mode just insert a tab if point is in the middle of a
+line.
+@example
+(setq c-tab-always-indent nil)
+@end example
+Here we have a variable whose value is normally @code{t} for `true'
+and the alternative is @code{nil} for `false'.
+@item
+Make searches case sensitive by default (in all buffers that do not
+override this).
+@example
+(setq-default case-fold-search nil)
+@end example
+This sets the default value, which is effective in all buffers that do
+not have local values for the variable.  Setting @code{case-fold-search}
+with @code{setq} affects only the current buffer's local value, which
+is probably not what you want to do in an init file.
+@item
+Make Text mode the default mode for new buffers.
+@example
+(setq default-major-mode 'text-mode)
+@end example
+Note that @code{text-mode} is used because it is the command for entering
+the mode we want.  A single-quote is written before it to make a symbol
+constant; otherwise, @code{text-mode} would be treated as a variable name.
+@item
+Turn on Auto Fill mode automatically in Text mode and related modes.
+@example
+(setq text-mode-hook
+'(lambda () (auto-fill-mode 1)))
+@end example
+Here we have a variable whose value should be a Lisp function.  The
+function we supply is a list starting with @code{lambda}, and a single
+quote is written in front of it to make it (for the purpose of this
+@code{setq}) a list constant rather than an expression.  Lisp functions
+are not explained here; for mode hooks it is enough to know that
+@code{(auto-fill-mode 1)} is an expression that will be executed when
+Text mode is entered.  You could replace it with any other expression
+that you like, or with several expressions in a row.
+@example
+(setq text-mode-hook 'turn-on-auto-fill)
+@end example
+This is another way to accomplish the same result.
+@code{turn-on-auto-fill} is a symbol whose function definition is
+@code{(lambda () (auto-fill-mode 1))}.
+@item
+Load the installed Lisp library named @file{foo} (actually a file
+@file{foo.elc} or @file{foo.el} in a standard Emacs directory).
+@example
+(load "foo")
+@end example
+When the argument to @code{load} is a relative pathname, not starting
+with @samp{/} or @samp{~}, @code{load} searches the directories in
+@code{load-path} (@pxref{Loading}).
+@item
+Load the compiled Lisp file @file{foo.elc} from your home directory.
+@example
+(load "~/foo.elc")
+@end example
+Here an absolute file name is used, so no searching is done.
+@item
+Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
+@example
+(global-set-key "\C-xl" 'make-symbolic-link)
+@end example
+or
+@example
+(define-key global-map "\C-xl" 'make-symbolic-link)
+@end example
+Note once again the single-quote used to refer to the symbol
+@code{make-symbolic-link} instead of its value as a variable.
+@item
+Do the same thing for C mode only.
+@example
+(define-key c-mode-map "\C-xl" 'make-symbolic-link)
+@end example
+@item
+Bind the function key @key{F1} to a command in C mode.
+Note that the names of function keys must be lower case.
+@example
+(define-key c-mode-map 'f1 'make-symbolic-link)
+@end example
+@item
+Bind the shifted version of @key{F1} to a command.
+@example
+(define-key c-mode-map '(shift f1) 'make-symbolic-link)
+@end example
+@item
+Redefine all keys which now run @code{next-line} in Fundamental mode
+to run @code{forward-line} instead.
+@example
+(substitute-key-definition 'next-line 'forward-line
+global-map)
+@end example
+@item
+Make @kbd{C-x C-v} undefined.
+@example
+(global-unset-key "\C-x\C-v")
+@end example
+One reason to undefine a key is so that you can make it a prefix.
+Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
+a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
+first.
+@item
+Make @samp{$} have the syntax of punctuation in Text mode.
+Note the use of a character constant for @samp{$}.
+@example
+(modify-syntax-entry ?\$ "." text-mode-syntax-table)
+@end example
+@item
+Enable the use of the command @code{eval-expression} without confirmation.
+@example
+(put 'eval-expression 'disabled nil)
+@end example
+@end itemize
+@node Terminal Init
+@subsection Terminal-Specific Initialization
+Each terminal type can have a Lisp library to be loaded into Emacs when
+it is run on that type of terminal.  For a terminal type named
+@var{termtype}, the library is called @file{term/@var{termtype}} and it is
+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
+The usual purpose of the terminal-specific library is to define the
+escape sequences used by the terminal's function keys using the library
+@file{keypad.el}.  See the file
+@file{term/vt100.el} for an example of how this is done.@refill
+When the terminal type contains a hyphen, only the part of the name
+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
+@vindex term-file-prefix
+The library's name is constructed by concatenating the value of the
+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
+The value of the variable @code{term-setup-hook}, if not @code{nil}, is
+called as a function of no arguments at the end of Emacs initialization,
+after both your @file{.emacs} file and any terminal-specific library have
+been read.  You can set the value in the @file{.emacs} file to override
+part of any of the terminal-specific libraries and to define
+initializations for terminals that do not have a library.@refill
+@node Audible Bell
+@section Changing the Bell Sound
+@cindex audible bell, changing
+@cindex bell, changing
+@vindex sound-alist
+@findex load-default-sounds
+@findex play-sound
+You can now change how the audible bell sounds using the variable
+@code{sound-alist}.
+@code{sound-alist}'s value is an list associating symbols with, among
+other things, strings of audio-data.  When @code{ding} is called with
+one of the symbols, the associated sound data is played instead of the
+standard beep.  This only works if you are logged in on the console of a
+machine with audio hardware. To listen to a sound of the provided type,
+call the function @code{play-sound} with the argument @var{sound}. You
+can also set the volume of the sound with the optional argument
+@var{volume}.@refill
+@cindex ding
+Each element of @code{sound-alist} is a list describing a sound.
+The first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+@table @code
+@item sound
+A string of raw sound data, or the name of another sound to play.
+The symbol @code{t} here means use the default X beep.
+@item volume
+An integer from 0-100, defaulting to @code{bell-volume}.
+@item pitch
+If using the default X beep, the pitch (Hz) to generate.
+@item duration
+If using the default X beep, the duration (milliseconds).
+@end table
+For compatibility, elements of `sound-alist' may also be of the form:
+@example
+( @var{sound-name} . @var{<sound>} )
+( @var{sound-name} @var{<volume>} @var{<sound>} )
+@end example
+You should probably add things to this list by calling the function
+@code{load-sound-file}.
+Note that you can only play audio data if running on the console screen
+of a machine with audio hardware which emacs understands, which at this
+time means a Sun SparcStation, SGI, or HP9000s700.
+Also note that the pitch, duration, and volume options are available
+everywhere, but most X servers ignore the `pitch' option.
+@vindex bell-volume
+The variable @code{bell-volume} should be an integer from 0 to 100,
+with 100 being loudest, which controls how loud the sounds emacs makes
+should be.  Elements of the @code{sound-alist} may override this value.
+This variable applies to the standard X bell sound as well as sound files.
+If the symbol @code{t} is in place of a sound-string, Emacs uses the
+default X beep.  This allows you to define beep-types of
+different volumes even when not running on the console.
+@findex load-sound-file
+You can add things to this list by calling the function
+@code{load-sound-file}, which reads in an audio-file and adds its data to
+the sound-alist. You can specify the sound with the @var{sound-name}
+argument and the file into which the sounds are loaded with the
+@var{filename} argument. The optional @var{volume} argument sets the
+volume.
+@code{load-sound-file (@var{filename sound-name} &optional @var{volume})}
+To load and install some sound files as beep-types, use the function
+@code{load-default-sounds} (note that this only works if you are on
+display 0 of a machine with audio hardware).
+The following beep-types are used by Emacs itself. Other Lisp
+packages may use other beep types, but these are the ones that the C
+kernel of Emacs uses.
+@table @code
+@item auto-save-error
+An auto-save does not succeed
+@item command-error
+The Emacs command loop catches an error
+@item undefined-key
+You type a key that is undefined
+@item undefined-click
+You use an undefined mouse-click combination
+@item no-completion
+Completion was not possible
+@item y-or-n-p
+You type something other than the required @code{y} or @code{n}
+@item yes-or-no-p
+You type something other than @code{yes} or @code{no}
+@end table
+@comment  node-name,  next,  previous,  up
+@node Faces
+@section Faces
+XEmacs has objects called extents and faces.  An @dfn{extent}
+is a region of text and a @dfn{face} is a collection of textual
+attributes, such as fonts and colors.  Every extent is displayed in some
+face; therefore, changing the properties of a face immediately updates the
+display of all associated extents.  Faces can be frame-local: you can
+have a region of text that displays with completely different
+attributes when its buffer is viewed from a different X window.
+The display attributes of faces may be specified either in Lisp or through
+the X resource manager.
+@subsection Customizing Faces
+You can change the face of an extent with the functions in
+this section.  All the functions prompt for a @var{face} as an
+argument; use completion for a list of possible values.
+@table @kbd
+@item M-x invert-face
+Swap the foreground and background colors of the given @var{face}.
+@item M-x make-face-bold
+Make the font of the given @var{face} bold.  When called from a
+program, returns @code{nil} if this is not possible.
+@item M-x make-face-bold-italic
+Make the font of the given @var{face} bold italic.
+When called from a program, returns @code{nil} if not possible.
+@item M-x make-face-italic
+Make the font of the given @var{face} italic.
+When called from a program, returns @code{nil} if not possible.
+@item M-x make-face-unbold
+Make the font of the given @var{face} non-bold.
+When called from a program, returns @code{nil} if not possible.
+@item M-x make-face-unitalic
+Make the font of the given @var{face} non-italic.
+When called from a program, returns @code{nil} if not possible.
+@item M-x make-face-larger
+Make the font of the given @var{face} a little larger.
+When called from a program, returns @code{nil} if not possible.
+@item M-x make-face-smaller
+Make the font of the given @var{face} a little smaller.
+When called from a program, returns @code{nil} if not possible.
+@item M-x set-face-background
+Change the background color of the given @var{face}.
+@item M-x set-face-background-pixmap
+Change the background pixmap of the given @var{face}.
+@item M-x set-face-font
+Change the font of the given @var{face}.
+@item M-x set-face-foreground
+Change the foreground color of the given @var{face}.
+@item M-x set-face-underline-p
+Change whether the given @var{face} is underlined.
+@end table
+@findex make-face-bold
+@findex make-face-bold-italic
+@findex make-face-italic
+@findex make-face-unbold
+@findex make-face-unitalic
+@findex make-face-larger
+@findex make-face-smaller
+@findex invert-face
+You can exchange the foreground and background color of the selected
+@var{face} with the function @code{invert-face}. If the face does not
+specify both foreground and background, then its foreground and
+background are set to the background and foreground of the default face.
+When calling this from a program, you can supply the optional argument
+@var{frame} to specify which frame is affected; otherwise, all frames
+are affected.
+@findex set-face-background
+You can set the background color of the specified @var{face} with the
+function @code{set-face-background}.  The argument @code{color} should
+be a string, the name of a color.  When called from a program, if the
+optional @var{frame} argument is provided, the face is changed only
+in that frame; otherwise, it is changed in all frames.
+@findex set-face-background-pixmap
+You can set the background pixmap of the specified @var{face} with the
+function @code{set-face-background-pixmap}.  The pixmap argument
+@var{name} should be a string, the name of a file of pixmap data.  The
+directories listed in the @code{x-bitmap-file-path} variable are
+searched.  The bitmap may also be a list of the form @code{(@var{width
+height data})}, where @var{width} and @var{height} are the size in
+pixels, and @var{data} is a string containing the raw bits of the
+bitmap.  If the optional @var{frame} argument is provided, the face is
+changed only in that frame; otherwise, it is changed in all frames.
+The variable @code{x-bitmap-file-path} takes as a value a list of the
+directories in which X bitmap files may be found.  If the value is
+@code{nil}, the list is initialized from the @code{*bitmapFilePath}
+resource.
+If the environment variable @b{XBMLANGPATH} is set, then it is consulted
+before the @code{x-bitmap-file-path} variable.
+@findex set-face-font
+You can set the font of the specified @var{face} with the function
+@code{set-face-font}.  The @var{font} argument should be a string, the
+name of a font.  When called from a program, if the
+optional @var{frame} argument is provided, the face is changed only
+in that frame; otherwise, it is changed in all frames.
+@findex set-face-foreground
+You can set the foreground color of the specified @var{face} with the
+function @code{set-face-foreground}.  The argument @var{color} should be
+a string, the name of a color.  If the optional @var{frame} argument is
+provided, the face is changed only in that frame; otherwise, it is
+changed in all frames.
+@findex set-face-underline-p
+You can set underline the specified @var{face} with the function
+@code{set-face-underline-p}. The argument @var{underline-p} can be used
+to make underlining an attribute of the face or not. If the optional
+@var{frame} argument is provided, the face is changed only in that
+frame; otherwise, it is changed in all frames.
+@node X Resources
+@section X Resources
+@cindex X resources
+@findex x-create-frame
+Historically, XEmacs has used the X resource application class @samp{Emacs}
+for its resources.  Unfortunately, GNU Emacs uses the same application
+class, and resources are not compatible between the two Emacsen.  This
+sharing of the application class often leads to trouble if you want to
+run both variants.
+Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
+any XEmacs resources in the resource database when the X connection is
+initialized.  Otherwise, it will use the class @samp{Emacs} for
+backwards compatability.  The variable @var{x-emacs-application-class}
+may be consulted to determine the application class being used.
+The examples in this section assume the application class is @samp{Emacs}.
+The Emacs resources are generally set per-frame. Each Emacs frame can have
+its own name or the same name as another, depending on the name passed to the
+@code{make-frame} function.
+You can specify resources for all frames with the syntax:
+@example
+Emacs*parameter: value
+@end example
+@noindent
+or
+@example
+Emacs*EmacsFrame.parameter:value
+@end example
+@noindent
+You can specify resources for a particular frame with the syntax:
+@example
+Emacs*FRAME-NAME.parameter: value
+@end example
+@noindent
+@menu
+* Geometry Resources::     Controlling the size and position of frames.
+* Iconic Resources::	   Controlling whether frames come up iconic.
+* Resource List::	   List of resources settable on a frame or device.
+* Face Resources::	   Controlling faces using resources.
+* Widgets::		   The widget hierarchy for XEmacs.
+* Menubar Resources::	   Specifying resources for the menubar.
+@end menu
+@node Geometry Resources
+@subsection Geometry Resources
+To make the default size of all Emacs frames be 80 columns by 55 lines,
+do this:
+@example
+Emacs*EmacsFrame.geometry: 80x55
+@end example
+@noindent
+To set the geometry of a particular frame named @samp{fred}, do this:
+@example
+Emacs*fred.geometry: 80x55
+@end example
+@noindent
+Important! Do not use the following syntax:
+@example
+Emacs*geometry: 80x55
+@end example
+@noindent
+You should never use @code{*geometry} with any X application. It does
+not say "make the geometry of Emacs be 80 columns by 55 lines."  It
+really says, "make Emacs and all subwindows thereof be 80x55 in whatever
+units they care to measure in."  In particular, that is both telling the
+Emacs text pane to be 80x55 in characters, and telling the menubar pane
+to be 80x55 pixels, which is surely not what you want.
+As a special case, this geometry specification also works (and sets the
+default size of all Emacs frames to 80 columns by 55 lines):
+@example
+Emacs.geometry: 80x55
+@end example
+@noindent
+since that is the syntax used with most other applications (since most
+other applications have only one top-level window, unlike Emacs).  In
+general, however, the top-level shell (the unmapped ApplicationShell
+widget named @samp{Emacs} that is the parent of the shell widgets that
+actually manage the individual frames) does not have any interesting
+resources on it, and you should set the resources on the frames instead.
+The @code{-geometry} command-line argument sets only the geometry of the
+initial frame created by Emacs.
+A more complete explanation of geometry-handling is
+@itemize @bullet
+@item
+The @code{-geometry} command-line option sets the @code{Emacs.geometry}
+resource, that is, the geometry of the ApplicationShell.
+@item
+For the first frame created, the size of the frame is taken from the
+ApplicationShell if it is specified, otherwise from the geometry of the
+frame.
+@item
+For subsequent frames, the order is reversed: First the frame, and then
+the ApplicationShell.
+@item
+For the first frame created, the position of the frame is taken from the
+ApplicationShell (@code{Emacs.geometry}) if it is specified, otherwise
+from the geometry of the frame.
+@item
+For subsequent frames, the position is taken only from the frame, and
+never from the ApplicationShell.
+@end itemize
+This is rather complicated, but it does seem to provide the most
+intuitive behavior with respect to the default sizes and positions of
+frames created in various ways.
+@node Iconic Resources
+@subsection Iconic Resources
+Analogous to @code{-geometry}, the @code{-iconic} command-line option
+sets the iconic flag of the ApplicationShell (@code{Emacs.iconic}) and
+always applies to the first frame created regardless of its name.
+However, it is possible to set the iconic flag on particular frames (by
+name) by using the @code{Emacs*FRAME-NAME.iconic} resource.
+@node Resource List
+@subsection Resource List
+Emacs frames accept the following resources:
+@table @asis
+@item @code{geometry} (class @code{Geometry}): string
+Initial geometry for the frame.  @xref{Geometry Resources}, for a
+complete discussion of how this works.
+@item @code{iconic} (class @code{Iconic}): boolean
+Whether this frame should appear in the iconified state.
+@item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int
+How many blank pixels to leave between the text and the edge of the
+window.
+@item @code{interline} (class @code{Interline}): int
+How many pixels to leave between each line (may not be implemented).
+@item @code{menubar} (class @code{Menubar}): boolean
+Whether newly-created frames should initially have a menubar.  Set to
+true by default.
+@item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean
+Whether XEmacs should leave the initial frame unmapped when it starts
+up.  This is useful if you are starting XEmacs as a server (e.g. in
+conjunction with gnuserv or the external client widget).  You can also
+control this with the @code{-unmapped} command-line option.
+@item @code{barCursor} (class @code{BarColor}): boolean
+Whether the cursor should be displayed as a bar, or the traditional box.
+@item @code{cursorColor} (class @code{CursorColor}): color-name
+The color of the text cursor.
+@item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer
+How wide the vertical scrollbars should be, in pixels; 0 means no
+vertical scrollbars.  You can also use a resource specification of the
+form @code{*scrollbar.width}, or the usual toolkit scrollbar resources:
+@code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid),
+or @code{*Scrollbar.thickness} (Athena).  We don't recommend that you
+use the toolkit resources, though, because they're dependent on how
+exactly your particular build of XEmacs was configured.
+@item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer
+How high the horizontal scrollbars should be, in pixels; 0 means no
+horizontal scrollbars.  You can also use a resource specification of the
+form @code{*scrollbar.height}, or the usual toolkit scrollbar resources:
+@code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid),
+or @code{*Scrollbar.thickness} (Athena).  We don't recommend that you use
+the toolkit resources, though, because they're dependent on how exactly
+your particular build of XEmacs was configured.
+@item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string
+Where the horizontal and vertical scrollbars should be positioned.  This
+should be one of the four strings @samp{BOTTOM_LEFT},
+@samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}.  Default is
+@samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and
+@samp{BOTTOM_LEFT} for the Athena scrollbars.
+@item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer
+@itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer
+@itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer
+@itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer
+Height and width of the four possible toolbars.
+@item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name
+@itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name
+Color of the top and bottom shadows for the toolbars.  NOTE: These resources
+do @emph{not} have anything to do with the top and bottom toolbars (i.e. the
+toolbars at the top and bottom of the frame)!  Rather, they affect the top
+and bottom shadows around the edges of all four kinds of toolbars.
+@item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name
+@itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name
+Pixmap of the top and bottom shadows for the toolbars.  If set, these
+resources override the corresponding color resources. NOTE: These
+resources do @emph{not} have anything to do with the top and bottom
+toolbars (i.e. the toolbars at the top and bottom of the frame)!
+Rather, they affect the top and bottom shadows around the edges of all
+four kinds of toolbars.
+@item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer
+Thickness of the shadows around the toolbars, in pixels.
+@item @code{visualBell} (class @code{VisualBell}): boolean
+Whether XEmacs should flash the screen rather than making an audible beep.
+@item @code{bellVolume} (class @code{BellVolume}): integer
+Volume of the audible beep.
+@item @code{useBackingStore} (class @code{UseBackingStore}): boolean
+Whether XEmacs should set the backing-store attribute of the X windows
+it creates.  This increases the memory usage of the X server but decreases
+the amount of X traffic necessary to update the screen, and is useful
+when the connection to the X server goes over a low-bandwidth line
+such as a modem connection.
+@end table
+Emacs devices accept the following resources:
+@table @asis
+@item @code{textPointer} (class @code{Cursor}): cursor-name
+The cursor to use when the mouse is over text.  This resource is used to
+initialize the variable @code{x-pointer-shape}.
+@item @code{selectionPointer} (class @code{Cursor}): cursor-name
+The cursor to use when the mouse is over a selectable text region (an
+extent with the @samp{highlight} property; for example, an Info
+cross-reference).  This resource is used to initialize the variable
+@code{x-selection-pointer-shape}.
+@item @code{spacePointer} (class @code{Cursor}): cursor-name
+The cursor to use when the mouse is over a blank space in a buffer (that
+is, after the end of a line or after the end-of-file).  This resource is
+used to initialize the variable @code{x-nontext-pointer-shape}.
+@item @code{modeLinePointer} (class @code{Cursor}): cursor-name
+The cursor to use when the mouse is over a modeline.  This resource is
+used to initialize the variable @code{x-mode-pointer-shape}.
+@item @code{gcPointer} (class @code{Cursor}): cursor-name
+The cursor to display when a garbage-collection is in progress.  This
+resource is used to initialize the variable @code{x-gc-pointer-shape}.
+@item @code{scrollbarPointer} (class @code{Cursor}): cursor-name
+The cursor to use when the mouse is over the scrollbar.  This resource
+is used to initialize the variable @code{x-scrollbar-pointer-shape}.
+@item @code{pointerColor} (class @code{Foreground}): color-name
+@itemx @code{pointerBackground} (class @code{Background}): color-name
+The foreground and background colors of the mouse cursor.  These
+resources are used to initialize the variables
+@code{x-pointer-foreground-color} and @code{x-pointer-background-color}.
+@end table
+@node Face Resources
+@subsection Face Resources
+The attributes of faces are also per-frame. They can be specified as:
+@example
+Emacs.FACE_NAME.parameter: value
+@end example
+@noindent
+or
+@example
+Emacs*FRAME_NAME.FACE_NAME.parameter: value
+@end example
+@noindent
+Faces accept the following resources:
+@table @asis
+@item @code{attributeFont} (class @code{AttributeFont}): font-name
+The font of this face.
+@item @code{attributeForeground} (class @code{AttributeForeground}): color-name
+@itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name
+The foreground and background colors of this face.
+@item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name
+The name of an @sc{xbm} file (or @sc{xpm} file, if your version of Emacs
+supports @sc{xpm}), to use as a background stipple.
+@item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean
+Whether text in this face should be underlined.
+@end table
+All text is displayed in some face, defaulting to the face named
+@code{default}.  To set the font of normal text, use
+@code{Emacs*default.attributeFont}. To set it in the frame named
+@code{fred}, use @code{Emacs*fred.default.attributeFont}.
+These are the names of the predefined faces:
+@table @code
+@item default
+Everything inherits from this.
+@item bold
+If this is not specified in the resource database, Emacs tries to find a
+bold version of the font of the default face.
+@item italic
+If this is not specified in the resource database, Emacs tries to find
+an italic version of the font of the default face.
+@item bold-italic
+If this is not specified in the resource database, Emacs tries to find a
+bold-italic version of the font of the default face.
+@item modeline
+This is the face that the modeline is displayed in.  If not specified in
+the resource database, it is determined from the default face by
+reversing the foreground and background colors.
+@item highlight
+This is the face that highlighted extents (for example, Info
+cross-references and possible completions, when the mouse passes over
+them) are displayed in.
+@item left-margin
+@itemx right-margin
+These are the faces that the left and right annotation margins are
+displayed in.
+@item zmacs-region
+This is the face that mouse selections are displayed in.
+@item isearch
+This is the face that the matched text being searched for is displayed
+in.
+@item info-node
+This is the face of info menu items.  If unspecified, it is copied from
+@code{bold-italic}.
+@item info-xref
+This is the face of info cross-references.  If unspecified, it is copied
+from @code{bold}. (Note that, when the mouse passes over a
+cross-reference, the cross-reference's face is determined from a
+combination of the @code{info-xref} and @code{highlight} faces.)
+@end table
+Other packages might define their own faces; to see a list of all faces,
+use any of the interactive face-manipulation commands such as
+@code{set-face-font} and type @samp{?} when you are prompted for the
+name of a face.
+If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not
+specified in the resource database, then XEmacs attempts to derive them
+from the font of the default face.  It can only succeed at this if you
+have specified the default font using the XLFD (X Logical Font
+Description) format, which looks like
+@example
+*-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+@end example
+@noindent
+If you use any of the other, less strict font name formats, some of which
+look like
+@example
+lucidasanstypewriter-12
+fixed
+9x13
+@end example
+then XEmacs won't be able to guess the names of the bold and italic
+versions.  All X fonts can be referred to via XLFD-style names, so you
+should use those forms.  See the man pages for @samp{X(1)},
+@samp{xlsfonts(1)}, and @samp{xfontsel(1)}.
+@node Widgets
+@subsection Widgets
+There are several structural widgets between the terminal EmacsFrame
+widget and the top level ApplicationShell; the exact names and types of
+these widgets change from release to release (for example, they changed
+between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
+subject to further change in the future, so you should avoid mentioning
+them in your resource database.  The above-mentioned syntaxes should be
+forward- compatible.  As of 19.13, the exact widget hierarchy is as
+follows:
+@example
+INVOCATION-NAME            "shell"       "container"     FRAME-NAME
+x-emacs-application-class  "EmacsShell"  "EmacsManager"  "EmacsFrame"
+@end example
+where INVOCATION-NAME is the terminal component of the name of the
+XEmacs executable (usually @samp{xemacs}), and
+@samp{x-emacs-application-class} is generally @samp{Emacs}.
+@node Menubar Resources
+@subsection Menubar Resources
+As the menubar is implemented as a widget which is not a part of XEmacs
+proper, it does not use the fac" mechanism for specifying fonts and
+colors: It uses whatever resources are appropriate to the type of widget
+which is used to implement it.
+If Emacs was compiled to use only the Motif-lookalike menu widgets, then one
+way to specify the font of the menubar would be
+@example
+Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+@end example
+If the Motif library is being used, then one would have to use
+@example
+Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+@end example
+because the Motif library uses the @code{fontList} resource name instead
+of @code{font}, which has subtly different semantics.
+The same is true of the scrollbars: They accept whichever resources are
+appropriate for the toolkit in use.

Mercurial > hg > xemacs-beta

comparison man/xemacs/custom.texi @ 428:3ecd8885ac67 r21-2-22