# HG changeset patch
# User Chong Yidong <cyd@stupidchicken.com>
# Date 1267902169 18000
# Node ID d4567b4f2db3bec1133c03a3f19b3aa124bba31b
# Parent  176028ab9fc6a89574be285bef8e244ff254837e
Improve documentation for setting buffer-local vars (Bug#5688).

* custom.texi (Init Examples): Add xref to Locals.

* major.texi (Choosing Modes): Mention usage of setq-default for
setting the default value of major-mode (Bug#5688).

diff -r 176028ab9fc6 -r d4567b4f2db3 doc/emacs/ChangeLog
--- a/doc/emacs/ChangeLog	Sat Mar 06 13:23:23 2010 -0500
+++ b/doc/emacs/ChangeLog	Sat Mar 06 14:02:49 2010 -0500
@@ -1,3 +1,10 @@
+2010-03-06  Chong Yidong  <cyd@stupidchicken.com>
+
+	* custom.texi (Init Examples): Add xref to Locals.
+
+	* major.texi (Choosing Modes): Mention usage of setq-default for
+	setting the default value of major-mode (Bug#5688).
+
 2010-03-02  Chong Yidong  <cyd@stupidchicken.com>
 
 	* frames.texi (Mouse Avoidance): Mention make-pointer-invisible.
diff -r 176028ab9fc6 -r d4567b4f2db3 doc/emacs/custom.texi
--- a/doc/emacs/custom.texi	Sat Mar 06 13:23:23 2010 -0500
+++ b/doc/emacs/custom.texi	Sat Mar 06 14:02:49 2010 -0500
@@ -2256,9 +2256,10 @@
 @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 not what you probably want to do in an init file.
+not have local values for the variable (@pxref{Locals}).  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
 @vindex user-mail-address
diff -r 176028ab9fc6 -r d4567b4f2db3 doc/emacs/major.texi
--- a/doc/emacs/major.texi	Sat Mar 06 13:23:23 2010 -0500
+++ b/doc/emacs/major.texi	Sat Mar 06 14:02:49 2010 -0500
@@ -196,17 +196,33 @@
 @code{magic-fallback-mode-alist} contains forms that check for image
 files, HTML/XML/SGML files, and Postscript files.
 
-  When you visit a file that does not specify a major mode to use, or
-when you create a new buffer with @kbd{C-x b}, the default value of
-the variable @code{major-mode} specifies which major mode to use.  Normally
-its value is the symbol @code{fundamental-mode}, which specifies
-Fundamental mode.  If the default value of @code{major-mode} is @code{nil},
-the major mode is taken from the previously current buffer.
+@vindex major-mode
+  Once a major mode is chosen, Emacs sets the value of the variable
+@code{major-mode} to the symbol for that major mode (e.g.,
+@code{text-mode} for Text mode).  This is a per-buffer variable
+(@pxref{Locals}); its buffer-local value is set automatically, and you
+should not change it yourself.
+
+  The default value of @code{major-mode} determines the major mode to
+use for files that do not specify a major mode, and for new buffers
+created with @kbd{C-x b}.  Normally, this default value is the symbol
+@code{fundamental-mode}, which specifies Fundamental mode.  You can
+change it via the Customization interface (@pxref{Easy
+Customization}), or by adding a line like this to your init file
+(@pxref{Init File}):
+
+@smallexample
+(setq-default major-mode 'text-mode)
+@end smallexample
+
+@noindent
+If the default value of @code{major-mode} is @code{nil}, the major
+mode is taken from the previously current buffer.
 
 @findex normal-mode
-  If you change the major mode of a buffer, you can go back to the major
-mode Emacs would choose automatically: use the command @kbd{M-x
-normal-mode} to do this.  This is the same function that
+  If you have changed the major mode of a buffer, you can return to
+the major mode Emacs would have chosen automatically, by typing
+@kbd{M-x normal-mode}.  This is the same function that
 @code{find-file} calls to choose the major mode.  It also processes
 the file's @samp{-*-} line or local variables list (if any).
 @xref{File Variables}.