+File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
+
+Introduction to Buffer-Local Variables
+--------------------------------------
+
+ A buffer-local variable has a buffer-local binding associated with a
+particular buffer. The binding is in effect when that buffer is
+current; otherwise, it is not in effect. If you set the variable while
+a buffer-local binding is in effect, the new value goes in that binding,
+so the global binding is unchanged; this means that the change is
+visible in that buffer alone.
+
+ A variable may have buffer-local bindings in some buffers but not in
+others. The global binding is shared by all the buffers that don't have
+their own bindings. Thus, if you set the variable in a buffer that does
+not have a buffer-local binding for it, the new value is visible in all
+buffers except those with buffer-local bindings. (Here we are assuming
+that there are no `let'-style local bindings to complicate the issue.)
+
+ The most common use of buffer-local bindings is for major modes to
+change variables that control the behavior of commands. For example, C
+mode and Lisp mode both set the variable `paragraph-start' to specify
+that only blank lines separate paragraphs. They do this by making the
+variable buffer-local in the buffer that is being put into C mode or
+Lisp mode, and then setting it to the new value for that mode.
+
+ The usual way to make a buffer-local binding is with
+`make-local-variable', which is what major mode commands use. This
+affects just the current buffer; all other buffers (including those yet
+to be created) continue to share the global value.
+
+ A more powerful operation is to mark the variable as "automatically
+buffer-local" by calling `make-variable-buffer-local'. You can think
+of this as making the variable local in all buffers, even those yet to
+be created. More precisely, the effect is that setting the variable
+automatically makes the variable local to the current buffer if it is
+not already so. All buffers start out by sharing the global value of
+the variable as usual, but any `setq' creates a buffer-local binding
+for the current buffer. The new value is stored in the buffer-local
+binding, leaving the (default) global binding untouched. The global
+value can no longer be changed with `setq'; you need to use
+`setq-default' to do that.
+
+ Local variables in a file you edit are also represented by
+buffer-local bindings for the buffer that holds the file within XEmacs.
+*Note Auto Major Mode::.
+
+\1f
+File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
+
+Creating and Deleting Buffer-Local Bindings
+-------------------------------------------
+
+ - Command: make-local-variable variable
+ This function creates a buffer-local binding in the current buffer
+ for VARIABLE (a symbol). Other buffers are not affected. The
+ value returned is VARIABLE.
+
+ The buffer-local value of VARIABLE starts out as the same value
+ VARIABLE previously had. If VARIABLE was void, it remains void.
+
+ ;; In buffer `b1':
+ (setq foo 5) ; Affects all buffers.
+ => 5
+ (make-local-variable 'foo) ; Now it is local in `b1'.
+ => foo
+ foo ; That did not change
+ => 5 ; the value.
+ (setq foo 6) ; Change the value
+ => 6 ; in `b1'.
+ foo
+ => 6
+
+ ;; In buffer `b2', the value hasn't changed.
+ (save-excursion
+ (set-buffer "b2")
+ foo)
+ => 5
+
+ Making a variable buffer-local within a `let'-binding for that
+ variable does not work. This is because `let' does not distinguish
+ between different kinds of bindings; it knows only which variable
+ the binding was made for.
+
+ *Please note:* do not use `make-local-variable' for a hook
+ variable. Instead, use `make-local-hook'. *Note Hooks::.
+
+ - Command: make-variable-buffer-local variable
+ This function marks VARIABLE (a symbol) automatically
+ buffer-local, so that any subsequent attempt to set it will make it
+ local to the current buffer at the time.
+
+ The value returned is VARIABLE.
+
+ - Function: local-variable-p variable buffer &optional after-set
+ This returns `t' if VARIABLE is buffer-local in buffer BUFFER;
+ else `nil'.
+
+ If optional third arg AFTER-SET is non-`nil', return `t' if SYMBOL
+ would be buffer-local after it is set, regardless of whether it is
+ so presently.
+
+ A `nil' value for BUFFER is _not_ the same as `(current-buffer)',
+ but means "no buffer". Specifically:
+
+ If BUFFER is `nil' and AFTER-SET is `nil', a return value of `t'
+ indicates that the variable is one of the special built-in
+ variables that is always buffer-local. (This includes
+ `buffer-file-name', `buffer-read-only', `buffer-undo-list', and
+ others.)
+
+ If BUFFER is `nil' and AFTER-SET is `t', a return value of `t'
+ indicates that the variable has had `make-variable-buffer-local'
+ applied to it.
+
+ - Function: buffer-local-variables &optional buffer
+ This function returns a list describing the buffer-local variables
+ in buffer BUFFER. It returns an association list (*note
+ Association Lists::) in which each association contains one
+ buffer-local variable and its value. When a buffer-local variable
+ is void in BUFFER, then it appears directly in the resulting list.
+ If BUFFER is omitted, the current buffer is used.
+
+ (make-local-variable 'foobar)
+ (makunbound 'foobar)
+ (make-local-variable 'bind-me)
+ (setq bind-me 69)
+ (setq lcl (buffer-local-variables))
+ ;; First, built-in variables local in all buffers:
+ => ((mark-active . nil)
+ (buffer-undo-list nil)
+ (mode-name . "Fundamental")
+ ...
+ ;; Next, non-built-in local variables.
+ ;; This one is local and void:
+ foobar
+ ;; This one is local and nonvoid:
+ (bind-me . 69))
+
+ Note that storing new values into the CDRs of cons cells in this
+ list does _not_ change the local values of the variables.
+
+ - Command: kill-local-variable variable
+ This function deletes the buffer-local binding (if any) for
+ VARIABLE (a symbol) in the current buffer. As a result, the
+ global (default) binding of VARIABLE becomes visible in this
+ buffer. Usually this results in a change in the value of
+ VARIABLE, since the global value is usually different from the
+ buffer-local value just eliminated.
+
+ If you kill the local binding of a variable that automatically
+ becomes local when set, this makes the global value visible in the
+ current buffer. However, if you set the variable again, that will
+ once again create a local binding for it.
+
+ `kill-local-variable' returns VARIABLE.
+
+ This function is a command because it is sometimes useful to kill
+ one buffer-local variable interactively, just as it is useful to
+ create buffer-local variables interactively.
+
+ - Function: kill-all-local-variables
+ This function eliminates all the buffer-local variable bindings of
+ the current buffer except for variables marked as "permanent". As
+ a result, the buffer will see the default values of most variables.
+
+ This function also resets certain other information pertaining to
+ the buffer: it sets the local keymap to `nil', the syntax table to
+ the value of `standard-syntax-table', and the abbrev table to the
+ value of `fundamental-mode-abbrev-table'.
+
+ Every major mode command begins by calling this function, which
+ has the effect of switching to Fundamental mode and erasing most
+ of the effects of the previous major mode. To ensure that this
+ does its job, the variables that major modes set should not be
+ marked permanent.
+
+ `kill-all-local-variables' returns `nil'.
+
+ A local variable is "permanent" if the variable name (a symbol) has a
+`permanent-local' property that is non-`nil'. Permanent locals are
+appropriate for data pertaining to where the file came from or how to
+save it, rather than with how to edit the contents.
+
+\1f