Some doc about electric-indent-mode.

* doc/lispref/text.texi (Margins): Fix the description of RET and `C-j'.

* doc/emacs/programs.texi (Basic Indent):
(Other C Commands): Fix the description of RET and `C-j'.

* doc/emacs/indent.texi (Indentation Commands): Move the description of
`C-j' from here...
* doc/emacs/basic.texi (Inserting Text): ... to here.

9 files changed, 37 insertions, 23 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 55c92de246..2433e3c8b8 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,12 @@
+2014-02-27  Xue Fuqiao  <[email protected]>
+
+	* programs.texi (Basic Indent):
+	(Other C Commands): Fix the description of RET and `C-j'.
+
+	* indent.texi (Indentation Commands): Move the description of
+	`C-j' from here...
+	* basic.texi (Inserting Text): ... to here.
+
 2014-02-25  Glenn Morris  <[email protected]>
 
 	* custom.texi (Terminal Init):
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 27a8ba9438..f2ec11c2c1 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -40,14 +40,20 @@ forward, so that point remains just after the inserted text.
 @xref{Point}.
 
 @kindex RET
+@kindex C-j
 @cindex newline
+@findex electric-indent-just-newline
   To end a line and start a new one, type @key{RET} (@code{newline}).
 (The @key{RET} key may be labeled @key{Return} or @key{Enter} on your
 keyboard, but we refer to it as @key{RET} in this manual.)  This
-command inserts a newline character into the buffer.  If point is at
-the end of the line, the effect is to create a new blank line after
-it; if point is in the middle of a line, the line is split at that
-position.
+command inserts a newline character into the buffer, then indent
+(@pxref{Indentation}) accroding to major mode.  If point is at the end
+of the line, the effect is to create a new blank line after it and
+indent the new line; if point is in the middle of a line, the line is
+split at that position.  To turn off the auto-indentation, you can
+either desable Electric Indent mode (@pxref{Indent Convenience}) or
+type @kbd{C-j}, which inserts just a newline, without any
+auto-indentation.
 
   As we explain later in this manual, you can change the way Emacs
 handles text insertion by turning on @dfn{minor modes}.  For instance,
diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi
index 9aec6202de..78e2e925e4 100644
--- a/doc/emacs/indent.texi
+++ b/doc/emacs/indent.texi
@@ -64,11 +64,6 @@ Emacs provides a variety of commands to perform indentation in other
 ways.
 
 @table @kbd
-@item C-j
-@kindex C-j
-@findex newline-and-indent
-Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
-
 @item C-M-o
 @kindex C-M-o
 @findex split-line
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 26e9539d75..4a6da9e4fd 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -366,9 +366,9 @@ which reformats Lisp objects with nice-looking indentation.
 @table @kbd
 @item @key{TAB}
 Adjust indentation of current line (@code{indent-for-tab-command}).
-@item C-j
+@item @key{RET}
 Insert a newline, then adjust indentation of following line
-(@code{newline-and-indent}).
+(@code{newline}).
 @end table
 
 @kindex TAB @r{(programming modes)}
@@ -382,12 +382,9 @@ the current line, based on the indentation and syntactic content of
 the preceding lines; if the region is active, @key{TAB} indents each
 line within the region, not just the current line.
 
-@kindex C-j @r{(indenting source code)}
-@findex newline-and-indent
-  The command @kbd{C-j} (@code{newline-and-indent}), which was
-documented in @ref{Indentation Commands}, does the same as @key{RET}
-followed by @key{TAB}: it inserts a new line, then adjusts the line's
-indentation.
+  The command @key{RET} (@code{newline}), which was documented in
+@ref{Inserting Text}, does the same as @key{C-j} followed by
+@key{TAB}: it inserts a new line, then adjusts the line's indentation.
 
   When indenting a line that starts within a parenthetical grouping,
 Emacs usually places the start of the line under the preceding line
@@ -1681,18 +1678,18 @@ hungry-delete feature is enabled.
 @findex c-context-line-break
 This command inserts a line break and indents the new line in a manner
 appropriate to the context.  In normal code, it does the work of
-@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
-additionally inserts a @samp{\} at the line break, and within comments
-it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
+@key{RET} (@code{newline}), in a C preprocessor line it additionally
+inserts a @samp{\} at the line break, and within comments it's like
+@kbd{M-j} (@code{c-indent-new-comment-line}).
 
 @code{c-context-line-break} isn't bound to a key by default, but it
 needs a binding to be useful.  The following code will bind it to
-@kbd{C-j}.  We use @code{c-initialization-hook} here to make sure
+@kbd{RET}.  We use @code{c-initialization-hook} here to make sure
 the keymap is loaded before we try to change it.
 
 @example
 (defun my-bind-clb ()
-  (define-key c-mode-base-map "\C-j"
+  (define-key c-mode-base-map "\C-m"
               'c-context-line-break))
 (add-hook 'c-initialization-hook 'my-bind-clb)
 @end example
@@ -1812,6 +1809,7 @@ defines these commands:
 @table @kbd
 @item @key{TAB}
 @code{tab-to-tab-stop}.
+@c FIXME: Maybe this should be consistent with other programming modes.
 @item C-j
 Insert a newline and then indent using @code{tab-to-tab-stop}.
 @item :
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 8d473033bd..0e64feab6f 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2014-02-27  Xue Fuqiao  <[email protected]>
 
+	* text.texi (Margins): Fix the description of RET and `C-j'.
+
 	* frames.texi (Multiple Terminals): Document
 	`display-monitor-attributes-list' and `display-monitor-attributes'.
 	(Display Feature Testing): Add some notes about multi-monitor.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 18701465d0..9df6cf61e0 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1717,7 +1717,7 @@ is value of @code{indent-line-function} in Paragraph-Indent Text mode.
 
 @defopt left-margin
 This variable specifies the base left margin column.  In Fundamental
