From ed1f0bd388e83e5ee065f7dde0f52bbfe9031933 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Tue, 18 Sep 2012 13:14:42 +0800 Subject: [PATCH] Doc fixes for defface and friends. * lisp/cus-edit.el (custom-unlispify-remove-prefixes): Add warning. * lisp/custom.el (defface): Doc fix. * doc/lispref/customize.texi (Customization): Define customization more carefully. (Common Keywords): Add xref to Constant Variables. * doc/lispref/display.texi (Faces): Discuss anonymous faces. (Face Attributes): Tweak intro. (Defining Faces): Move after the Face Attributes node. Copyedits. (Displaying Faces): Describe role of inheritance. * doc/lispref/variables.texi (Defining Variables): Link to defcustom's node instead of the higher-level Customization chapter. Fixes: debbugs:11440 --- doc/lispref/ChangeLog | 14 ++ doc/lispref/customize.texi | 73 ++++--- doc/lispref/display.texi | 376 +++++++++++++++++++------------------ doc/lispref/elisp.texi | 2 +- doc/lispref/text.texi | 11 +- doc/lispref/variables.texi | 3 +- lisp/ChangeLog | 6 + lisp/cus-edit.el | 5 +- lisp/custom.el | 110 +++++------ 9 files changed, 331 insertions(+), 269 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ce99c81a912..329c194f45a 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,17 @@ +2012-09-18 Chong Yidong + + * display.texi (Faces): Discuss anonymous faces. + (Face Attributes): Tweak intro. + (Defining Faces): Move after the Face Attributes node. Copyedits. + (Displaying Faces): Describe role of inheritance. + + * customize.texi (Customization): Define customization more + carefully (Bug#11440). + (Common Keywords): Add xref to Constant Variables. + + * variables.texi (Defining Variables): Link to defcustom's node + instead of the higher-level Customization chapter. + 2012-09-11 Paul Eggert Simplify, document, and port floating-point (Bug#12381). diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 38dfc949264..c9d22851ed2 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -6,13 +6,30 @@ @chapter Customization Settings @cindex customization item - This chapter describes how to declare customizable variables and -customization groups for classifying them. We use the term -@dfn{customization item} to include customizable variables, -customization groups, as well as faces. - - @xref{Defining Faces}, for the @code{defface} macro, which is used -for declaring customizable faces. + Users of Emacs can customize variables and faces without writing +Lisp code, by using the Customize interface. @xref{Easy +Customization,,, emacs, The GNU Emacs Manual}. This chapter describes +how to define @dfn{customization items} that users can interact with +through the Customize interface. + + Customization items include customizable variables, which are +defined with the +@ifinfo +@code{defcustom} macro (@pxref{Variable Definitions}); +@end ifinfo +@ifnotinfo +@code{defcustom} macro; +@end ifnotinfo +customizable faces, which are defined with @code{defface} (described +separately in @ref{Defining Faces}); and @dfn{customization groups}, +defined with +@ifinfo +@code{defgroup} (@pxref{Group Definitions}), +@end ifinfo +@ifnotinfo +@code{defgroup}, +@end ifnotinfo +which act as containers for groups of related customization items. @menu * Common Keywords:: Common keyword arguments for all kinds of @@ -29,9 +46,10 @@ for declaring customizable faces. @cindex customization keywords The customization declarations that we will describe in the next few -sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword -arguments for specifying various information. This section describes -keywords that apply to all types of customization declarations. +sections---@code{defcustom}, @code{defgroup}, etc.---all accept +keyword arguments (@pxref{Constant Variables}) for specifying various +information. This section describes keywords that apply to all types +of customization declarations. All of these keywords, except @code{:tag}, can be used more than once in a given item. Each use of the keyword has an independent effect. @@ -188,14 +206,14 @@ choice is the official name of the package, such as MH-E or Gnus. @cindex define customization group @cindex customization groups, defining - Each Emacs Lisp package should have one main customization group which -contains all the options, faces and other groups in the package. If the -package has a small number of options and faces, use just one group and -put everything in it. When there are more than twelve or so options and -faces, then you should structure them into subgroups, and put the -subgroups under the package's main customization group. It is OK to -put some of the options and faces in the package's main group alongside -the subgroups. + Each Emacs Lisp package should have one main customization group +which contains all the options, faces and other groups in the package. +If the package has a small number of options and faces, use just one +group and put everything in it. When there are more than twenty or so +options and faces, then you should structure them into subgroups, and +put the subgroups under the package's main customization group. It is +OK to put some of the options and faces in the package's main group +alongside the subgroups. The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, @@ -251,7 +269,17 @@ confusing names for options and faces. @node Variable Definitions @section Defining Customization Variables @cindex define customization options -@cindex customization variables, how to define +@cindex customizable variables, how to define +@cindex user options, how to define + + @dfn{Customizable variables}, also called @dfn{user options}, are +global Lisp variables whose values can be set through the Customize +interface. Unlike other global variables, which are defined with +@code{defvar} (@pxref{Defining Variables}), customizable variables are +defined using the @code{defcustom} macro. In addition to calling +@code{defvar} as a subroutine, @code{defcustom} states how the +variable should be displayed in the Customize interface, the values it +is allowed to take, etc. @defmac defcustom option standard doc [keyword value]@dots{} This macro declares @var{option} as a user option (i.e.@: a @@ -291,13 +319,14 @@ has not been assigned the right value yet. In that case, use standard value after Emacs starts up. @end defmac - @code{defcustom} accepts the following additional keywords: + In addition to the keywords listed in @ref{Common Keywords}, this +macro accepts the following keywords: @table @code @item :type @var{type} Use @var{type} as the data type for this option. It specifies which -values are legitimate, and how to display the value. -@xref{Customization Types}, for more information. +values are legitimate, and how to display the value +(@pxref{Customization Types}). @item :options @var{value-list} @kindex options@r{, @code{defcustom} keyword} diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 64aa891e56b..11a86f3c1c5 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1863,20 +1863,36 @@ height. A @dfn{face} is a collection of graphical @dfn{attributes} for displaying text: font, foreground color, background color, optional -underlining, and so on. Faces control how Emacs displays text in -buffers, as well as other parts of the frame such as the mode line. -@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of -faces Emacs normally comes with. - -@cindex face id - For most purposes, you refer to a face in Lisp programs using its -@dfn{face name}, which is usually a Lisp symbol. For backward -compatibility, a face name can also be a string, which is equivalent -to a Lisp symbol of the same name. +underlining, etc. Faces control how Emacs displays text in buffers, +as well as other parts of the frame such as the mode line. + +@cindex anonymous face + One way to represent a face is as a property list of attributes, +like @code{(:foreground "red" :weight bold)}. For example, you can +assign such an @dfn{anonymous face} as the value of the @code{face} +text property; this causes Emacs to display the underlying text with +the specified attributes. @xref{Special Properties}. + +@cindex face name + More commonly, a face is referred to via a @dfn{face name}: a Lisp +symbol which is associated with a set of face attributes. Named faces +are defined using the @code{defface} macro (@pxref{Defining Faces}). +Emacs defines several standard named faces; @xref{Standard Faces,,, +emacs, The GNU Emacs Manual}. + + Many parts of Emacs require named faces, and do not accept anonymous +faces. These include the functions documented in @ref{Attribute +Functions}, and the variable @code{font-lock-keywords} +(@pxref{Search-based Fontification}). Unless otherwise stated, we +will use the term @dfn{face} to refer only to named faces. + + For backward compatibility, you can also use a string to specify a +face name; that is equivalent to a Lisp symbol with the same name. @defun facep object -This function returns a non-@code{nil} value if @var{object} is a Lisp -symbol or string that names a face. Otherwise, it returns @code{nil}. +This function returns a non-@code{nil} value if @var{object} is a +named face: a Lisp symbol or string which serves as a face name. +Otherwise, it returns @code{nil}. @end defun By default, each face name corresponds to the same set of attributes @@ -1884,8 +1900,8 @@ in all frames. But you can also assign a face name a special set of attributes in one frame (@pxref{Attribute Functions}). @menu -* Defining Faces:: How to define a face. * Face Attributes:: What is in a face? +* Defining Faces:: How to define a face. * Attribute Functions:: Functions to examine and set face attributes. * Displaying Faces:: How Emacs combines the faces specified for a character. * Face Remapping:: Remapping faces to alternative definitions. @@ -1900,161 +1916,21 @@ attributes in one frame (@pxref{Attribute Functions}). * Low-Level Font:: Lisp representation for character display fonts. @end menu -@node Defining Faces -@subsection Defining Faces - - The @code{defface} macro defines a face and specifies its default -appearance. The user can subsequently customize the face using the -Customize interface (@pxref{Customization}). - -@defmac defface face spec doc [keyword value]@dots{} -This macro declares @var{face} as a customizable face whose default -attributes are given by @var{spec}. You should not quote the symbol -@var{face}, and it should not end in @samp{-face} (that would be -redundant). The argument @var{doc} is a documentation string for the -face. The additional @var{keyword} arguments have the same meanings -as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). - -When @code{defface} executes, it defines the face according to -@var{spec}, then uses any customizations that were read from the -init file (@pxref{Init File}) to override that specification. - -When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs -Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} -overrides any customizations of the face. This way, the face reflects -exactly what the @code{defface} says. - -@cindex face specification -The @var{spec} argument is a @dfn{face specification}, which states -how the face should appear on different kinds of terminals. It should -be an alist whose elements each have the form - -@example -(@var{display} . @var{plist}) -@end example - -@noindent -@var{display} specifies a class of terminals (see below), while -@var{plist} is a property list of face attributes and their values, -specifying how the face appears on such terminals -@iftex -(see the next section for details about face attributes). -@end iftex -@ifnottex -(@pxref{Face Attributes}, for details about face attributes). -@end ifnottex - -The @var{display} part of an element of @var{spec} determines which -frames the element matches. If more than one element of @var{spec} -matches a given frame, the first element that matches is the one used -for that frame. There are three possibilities for @var{display}: - -@table @asis -@item @code{default} -This element of @var{spec} doesn't match any frames; instead, it -specifies defaults that apply to all frames. This element, if used, -must be the first element of @var{spec}. Each of the following -elements can override any or all of these defaults. - -@item @code{t} -This element of @var{spec} matches all frames. Therefore, any -subsequent elements of @var{spec} are never used. Normally -@code{t} is used in the last (or only) element of @var{spec}. - -@item a list -If @var{display} is a list, each element should have the form -@code{(@var{characteristic} @var{value}@dots{})}. Here -@var{characteristic} specifies a way of classifying frames, and the -@var{value}s are possible classifications which @var{display} should -apply to. Here are the possible values of @var{characteristic}: - -@table @code -@item type -The kind of window system the frame uses---either @code{graphic} (any -graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), -@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} -(a non-graphics-capable display). -@xref{Window Systems, window-system}. - -@item class -What kinds of colors the frame supports---either @code{color}, -@code{grayscale}, or @code{mono}. - -@item background -The kind of background---either @code{light} or @code{dark}. - -@item min-colors -An integer that represents the minimum number of colors the frame -should support. This matches a frame if its -@code{display-color-cells} value is at least the specified integer. - -@item supports -Whether or not the frame can display the face attributes given in -@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face -Attribute Testing}, for more information on exactly how this testing -is done. -@end table - -If an element of @var{display} specifies more than one @var{value} for a -given @var{characteristic}, any of those values is acceptable. If -@var{display} has more than one element, each element should specify a -different @var{characteristic}; then @emph{each} characteristic of the -frame must match one of the @var{value}s specified for it in -@var{display}. -@end table -@end defmac - - Here's how the standard face @code{highlight} is defined: - -@example -(defface highlight - '((((class color) (min-colors 88) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 88) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 16) (background light)) - :background "darkseagreen2") - (((class color) (min-colors 16) (background dark)) - :background "darkolivegreen") - (((class color) (min-colors 8)) - :background "green" :foreground "black") - (t :inverse-video t)) - "Basic face for highlighting." - :group 'basic-faces) -@end example - - Internally, Emacs stores the face's default specification in its -@code{face-defface-spec} symbol property (@pxref{Property Lists}). -The @code{saved-face} property stores the face specification saved by -the user, using the customization buffer; the @code{customized-face} -property stores the face specification customized for the current -session, but not saved; and the @code{theme-face} property stores an -alist associating the active customization settings and Custom themes -with their specifications for that face. The face's documentation -string is stored in the @code{face-documentation} property. But -normally you should not try to set any of these properties directly. -@xref{Applying Customizations}, for the @code{custom-set-faces} -function, which is used to apply customized face settings. - - People are sometimes tempted to create variables whose values -specify a face to use. In the vast majority of cases, this is not -necessary; it is preferable to simply use faces directly. - @node Face Attributes @subsection Face Attributes @cindex face attributes - The effect of using a face is determined by a fixed set of @dfn{face -attributes}. This table lists all the face attributes, their possible -values, and their effects. You can specify more than one face for a -given piece of text; Emacs merges the attributes of all the faces to -determine how to display the text. @xref{Displaying Faces}. + @dfn{Face attributes} determine the visual appearance of a face. +The following table lists all the face attributes, their possible +values, and their effects. - In addition to the values given below, each face attribute can also -have the value @code{unspecified}. This special value means the face -doesn't specify that attribute. In face merging, when the first face -fails to specify a particular attribute, the next face gets a chance. -However, the @code{default} face must specify all attributes. + Apart from the values given below, each face attribute can have the +value @code{unspecified}. This special value means that the face +doesn't specify that attribute directly. An @code{unspecified} +attribute tells Emacs to refer instead to a parent face (see the +description @code{:inherit} attribute below); or, failing that, to an +underlying face (@pxref{Displaying Faces}). The @code{default} face +must specify all attributes. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2063,7 +1939,7 @@ attribute is ignored. @table @code @item :family Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU -Emacs Manual}, for more information about font families; the function +Emacs Manual}, for more information about font families. The function @code{font-family-list} (see below) returns a list of available family names. @xref{Fontsets}, for information about fontsets. @@ -2083,9 +1959,8 @@ The height of the font. In the simplest case, this is an integer in units of 1/10 point. The value can also be a floating point number or a function, which -specifies the height relative to an @dfn{underlying face} (i.e., a -face that has a lower priority in the list described in -@ref{Displaying Faces}). If the value is a floating point number, +specifies the height relative to an @dfn{underlying face} +(@pxref{Displaying Faces}). If the value is a floating point number, that specifies the amount by which to scale the height of the underlying face. If the value is a function, that function is called with one argument, the height of the underlying face, and returns the @@ -2261,11 +2136,147 @@ suitable for use with @code{:stipple} (see above). It returns @code{nil} otherwise. @end defun +@node Defining Faces +@subsection Defining Faces + + The usual way to define a face is through the @code{defface} macro. +This macro defines a face name, and associates that name with a set of +face attributes. It also sets up the face so that the user can +customize it via the Customize interface (@pxref{Customization}). + +@defmac defface face spec doc [keyword value]@dots{} +This macro declares @var{face} as a customizable face whose default +attributes are given by @var{spec}. You should not quote the symbol +@var{face}, and it should not end in @samp{-face} (that would be +redundant). The argument @var{doc} is a documentation string for the +face. The additional @var{keyword} arguments have the same meanings +as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). + +When @code{defface} executes, it defines the face according to +@var{spec}, then uses any customizations that were read from the +init file (@pxref{Init File}) to override that specification. + +When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs +Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} +overrides any customizations of the face. This way, the face reflects +exactly what the @code{defface} says. + +@cindex face specification +The @var{spec} argument is a @dfn{face specification}, which states +how the face should appear on different kinds of terminals. It should +be an alist whose elements each have the form + +@example +(@var{display} . @var{plist}) +@end example + +@noindent +@var{display} specifies a class of terminals (see below). @var{plist} +is a property list of face attributes and their values, specifying how +the face appears on such terminals. For backward compatibility, you +can also write an element as @code{(@var{display} @var{plist})}. + +The @var{display} part of an element of @var{spec} determines which +terminals the element matches. If more than one element of @var{spec} +matches a given terminal, the first element that matches is the one +used for that terminal. There are three possibilities for +@var{display}: + +@table @asis +@item @code{default} +This element of @var{spec} doesn't match any terminal; instead, it +specifies defaults that apply to all terminals. This element, if +used, must be the first element of @var{spec}. Each of the following +elements can override any or all of these defaults. + +@item @code{t} +This element of @var{spec} matches all terminals. Therefore, any +subsequent elements of @var{spec} are never used. Normally @code{t} +is used in the last (or only) element of @var{spec}. + +@item a list +If @var{display} is a list, each element should have the form +@code{(@var{characteristic} @var{value}@dots{})}. Here +@var{characteristic} specifies a way of classifying terminals, and the +@var{value}s are possible classifications which @var{display} should +apply to. Here are the possible values of @var{characteristic}: + +@table @code +@item type +The kind of window system the terminal uses---either @code{graphic} +(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS +console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a +non-graphics-capable display). @xref{Window Systems, window-system}. + +@item class +What kinds of colors the terminal supports---either @code{color}, +@code{grayscale}, or @code{mono}. + +@item background +The kind of background---either @code{light} or @code{dark}. + +@item min-colors +An integer that represents the minimum number of colors the terminal +should support. This matches a terminal if its +@code{display-color-cells} value is at least the specified integer. + +@item supports +Whether or not the terminal can display the face attributes given in +@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face +Attribute Testing}, for more information on exactly how this testing +is done. +@end table + +If an element of @var{display} specifies more than one @var{value} for +a given @var{characteristic}, any of those values is acceptable. If +@var{display} has more than one element, each element should specify a +different @var{characteristic}; then @emph{each} characteristic of the +terminal must match one of the @var{value}s specified for it in +@var{display}. +@end table +@end defmac + + Here's how the standard face @code{highlight} is defined: + +@example +(defface highlight + '((((class color) (min-colors 88) (background light)) + :background "darkseagreen2") + (((class color) (min-colors 88) (background dark)) + :background "darkolivegreen") + (((class color) (min-colors 16) (background light)) + :background "darkseagreen2") + (((class color) (min-colors 16) (background dark)) + :background "darkolivegreen") + (((class color) (min-colors 8)) + :background "green" :foreground "black") + (t :inverse-video t)) + "Basic face for highlighting." + :group 'basic-faces) +@end example + + Internally, Emacs stores the face's default specification in its +@code{face-defface-spec} symbol property (@pxref{Property Lists}). +The @code{saved-face} property stores the face specification saved by +the user, using the customization buffer; the @code{customized-face} +property stores the face specification customized for the current +session, but not saved; and the @code{theme-face} property stores an +alist associating the active customization settings and Custom themes +with their specifications for that face. The face's documentation +string is stored in the @code{face-documentation} property. But +normally you should not try to set any of these properties directly. +@xref{Applying Customizations}, for the @code{custom-set-faces} +function, which is used to apply customized face settings. + + People are sometimes tempted to create variables whose values +specify a face to use. In the vast majority of cases, this is not +necessary; it is preferable to simply use faces directly. + @node Attribute Functions @subsection Face Attribute Functions This section describes the functions for accessing and modifying the -attributes of an existing face. +attributes of an existing named face. @defun set-face-attribute face frame &rest arguments This function sets one or more attributes of @var{face} for @@ -2467,8 +2478,12 @@ This function returns the @code{:inverse-video} attribute of face @var{face}. @node Displaying Faces @subsection Displaying Faces - Here is how Emacs determines the face to use for displaying any -given piece of text: + When Emacs displays a given piece of text, the visual appearance of +the text may be determined by faces drawn from different sources. If +these various sources together specify more than one face for a +particular character, Emacs merges the attributes of the various +faces. Here is the order in which Emacs merges the faces, from +highest to lowest priority: @itemize @bullet @item @@ -2482,11 +2497,11 @@ Manual}. @item If the text lies within an overlay with a non-@code{nil} @code{face} -property, Emacs applies the face or face attributes specified by that -property. If the overlay has a @code{mouse-face} property and the -mouse is ``near enough'' to the overlay, Emacs applies the face or -face attributes specified by the @code{mouse-face} property instead. -@xref{Overlay Properties}. +property, Emacs applies the face(s) specified by that property. If +the overlay has a @code{mouse-face} property and the mouse is ``near +enough'' to the overlay, Emacs applies the face or face attributes +specified by the @code{mouse-face} property instead. @xref{Overlay +Properties}. When multiple overlays cover one character, an overlay with higher priority overrides those with lower priority. @xref{Overlays}. @@ -2508,11 +2523,12 @@ If any given attribute has not been specified during the preceding steps, Emacs applies the attribute of the @code{default} face. @end itemize - If these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various faces -specified. For each attribute, Emacs tries using the above order -(i.e.@: first the face of any special glyph; then the face for region -highlighting, if appropriate; and so on). + At each stage, if a face has a valid @code{:inherit} attribute, +Emacs treats any attribute with an @code{unspecified} value as having +the corresponding value drawn from the parent face(s). @pxref{Face +Attributes}. Note that the parent face(s) may also leave the +attribute unspecified; in that case, the attribute remains unspecified +at the next level of face merging. @node Face Remapping @subsection Face Remapping diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index caa5185dec3..db770616820 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1366,8 +1366,8 @@ Overlays Faces -* Defining Faces:: How to define a face. * Face Attributes:: What is in a face? +* Defining Faces:: How to define a face. * Attribute Functions:: Functions to examine and set face attributes. * Displaying Faces:: How Emacs combines the faces specified for a character. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index fe7f24e42cd..a5910ea921b 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2999,12 +2999,11 @@ can be the following: A face name (a symbol or string). @item -A property list of face attributes. This has the -form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a -face attribute name and @var{value} is a meaningful value for that -attribute. With this feature, you do not need to create a face each -time you want to specify a particular attribute for certain text. -@xref{Face Attributes}. +A property list of face attributes. This has the form (@var{keyword} +@var{value} @dots{}), where each @var{keyword} is a face attribute +name and @var{value} is a meaningful value for that attribute. With +this feature, you do not need to create a face each time you want to +specify a particular attribute for certain text. @item A list of faces. This specifies a face which is an aggregate of the diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index c5b66757ace..1c0abcb8e66 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -403,7 +403,8 @@ unconditionally initializes the variable, whereas @code{defvar} initializes it only if it is originally void. To define a customizable variable, you should use @code{defcustom} -(which calls @code{defvar} as a subroutine). @xref{Customization}. +(which calls @code{defvar} as a subroutine). @xref{Variable +Definitions}. @defspec defvar symbol [value [doc-string]] This special form defines @var{symbol} as a variable. Note that diff --git a/lisp/ChangeLog b/lisp/ChangeLog index c1c9e5ee1c8..7ed5f6af14b 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,9 @@ +2012-09-18 Chong Yidong + + * custom.el (defface): Doc fix. + + * cus-edit.el (custom-unlispify-remove-prefixes): Add warning. + 2012-09-18 Martin Blais (tiny change) * progmodes/compile.el (compilation-start): Use compilation-always-kill diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el index 86a19131569..2e6f2b14625 100644 --- a/lisp/cus-edit.el +++ b/lisp/cus-edit.el @@ -526,7 +526,10 @@ WIDGET is the widget to apply the filter entries of MENU on." :type 'boolean) (defcustom custom-unlispify-remove-prefixes nil - "Non-nil means remove group prefixes from option names in buffer." + "Non-nil means remove group prefixes from option names in buffer. +Discarding prefixes often leads to confusing names for options +and faces in Customize buffers, so do not set this to a non-nil +value unless you are sure you know what it does." :group 'custom-menu :group 'custom-buffer :type 'boolean) diff --git a/lisp/custom.el b/lisp/custom.el index 01b0e6d1650..dfc8e631152 100644 --- a/lisp/custom.el +++ b/lisp/custom.el @@ -350,68 +350,62 @@ FACE does not need to be quoted. Third argument DOC is the face documentation. -If FACE has been set with `custom-set-faces', set the face attributes -as specified by that function, otherwise set the face attributes -according to SPEC. - -The remaining arguments should have the form - - [KEYWORD VALUE]... +If FACE has been set with `custom-set-faces', set the face +attributes as specified by that function, otherwise set the face +attributes according to SPEC. +The remaining arguments should have the form [KEYWORD VALUE]... For a list of valid keywords, see the common keywords listed in `defcustom'. -SPEC should be an alist of the form ((DISPLAY ATTS)...). - -In the first element, DISPLAY can be `default'. The ATTS in that -element then act as defaults for all the following elements. - -Aside from that, DISPLAY specifies conditions to match some or -all frames. For each frame, the first element of SPEC where the -DISPLAY conditions are satisfied is the one that applies to that -frame. The ATTRs in this element take effect, and the following -elements are ignored, on that frame. - -In the last element, DISPLAY can be t. That element applies to a -frame if none of the previous elements (except the `default' if -any) did. - -ATTS is a list of face attributes followed by their values: - (ATTR VALUE ATTR VALUE...) - -The possible attributes are `:family', `:width', `:height', `:weight', -`:slant', `:underline', `:overline', `:strike-through', `:box', -`:foreground', `:background', `:stipple', `:inverse-video', and `:inherit'. - -DISPLAY can be `default' (only in the first element), the symbol -t (only in the last element) to match all frames, or an alist of -conditions of the form \(REQ ITEM...). For such an alist to -match a frame, each of the conditions must be satisfied, meaning -that the REQ property of the frame must match one of the -corresponding ITEMs. These are the defined REQ values: - -`type' (the value of `window-system') - Under X, in addition to the values `window-system' can take, - `motif', `lucid', `gtk' and `x-toolkit' are allowed, and match when - the Motif toolkit, Lucid toolkit, GTK toolkit or any X toolkit is in use. - -`class' (the frame's color support) - Should be one of `color', `grayscale', or `mono'. - -`background' (what color is used for the background text) - Should be one of `light' or `dark'. - -`min-colors' (the minimum number of colors the frame should support) - Should be an integer, it is compared with the result of - `display-color-cells'. - -`supports' (only match frames that support the specified face attributes) - Should be a list of face attributes. See the documentation for - the function `display-supports-face-attributes-p' for more - information on exactly how testing is done. - -See Info node `(elisp) Customization' in the Emacs Lisp manual -for more information." +SPEC should be an alist of the form + + ((DISPLAY . ATTS)...) + +where DISPLAY is a form specifying conditions to match certain +terminals and ATTS is a property list (ATTR VALUE ATTR VALUE...) +specifying face attributes and values for frames on those +terminals. On each terminal, the first element with a matching +DISPLAY specification takes effect, and the remaining elements in +SPEC are disregarded. + +As a special exception, in the first element of SPEC, DISPLAY can +be the special value `default'. Then the ATTS in that element +act as defaults for all the following elements. + +For backward compatibility, elements of SPEC can be written +as (DISPLAY ATTS) instead of (DISPLAY . ATTS). + +Each DISPLAY can have the following values: + - `default' (only in the first element). + - The symbol t, which matches all terminals. + - An alist of conditions. Each alist element must have the form + (REQ ITEM...). A matching terminal must satisfy each + specified condition by matching one of its ITEMs. Each REQ + must be one of the following: + - `type' (the terminal type). + Each ITEM must be one of the values returned by + `window-system'. Under X, additional allowed values are + `motif', `lucid', `gtk' and `x-toolkit'. + - `class' (the terminal's color support). + Each ITEM should be one of `color', `grayscale', or `mono'. + - `background' (what color is used for the background text) + Each ITEM should be one of `light' or `dark'. + - `min-colors' (the minimum number of supported colors) + Each ITEM should be an integer, which is compared with the + result of `display-color-cells'. + - `supports' (match terminals supporting certain attributes). + Each ITEM should be a list of face attributes. See + `display-supports-face-attributes-p' for more information on + exactly how testing is done. + +In the ATTS property list, possible attributes are `:family', +`:width', `:height', `:weight', `:slant', `:underline', +`:overline', `:strike-through', `:box', `:foreground', +`:background', `:stipple', `:inverse-video', and `:inherit'. + +See Info node `(elisp) Faces' in the Emacs Lisp manual for more +information." (declare (doc-string 3)) ;; It is better not to use backquote in this file, ;; because that makes a bootstrapping problem -- 2.39.2