Printing \\= in the docstring

Printing \\= in the docstring

[Heime]

On Tuesday, July 16th, 2024 at 9:22 AM, Heime <heimeborgia@protonmail.com> wrote:

> How can I print \\= in the docstring ?

When I try \\= the = does not display.  Neither does \\\\= or \\\=

Re: Printing \\= in the docstring

[Stephen Berman]

On Mon, 15 Jul 2024 22:43:26 +0000 Heime <heimeborgia@protonmail.com> wrote:

> On Tuesday, July 16th, 2024 at 9:22 AM, Heime <heimeborgia@protonmail.com> wrote:
>
>> How can I print \\= in the docstring ?
>
> When I try \\= the = does not display.  Neither does \\\\= or \\\=

To print the sequence "\\=" as a string but not as a doc string escape
sequence, using "\\\\=" does work.  But if you want to print it in the
context of a doc string escape sequence, you have to double it, just
like you have to double "\" in normal Lisp strings.  For example, this
in a doc string:

"\\\\=\\=\\=`\\(\\s-\\\\=\\=\\=\\[\\-\\]\\s-\\)\\(.*\\) uses \\\\="

appears like this in a "*Help*" buffer:

\\=`\(\s-\\=\[\-\]\s-\)\(.*\) uses \\=

Steve Berman

Re: Printing \\= in the docstring

[Heime]

On Tuesday, July 16th, 2024 at 11:10 AM, Stephen Berman <stephen.berman@gmx.net> wrote:

> On Mon, 15 Jul 2024 22:43:26 +0000 Heime heimeborgia@protonmail.com wrote:
> 
> > On Tuesday, July 16th, 2024 at 9:22 AM, Heime heimeborgia@protonmail.com wrote:
> > 
> > > How can I print \\= in the docstring ?
> > 
> > When I try \\= the = does not display. Neither does \\\\= or \\\=
> 
> 
> To print the sequence "\\=" as a string but not as a doc string escape
> sequence, using "\\\\=" does work. But if you want to print it in the
> context of a doc string escape sequence, you have to double it, just
> like you have to double "\" in normal Lisp strings. For example, this
> in a doc string:
> 
> "\\\\=\\=\\=`\\\\(\\\\s-\\\\\\\\=\\\\=\\\\=\\\\[\\\\-\\\\]\\\\s-\\\\)\\\\(.*\\\\) uses \\\\\\\\=" appears like this in a "*Help*" buffer: \\\\=`\(\s-\\=\[\-\]\s-\)\(.*\) uses \\=
> 
> Steve Berman

If I use "\\\\=" the only thing that is displayed is "\" when using "C-h v myvar".

Re: Printing \\= in the docstring

[Stephen Berman]

On Tue, 16 Jul 2024 08:20:05 +0000 Heime <heimeborgia@protonmail.com> wrote:

> On Tuesday, July 16th, 2024 at 11:10 AM, Stephen Berman
> <stephen.berman@gmx.net> wrote:
>
>> On Mon, 15 Jul 2024 22:43:26 +0000 Heime heimeborgia@protonmail.com wrote:
>>
>> > On Tuesday, July 16th, 2024 at 9:22 AM, Heime heimeborgia@protonmail.com wrote:
>> >
>> > > How can I print \\= in the docstring ?
>> >
>> > When I try \\= the = does not display. Neither does \\\\= or \\\=
>>
>>
>> To print the sequence "\\=" as a string but not as a doc string escape
>> sequence, using "\\\\=" does work. But if you want to print it in the
>> context of a doc string escape sequence, you have to double it, just
>> like you have to double "\" in normal Lisp strings. For example, this
>> in a doc string:
>>
>> "\\\\=\\=\\=`\\\\(\\\\s-\\\\\\\\=\\\\=\\\\=\\\\[\\\\-\\\\]\\\\s-\\\\)\\\\(.*\\\\)
>> uses \\\\\\\\=" appears like this in a "*Help*" buffer:
>> \\\\=`\(\s-\\=\[\-\]\s-\)\(.*\) uses \\=
>>
>> Steve Berman
>
> If I use "\\\\=" the only thing that is displayed is "\" when using "C-h v myvar".

It works in the example I gave just above.  As so often you have not
provided a complete reproducer, so I can only try to guess why what you
did does not work.  But I won't guess now.

Steve Berman

Re: Printing \\= in the docstring

[Heime]

Sent with Proton Mail secure email.

On Tuesday, July 16th, 2024 at 8:25 PM, Stephen Berman <stephen.berman@gmx.net> wrote:

> On Tue, 16 Jul 2024 08:20:05 +0000 Heime heimeborgia@protonmail.com wrote:
> 
> > On Tuesday, July 16th, 2024 at 11:10 AM, Stephen Berman
> > stephen.berman@gmx.net wrote:
> > 
> > > On Mon, 15 Jul 2024 22:43:26 +0000 Heime heimeborgia@protonmail.com wrote:
> > > 
> > > > On Tuesday, July 16th, 2024 at 9:22 AM, Heime heimeborgia@protonmail.com wrote:
> > > > 
> > > > > How can I print \\= in the docstring ?
> > > > 
> > > > When I try \\= the = does not display. Neither does \\\\= or \\\=
> > > 
> > > To print the sequence "\\=" as a string but not as a doc string escape
> > > sequence, using "\\\\=" does work. But if you want to print it in the
> > > context of a doc string escape sequence, you have to double it, just
> > > like you have to double "\" in normal Lisp strings. For example, this
> > > in a doc string:
> > > 
> > > "\\\\=\\=\\=`\\\\\\\\(\\\\\\\\s-\\\\\\\\\\\\\\\\=\\\\\\\\=\\\\\\\\=\\\\\\\\[\\\\\\\\-\\\\\\\\]\\\\\\\\s-\\\\\\\\)\\\\\\\\(.*\\\\\\\\) uses \\\\\\\\\\\\\\\\=" appears like this in a "*Help*" buffer: \\\\\\\\=`\(\s-\\=\[\-\]\s-\)\(.*\) uses \\=
> > > 
> > > Steve Berman
> > 
> > If I use "\\\\=" the only thing that is displayed is "\" when using "C-h v myvar".
> 
> 
> It works in the example I gave just above. As so often you have not
> provided a complete reproducer, so I can only try to guess why what you
> did does not work. But I won't guess now.
> 
> Steve Berman

