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

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

> > "\=\e" will print as "\e"? Right?  So it's not a noop, and the fix I
> > applied was correct.
> 
> No.  The *only* special sequences processed by 
> substitute-command-keys' are '\=', '\[', '\<' and '\{'.
> Nothing else.

Correct.

> The sentence is about how to write these special sequences in
> the doc string so that they are not treated specially,

Correct.

> so the examples should talk about '\=' and '\[', not about '\'.

It's OK to mention that in "\=\[" the \= escapes the \ so that \[ appears in the
output.  But it is only the \ that is being escaped here.

Escaping a character means making it act normally, not specially.  Only the \
acts specially, and it does so only when it precedes [, {, etc.

So yes, this escaping of \ only has an effect when the \ precedes [, {, etc.

But strictly speaking it is only the \ that gets escaped in these contexts.  The
=, [, etc. does not need to be escaped because those are not treated specially
unless preceded by an unescaped \.  So only one character needs to be escaped:
the \.

Anyway, it's a minor point (bug).  I really don't care what you do with it.

When I read the doc string, I found it confusing.  I looked at the code and
understood.  It is _enough_ to say that \= escapes a \, preventing it from
introducing a substitution when followed by =, [, etc.

Or as I said in the beginning:

> This is uncessarily complex and misleading.  All the `\=' does is
> quote/escape the (single) next character, whatever it is.  Nothing
> more.