mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-22 07:09:54 +00:00
Code Issues Releases Activity

Moderate recommendation to escape '(' in doc strings

Browse Source 
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.
This commit is contained in:
Mattias Engdegård 2020-01-25 16:16:37 +01:00
parent d7cd4ab7d9
commit 2e9a153b26
2 changed files with 19 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/lispref/tips.texi
View File

@ -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

4
etc/NEWS
View File

@ -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