Misleading single "\" in Emacs Manual Section 25.3

Misleading single "\" in Emacs Manual Section 25.3

[Heime]

The Elisp documentation "25.3 Substituting Key Bindings in Documentation" states
that  each '\' must be doubled when written in a string in Emacs Lisp. 

I find this a bit confusing because the section is about writing within the documentation
string.  Meaning that the "\" should be doubled.

Using "\[COMMAND]" will not work in the documentation.  One has to use "\\[COMMAND]"

The commands in the section with a single "\" is misleading.

Re: Misleading single "\" in Emacs Manual Section 25.3

[Eli Zaretskii]

> Date: Tue, 16 Jul 2024 08:50:15 +0000
> From: Heime <heimeborgia@protonmail.com>
> 
> 
> The Elisp documentation "25.3 Substituting Key Bindings in Documentation" states
> that  each '\' must be doubled when written in a string in Emacs Lisp. 
> 
> I find this a bit confusing because the section is about writing within the documentation
> string.  Meaning that the "\" should be doubled.
> 
> Using "\[COMMAND]" will not work in the documentation.  One has to use "\\[COMMAND]"
> 
> The commands in the section with a single "\" is misleading.

I don't think they are misleading, since the text says right away that
each backslash in the forms above needs to be doubled.

Misleading single "\" in Emacs Manual Section 25.3

[Heime]

On Tuesday, July 16th, 2024 at 10:31 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Tue, 16 Jul 2024 08:50:15 +0000
> > From: Heime heimeborgia@protonmail.com
> > 
> > The Elisp documentation "25.3 Substituting Key Bindings in Documentation" states
> > that each '\' must be doubled when written in a string in Emacs Lisp.
> > 
> > I find this a bit confusing because the section is about writing within the documentation
> > string. Meaning that the "\" should be doubled.
> > 
> > Using "\[COMMAND]" will not work in the documentation. One has to use "\\[COMMAND]"
> > 
> > The commands in the section with a single "\" is misleading.
> 
> 
> I don't think they are misleading, since the text says right away that
> each backslash in the forms above needs to be doubled.

It is already confusing enough on how many \ are needed for some expressions to be
printed (e.g. for regex expressions).  

When the topic is about documentation strings, the commands should conform to what
one would type in the documentation string.  

After that, it can be stated that the string processing phase will strip away one layer
of backslashes.  It would be more understandable this way.  Some readers will initially 
think that they should write \= in their string directly.

Re: Misleading single "\" in Emacs Manual Section 25.3

[Eli Zaretskii]

> Date: Tue, 16 Jul 2024 12:39:08 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: help-gnu-emacs@gnu.org
> 
> > > The commands in the section with a single "\" is misleading.
> > 
> > 
> > I don't think they are misleading, since the text says right away that
> > each backslash in the forms above needs to be doubled.
> 
> It is already confusing enough on how many \ are needed for some expressions to be
> printed (e.g. for regex expressions).  
> 
> When the topic is about documentation strings, the commands should conform to what
> one would type in the documentation string.  

I disagree.

> Some readers will initially think that they should write \= in their
> string directly.

Only if they fail to pay attention to the note about doubling the
backslashes.

Re: Misleading single "\" in Emacs Manual Section 25.3

[Heime]

On Wednesday, July 17th, 2024 at 1:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Tue, 16 Jul 2024 12:39:08 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: help-gnu-emacs@gnu.org
> > 
> > > > The commands in the section with a single "\" is misleading.
> > > 
> > > I don't think they are misleading, since the text says right away that
> > > each backslash in the forms above needs to be doubled.
> > 
> > It is already confusing enough on how many \ are needed for some expressions to be
> > printed (e.g. for regex expressions).
> > 
> > When the topic is about documentation strings, the commands should conform to what
> > one would type in the documentation string.
> 
> 
> I disagree.
> 
> > Some readers will initially think that they should write \= in their
> > string directly.
> 
> 
> Only if they fail to pay attention to the note about doubling the
> backslashes.

