GNU bug report logs - #20759
25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 20759 in the body.
You can then email your comments to 20759 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)
Date: Sun, 07 Jun 2015 17:41:47 +0200

Hello,

probably related to the recent changes to the type of quotation used in
documentation:

M-: (require 'pcase) RET
C-h f  pcase  RET

prints as last paragraph:

  -- (‘ QPAT)
  
  Backquote-style pcase patterns.
  [...]


The backquote in the pattern description has been replaced by a curved
quote, which is wrong.


Thanks,

Michael.



In GNU Emacs 25.0.50.3 (x86_64-unknown-linux-gnu, GTK+ Version 3.14.5)
 of 2015-06-07 on drachen
Windowing system distributor `The X.Org Foundation', version 11.0.11701000
System Description:	Debian GNU/Linux testing (stretch)

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND DBUS GSETTINGS NOTIFY
LIBXML2 FREETYPE XFT ZLIB TOOLKIT_SCROLL_BARS GTK3

Message #8 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: michael_heerdegen <at> web.de
Cc: 20759 <at> debbugs.gnu.org
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Sun, 07 Jun 2015 14:14:43 -0400

Michael Heerdegen wrote:

> The backquote in the pattern description has been replaced by a curved
> quote, which is wrong.

Please feel free to just fix it. TIA.

Message #11 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: michael_heerdegen <at> web.de
Cc: 20759 <at> debbugs.gnu.org
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Sun, 07 Jun 2015 14:18:22 -0400

Glenn Morris wrote:

> Michael Heerdegen wrote:
>
>> The backquote in the pattern description has been replaced by a curved
>> quote, which is wrong.
>
> Please feel free to just fix it. TIA.

Oh, it seems to be some generated thing. I assumed it was just a typo.

Message #14 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 20759 <at> debbugs.gnu.org
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Sun, 07 Jun 2015 20:41:22 +0200

Glenn Morris <rgm <at> gnu.org> writes:

> Oh, it seems to be some generated thing. I assumed it was just a typo.

The generated doc was correct until some days or so.  So I guess it's
related to the recent changes switching to the new quoting style.

Michael.

Message #19 received at 20759-done <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: michael_heerdegen <at> web.de, 20759-done <at> debbugs.gnu.org
Subject: Re: bug#20759: 25.0.50;  pcase doc: (‘ QPAT) instead of (` QPAT)
Date: Sun, 7 Jun 2015 23:42:02 +0300

On 06/07/2015 06:41 PM, Michael Heerdegen wrote:

> The backquote in the pattern description has been replaced by a curved
> quote, which is wrong.

Should be fixed now.

Message #22 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: 20759 <at> debbugs.gnu.org
Cc: michael_heerdegen <at> web.de, Glenn Morris <rgm <at> gnu.org>,
 Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: 25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)
Date: Thu, 11 Jun 2015 10:37:37 -0700

[Message part 1 (text/plain, inline)]

That bug was a symptom of a more general confusion between raw 
docstrings and formatted docstrings, which I attempted to fix in commit 
b2205626370071bc85dc07b043c833bc50c0baec with the attached patch.

As the patch mentions, I'm puzzled about the syntax ‘(` PAT)’ in the 
docstring, since lread.c says that syntax is obsolete and ‘format’ 
quotes the grave accent.  The attached patch causes C-h f to suggest the 
syntax ‘(\` PAT)’ which is "safer" in some sense, I suppose.  If it's 
intended that pcase usage omit the backslash, then I guess that ‘format’ 
and/or lread.c need to be updated accordingly.

[0001-Fix-quoting-of-help-for-functions-with-odd-names.patch (text/x-patch, attachment)]

Message #25 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 20759 <at> debbugs.gnu.org, Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Fri, 12 Jun 2015 14:20:35 +0200

Paul Eggert <eggert <at> cs.ucla.edu> writes:

> As the patch mentions, I'm puzzled about the syntax ‘(` PAT)’ in the
> docstring, since lread.c says that syntax is obsolete and ‘format’
> quotes the grave accent.  The attached patch causes C-h f to suggest
> the syntax ‘(\` PAT)’ which is "safer" in some sense, I suppose.  If
> it's intended that pcase usage omit the backslash, then I guess that
> ‘format’ and/or lread.c need to be updated accordingly.

Thanks for working on that.

Thinking again about this, maybe `PAT would be didactically better, in
this special case of the pcase doc.  People not being aware of backquote
being a reader macro should not think

   (pcase '(1 2) ((\` (1 2)) t))

is the "correct" way to use this (instead of

   (pcase '(1 2) (`(1 2) t))

).

I know that the doc of pcase is generated automatically, and your
(Paul's) patch makes this more consistent.

OTOH, we write 'VAL and not (\' VAL) some lines above in the same
documentation.


Regards,

Michael.

Message #28 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 20759 <at> debbugs.gnu.org, Paul Eggert <eggert <at> cs.ucla.edu>,
 Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Fri, 12 Jun 2015 10:05:40 -0400

> Thinking again about this, maybe `PAT would be didactically better, in

Indeed.


        Stefan

Message #31 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 20759 <at> debbugs.gnu.org, Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)
Date: Fri, 12 Jun 2015 16:34:09 -0700

[Message part 1 (text/plain, inline)]

On 06/12/2015 05:20 AM, Michael Heerdegen wrote:
> Thinking again about this, maybe `PAT would be didactically better, in
> this special case of the pcase doc.

Sure, that's doable.  For consistency, the usage string computed 
automatically by "C-h f `" should be "`STRUCTURE", not "(\` 
STRUCTURE)".  I installed the attached.

[0001-Document-X-as-X-not-as-X.patch (text/x-patch, attachment)]

Message #34 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 20759 <at> debbugs.gnu.org,
 Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT)
 instead of (` QPAT)
Date: Sat, 13 Jun 2015 10:12:39 -0400

> * lisp/help.el (help-split-fundoc, help--make-usage-docstring):
> Document (backquote FOO) as "`FOO", not as "(` FOO)" (Bug#20759).

Since the result of help-split-fundoc is also sometimes fed back to
help-add-fundoc-usage, help-add-fundoc-usage would need to be
updated correspondingly.

So, maybe a better approach is to do this in help-fns--signature.


        Stefan

Message #37 received at 20759 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 20759 <at> debbugs.gnu.org,
 Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)
Date: Sat, 13 Jun 2015 09:36:33 -0700

Stefan Monnier wrote:
> maybe a better approach is to do this in help-fns--signature.

Thanks, that does sound better.  I installed a patch along those lines as commit 
8afef016e2bc413c7a4913554ea6ed2c55474de6.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.