(defconst mydocstring ""

  "In the docstring, apply the escape sequence \\\\= to stop conversion by
  `substitute-command-keys'."

Re: Printing \\= in the docstring

[Stephen Berman]

On Tue, 16 Jul 2024 08:32:36 +0000 Heime <heimeborgia@protonmail.com> wrote:

> Sent with Proton Mail secure email.
>
> On Tuesday, July 16th, 2024 at 8:25 PM, Stephen Berman
> <stephen.berman@gmx.net> wrote:
>
>> On Tue, 16 Jul 2024 08:20:05 +0000 Heime heimeborgia@protonmail.com wrote:
>>
>> > On Tuesday, July 16th, 2024 at 11:10 AM, Stephen Berman
>> > stephen.berman@gmx.net wrote:
>> >
>> > > On Mon, 15 Jul 2024 22:43:26 +0000 Heime heimeborgia@protonmail.com wrote:
>> > >
>> > > > On Tuesday, July 16th, 2024 at 9:22 AM, Heime
>> > > > heimeborgia@protonmail.com wrote:
>> > > >
>> > > > > How can I print \\= in the docstring ?
>> > > >
>> > > > When I try \\= the = does not display. Neither does \\\\= or \\\=
>> > >
>> > > To print the sequence "\\=" as a string but not as a doc string escape
>> > > sequence, using "\\\\=" does work. But if you want to print it in the
>> > > context of a doc string escape sequence, you have to double it, just
>> > > like you have to double "\" in normal Lisp strings. For example, this
>> > > in a doc string:
>> > >
>> > > "\\\\=\\=\\=`\\\\\\\\(\\\\\\\\s-\\\\\\\\\\\\\\\\=\\\\\\\\=\\\\\\\\=\\\\\\\\[\\\\\\\\-\\\\\\\\]\\\\\\\\s-\\\\\\\\)\\\\\\\\(.*\\\\\\\\)
>> > > uses \\\\\\\\\\\\\\\\=" appears like this in a "*Help*" buffer:
>> > > \\\\\\\\=`\(\s-\\=\[\-\]\s-\)\(.*\) uses \\=
>> > >
>> > > Steve Berman
>> >
>> > If I use "\\\\=" the only thing that is displayed is "\" when using "C-h v
>> > myvar".
>>
>>
>> It works in the example I gave just above. As so often you have not
>> provided a complete reproducer, so I can only try to guess why what you
>> did does not work. But I won't guess now.
>>
>> Steve Berman
>
> (defconst mydocstring ""
>
>   "In the docstring, apply the escape sequence \\\\= to stop conversion by
>   `substitute-command-keys'."

Thank you, now I can reproduce the problem.  From brief testing it seems
"\\\\=" in a doc string only prints as "\\=" when it is the final
character sequence in the doc string.  This could be a bug but I don't
have time to debug it now.  However, escaping "\\=" as above does work:

(defvar mydocstring ""

  "In the docstring, apply the escape sequence \\\\=\\=\\= to stop
conversion by `substitute-command-keys'.")

So I guess the recommendation is to always use this if you want to see
"\\=" in a *Help* buffer.

Steve Berman

Re: Printing \\= in the docstring

[Stephen Berman]

On Tue, 16 Jul 2024 10:49:05 +0200 Stephen Berman <stephen.berman@gmx.net> wrote:

> On Tue, 16 Jul 2024 08:32:36 +0000 Heime <heimeborgia@protonmail.com> wrote:
[...]
>> (defconst mydocstring ""
>>
>>   "In the docstring, apply the escape sequence \\\\= to stop conversion by
>>   `substitute-command-keys'."
>
> Thank you, now I can reproduce the problem.  From brief testing it seems
> "\\\\=" in a doc string only prints as "\\=" when it is the final
> character sequence in the doc string.  This could be a bug but I don't
> have time to debug it now.  However, escaping "\\=" as above does work:
>
> (defvar mydocstring ""
>
>   "In the docstring, apply the escape sequence \\\\=\\=\\= to stop
> conversion by `substitute-command-keys'.")

After seeing your post about the discussion of substitute-command-keys
in the Elisp manual, and re-reading that section, I have to make what I
wrote above more precise: to make "\\=" appear in a *Help* buffer by
itself, i.e. not functioning as an escape sequence, write "\\\\=\\=" in
the doc string; to make "\\=" appear in a *Help* buffer in a context
where it functions as an escape sequence, write "\\\\=\\=\\=" in the doc
string.  So in the above example of a doc string for the variable
`mydocstring', "\\\\=\\=" suffices.

Steve Berman