From: Alan Mackenzie Date: Thu, 15 Feb 2018 20:58:15 +0000 (+0000) Subject: Document open-paren-in-column-0-is-defun-start being of less importance X-Git-Tag: emacs-27.0.90~5679 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=aead21d83ed073f179df856a93228202ff9baee0;p=emacs.git 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. --- 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