formatting - 如何正确包装涉及键绑定的 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与替换它们的字符串的长度不同，这会在我的源代码中抛出换行。有没有办法强制emacs在运行之后substitute-command-keys和显示给用户之前重新计算包含在我的文档字符串中的段落？

标签： formattingkeyboard-shortcutsdocumentationelisp

Answer 1

有没有办法强制emacs在运行substitute-command-keys之后并在向用户显示之前重新计算包裹在我的文档字符串中的段落？

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

请注意，您不需要超出源代码中的常规填充列来执行此操作——您可以使用“转义换行符”（反斜杠+换行符）在文档字符串源中换行，因为读者会从字符串（请参阅C-hig (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+."