bug#1375: 23.0.60; Elisp manual node Special Properties

bug#1375: 23.0.60; Elisp manual node Special Properties

[Drew Adams]

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'
 

bug#1375: 23.0.60; Elisp manual node Special Properties

[Lars Magne Ingebrigtsen]

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

>
>  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?

Yes, that's not very clear.

The documentation has changed in the mean time -- the third item has
been dropped.  But it still remained less clear than it could have been,
so I've rewritten it slightly now.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/