Or me can leave everything as is, but elaborate further about how the
processing phase of a docstring will strip away one layer of backslashes.

Then show couple of examples

  Entry        |  Interpretation
  -------------+----------------
  \\[COMMAND]  |  \[COMMAND]
  \\[\\-\\]    |  \[\-\]

Re: Misleading single "\" in Emacs Manual Section 25.3

[Heime]

On Wednesday, July 17th, 2024 at 1:53 AM, Heime <heimeborgia@protonmail.com> wrote:

> On Wednesday, July 17th, 2024 at 1:36 AM, Eli Zaretskii eliz@gnu.org wrote:
> 
> > > Date: Tue, 16 Jul 2024 12:39:08 +0000
> > > From: Heime heimeborgia@protonmail.com
> > > Cc: help-gnu-emacs@gnu.org
> > > 
> > > > > The commands in the section with a single "\" is misleading.
> > > > 
> > > > I don't think they are misleading, since the text says right away that
> > > > each backslash in the forms above needs to be doubled.
> > > 
> > > It is already confusing enough on how many \ are needed for some expressions to be
> > > printed (e.g. for regex expressions).
> > > 
> > > When the topic is about documentation strings, the commands should conform to what
> > > one would type in the documentation string.
> > 
> > I disagree.
> > 
> > > Some readers will initially think that they should write \= in their
> > > string directly.
> > 
> > Only if they fail to pay attention to the note about doubling the
> > backslashes.
> 
> 
> Or me can leave everything as is, but elaborate further about how the
> processing phase of a docstring will strip away one layer of backslashes.
> 
> Then show couple of examples
> 
> Entry | Interpretation
> -------------+----------------
> \\[COMMAND] | \[COMMAND]
> \\[\\-\\] | \[\-\]
> 

This addition could be introduced

"When emacs processes a docstring, it removes (strips away) one
level (layer) of backslashes.  This means that each backslash
written in the docstring needs to be doubled to ensure the
correct number of backslashes are interpreted."

Re: Misleading single "\" in Emacs Manual Section 25.3

[Eli Zaretskii]

> Date: Tue, 16 Jul 2024 14:21:56 +0000
> From: Heime <heimeborgia@protonmail.com>
> Cc: help-gnu-emacs@gnu.org, Heime <heimeborgia@protonmail.com>
> 
> This addition could be introduced
> 
> "When emacs processes a docstring, it removes (strips away) one
> level (layer) of backslashes.  This means that each backslash
> written in the docstring needs to be doubled to ensure the
> correct number of backslashes are interpreted."

This is already explained where the syntax for strings in Emacs Lisp
is described in the manual.

Re: Misleading single "\" in Emacs Manual Section 25.3

[Heime]

Sent with Proton Mail secure email.

On Wednesday, July 17th, 2024 at 2:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> > Date: Tue, 16 Jul 2024 14:21:56 +0000
> > From: Heime heimeborgia@protonmail.com
> > Cc: help-gnu-emacs@gnu.org, Heime heimeborgia@protonmail.com
> > 
> > This addition could be introduced
> > 
> > "When emacs processes a docstring, it removes (strips away) one
> > level (layer) of backslashes. This means that each backslash
> > written in the docstring needs to be doubled to ensure the
> > correct number of backslashes are interpreted."
> 
> 
> This is already explained where the syntax for strings in Emacs Lisp
> is described in the manual.

Could you make a function where one can pass a string with the syntax one
puts in a docstring, that returns the effect of docstring processing, where 
the first layer of \ is stripped.  That would help me ouite a lot because
I am ending up with many and many \ for expressions to display as I want them.

Re: Misleading single "\" in Emacs Manual Section 25.3

[Stefan Monnier via Users list for the GNU Emacs text editor]

> Could you make a function where one can pass a string with the syntax
> one puts in a docstring, that returns the effect of docstring
> processing, where the first layer of \ is stripped.

Define precisely what you mean by "the effect of docstring processing"
and define precisely what you mean by "returns".


        Stefan


PS: There's `read` (and `read-from-string`) and its inverse `prin1`.