Re: doc string for face-attribute-relative-p doesn't help

Re: doc string for face-attribute-relative-p doesn't help

[Richard Stallman]

      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?

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

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.

Re: doc string for face-attribute-relative-p doesn't help

[David Kastrup]

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

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

"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)))

Re: doc string for face-attribute-relative-p doesn't help

[John S. Yates, Jr.]

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

Re: doc string for face-attribute-relative-p doesn't help

[John S. Yates, Jr.]

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

RE: doc string for face-attribute-relative-p doesn't help

[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.
    >
    > 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.

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

"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?

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

"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"]

RE: doc string for face-attribute-relative-p doesn't help

[Drew Adams]

    > 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.

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

"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_.

RE: doc string for face-attribute-relative-p doesn't help

[Drew Adams]

    > 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.

Re: doc string for face-attribute-relative-p doesn't help

[Richard Stallman]

    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?

Re: doc string for face-attribute-relative-p doesn't help

[Miles Bader]

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.