[Emacs-diffs] trunk r116797: * doc/lispref/modes.texi (Auto-Indentation): Mention electric-indent variables.

[Stefan Monnier]

------------------------------------------------------------
revno: 116797
revision-id: address@hidden
parent: address@hidden
committer: Stefan Monnier <address@hidden>
branch nick: trunk
timestamp: Tue 2014-03-18 17:14:36 -0400
message:
  * doc/lispref/modes.texi (Auto-Indentation): Mention electric-indent 
variables.
  * doc/misc/cc-mode.texi (Indentation Commands): Remove C-j, since it's not
  defined by CC-mode but globally.
  (FAQ): Tweak text about RET and auto-indentation.
  * doc/misc/vip.texi (Other Vi Commands): Adjust doc of C-j.
modified:
  doc/emacs/basic.texi           basic.texi-20091113204419-o5vbwnq5f7feedwu-6233
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/modes.texi         modes.texi-20091113204419-o5vbwnq5f7feedwu-6201
  doc/lispref/text.texi          text.texi-20091113204419-o5vbwnq5f7feedwu-6215
  doc/misc/ChangeLog             changelog-20091113204419-o5vbwnq5f7feedwu-6331
  doc/misc/cc-mode.texi          
ccmode.texi-20091113204419-o5vbwnq5f7feedwu-6291
  doc/misc/vip.texi              vip.texi-20091113204419-o5vbwnq5f7feedwu-6327
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1

=== modified file 'doc/emacs/basic.texi'
--- a/doc/emacs/basic.texi      2014-03-03 05:12:12 +0000
+++ b/doc/emacs/basic.texi      2014-03-18 21:14:36 +0000
@@ -42,7 +42,7 @@
 @kindex RET
 @kindex C-j
 @cindex newline
address@hidden electric-indent-just-newline
address@hidden @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

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-18 11:29:33 +0000
+++ b/doc/lispref/ChangeLog     2014-03-18 21:14:36 +0000
@@ -1,3 +1,7 @@
+2014-03-18  Stefan Monnier  <address@hidden>
+
+       * modes.texi (Auto-Indentation): Mention electric-indent variables.
+
 2014-03-18  Juanma Barranquero  <address@hidden>
 
        * functions.texi (Advising Named Functions): Fix reference.

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2014-03-05 07:41:48 +0000
+++ b/doc/lispref/modes.texi    2014-03-18 21:14:36 +0000
@@ -3303,18 +3303,28 @@
 @section Automatic Indentation of code
 
 For programming languages, an important feature of a major mode is to
-provide automatic indentation.  This is controlled in Emacs by
address@hidden (@pxref{Mode-Specific Indent}).
-Writing a good indentation function can be difficult and to a large
-extent it is still a black art.
-
-Many major mode authors will start by writing a simple indentation
-function that works for simple cases, for example by comparing with the
-indentation of the previous text line.  For most programming languages
-that are not really line-based, this tends to scale very poorly:
-improving such a function to let it handle more diverse situations tends
-to become more and more difficult, resulting in the end with a large,
-complex, unmaintainable indentation function which nobody dares to touch.
+provide automatic indentation.  There are two parts: one is to decide what
+is the right indentation of a line, and the other is to decide when to
+reindent a line.  By default, Emacs reindents a line whenever you
+type a character in @code{electric-indent-chars}, which by default only
+includes Newline.  Major modes can add chars to @code{electric-indent-chars}
+according to the syntax of the language.
+
+Deciding what is the right indentation is controlled in Emacs by
address@hidden (@pxref{Mode-Specific Indent}).  For some modes,
+the @emph{right} indentation cannot be known reliably, typically because
+indentation is significant so several indentations are valid but with different
+meanings.  In that case, the mode should set @code{electric-indent-inhibit} to
+make sure the line is not constantly re-indented against the user's wishes.
+
+Writing a good indentation function can be difficult and to a large extent it
+is still a black art.  Many major mode authors will start by writing a simple
+indentation function that works for simple cases, for example by comparing with
+the indentation of the previous text line.  For most programming languages that
+are not really line-based, this tends to scale very poorly: improving
+such a function to let it handle more diverse situations tends to become more
+and more difficult, resulting in the end with a large, complex, unmaintainable
+indentation function which nobody dares to touch.
 
 A good indentation function will usually need to actually parse the
 text, according to the syntax of the language.  Luckily, it is not
@@ -3332,7 +3342,7 @@
 purpose of indentation it has the advantage of not needing to
 guess a ``safe'' starting point, and it generally enjoys the property
 that only a minimum of text will be analyzed to decide the indentation
-of a line, so indentation will tend to be unaffected by syntax errors in
+of a line, so indentation will tend to be less affected by syntax errors in
 some earlier unrelated piece of code.  Parsing forward on the other hand
 is usually easier and has the advantage of making it possible to
 reindent efficiently a whole region at a time, with a single parse.

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2014-03-18 01:19:03 +0000
+++ b/doc/lispref/text.texi     2014-03-18 21:14:36 +0000
@@ -3946,7 +3946,7 @@
 intervals with the same properties, and we kill the text of one interval
 and yank it back.  The same interval-coalescence feature that rescues
 the other case causes trouble in this one: after yanking, we have just
-one interval.  One again, editing does not preserve the distinction
+one interval.  Once again, editing does not preserve the distinction
 between one interval and two.
 
   Insertion of text at the border between intervals also raises

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2014-03-18 21:12:42 +0000
+++ b/doc/misc/ChangeLog        2014-03-18 21:14:36 +0000
@@ -1,10 +1,18 @@
+2014-03-18  Stefan Monnier  <address@hidden>
+
+       * vip.texi (Other Vi Commands): Adjust doc of C-j.
+
+       * cc-mode.texi (Indentation Commands): Remove C-j, since it's not
+       defined by CC-mode but globally.
+       (FAQ): Tweak text about RET and auto-indentation.
+
 2014-03-18  David Engster  <address@hidden>
 
        * ede.texi (Project Local Variables): Remove reference to
        `ede-java-root' and the example using it.
        (Android projects, ede-java-root): Remove nodes since they are
        only in CEDET upstream (Bug#17030).  All nodes updated.
-        (ede-cpp-root): Document the :compile-command slot.
+       (ede-cpp-root): Document the :compile-command slot.
        (ede-linux): Document new variables
        `project-linux-build-directory-default' and
        `project-linux-architecture-default'.
@@ -11205,7 +11213,7 @@
 
 1998-03-01  Kim-Minh Kaplan  <address@hidden>
 
-       * gnus.texi (Easy Picons): Removed references to
+       * gnus.texi (Easy Picons): Remove references to
        `gnus-group-display-picons'.
        (Hard Picons): Ditto.
 

=== modified file 'doc/misc/cc-mode.texi'
--- a/doc/misc/cc-mode.texi     2014-02-27 11:59:35 +0000
+++ b/doc/misc/cc-mode.texi     2014-03-18 21:14:36 +0000
@@ -751,13 +751,6 @@
 @end itemize
 
 @table @asis
address@hidden FIXME: This should be `electric-indent-just-newline' since GNU 
Emacs 24.4.
address@hidden @kbd{C-j} (@code{newline-and-indent})
address@hidden C-j
address@hidden newline-and-indent
-Inserts a newline and indents the new blank line, ready to start
-typing.  This is a standard (X)Emacs command.
-
 @item @kbd{C-M-q} (@code{c-indent-exp})
 @kindex C-M-q
 @findex c-indent-exp
@@ -7054,19 +7047,20 @@
 @item
 @kindex RET
 @kindex C-j
address@hidden doesn't the @kbd{RET} key indent the new line?}
address@hidden 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
address@hidden adds a newline and indents it.  You can make @kbd{RET} do this
-too by adding this to your @code{c-initialization-hook}:
address@hidden does/doesn't the @kbd{RET} key indent the new line?}
+
+Emacs's convention used to be that @kbd{RET} just adds a newline, and that
address@hidden adds a newline and indents it.  In Emacs-24.4, this convention 
was
+reversed.
+
+If you use an older Emacs and you want @kbd{RET} do this
+too, add this to your @code{c-initialization-hook}:
 
 @example
 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
 @end example
 
address@hidden Started}.  This is a very common question.  If you want
-this to be the default behavior, don't lobby us, lobby address@hidden  @t{:-)}
address@hidden Started}.  This was a very common question.
 
 @item
 @emph{How do I stop my code jumping all over the place when I type?}

=== modified file 'doc/misc/vip.texi'
--- a/doc/misc/vip.texi 2014-02-27 11:59:35 +0000
+++ b/doc/misc/vip.texi 2014-03-18 21:14:36 +0000
@@ -1568,9 +1568,8 @@
 @kindex 011 TAB (@code{indent-for-tab-command})
 Indent line for current major mode (@code{indent-for-tab-command}).
 @item C-j
address@hidden FIXME: This should be `electric-indent-just-newline' since GNU 
Emacs 24.4.
address@hidden 012 @kbd{C-j} (@code{newline-and-indent})
-Insert a newline, then indent according to mode (@code{newline-and-indent}).
address@hidden 012 @kbd{C-j} (@code{electric-indent-just-newline'} or 
@code{newline-and-indent})
+Insert a newline, and maybe indent according to mode.
 @item C-k
 @kindex 013 @kbd{C-k} (@code{kill-line})
 Kill the rest of the current line; before a newline, kill the newline.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-03-15 03:07:06 +0000
+++ b/etc/NEWS  2014-03-18 21:14:36 +0000
@@ -355,6 +355,7 @@
 
 ** Indentation changes
 
++++
 *** `electric-indent-mode' is now enabled by default.
 E.g., typing RET reindents the current line and indents the new line.
 `C-j' inserts a newline but does not indent.