diff options
| author | Mattias Engdegård <mattiase@acm.org> | 2020-01-25 16:16:37 +0100 |
|---|---|---|
| committer | Mattias Engdegård <mattiase@acm.org> | 2020-01-26 14:52:15 +0100 |
| commit | 2e9a153b26da820da5b731261ed9ca437c0212a3 (patch) | |
| tree | 9e272582a13d2e077e129efb7288ad2ea16be228 /doc/lispref/tips.texi | |
| parent | d7cd4ab7d948427104003f1d35cf52a4eac45d0a (diff) | |
| download | emacs-2e9a153b26da820da5b731261ed9ca437c0212a3.tar.gz emacs-2e9a153b26da820da5b731261ed9ca437c0212a3.tar.bz2 emacs-2e9a153b26da820da5b731261ed9ca437c0212a3.zip | |
Moderate recommendation to escape '(' in doc strings
Thanks to 57e2ca5c50 and related changes, opening brackets at the
leftmost column inside doc strings are no longer mistaken for the
start of a defun.
* doc/lispref/tips.texi (Documentation Tips): Clarify recommendation
and move it down the list.
* etc/NEWS: Announce.
Diffstat (limited to 'doc/lispref/tips.texi')
| -rw-r--r-- | doc/lispref/tips.texi | 27 |
1 files changed, 15 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 |