emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: set-face-attribute and floating point :height values


From: Drew Adams
Subject: RE: set-face-attribute and floating point :height values
Date: Mon, 31 Jan 2011 14:04:11 -0800

> > You're saying: make the default font height be 1.4 times the default
> > font height. The default font height must be absolute.
> > http://debbugs.gnu.org/cgi/bugreport.cgi?bug=2659
> 
> Ah, I see now.  So the underlying face must already have 
> *some* :height value, so this is not the right way to
> specify the initial face-height.

It might help if the doc either avoided the undefined term "underlying face" or
explained what it means by that.

Does it mean to refer to face-attribute inheritance?  If so, it should say so;
if not, it should say what is really meant by an "underlying" face for the face
whose attribute you are setting.  Can multiple faces underly a given face?  How
to find the underlying faces for a given face?  Etc.

The Elisp manual (node Face Attributes) does a pretty good job here in fact, but
the relation to face inheritance is not so clear.  A distinction is made in the
`:inherit' entry of node Face Attributes, but without any explicit definitions.

There should be a cross-ref to node Face Attributes from any other places (e.g.
node Attribute Functions, `merge-face-attributes') where we mention underlying
faces.

The doc string for `set-face-attribute' explains nothing about "underlying
face", however.  It needs at least a pointer to the corresponding manual page to
become comprehensible.

FWIW, there are additional places in the docs where "underlying" is used with no
real definition/explanation.  It might seem shorter for the person writing the
description to use such a term, but without any explanation it can take longer
for a user to understand what is meant.  Sometimes adding a cross reference
might suffice to clear things up.

If a sentence makes about the same amount of sense with and without the
qualifier "underlying" it's a sign that it should probably just be removed.
E.g., if in some context "the file system" is about as clear as "the underlying
file system", then go with the former.  Put differently, if "the file system" is
not clear enough in some context then just adding "underlying" will not help: If
it has any effect it will only be to confuse (why the qualifier? what does it
mean here?).

Emacs manual:
"underlying text representation" (for images)
"underlying system's text representation" (for international coding)
"underlying details about charsets" (for charsets)
"underlying VC" (for version control)
"underlying method" (for EDE)
"underlying shell" (for shell options)
"underlying face" (for face resources)

Elisp manual:
"underlying OS" (for frame configs)
"underlying OS" (for subprocesses)
"underlying buffer text" (for keymaps)
"underlying platform" (for eol conversion)
"`underlying face'" (for face attributes)

Doc strings:
"underlying file system" (expand-file-name)
"underlying face" (face-remapping-alist)
"underlying face" (set-face-attribute)
"underlying file system" (shell-quote-wildcard-pattern)
"underyling version-control system (vc-rollback)




reply via email to

[Prev in Thread] Current Thread [Next in Thread]