Document open-paren-in-column-0-is-defun-start being of less importance

* doc/emacs/programs.texi (Left Margin Paren): Update to reflect the recent
change in syntax.c, whereby a paren at column 0 is no longer taken as a
beginning of defun in moving backwards over comments.

1 files changed, 14 insertions, 48 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 42891245451..d7041a0beb4 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -151,56 +151,22 @@ Emacs we use it for all languages.
 
 @cindex open-parenthesis in leftmost column
 @cindex ( in leftmost column
-  Many programming-language modes assume by default that any opening
-delimiter found at the left margin is the start of a top-level
-definition, or defun.  Therefore, @strong{don't put an opening
-delimiter at the left margin unless it should have that significance}.
-For instance, never put an open-parenthesis at the left margin in a
-Lisp file unless it is the start of a top-level list.
-
-  The convention speeds up many Emacs operations, which would
-otherwise have to scan back to the beginning of the buffer to analyze
-the syntax of the code.
-
-  If you don't follow this convention, not only will you have trouble
-when you explicitly use the commands for motion by defuns; other
-features that use them will also give you trouble.  This includes the
-indentation commands (@pxref{Program Indent}) and Font Lock mode
-(@pxref{Font Lock}).
-
-  The most likely problem case is when you want an opening delimiter
-at the start of a line inside a string.  To avoid trouble, put an
-escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
-other Lisp dialects) before the opening delimiter.  This will not
-affect the contents of the string, but will prevent that opening
-delimiter from starting a defun.  Here's an example:
-
-@example
-  (insert "Foo:
-\(bar)
-")
-@end example
-
-  To help you catch violations of this convention, Font Lock mode
-highlights confusing opening delimiters (those that ought to be
-quoted) in bold red.
+  Many programming-language modes have traditionally assumed that any
+opening parenthesis or brace found at the left margin is the start of
+a top-level definition, or defun.  So, by default, commands which seek
+the beginning of a defun accept such a delimiter as signifying that
+position.
 
 @vindex open-paren-in-column-0-is-defun-start
-  If you need to override this convention, you can do so by setting
-the variable @code{open-paren-in-column-0-is-defun-start}.
-If this user option is set to @code{t} (the default), opening
-parentheses or braces at column zero always start defuns.  When it is
-@code{nil}, defuns are found by searching for parens or braces at the
-outermost level.
-
-  Usually, you should leave this option at its default value of
-@code{t}.  If your buffer contains parentheses or braces in column
-zero which don't start defuns, and it is somehow impractical to remove
-these parentheses or braces, it might be helpful to set the option to
-@code{nil}.  Be aware that this might make scrolling and display in
-large buffers quite sluggish.  Furthermore, the parentheses and braces
-must be correctly matched throughout the buffer for it to work
-properly.
+  If you want to override this convention, you can do so by setting
+the user option @code{open-paren-in-column-0-is-defun-start} to
+@code{nil}.  If this option is set to @code{t} (the default), commands
+seeking the start of a defun will stop at opening parentheses or
+braces at column zero.  When it is @code{nil}, defuns are found by
+searching for parens or braces at the outermost level.  Since
+low-level Emacs routines no longer depend on this convention, you
+usually won't need to change
+@code{open-paren-in-column-0-is-defun-start} from its default.
 
 @node Moving by Defuns
 @subsection Moving by Defuns