commit bdaec3f934b758a00605059d1abace5b6fb83018
parent 8198fd9c58a2b0570eea80c2388166158af04f9b
Author: Benno Schulenberg <bensberg@telfort.nl>
Date: Fri, 9 Sep 2022 16:32:41 +0200
docs: clarify the distinction between binding a function and "{function}"
This addresses https://savannah.gnu.org/bugs/?63010.
Inspired-by: Tasos Papastylianou <tpapastylianou@hotmail.com>
Diffstat:
2 files changed, 25 insertions(+), 6 deletions(-)
diff --git a/doc/nano.texi b/doc/nano.texi
@@ -1344,9 +1344,9 @@ Rebinds @code{key} to @code{function} in the context of @code{menu}
@item bind key "string" menu
Makes @code{key} produce @code{string} in the context of @code{menu}
(or in all menus where the key exists when @code{all} is used).
-Besides literal text, the @code{string} may contain function names
-between braces. These functions will be invoked when the key is typed.
-To include a literal opening brace, use @code{@{@{@}}.
+Besides literal text and/or control codes, the @code{string} may contain
+function names between braces. These functions will be invoked when the
+key is typed. To include a literal opening brace, use @code{@{@{@}}.
@item unbind key menu
Unbinds @code{key} from @code{menu}
@@ -1354,6 +1354,16 @@ Unbinds @code{key} from @code{menu}
@end table
+Note that @code{bind key "@{function@}" menu} is equivalent to
+@code{bind key function menu}, except that for the latter form
+@command{nano} will check the availabilty of the @code{function}
+in the given @code{menu} at startup time (and report an error if
+it does not exist there), whereas for the first form @command{nano}
+will check at execution time that the @code{function} exists but not
+whether it makes any sense in the current menu. The user has to take
+care that a function name between braces (or any sequence of them)
+is appropriate. Strange behavior can result when it is not.
+
@sp 1
The format of @code{key} should be one of:
diff --git a/doc/nanorc.5 b/doc/nanorc.5
@@ -559,14 +559,23 @@ Rebinds the given \fIkey\fP to the given \fIfunction\fP in the given \fImenu\fP
.BI bind " key " """" string """" " menu"
Makes the given \fIkey\fR produce the given \fIstring\fR in the given
\fImenu\fR (or in all menus where the key exists when \fBall\fR is used).
-Besides literal text, the \fIstring\fR may contain function names
-between braces. These functions will be invoked when the key is typed.
-To include a literal opening brace, use \fB{{}\fR.
+Besides literal text and/or control codes, the \fIstring\fR may contain
+function names between braces. These functions will be invoked when
+the key is typed. To include a literal opening brace, use \fB{{}\fR.
.TP
.BI unbind " key menu"
Unbinds the given \fIkey\fP from the given \fImenu\fP (or from all
menus where the key exists when \fBall\fP is used).
.RE
+.sp
+Note that \fBbind \fIkey\fR \fB"{\fIfunction\fB}"\fR \fImenu\fR is equivalent
+to \fBbind \fIkey\fR \fIfunction\fR \fImenu\fR, except that for the latter form
+\fBnano\fR will check the availabilty of the \fIfunction\fR in the given \fImenu\fR
+at startup time (and report an error if it does not exist there), whereas for the
+first form \fBnano\fR will check at execution time that the \fIfunction\fR exists
+but not whether it makes any sense in the current menu. The user has to take care
+that a function name between braces (or any sequence of them) is appropriate.
+Strange behavior can result when it is not.
.TP
The format of \fIkey\fP should be one of:
