all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* 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 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  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 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  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-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

* 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

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.