GNU bug report logs - #12884
24.2.50; defun*: argument lists in documentation look terrible

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 12884 in the body.
You can then email your comments to 12884 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: 24.2.50; defun*: argument lists in documentation look terrible
Date: Wed, 14 Nov 2012 17:47:20 +0100

If I e.g. define something like that:

(defun* my-toggle-item (mode-or-var
                               &key
                               ((:selected enabled-spec) `(am-bound-and-true-p ',mode-or-var))
                               ((:help     help-string)   (am-make-symbol-docstring mode-or-var)))
  "Toggle item creater for modes and flags."
  ...)

the docstring then looks like that for me:

| my-toggle-item is a Lisp function.
| 
| (my-toggle-item #:MODE-OR-VAR &key ((:selected #:ENABLED-SPEC) (\`
| (am-bound-and-true-p (quote (\, mode-or-var))))) ((:help
| #:HELP-STRING) (am-make-symbol-docstring mode-or-var)))
| 
| Toggle item creater for modes and flags.

This looks terrible with all this #: and quote \, stuff.

The culprit is `cl--transform-lambda', which just uses this:

(format "%S"
        (cons 'fn
              (cl--make-usage-args orig-args)))

I think we can easily improve this, e.g. by using something like

(let (print-gensym print-level print-length (print-quoted t))
  (format "%S"
     (cons 'fn (cl--make-usage-args orig-args))))

instead.  Looks much better in *Help* and with eldoc.


Thanks,

Michael.




In GNU Emacs 24.2.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.10)
 of 2012-11-13 on drachen
Bzr revision: rgm <at> gnu.org-20121113081658-e63viomclbw6bjee
Windowing system distributor `The X.Org Foundation', version 11.0.10707000
System Description:	Debian GNU/Linux testing (wheezy)

Configured using:
 `configure '--prefix=/usr/local/built/''

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 12884 <at> debbugs.gnu.org
Subject: Re: bug#12884: 24.2.50;
	defun*: argument lists in documentation look terrible
Date: Wed, 14 Nov 2012 14:49:08 -0500

> | (my-toggle-item #:MODE-OR-VAR &key ((:selected #:ENABLED-SPEC) (\`
> | (am-bound-and-true-p (quote (\, mode-or-var))))) ((:help
> | #:HELP-STRING) (am-make-symbol-docstring mode-or-var)))

Let me just say that I will resist the urge to tell you what I think
about this style of argument list ;-)

> This looks terrible with all this #: and quote \, stuff.

Binding print-quoted makes sense to improve the quote/backquote syntax.
But I don't understand why we have those #: in there.  I understand it's
there to say the symbols are not interned, but I don't understand why
they're not interned.


        Stefan

Message #11 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: Re: bug#12884: 24.2.50;
	defun*: argument lists in documentation look terrible
Date: Wed, 14 Nov 2012 22:51:09 +0100

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

> > | (my-toggle-item #:MODE-OR-VAR &key ((:selected #:ENABLED-SPEC) (\`
> > | (am-bound-and-true-p (quote (\, mode-or-var))))) ((:help
> > | #:HELP-STRING) (am-make-symbol-docstring mode-or-var)))
>
> Let me just say that I will resist the urge to tell you what I think
> about this style of argument list ;-)

Please don't resist.  What's wrong with it?

> > This looks terrible with all this #: and quote \, stuff.
>
> Binding print-quoted makes sense to improve the quote/backquote syntax.
> But I don't understand why we have those #: in there.  I understand it's
> there to say the symbols are not interned, but I don't understand why
> they're not interned.

See `cl--make-usage-args'.  It upcases the names of the arguments and
makes them a symbol again.  The one who wrote that wanted that no new
symbols are interned, and so used `make-symbol'.  Dunno if there's a
reason to do so.


- Michael.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 12884-done <at> debbugs.gnu.org
Subject: Re: bug#12884: 24.2.50;
	defun*: argument lists in documentation look terrible
Date: Wed, 14 Nov 2012 20:28:07 -0500

>> > This looks terrible with all this #: and quote \, stuff.
>> Binding print-quoted makes sense to improve the quote/backquote syntax.
>> But I don't understand why we have those #: in there.  I understand it's
>> there to say the symbols are not interned, but I don't understand why
>> they're not interned.
> See `cl--make-usage-args'.  It upcases the names of the arguments and
> makes them a symbol again.  The one who wrote that wanted that no new
> symbols are interned, and so used `make-symbol'.  Dunno if there's a
> reason to do so.

Ah, yes of course.
I installed a patch similar to yours, except I didn't touch print-length
and print-level, since I can't think of a good reason to favor nil
for them.


        Stefan

Previous Next

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