GNU bug report logs - #24925
25.1.50; Suboptimal explanation of FACESPEC in (elisp) Search-based Fontification

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 24925 in the body.
You can then email your comments to 24925 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: 25.1.50; Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 17:20:38 +0100

Hi,

Gotten attentive by a question in emacs-help, I want to suggest to
improve this paragraph:

     In this kind of element, FACESPEC is an expression whose value
     specifies the face to use for highlighting.  In the simplest case,
     FACESPEC is a Lisp variable (a symbol) whose value is a face name.

The first sentence is not good because an expression has no associated
value.  Reading that sentence, the reader might get the false impression
that the expression must be constant or a constant (always evaluate to
the same value).  While this interpretation is not suggesting to the
advanced reader, I think lots of Lisp newbies will rely on this part of
the documentation, and it's already confusing that faces use a separate
name space, but like variables are specified as symbols, so we should
try to be non-ambiguous.

The second sentence is also confusing: I think the simplest case is
actually a face name specified directly, i.e. a quoted symbol.  We can
mention these both cases in one sentence of cause.


Thanks,

Michael.



In GNU Emacs 25.1.50.8 (x86_64-pc-linux-gnu, GTK+ Version 3.22.2)
 of 2016-11-10 built on drachen
Repository revision: 78aece497ce9dc784d5e3d2707d76766eed2a174
Windowing system distributor 'The X.Org Foundation', version 11.0.11804000
System Description:	Debian GNU/Linux testing (stretch)

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND DBUS GSETTINGS NOTIFY
LIBXML2 FREETYPE XFT ZLIB TOOLKIT_SCROLL_BARS GTK3 X11

Important settings:
  value of $LC_ALL: de_DE.utf8
  value of $LC_COLLATE: C
  value of $LC_TIME: C
  value of $LANG: de_DE.utf8
  locale-coding-system: utf-8-unix

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24925 <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 18:39:05 +0200

> From: Michael Heerdegen <michael_heerdegen <at> web.de>
> Date: Fri, 11 Nov 2016 17:20:38 +0100
> 
>      In this kind of element, FACESPEC is an expression whose value
>      specifies the face to use for highlighting.  In the simplest case,
>      FACESPEC is a Lisp variable (a symbol) whose value is a face name.
> 
> The first sentence is not good because an expression has no associated
> value.

??? An expression certainly can have a value.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24925 <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 18:06:27 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> > From: Michael Heerdegen <michael_heerdegen <at> web.de>
> > Date: Fri, 11 Nov 2016 17:20:38 +0100
> > 
> >      In this kind of element, FACESPEC is an expression whose value
> >      specifies the face to use for highlighting.  In the simplest case,
> >      FACESPEC is a Lisp variable (a symbol) whose value is a face name.
> > 
> > The first sentence is not good because an expression has no associated
> > value.
>
> ??? An expression certainly can have a value.

I really think that first sentence can be interpreted in different ways
when being read - see the rest of what I said.  Let's be more specific:
say that the expression is evaluated dynamically, and that the according
return value at that time is used. In contrast to having "a" value; like
evaluating only one time when the spec is added, or expecting the
expression to be constant.


Michael.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24925 <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 19:57:47 +0200

> From: Michael Heerdegen <michael_heerdegen <at> web.de>
> Cc: 24925 <at> debbugs.gnu.org
> Date: Fri, 11 Nov 2016 18:06:27 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > > From: Michael Heerdegen <michael_heerdegen <at> web.de>
> > > Date: Fri, 11 Nov 2016 17:20:38 +0100
> > > 
> > >      In this kind of element, FACESPEC is an expression whose value
> > >      specifies the face to use for highlighting.  In the simplest case,
> > >      FACESPEC is a Lisp variable (a symbol) whose value is a face name.
> > > 
> > > The first sentence is not good because an expression has no associated
> > > value.
> >
> > ??? An expression certainly can have a value.
> 
> I really think that first sentence can be interpreted in different ways
> when being read - see the rest of what I said.  Let's be more specific:
> say that the expression is evaluated dynamically, and that the according
> return value at that time is used. In contrast to having "a" value; like
> evaluating only one time when the spec is added, or expecting the
> expression to be constant.

I really don't understand what's bugging you in that text.  IMO, it's
crystal clear.  Perhaps I'm missing something.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24925 <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 19:25:41 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> I really don't understand what's bugging you in that text.  IMO, it's
> crystal clear.  Perhaps I'm missing something.

What about the second sentence I had quoted (talking about "the simplest
case")?


Michael.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 24925 <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Fri, 11 Nov 2016 21:08:08 +0200

> From: Michael Heerdegen <michael_heerdegen <at> web.de>
> Cc: 24925 <at> debbugs.gnu.org
> Date: Fri, 11 Nov 2016 19:25:41 +0100
> 
> What about the second sentence I had quoted (talking about "the simplest
> case")?

I don't have any opinions on that, since I'm not experienced enough
with font-lock to say which use case is the simplest.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24925-done <at> debbugs.gnu.org
Subject: Re: bug#24925: 25.1.50;
 Suboptimal explanation of FACESPEC in (elisp) Search-based
 Fontification
Date: Tue, 15 Nov 2016 03:39:07 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> I don't have any opinions on that, since I'm not experienced enough
> with font-lock to say which use case is the simplest.

Ok, if it sounds ok to you so far, then don't let's get into
bikeshedding.  Closing.


Thanks,

Michael.

Previous Next

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