GNU bug report logs - #12912
24.3.50; doc string for `read-face-name'

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 12912 in the body.
You can then email your comments to 12912 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: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc string for `read-face-name'
Date: Fri, 16 Nov 2012 16:37:34 -0800

This doc seems to be incomplete and unclear wrt DEFAULT.
 
It speaks of a case where DEFAULT is not a string.  It does not say what
else it must/can be (besides nil).  Can it be a symbol - e.g., a face
symbol?  Can it be a list of strings, i.e., multiple defaults?  A list
of faces (symbols)?
 
What's more, there is nothing in the doc string that indicates that the
face name(s) is/are read using `completing-read-multiple'.  Not that
that implementation detail need be mentioned explicitly, but its
_behavior_, i.e., what the behavior of `read-face-name' is, should be
described.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-11-05 on MS-W7-DANI
Bzr revision: 110809 lekktu <at> gmail.com-20121105172930-a5gn0bwi4lndchhw
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libXpm-3.5.10/include -I../../libs/libXpm-3.5.10/src
 -I../../libs/libpng-1.2.37-lib/include -I../../libs/zlib-1.2.5
 -I../../libs/giflib-4.1.4-1-lib/include
 -I../../libs/jpeg-6b-4-lib/include
 -I../../libs/tiff-3.8.2-1-lib/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.9-w32-bin/include
 -I../../libs/libiconv-1.9.2-1-lib/include'
 

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <12912 <at> debbugs.gnu.org>
Subject: RE: bug#12912: 24.3.50; doc string for `read-face-name'
Date: Fri, 16 Nov 2012 16:50:28 -0800

The doc string is also bad wrt PROMPT.  It correctly says that it should not end
in a space, but it should also say that it should not end in a colon.

In fact, it would be far more understandable if it said (as I think we say
elsewhere for such silly prompt handling) that ": " will automatically be
appended to PROMPT.  That tells you the reason and everything you need to know.

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

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 12912-done <at> debbugs.gnu.org
Subject: Re: bug#12912: 24.3.50; doc string for `read-face-name'
Date: Wed, 09 Jan 2013 17:46:57 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> This doc seems to be incomplete and unclear wrt DEFAULT.
>  
> It speaks of a case where DEFAULT is not a string.  It does not say what
> else it must/can be (besides nil).  Can it be a symbol - e.g., a face
> symbol?  Can it be a list of strings, i.e., multiple defaults?  A list
> of faces (symbols)?
>  
> What's more, there is nothing in the doc string that indicates that the
> face name(s) is/are read using `completing-read-multiple'.  Not that
> that implementation detail need be mentioned explicitly, but its
> _behavior_, i.e., what the behavior of `read-face-name' is, should be
> described.

Should be fixed now, thanks.

Previous Next

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