Subject: bug#1375: 23.0.60; Elisp manual node Special Properties

From: "Drew Adams" <[email-masked]>
Date: Tue, 18 Nov 2008 22:55:37 -0800

The text says this:
 
 In the simplest case, the value is a face name.  It can also be a
 list; then each element can be any of these possibilities;
 
    * A face name (a symbol or string).
 
    * A property list of face attributes.  This has the form
      (KEYWORD VALUE ...), where each KEYWORD is a face attribute
      name and VALUE is a meaningful value for that attribute.
      With this feature, you do not need to create a face each time
      you want to specify a particular attribute for certain text.
      *Note Face Attributes::.
 
    * A cons cell with the form `(foreground-color . COLOR-NAME)'
      or `(background-color . COLOR-NAME)'.  These are older,
      deprecated equivalents for `(:foreground COLOR-NAME)' and
      `(:background COLOR-NAME)'.  Please convert code that uses
      them.
 
 It works to use the latter two forms directly as the value of the
 `face' property.
 
The "latter two forms" in the last sentence seems to refer to the last
two bullets. Is that right? And the first sentence above seems to
refer to the first bullet, no?
 
If so, then the last sentence and the first sentence together say that
the `face' property can have any of the bullets as its value, no?
 
If so, then all of this together says that a `face' property value can
be any of the bullets or a list of any of the bullets. Isn't that
right?
 
If so, then that's what we should say, directly. The current text is a
bit confusing. We start off saying it can be a face name or a list of
any of the bullets. Then we end by (I think) saying that it can also
be either of the last two bullets. But we already said it could be a
face name (the first bullet).
 
Unless there is some careful distinction being made here between the
statement that it could be a face name (not described) or a face name
which is a string or a symbol. I don't think that's the case,
however. If it is, then that needs to be explained.
 
Maybe it's just late and I'm misreading this and missing something,
but it seems overly complicated for (what I think) it's saying.

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-11-08 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'