Commit fb5b8aca authored by Chong Yidong's avatar Chong Yidong

Updates to Display chapter of Lisp manual.

* doc/lispref/display.texi (The Echo Area): Add xref to Output Streams.
(Displaying Messages): Improve doc of message.
(Echo Area Customization, Invisible Text): Copyedits.
(Invisible Text): Mention that spec comparison is done with eq.
(Width): Improve doc of char-width.
(Faces): Recommend using symbol instead of string for face name.
Minor clarifications.
(Defining Faces): Copyedits.  Update face example.
(Attribute Functions): Mark set-face-foreground etc as commands.
(Face Remapping): Mention text-scale-adjust.  Clarify
face-remapping-alist and related docs.
(Face Functions): Don't document make-face or copy-face.

* lisp/faces.el (make-face, make-empty-face, copy-face):
* lisp/face-remap.el (face-remap-add-relative, face-remap-set-base):
Doc fixes.

* src/xfaces.c (Vface_remapping_alist): Doc fix.
parent dc9924b8
2012-03-21 Chong Yidong <cyd@gnu.org>
* display.texi (The Echo Area): Add xref to Output Streams.
(Displaying Messages): Improve doc of message.
(Echo Area Customization, Invisible Text): Copyedits.
(Invisible Text): Mention that spec comparison is done with eq.
(Width): Improve doc of char-width.
(Faces): Recommend using symbol instead of string for face name.
Minor clarifications.
(Defining Faces): Copyedits. Update face example.
(Attribute Functions): Mark set-face-foreground etc as commands.
(Face Remapping): Mention text-scale-adjust. Clarify
face-remapping-alist and related docs.
(Face Functions): Don't document make-face or copy-face.
2012-03-20 Chong Yidong <cyd@gnu.org>
* display.texi (Forcing Redisplay): Various rewrites to reflect
......
This diff is collapsed.
......@@ -123,6 +123,8 @@ and pops down the *Completions* buffer accordingly.
*** Completion style can be set per-category `completion-category-overrides'.
+++
*** Completion of buffers now uses substring completion by default.
---
*** The `widget-complete-field' option has been removed.
** Mail changes
......
2012-03-21 Chong Yidong <cyd@gnu.org>
* faces.el (make-face, make-empty-face, copy-face):
* face-remap.el (face-remap-add-relative, face-remap-set-base):
Doc fixes.
2012-03-21 Stefan Monnier <monnier@iro.umontreal.ca>
* wid-edit.el (widget-complete-field): Remove (bug#11051).
......
......@@ -106,21 +106,20 @@ The list structure of ENTRY may be destructively modified."
;;;###autoload
(defun face-remap-add-relative (face &rest specs)
"Add a face remapping entry of FACE to SPECS in the current buffer.
Return a cookie which can be used to delete the remapping with
Return a cookie which can be used to delete this remapping with
`face-remap-remove-relative'.
SPECS can be any value suitable for the `face' text property,
including a face name, a list of face names, or a face-attribute
property list. The attributes given by SPECS will be merged with
any other currently active face remappings of FACE, and with the
global definition of FACE. An attempt is made to sort multiple
entries so that entries with relative face-attributes are applied
after entries with absolute face-attributes.
The base (lowest priority) remapping may be set to a specific
value, instead of the default of the global face definition,
using `face-remap-set-base'."
The remaining arguments, SPECS, should be either a list of face
names, or a property list of face attribute/value pairs. The
remapping specified by SPECS takes effect alongside the
remappings from other calls to `face-remap-add-relative', as well
as the normal definition of FACE (at lowest priority). This
function tries to sort multiple remappings for the same face, so
that remappings specifying relative face attributes are applied
after remappings specifying absolute face attributes.
The base (lowest priority) remapping may be set to something
other than the normal definition of FACE via `face-remap-set-base'."
(while (and (consp specs) (null (cdr specs)))
(setq specs (car specs)))
(make-local-variable 'face-remapping-alist)
......@@ -148,7 +147,9 @@ COOKIE should be the return value from that function."
;;;###autoload
(defun face-remap-reset-base (face)
"Set the base remapping of FACE to inherit from FACE's global definition."
"Set the base remapping of FACE to the normal definition of FACE.
This causes the remappings specified by `face-remap-add-relative'
to apply on top of the normal definition of FACE."
(let ((entry (assq face face-remapping-alist)))
(when entry
;; If there's nothing except a base remapping, we simply remove
......@@ -163,10 +164,15 @@ COOKIE should be the return value from that function."
;;;###autoload
(defun face-remap-set-base (face &rest specs)
"Set the base remapping of FACE in the current buffer to SPECS.
If SPECS is empty, the default base remapping is restored, which
inherits from the global definition of FACE; note that this is
different from SPECS containing a single value `nil', which does
not inherit from the global definition of FACE."
This causes the remappings specified by `face-remap-add-relative'
to apply on top of the face specification given by SPECS. SPECS
should be either a list of face names, or a property list of face
attribute/value pairs.
If SPECS is empty, call `face-remap-reset-base' to use the normal
definition of FACE as the base remapping; note that this is
different from SPECS containing a single value `nil', which means
not to inherit from the global definition of FACE at all."
(while (and (consp specs) (not (null (car specs))) (null (cdr specs)))
(setq specs (car specs)))
(if (or (null specs)
......
......@@ -122,15 +122,13 @@ REGISTRY, ALTERNATIVE1, ALTERNATIVE2, and etc."
"Return a list of all defined faces."
(mapcar #'car face-new-frame-defaults))
;;; ### If not frame-local initialize by what X resources?
(defun make-face (face &optional no-init-from-resources)
"Define a new face with name FACE, a symbol.
NO-INIT-FROM-RESOURCES non-nil means don't initialize frame-local
variants of FACE from X resources. (X resources recognized are found
in the global variable `face-x-resources'.) If FACE is already known
as a face, leave it unmodified. Value is FACE."
Do not call this directly from Lisp code; use `defface' instead.
If NO-INIT-FROM-RESOURCES is non-nil, don't initialize face
attributes from X resources. If FACE is already known as a face,
leave it unmodified. Return FACE."
(interactive (list (read-from-minibuffer
"Make face: " nil nil t 'face-name-history)))
(unless (facep face)
......@@ -145,31 +143,30 @@ as a face, leave it unmodified. Value is FACE."
(make-face-x-resource-internal face)))
face)
(defun make-empty-face (face)
"Define a new, empty face with name FACE.
If the face already exists, it is left unmodified. Value is FACE."
Do not call this directly from Lisp code; use `defface' instead."
(interactive (list (read-from-minibuffer
"Make empty face: " nil nil t 'face-name-history)))
(make-face face 'no-init-from-resources))
(defun copy-face (old-face new-face &optional frame new-frame)
"Define a face just like OLD-FACE, with name NEW-FACE.
If NEW-FACE already exists as a face, it is modified to be like
OLD-FACE. If it doesn't already exist, it is created.
If the optional argument FRAME is given as a frame, NEW-FACE is
changed on FRAME only.
If FRAME is t, the frame-independent default specification for OLD-FACE
is copied to NEW-FACE.
If FRAME is nil, copying is done for the frame-independent defaults
and for each existing frame.
If the optional fourth argument NEW-FRAME is given,
copy the information from face OLD-FACE on frame FRAME
to NEW-FACE on frame NEW-FRAME. In this case, FRAME may not be nil."
"Define a face named NEW-FACE, which is a copy of OLD-FACE.
This function does not copy face customization data, so NEW-FACE
will not be made customizable. Most Lisp code should not call
this function; use `defface' with :inherit instead.
If NEW-FACE already exists as a face, modify it to be like
OLD-FACE. If NEW-FACE doesn't already exist, create it.
If the optional argument FRAME is a frame, change NEW-FACE on
FRAME only. If FRAME is t, copy the frame-independent default
specification for OLD-FACE to NEW-FACE. If FRAME is nil, copy
the defaults as well as the faces on each existing frame.
If the optional fourth argument NEW-FRAME is given, copy the
information from face OLD-FACE on frame FRAME to NEW-FACE on
frame NEW-FRAME. In this case, FRAME must not be nil."
(let ((inhibit-quit t))
(if (null frame)
(progn
......
2012-03-21 Chong Yidong <cyd@gnu.org>
* xfaces.c (Vface_remapping_alist): Doc fix.
2012-03-20 Eli Zaretskii <eliz@gnu.org>
* w32proc.c (Fw32_set_console_codepage)
......
......@@ -6599,20 +6599,22 @@ ignore. */);
doc: /* Alist of face remappings.
Each element is of the form:
(FACE REPLACEMENT...),
(FACE . REPLACEMENT),
which causes display of the face FACE to use REPLACEMENT... instead.
REPLACEMENT... is interpreted the same way as the value of a `face'
text property: it may be (1) A face name, (2) A list of face names,
(3) A property-list of face attribute/value pairs, or (4) A list of
face names or lists containing face attribute/value pairs.
which causes display of the face FACE to use REPLACEMENT instead.
REPLACEMENT is a face specification, i.e. one of the following:
Multiple entries in REPLACEMENT... are merged together to form the final
result, with faces or attributes earlier in the list taking precedence
over those that are later.
(1) a face name
(2) a property list of attribute/value pairs, or
(3) a list in which each element has the form of (1) or (2).
Face-name remapping cycles are suppressed; recursive references use the
underlying face instead of the remapped face. So a remapping of the form:
List values for REPLACEMENT are merged to form the final face
specification, with earlier entries taking precedence, in the same as
as in the `face' text property.
Face-name remapping cycles are suppressed; recursive references use
the underlying face instead of the remapped face. So a remapping of
the form:
(FACE EXTRA-FACE... FACE)
......@@ -6620,13 +6622,13 @@ underlying face instead of the remapped face. So a remapping of the form:
(FACE (FACE-ATTR VAL ...) FACE)
will cause EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
existing definition of FACE. Note that for the default face, this isn't
necessary, as every face inherits from the default face.
causes EXTRA-FACE... or (FACE-ATTR VAL ...) to be _merged_ with the
existing definition of FACE. Note that this isn't necessary for the
default face, since every face inherits from the default face.
Making this variable buffer-local is a good way to allow buffer-specific
face definitions. For instance, the mode my-mode could define a face
`my-mode-default', and then in the mode setup function, do:
If this variable is made buffer-local, the face remapping takes effect
only in that buffer. For instance, the mode my-mode could define a
face `my-mode-default', and then in the mode setup function, do:
(set (make-local-variable 'face-remapping-alist)
'((default my-mode-default)))).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment