diff options
| -rw-r--r-- | doc/emacs/basic.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/lispref/modes.texi | 36 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 2 | ||||
| -rw-r--r-- | doc/misc/ChangeLog | 12 | ||||
| -rw-r--r-- | doc/misc/cc-mode.texi | 22 | ||||
| -rw-r--r-- | doc/misc/vip.texi | 5 | ||||
| -rw-r--r-- | etc/NEWS | 1 |
8 files changed, 50 insertions, 34 deletions
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index c0a93c9396d..c5ded11c62e 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -42,7 +42,7 @@ forward, so that point remains just after the inserted text. @kindex RET @kindex C-j @cindex newline -@findex electric-indent-just-newline +@c @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 diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index dbab5f1fd5d..723bd1188c6 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * modes.texi (Auto-Indentation): Mention electric-indent variables. + 2014-03-18 Juanma Barranquero <lekktu@gmail.com> * functions.texi (Advising Named Functions): Fix reference. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 30b0f758c27..c30547e65ab 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3303,18 +3303,28 @@ reasonably fast. @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 -@code{indent-line-function} (@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 +@code{indent-line-function} (@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 @@ programming languages are designed to be parsed forward, but for the 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. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 1a9a3d0a0ec..f8a3e873449 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3946,7 +3946,7 @@ single interval. But suppose instead that we have two adjacent 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 diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index a2d201ff692..8796cafa4d6 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,10 +1,18 @@ +2014-03-18 Stefan Monnier <monnier@iro.umontreal.ca> + + * 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 <deng@randomsample.de> * 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 <KimMinh.Kaplan@utopia.eunet.fr> - * gnus.texi (Easy Picons): Removed references to + * gnus.texi (Easy Picons): Remove references to `gnus-group-display-picons'. (Hard Picons): Ditto. diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index c7f51b4dcbe..f6537ac22b3 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -751,13 +751,6 @@ 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 -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 @@ Set the variable @code{c-basic-offset}. @xref{Getting Started}. @item @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. +@emph{Why 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 +@kbd{C-j} adds a newline and indents it. In Emacs-24.4, this convention was +reversed. -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 -too by adding this to your @code{c-initialization-hook}: +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 -@xref{Getting Started}. This is a very common question. If you want -this to be the default behavior, don't lobby us, lobby RMS@! @t{:-)} +@xref{Getting Started}. This was a very common question. @item @emph{How do I stop my code jumping all over the place when I type?} diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 95f829d14ed..2c888fd1432 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -1568,9 +1568,8 @@ 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}). +@kindex 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. @@ -355,6 +355,7 @@ means to always load the .elc file. ** 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. |