diff options
| -rw-r--r-- | doc/lispref/tips.texi | 27 | ||||
| -rw-r--r-- | etc/NEWS | 4 |
2 files changed, 19 insertions, 12 deletions
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 4395069fe24..0610f8029df 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -803,18 +803,6 @@ starting the sentence with lower-case ``t'', which could be somewhat distracting. @item -If a line in a documentation string begins with an open-parenthesis, -write a backslash before the open-parenthesis, like this: - -@example -The argument FOO can be either a number -\(a buffer position) or a string (a file name). -@end example - -This prevents the open-parenthesis from being treated as the start of a -defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). - -@item Write documentation strings in the active voice, not the passive, and in the present tense, not the future. For instance, use ``Return a list containing A and B.@:'' instead of ``A list containing A and B will be @@ -849,6 +837,21 @@ The documentation string for a variable that is a yes-or-no flag should start with words such as ``Non-nil means'', to make it clear that all non-@code{nil} values are equivalent and indicate explicitly what @code{nil} and non-@code{nil} mean. + +@item +If a line in a documentation string begins with an open-parenthesis, +consider writing a backslash before the open-parenthesis, like this: + +@example +The argument FOO can be either a number +\(a buffer position) or a string (a file name). +@end example + +This avoids a bug in Emacs versions older than 27.1, where the +@samp{(} was treated as the start of a defun +(@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). +If you do not anticipate anyone editing your code with older Emacs +versions, there is no need for this work-around. @end itemize @node Comment Tips @@ -3338,6 +3338,10 @@ versions. 'forward-comment', 'scan-sexps', and 'forward-sexp' when parsing backward. The new variable 'comment-use-syntax-ppss' can be set to nil to recover the old behavior if needed. +This also means that there is no longer any need to precede opening +brackets at the start of a line inside documentation strings with a +backslash, although there is no harm in doing so to make the code +easier to edit with an older Emacs version. --- ** The 'server-name' and 'server-socket-dir' variables are set when a |