* Re: doc string for face-attribute-relative-p doesn't help [not found] <MEEKKIABFKKDFJMPIOEBKEIGDCAA.drew.adams@oracle.com> @ 2006-06-25 15:33 ` Richard Stallman 2006-06-26 4:39 ` Miles Bader 0 siblings, 1 reply; 14+ messages in thread From: Richard Stallman @ 2006-06-25 15:33 UTC (permalink / raw) Cc: Drew Adams Return non-nil if face ATTRIBUTE VALUE is relative. What does that mean? How is ATTRIBUTE VALUE a face? This is incomprehensible to me. I don't understand it either. Can someone explain? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-25 15:33 ` doc string for face-attribute-relative-p doesn't help Richard Stallman @ 2006-06-26 4:39 ` Miles Bader 2006-06-26 7:45 ` David Kastrup 2006-06-26 11:13 ` John S. Yates, Jr. 0 siblings, 2 replies; 14+ messages in thread From: Miles Bader @ 2006-06-26 4:39 UTC (permalink / raw) Cc: Drew Adams, emacs-devel Richard Stallman <rms@gnu.org> writes: > Return non-nil if face ATTRIBUTE VALUE is relative. > > What does that mean? How is ATTRIBUTE VALUE a face? This is > incomprehensible to me. > > I don't understand it either. Can someone explain? 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). -Miles -- Yo mama's so fat when she gets on an elevator it HAS to go down. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 4:39 ` Miles Bader @ 2006-06-26 7:45 ` David Kastrup 2006-06-26 16:17 ` Drew Adams 2006-06-26 11:13 ` John S. Yates, Jr. 1 sibling, 1 reply; 14+ messages in thread From: David Kastrup @ 2006-06-26 7:45 UTC (permalink / raw) Cc: rms, Drew Adams, emacs-devel Miles Bader <miles.bader@necel.com> writes: > Richard Stallman <rms@gnu.org> writes: >> Return non-nil if face ATTRIBUTE VALUE is relative. >> >> What does that mean? How is ATTRIBUTE VALUE a face? This is >> incomprehensible to me. >> >> I don't understand it either. Can someone explain? > > 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. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum ^ permalink raw reply [flat|nested] 14+ messages in thread
* RE: doc string for face-attribute-relative-p doesn't help 2006-06-26 7:45 ` David Kastrup @ 2006-06-26 16:17 ` Drew Adams 2006-06-27 2:08 ` Miles Bader 0 siblings, 1 reply; 14+ messages in thread From: Drew Adams @ 2006-06-26 16:17 UTC (permalink / raw) >> 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. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 16:17 ` Drew Adams @ 2006-06-27 2:08 ` Miles Bader 2006-06-27 3:33 ` Drew Adams 0 siblings, 1 reply; 14+ messages in thread From: Miles Bader @ 2006-06-27 2:08 UTC (permalink / raw) Cc: emacs-devel "Drew Adams" <drew.adams@oracle.com> writes: > I don't think so. It isn't clear to me, even after reading it a couple of > times. It seems to me that the real problem is a lack of knowledge about how face rendering in general works. This should be solved by having a good overview of face rendering in the manual (I don't know if there is one or not), not by trying to shove that information in every function docstring that's somehow related to faces. -Miles -- Come now, if we were really planning to harm you, would we be waiting here, beside the path, in the very darkest part of the forest? ^ permalink raw reply [flat|nested] 14+ messages in thread
* RE: doc string for face-attribute-relative-p doesn't help 2006-06-27 2:08 ` Miles Bader @ 2006-06-27 3:33 ` Drew Adams 2006-06-27 3:52 ` Miles Bader 0 siblings, 1 reply; 14+ messages in thread From: Drew Adams @ 2006-06-27 3:33 UTC (permalink / raw) > I don't think so. It isn't clear to me, even after reading it > a couple of times. It seems to me that the real problem is a lack of knowledge about how face rendering in general works. This should be solved by having a good overview of face rendering in the manual (I don't know if there is one or not), not by trying to shove that information in every function docstring that's somehow related to faces. Yes, such an explanation in the manual is probably needed - that's what I was trying to suggest. Whether it should take the form of a new, separate section or just cleanup of existing text, I don't know. If a new section is added, the existing text should still be cleaned up so that it makes more sense (possibly cross-referencing the new section, to help). I agree, too, that each function's doc string need not try to explain everything. If the doc defines the terms it uses (e.g. "underlying", "relative") and explains them clearly, then that lessens the burden of explanation for doc strings. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-27 3:33 ` Drew Adams @ 2006-06-27 3:52 ` Miles Bader 2006-06-27 4:27 ` Drew Adams 2006-06-27 16:16 ` Richard Stallman 0 siblings, 2 replies; 14+ messages in thread From: Miles Bader @ 2006-06-27 3:52 UTC (permalink / raw) Cc: emacs-devel "Drew Adams" <drew.adams@oracle.com> writes: > I agree, too, that each function's doc string need not try to explain > everything. If the doc defines the terms it uses (e.g. "underlying", > "relative") and explains them clearly, then that lessens the burden of > explanation for doc strings. I've always wondered if there should be more attempts to link from docstrings into the elisp manual. It would reduce the burden of trying to make docstrings too all-encompassing. Consider, for instance, if there were automatically added "See (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of _every_ face function's docstring. [I seem to recall that this was discussed in some manner before?? Anybody remember?] -miles -- o The existentialist, not having a pillow, goes everywhere with the book by Sullivan, _I am going to spit on your graves_. ^ permalink raw reply [flat|nested] 14+ messages in thread
* RE: doc string for face-attribute-relative-p doesn't help 2006-06-27 3:52 ` Miles Bader @ 2006-06-27 4:27 ` Drew Adams 2006-06-27 16:16 ` Richard Stallman 1 sibling, 0 replies; 14+ messages in thread From: Drew Adams @ 2006-06-27 4:27 UTC (permalink / raw) > I agree, too, that each function's doc string need not try to explain > everything. If the doc defines the terms it uses (e.g. "underlying", > "relative") and explains them clearly, then that lessens the burden of > explanation for doc strings. I've always wondered if there should be more attempts to link from docstrings into the elisp manual. It would reduce the burden of trying to make docstrings too all-encompassing. Consider, for instance, if there were automatically added "See (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of _every_ face function's docstring. [I seem to recall that this was discussed in some manner before?? Anybody remember?] [I don't remember such a discussion. Perhaps you are thinking of my request that we add a source-code link to the Customize section for an object (e.g. a variable) - see subject line "Getting more info on a variable in Customize buffers" from 2005/1/1.] Wrt your suggestion for *Help*: I support the idea. "See (elisp)<node name>" might not be clear to some users, and doesn't really help. The link just needs to take you to the right manual node; it need not be named after the node. It could simply say "More...", since *Help* is already providing doc on the function (or variable, or...). If the function or variable is discussed in both manuals, Emacs and Emacs Lisp, then the links could be called "Emacs Manual" and "Emacs-Lisp manual". Alternatively, we could just use "Emacs Manual" and "Emacs-Lisp manual" always (not "More.."), whichever applied. Some objects are not discussed in either manual, so they would have no manual link. Together with a) the link to the source code on the object (e.g. function) name itself, and b) the link to customize the object, users would have everything on the object in one place. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-27 3:52 ` Miles Bader 2006-06-27 4:27 ` Drew Adams @ 2006-06-27 16:16 ` Richard Stallman 2006-06-28 6:41 ` Miles Bader 1 sibling, 1 reply; 14+ messages in thread From: Richard Stallman @ 2006-06-27 16:16 UTC (permalink / raw) Cc: drew.adams, emacs-devel Consider, for instance, if there were automatically added "See (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of _every_ face function's docstring. It isn't hard to add a link that will take you to the Info file, right? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-27 16:16 ` Richard Stallman @ 2006-06-28 6:41 ` Miles Bader 0 siblings, 0 replies; 14+ messages in thread From: Miles Bader @ 2006-06-28 6:41 UTC (permalink / raw) Cc: drew.adams, emacs-devel Richard Stallman <rms@gnu.org> writes: > Consider, for instance, if there were automatically added "See > (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of > _every_ face function's docstring. > > It isn't hard to add a link that will take you to the Info file, > right? > Yes it seems that you can do that by inserting text which matches `help-xref-info-regexp'. An example is the function `convert-standard-filename'. -Miles -- Yo mama's so fat when she gets on an elevator it HAS to go down. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 4:39 ` Miles Bader 2006-06-26 7:45 ` David Kastrup @ 2006-06-26 11:13 ` John S. Yates, Jr. 2006-06-26 10:57 ` Miles Bader 1 sibling, 1 reply; 14+ messages in thread From: John S. Yates, Jr. @ 2006-06-26 11:13 UTC (permalink / raw) Cc: rms, Drew Adams, emacs-devel Miles Bader writes: >Richard Stallman <rms@gnu.org> writes: >> Return non-nil if face ATTRIBUTE VALUE is relative. >> >> What does that mean? How is ATTRIBUTE VALUE a face? This is >> incomprehensible to me. >> >> I don't understand it either. Can someone explain? > >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). Might "Return non-nil if face ATTRIBUTE VALUE is derived from the inherited face." be clearer? /john ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 11:13 ` John S. Yates, Jr. @ 2006-06-26 10:57 ` Miles Bader 2006-06-26 12:28 ` John S. Yates, Jr. 0 siblings, 1 reply; 14+ messages in thread From: Miles Bader @ 2006-06-26 10:57 UTC (permalink / raw) Cc: rms, Drew Adams, emacs-devel "John S. Yates, Jr." <john@yates-sheets.org> writes: > Might "Return non-nil if face ATTRIBUTE VALUE is derived from > the inherited face." be clearer? I'm afraid that doesn't even make sense to me... -Miles -- ((lambda (x) (list x x)) (lambda (x) (list x x))) ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 10:57 ` Miles Bader @ 2006-06-26 12:28 ` John S. Yates, Jr. 2006-06-27 2:12 ` Miles Bader 0 siblings, 1 reply; 14+ messages in thread From: John S. Yates, Jr. @ 2006-06-26 12:28 UTC (permalink / raw) Cc: rms, Drew Adams, emacs-devel On Mon, 26 Jun 2006 19:57:03 +0900, you wrote: >"John S. Yates, Jr." <john@yates-sheets.org> writes: >> Might "Return non-nil if face ATTRIBUTE VALUE is derived from >> the inherited face." be clearer? > >I'm afraid that doesn't even make sense to me... Fair enough. Perhaps I was too quick to respond with too little knowledge of the actual function being documented. My guess had been that the issue was to describe attribute inheritance. If that is indeed the case then "relative to" is at best unfamiliar terminology. Backing off and focusing only on terminology for describing definitions, I find "in terms of", "as a function of" or "based on" all easier to swallow than "defined relative to". /john ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: doc string for face-attribute-relative-p doesn't help 2006-06-26 12:28 ` John S. Yates, Jr. @ 2006-06-27 2:12 ` Miles Bader 0 siblings, 0 replies; 14+ messages in thread From: Miles Bader @ 2006-06-27 2:12 UTC (permalink / raw) Cc: rms, Drew Adams, emacs-devel "John S. Yates, Jr." <john@yates-sheets.org> writes: > Backing off and focusing only on terminology for describing > definitions, I find "in terms of", "as a function of" or "based > on" all easier to swallow than "defined relative to". The key point is whether the value in question acts as an absolute setting, or whether it acts as a modifier (including the "null modifier" `unspecified') for the (absolute) value in an underlying face. [I probably use the term "relative" to contrast with "absolute" out of habit, from typical usage when describing filenames.] -Miles -- My spirit felt washed. With blood. [Eli Shin, on "The Passion of the Christ"] ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2006-06-28 6:41 UTC | newest] Thread overview: 14+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <MEEKKIABFKKDFJMPIOEBKEIGDCAA.drew.adams@oracle.com> 2006-06-25 15:33 ` doc string for face-attribute-relative-p doesn't help Richard Stallman 2006-06-26 4:39 ` Miles Bader 2006-06-26 7:45 ` David Kastrup 2006-06-26 16:17 ` Drew Adams 2006-06-27 2:08 ` Miles Bader 2006-06-27 3:33 ` Drew Adams 2006-06-27 3:52 ` Miles Bader 2006-06-27 4:27 ` Drew Adams 2006-06-27 16:16 ` Richard Stallman 2006-06-28 6:41 ` Miles Bader 2006-06-26 11:13 ` John S. Yates, Jr. 2006-06-26 10:57 ` Miles Bader 2006-06-26 12:28 ` John S. Yates, Jr. 2006-06-27 2:12 ` Miles Bader
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.