如何正确包装涉及键绑定的 Elisp 文档字符串？

Question

Emacs Lisp 具有使文档适应用户当前键绑定的功能，方法是在文档字符串中引用命令名称，并让 Emacs 在用户请求文档时为该命令动态插入当前键绑定。但是，当我在提到许多键绑定的文档字符串中使用它时，它会完全弄乱换行。以我的包裹中的这个例子为例：

(substitute-command-keys
 "Fix ido behavior when `require-match' is non-nil.

Standard ido will allow
\\<ido-common-completion-map>\\[ido-select-text] to exit with an
incomplete completion even when `require-match' is non-nil.
Ordinary completion does not allow this. In ordinary completion,
\\[ido-exit-minibuffer] on an incomplete match is equivalent to
\\[ido-complete], and \\[ido-select-text] selects the first
match. Since \\[ido-exit-minibuffer] in ido already selects the
first match, this advice sets up \\[ido-select-text] to be
equivalent to \\[ido-complete] in the same situation.

This advice only activates if the current ido completion was
called through ido-cr+.")

使用标准绑定，向用户显示的文档字符串如下所示：

Fix ido behavior when ‘require-match’ is non-nil.

Standard ido will allow
C-j to exit with an
incomplete completion even when ‘require-match’ is non-nil.
Ordinary completion does not allow this. In ordinary completion,
RET on an incomplete match is equivalent to
TAB, and C-j selects the first
match. Since RET in ido already selects the
first match, this advice sets up C-j to be
equivalent to TAB in the same situation.

This advice only activates if the current ido completion was
called through ido-cr+.

由于中间段落中行长的随机变化，它看起来很糟糕并且难以理解。 实际上应该是这样的：

Fix ido behavior when ‘require-match’ is non-nil.

Standard ido will allow C-j to exit with an incomplete completion
even when ‘require-match’ is non-nil. Ordinary completion does
not allow this. In ordinary completion, RET on an incomplete
match is equivalent to TAB, and C-j selects the first match.
Since RET in ido already selects the first match, this advice
sets up C-j to be equivalent to TAB in the same situation.

This advice only activates if the current ido completion was
called through ido-cr+.

显然，问题在于substitute-command-keys 识别的特殊序列与替换它们的字符串长度不同，这会在我的源代码中抛出换行。在运行substitute-command-keys 之后并在向用户显示之前，是否有某种方法可以强制 emacs 重新计算包含在我的文档字符串中的段落？

Answer 1

您可以将visual-line-mode 与adaptive-wrap 一起使用。这样你就可以继续逻辑行，不要自己拆分它们。

Answer 2

是否有某种方法可以强制 emacs 在运行替代命令键之后并在将其显示给用户之前重新计算包含在我的文档字符串中的段落？

我不这么认为（通常这无疑是有问题的），但如果您期望显示短键绑定（而不是M-x name-of-command），那么您可以使用更长的行和 trust 它们将被呈现为较短的行。如果假设是错误的，那么您将渲染比您想要的更长的线条（而不是比您想要的短的线条的当前情况）。

请注意，您无需超出源代码中的常规填充列即可执行此操作 - 您可以使用“转义换行符”（反斜杠+换行符）在文档字符串源中换行，因为读者会忽略这些来自字符串的序列（参考 Chig (elisp)Syntax for Strings）。

例如：

(substitute-command-keys
 "Fix ido behavior when `require-match' is non-nil.

Standard ido will allow \\<ido-common-completion-map>\
\\[ido-select-text] to exit with an incomplete completion
even when `require-match' is non-nil.  Ordinary completion does
not allow this.  In ordinary completion, \\[ido-exit-minibuffer]\
 on an incomplete match
is equivalent to \\[ido-complete], and \\[ido-select-text]\
 selects the first match.  Since \\[ido-exit-minibuffer]
in ido already selects the first match, this advice sets up\
 \\[ido-select-text] to
be equivalent to \\[ido-complete] in the same situation.

This advice only activates if the current ido completion was
called through ido-cr+.")

渲染：

"Fix ido behavior when `require-match' is non-nil.

Standard ido will allow C-j to exit with an incomplete completion
even when `require-match' is non-nil.  Ordinary completion does
not allow this.  In ordinary completion, RET on an incomplete match
is equivalent to TAB, and C-j selects the first match.  Since RET
in ido already selects the first match, this advice sets up C-j to
be equivalent to TAB in the same situation.

This advice only activates if the current ido completion was
called through ido-cr+."