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).

3 files changed, 36 insertions, 12 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index a9d7e1bcf69..55ae0882882 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -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 --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index a4914531192..408de24ed6e 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -2256,9 +2256,10 @@ override this).
 @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 --git a/doc/emacs/major.texi b/doc/emacs/major.texi
index e2e7c3d2a4c..19ab86f91dd 100644
--- a/doc/emacs/major.texi
+++ b/doc/emacs/major.texi
@@ -196,17 +196,33 @@ only after @code{auto-mode-alist}.  By default,
 @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}.