bug#11225: 24.1.50; Explanation of SPECS arg in docstrings in face-remap.el insufficient

[Michael Heerdegen]

Hello,

there are commands in face-remap.el that take a "specs" argument
(`face-remap-add-relative', `face-remap-set-base').  Their doc tells
that SPECS can also be a list of faces.  It doesn't explain what the
meaning of a list of faces for that functions is.

Also the manual doesn't explain it (Node "Face Remapping").  There
is only this little example:

      ;; Remap the `escape-glyph' face into a combination
      ;; of the `highlight' and `italic' faces:
      (face-remap-add-relative 'escape-glyph 'highlight 'italic)

which seems to say that the given faces are combined in some way (how?).

Maybe the docstrings and the manual can be clarified by adding just
one or two sentences that describe the meaning.


Thanks,

Michael


In GNU Emacs 24.1.50.1 (i486-pc-linux-gnu, GTK+ Version 3.2.3)
 of 2012-04-10 on zelenka, modified by Debian
 (emacs-snapshot package, version 2:20120410-1)
Windowing system distributor `The X.Org Foundation', version 11.0.11104000
Configured using:
 `configure '--build' 'i486-linux-gnu' '--host' 'i486-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 
'--enable-locallisppath=/etc/emacs-snapshot:/etc/emacs:/usr/local/share/emacs/24.1.50/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.1.50/site-lisp:/usr/share/emacs/site-lisp'
 '--without-compress-info' '--with-crt-dir=/usr/lib/i386-linux-gnu/'
 '--with-x=yes' '--with-x-toolkit=gtk3' '--with-imagemagick=yes'
 'build_alias=i486-linux-gnu' 'host_alias=i486-linux-gnu'
 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2''