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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Subject: bug#12884: closed (Re: bug#12884: 24.2.50; defun*: argument lists
 in documentation look terrible)
Date: Thu, 15 Nov 2012 01:29:03 +0000

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

Your bug report

#12884: 24.2.50; defun*: argument lists in documentation look terrible

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 12884 <at> debbugs.gnu.org.

-- 
12884: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=12884
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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

[Message part 3 (message/rfc822, inline)]

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/''

Previous Next

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