RE: Character literals for Unicode (control) characters

[Drew Adams <drew.adams@oracle.com>]

> > so M-q is just not up to the job, and shouldn't be used.
> 
> But there's no real alternative, is there? IOW, you might as well
> use M-q, because if you use something like \\[my-function], you
> never know if that'll display as a short key binding, a long key 
> binding, or as `M-x my-function', which can actually be very long.

You never know for sure.  But usually you know what to _expect_.
Often a doc string with \\[...] is for a command that is used
in a given context, where you can have a good idea whether the
command is likely to be bound to a key or not.

But of course, it could be bound to another key than the
default one, and the bound key could have a much longer
description because of prefix keys.

So no, there is no silver bullet here.  You just need to use
good, common sense, aiming for the most typical, expected,
default use case/context.

The reason for conventional doc strings, including a maximum
line length, is for user convenience.  This includes simply
reading but also things like window and frame fitting to the
buffer content (line lengths and number of lines).

As with all attempts to help users at coding time, we can
only either (1) try to address the most common expected use
cases or (2) provide users a way to customize the behavior.
For doc strings, this comes down mainly to #1.

> (I guess the best way would be to custom-wrap doc strings before
> displaying them, after constructs such as \\[...] have been
> resolved.)

It's not just about wrapping.  You need to look at rendered
doc strings to see what the effect is on embedded TAB chars
also, e.g., to try to align text that is essentially tabular,
such as key descriptions.

It's really not a big deal to use `C-M-x' to reevaluate,
and then use `C-h f' to see what the doc string looks like
when rendered.

And yes, you might need to first put the current buffer in
the right mode, so it picks up the right keymaps.  You might
even need to set the font so that it displays each of the
chars in the doc string correctly.