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

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

[Drew Adams]

Both the doc string and the doc in the Elisp manual (node `Keys in
Documentation') are unnecessarily confusing wrt `\='.
 
They both correctly say that `\=' "quotes the following character and is
discarded".  However, they then say this to illustrate what is meant:
 
 "thus, `\=\[' puts `\[' into the output, and `\=\=' puts
  `\=' into the output."
 
This is uncessarily complex and misleading.  All the `\=' does is
quote/escape the (single) next character, whatever it is.  Nothing
more.
 
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.  The character following the escaped
character does not enter into (i.e., affect) the behavior at all.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-06-20 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
 

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

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.  The character following the escaped
> character does not enter into (i.e., affect) the behavior at all.

I've now done this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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 \=.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

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

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

[Lars Magne Ingebrigtsen]

Andreas Schwab <schwab@linux-m68k.org> writes:

> "Drew Adams" <drew.adams@oracle.com> writes:
>
>> 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 \=.

I see.  I thought it worked the normal way, in that "\e" would be "e".
Thanks for correcting this.  Did you do the manual, too?  If not I can
take care of that.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Lars Magne Ingebrigtsen]

Andreas Schwab <schwab@linux-m68k.org> writes:

> "Drew Adams" <drew.adams@oracle.com> writes:
>
>> 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 \=.

I see.  I thought it worked the normal way, in that "\e" would be "e".
Thanks for correcting this.  Did you do the manual, too?  If not I can
take care of that.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

> > This is wrong, because \ by itself has no special meaning, 
> > so you don't need to precede it by \=.
> 
> I see.  I thought it worked the normal way, in that "\e" would be "e".

It does.  That is correct.

Andreas was wrong in saying it is wrong.

What is true is that \ by itself (not followed by [, =, etc.) does not _NEED_ to
be escaped.  But it is certainly true that \= escapes \, whether it needs to in
any given context (e.g. \[) or not (e.g. \ abc).  If it escapes a \ that does
not need escaping, the effect is a no-op.

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

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> What is true is that \ by itself (not followed by [, =, etc.) does not
> _NEED_ to be escaped.  But it is certainly true that \= escapes \,
> whether it needs to in any given context (e.g. \[) or not (e.g. \
> abc).  If it escapes a \ that does not need escaping, the effect is a
> no-op.

Uhm.  Now I'm even more confused.

"\=\e" will print as "\e"?  Right?  So it's not a noop, and the fix I
applied was correct.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Andreas Schwab]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> "\=\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.  The sentence is about how
to write these special sequences in the doc string so that they are not
treated specially, so the examples should talk about '\=' and '\[', not
about '\'.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> > "\=\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.

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

[Drew Adams]

> > What is true is that \ by itself (not followed by [, =, 
> > etc.) does not _NEED_ to be escaped.  But it is certainly true
> > that \= escapes \, whether it needs to in any given context
> > (e.g. \[) or not (e.g. \abc).  If it escapes a \ that does not
> > need escaping, the effect is a no-op.
> 
> Uhm.  Now I'm even more confused.
> 
> "\=\e" will print as "\e"?  Right?

Right.

> So it's not a noop,

It's a no-op in the sense that it does nothing.  Of course, it is still the case
that, as the doc string says, the \= itself "is discarded".  What remains is the
\ that was escaped.

Not sure what your confusion is.  \= escapes the char that follows it.  What
does escaping mean in this context?  Preventing \ from having any special
behavior when it precedes =, [, etc.

The point is that it is not the pair of characters \=, \[, etc. that is escaped.
\ is the only char escaped: it is prevented from doing anything special; it just
appears in the output as is.  Because \ gets escaped, it has no special
`substitute-command-keys' effect on what follows it, whatever that might be.

> and the fix I applied was correct.

Dunno what it was.

What I described is a proper fix, IMO.

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

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

>> and the fix I applied was correct.
>
> Dunno what it was.
>
> What I described is a proper fix, IMO.

You don't read the emacs-diffs mailing list?  :-)

I implemented what you described.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

> > Dunno what it was.
> 
> You don't read the emacs-diffs mailing list?  :-)

Nope.  Sorry.

> I implemented what you described.

Thank you.

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> Escaping a character means making it act normally, not specially.  Only the \
> acts specially,

Wrong.

> and it does so only when it precedes [, {, etc.

Right.  And only this is of interest.

> It is _enough_ to say that \= escapes a \, preventing it from
> introducing a substitution when followed by =, [, etc.

No, this is the wrong thing to do.  The doc string should say how to
produce a value that contains the two character sequences '\=' or '\['.
That's the *whole* point of the examples (and these are *examples*, not
specification).

You don't need '\=' to produce a backslash in the value.  So that is
useless to say so.

A doc string needs to get to the point, not be technically correct.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Stefan Monnier]

>> 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 \=.

Actually \ does have a special meaning, which depends on the following
char (just like \ in regexps).  The difference between that and regexps
is that in regexp \<char> turns into just <char> when \<char> has no
special meaning, where it turns into \<char> here.


        Stefan

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

[Andreas Schwab]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Actually \ does have a special meaning, which depends on the following
> char (just like \ in regexps).  The difference between that and regexps
> is that in regexp \<char> turns into just <char> when \<char> has no
> special meaning, where it turns into \<char> here.

If you want a \ in a regexp you must write \\, always.  But if you want
to have a \ from substitute-command-keys you just write \, and if you
want \\= you must write \\=\=.  Thus \ by itself is not special here.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Stefan Monnier]

>> Actually \ does have a special meaning, which depends on the following
>> char (just like \ in regexps).  The difference between that and regexps
>> is that in regexp \<char> turns into just <char> when \<char> has no
>> special meaning, where it turns into \<char> here.

> If you want a \ in a regexp you must write \\, always.  But if you want
> to have a \ from substitute-command-keys you just write \, and if you
> want \\= you must write \\=\=.  Thus \ by itself is not special here.

The "by itself" doesn't mean much, and \ is special because it changes
the meaning of the subsequent character.  I agree it's not special in
the same way as it is in regexps, but it is still special.


        Stefan