bug#8935: 24.0.50; `substitute-command-keys' doc

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

> > It has no special effect on special character combinations 
> > such as `\[' and `\='.  If you really want to say something
> > about escaping `\' as the next character then I suppose you
> > could: "In particular, `\=\' produces `\' in the output.
> 
> This is wrong, because \ by itself has no special meaning, so 
> you don't need to precede it by \=.

It's not wrong.  \ by itself has no special meaning, so it need not be escaped
when by itself - agreed.

But \ followed by these particular chars (e.g. `[') does have special meaning
for `substitute-command-keys', so when followed by such a char it does need to
be escaped, if you want `\' in the output.

It is nevertheless the \ and only the \ that is escaped.  The escaping code
takes no look past the \ to see what follows it.  It is you, the programmer, who
decides whether a particular \ needs escaping, and yes, you do that by looking
at the following char (e.g. `[').

But _you_ do that - that is not part of what `substitute-command-keys' does or
`\=' does.