From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: doc string for face-attribute-relative-p doesn't help Date: Mon, 26 Jun 2006 09:17:43 -0700 Message-ID: References: <85y7vkl5ru.fsf@lola.goethe.zz> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1151338695 30012 80.91.229.2 (26 Jun 2006 16:18:15 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 26 Jun 2006 16:18:15 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jun 26 18:18:13 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Futmk-0005cF-1r for ged-emacs-devel@m.gmane.org; Mon, 26 Jun 2006 18:18:03 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Futmj-00079K-4i for ged-emacs-devel@m.gmane.org; Mon, 26 Jun 2006 12:18:01 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FutmV-00077C-RB for emacs-devel@gnu.org; Mon, 26 Jun 2006 12:17:47 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FutmU-00076O-Ul for emacs-devel@gnu.org; Mon, 26 Jun 2006 12:17:47 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FutmU-000767-OS for emacs-devel@gnu.org; Mon, 26 Jun 2006 12:17:46 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1FutyP-00031W-0T for emacs-devel@gnu.org; Mon, 26 Jun 2006 12:30:05 -0400 Original-Received: from rgmsgw301.us.oracle.com (rgmsgw301.us.oracle.com [138.1.186.50]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id k5QGHiEO006635 for ; Mon, 26 Jun 2006 11:17:44 -0500 Original-Received: from dradamslap (dradams-lap.us.oracle.com [130.35.177.126]) by rgmsgw301.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k5QGHhmB018971 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Mon, 26 Jun 2006 10:17:43 -0600 Original-To: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-reply-to: <85y7vkl5ru.fsf@lola.goethe.zz> Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:56201 Archived-At: >> Return non-nil if face ATTRIBUTE VALUE is relative. >> >> What does that mean? How is ATTRIBUTE VALUE a face? This is >> incomprehensible to me. > > It returns non-nil if the face attribute ATTRIBUTE is relative > when it has value VALUE. "Relative" means that the value doesn't > _override_ that attribute of an underlying face during face merging, > but rather _modifies_ it. > > For most attributes the only value with that property is > `unspecified'; some attributes have other relative values (for > instance, with :height, floating-point numbers are relative, as > they specify a scale value rather than an absolute size). Fine text for a footnote. I don't think so. It isn't clear to me, even after reading it a couple of times. For one thing, "underlying" face is unclear to me. It is used throughout the face doc, but I find no explanation of what is meant, even in the section on merging. What are the faces "underlying" a face? How are they determined? What does it mean for them to "underly" the face - what is the effect of "underlying"? "Underlying" is apparently not the same thing as "inherited by". There is no way to understand this without knowing what "underlying" means. For another thing, I suspect that "relative" is not the right word here, but it is the one that is used everywhere in the doc for this. What is relative to what? There also seems to be confusion in Miles's text about whether it is the attribute or the value that is "relative" - both are suggested. There seem to be three things to distinguish: 1) the face, 2) its underlying faces (=?), and 3) the appearance of the face (combined with its underlying faces, presumably). I suspect that this is about direct vs indirect application of an attribute value to the attribute's face. When "relative", the value affects the face's appearance only indirectly, by being applied not to the face itself but to one (or more?) of its underlying faces. Here is another attempt at wording, assuming I understand some of what this is about. ATTRIBUTE with VALUE affects face indirectly, via an underlying face. Returns non-nil if, when ATTRIBUTE's face has an underlying face and ATTRIBUTE has value VALUE, the appearance of ATTRIBUTE's face is determined by applying VALUE to the underlying face. For example, a floating-point value for a :height face attribute is applied as a scale factor to the height of an underlying face. Returns non-nil for any ATTRIBUTE if VALUE is `unspecified'. Returns nil if the face has no underlying face. Returns nil if VALUE is applied directly to the face itself to determine its appearance. For example, face attribute :foreground is not relative for any VALUE. `unspecified' seems to be a special case, to me (so it needs to be mentioned). It is not really applied in any way to the underlying face to determine the appearance - it is simply ignored, no? It's not clear to me whether: - a face always has an underlying face (e.g. `default') - a face can have more than one underlying face, and, if it does, which of them (one? several? how decided?) is the target of VALUE. I think the answers are yes (so, remove the sentence about "no underlying face") and yes (so, clarify which VALUE applies to). This should be clarified in the doc. I don't claim to understand this, so the text above is no doubt incorrect. Maybe it will help someone come up with accurate text, by pointing out some of the communication difficulties. The Elisp manual needs to clarify what "underlying" means, as well as "relative" (which I suspect is a misnomer for something involving indirection). HTH.