Re: face-remapping patch

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 29 May 2008 04:47:30 -0400
> From: Miles Bader <miles@gnu.org>
> Cc: Emacs-Devel <emacs-devel@gnu.org>
> 
> Here's a new patch addressing your comments.

Not my comments, but allow me a few remarks on the manual bits.

> +@tindex face-remapping-alist

Are we still using @tindex?  I thought it was not needed anymore a
long time ago, and should not be used.  I don't see it anywhere in the
ELisp manual in CVS trunk.

> +  This variable is used for buffer-local changes in the appearance of
> +a face, for instance making the @code{default} face a variable-pitch
> +face in a particular buffer.
> +
> +  Its value should be an alist, whose elements have the form
> +@code{(@var{face} @var{remapping}@dots{})}; when the text specifies
> +face @var{face}, Emacs redisplay uses @var{remapping}@dots{} instead.

It took me a few moments to understand what you meant by "when text
specifies face".  I finally realized that you are talking about text
properties, so please add the word "property" here, because in Emacs,
text does not specify anything except itself.

> +@var{remapping}@dots{} may be any face specification suitable for a

Using @dots{} in the middle of text will cause TeX render it as an end
of a sentence, I think.  At least put a @: after it, if you must use
it (I'd recommend against that).

> +@code{face} text property, usually a face name, but also perhaps a
> +property list of face attribute/value pairs; @xref{Special
> +Properties}.

It's not a good idea to use @xref in the middle of a sentence: it
produces capitalized "See" which is incorrect English.  "see @ref" is
a better alternative; or just start a new sentence.

> +The new definition @var{remapping}@dots{} is the complete
> +specification of how to display @var{face}---it entirely replaces,
> +rather than augmenting or modifying, the normal definition of that
> +face.

Isn't "augments or modifies" more correct, English-wise (because it
matches "replaces" better)?

> +If @var{remapping}@dots{} recursively references the same face name
> +@var{face}, either directly remapping entry, or via the
> +@code{:inherit} attribute of some other face in
> +@var{remapping}@dots{}, then that reference uses normal frame-wide
> +definition of @var{face} instead of the `remapped' definition.
                                            ^^^^^^^^
There should never be a need to use `...' in Texinfo.  Either you want
``...'', for quoting, or you want @samp.  I think you want the former
here.

> +For instance, if the @code{mode-line} face is remapped using this
> +entry in @code{face-remapping-alist}:
> +@example
> +(mode-line italic mode-line)
> +@end example
> +Then the new definition of the @code{mode-line} face inherits from the
   ^^^^
This "Then" should not begin with a capital letter, since it continues
the sentence before the @example, and you want an @outdent before it,
to prevent automatic indentation of each new paragraph.