-mode, @kbd{C-j} indents to this column.  This variable automatically
+mode, @kbd{RET} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.
 @end defopt
 
diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi
index 2d916b8416..c7f51b4dcb 100644
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -751,6 +751,7 @@ very useful in this case.
 @end itemize
 
 @table @asis
+@c FIXME: This should be `electric-indent-just-newline' since GNU Emacs 24.4.
 @item @kbd{C-j} (@code{newline-and-indent})
 @kindex C-j
 @findex newline-and-indent
@@ -7054,6 +7055,7 @@ Set the variable @code{c-basic-offset}.  @xref{Getting Started}.
 @kindex RET
 @kindex C-j
 @emph{Why doesn't the @kbd{RET} key indent the new line?}
+@c FIXME: `electric-indent-mode' is enabled by default in GNU Emacs 24.4.
 
 Emacs's convention is that @kbd{RET} just adds a newline, and that
 @kbd{C-j} adds a newline and indents it.  You can make @kbd{RET} do this
diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi
index 305a54800c..6dde042a31 100644
--- a/doc/misc/octave-mode.texi
+++ b/doc/misc/octave-mode.texi
@@ -148,6 +148,7 @@ and return values which have to be entered without parentheses
 in one of your Emacs startup files.
 @end table
 
+@c FIXME: `electric-indent-mode' is enabled by default in GNU Emacs 24.4.
 A common problem is that the @key{RET} key does @emph{not} indent the
 line to where the new text should go after inserting the newline.  This
 is because the standard Emacs convention is that @key{RET} (aka
diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi
index 90dc3cd8de..95f829d14e 100644
--- a/doc/misc/vip.texi
+++ b/doc/misc/vip.texi
@@ -1568,6 +1568,7 @@ Set mark and push previous mark on mark ring (@code{set-mark-command}).
 @kindex 011 TAB (@code{indent-for-tab-command})
 Indent line for current major mode (@code{indent-for-tab-command}).
 @item C-j
+@c FIXME: This should be `electric-indent-just-newline' since GNU Emacs 24.4.
 @kindex 012 @kbd{C-j} (@code{newline-and-indent})
 Insert a newline, then indent according to mode (@code{newline-and-indent}).
 @item C-k