How can I properly wrap my Elisp docstrings that involve keybinds?

Question

Emacs Lisp has a facility for adapting documentation to the user's current key bindings, by referencing the command name in the docstring and letting Emacs dynamically insert the current key binding for that command when the user requests the documention. However, when I use this in a docstring that mentions many key bindings, it completely messes up the line wrapping. Take this example from my package:

(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+.")

With the standard bindings, the docstring displayed to the user looks like this:

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+.

which looks atrocious and borderline unreadable due to the random variations in line length in the middle paragraph. Here's what it should actually look like:

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+.

Obviously, the problem is that the special sequences recognized by substitute-command-keys are not the same length as the strings that replace them, which throws off the line wrapping in my source code. Is there some way to force emacs to re-compute the paragraph wrapping in my docstring after running substitute-command-keys and before displaying it to the user?

Answer 1

You could use visual-line-mode together with adaptive-wrap. This way you can continue logical lines and don't split them yourself.

Answer 2

Is there some way to force emacs to re-compute the paragraph wrapping in my docstring after running substitute-command-keys and before displaying it to the user?

I don't believe so (and in general it would undoubtedly be problematic), but if you expect the short keybindings to be displayed (rather than M-x name-of-command) then you can use longer lines and trust they will be rendered as shorter lines. If the assumption is wrong, then you'll render lines which are longer than you wanted (rather than the current situation of lines which are shorter than you wanted).

Note that you don't need to exceed your regular fill column in your source code to do this -- you can break lines in the docstring source with an "escaped newline" (backslash+newline), as the reader omits these sequences from the string (refer to C-hig (elisp)Syntax for Strings).

E.g.:

(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+.")

renders:

"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+."