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 @@ -802,18 +802,6 @@ explicitly what constitutes truth. The word ``return'' avoids 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 @@ -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 diff --git a/etc/NEWS b/etc/NEWS index 792851e5af5..433f1f76b80 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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