From: Eli Zaretskii <eliz@gnu.org>
To: Drew Adams <drew.adams@oracle.com>
Cc: 27246-done@debbugs.gnu.org
Subject: bug#27246: 24.5; doc of `face-spec-set'
Date: Sat, 10 Jun 2017 12:18:49 +0300 [thread overview]
Message-ID: <838tl06w06.fsf@gnu.org> (raw)
In-Reply-To: <ec9f5e06-cd27-440b-a213-8dbb331f5d6c@default> (message from Drew Adams on Sun, 4 Jun 2017 22:43:34 -0700 (PDT))
> Date: Sun, 4 Jun 2017 22:43:34 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
>
> 1. The doc string and (elisp ) `Defining Faces' do not agree about
> argument SPEC-TYPE when its value is not one of the special values
> documented.
>
> The doc string says:
>
> Any other value means not to set any spec, but to run the
> function for its other effects.
>
> Huh? What "other effects"? Not clear, but we can guess (and looking at
> the code confirms) that what is hinted at is perhaps this:
>
> This function also defines FACE as a valid face name if it is not
> already one, and (re)calculates its attributes on existing frames.
>
> But the Elisp manual says instead:
>
> Any other value of SPEC-TYPE is reserved for internal use.
I've now clarified what "other effects" means (your guess is correct).
> IOW, the doc string tells us to use another SPEC-TYPE value to get the
> effect of defining a face and (re)calculating its attributes on existing
> frames. But the Elisp manual tells us NOT to use any other SPEC-TYPE
> value, because other values are reserved for internal use.
I've clarified in the manual that FACE's definition and recalculation
of its attributes are done for any other value of SPEC-TYPE. As for
the rest, I think it's quite allright for the manual to say
"reserved", while the doc string describes the current behavior (and
will presumably be changed if that behavior ever changes). I don't
see how this is a request NOT to use other values, just to keep in
mind that their effect might change in the future. And the sources
are really there to tell the full story.
> 2. I also find this part unclear:
>
> Doc string:
>
> nil or `face-override-spec' means the override spec (which is usually
> what you want if calling this function outside of Custom code);
>
> Manual:
>
> If [SPEC-TYPE] is nil or `face-override-spec', this function sets
> the "override spec", which overrides over all other face specs on
> FACE.
>
> "if calling this function outside of Custom code"? What does that
> mean for users?
It means nothing for users. For Lisp programmers, it means what it
says: when this function is called from Lisp outside Custom, use this
value of SPEC-TYPE. (I've made both places be more consistent.)
> ("other face specs on FACE"? Does that mean the default (`defface')
> spec plus the customized spec plus the saved custom spec?
Yes. I've made the text more explicit about this.
> And it's not clear here what those are, either.)
They are described right there, so I don't see what could be unclear
about them, if you write code that sets face attributes.
Thanks.
prev parent reply other threads:[~2017-06-10 9:18 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-05 5:43 bug#27246: 24.5; doc of `face-spec-set' Drew Adams
2017-06-10 9:18 ` Eli Zaretskii [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=838tl06w06.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=27246-done@debbugs.gnu.org \
--cc=drew.adams@oracle.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).