From: Chong Yidong Date: Tue, 30 Aug 2011 15:24:07 +0000 (-0400) Subject: Document new Emacs 24 faces in Lisp manual. X-Git-Tag: emacs-pretest-24.0.90~104^2~152^2~30 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=35137ed3a511d8e27e8fb07f506f55d76e2f6e0f;p=emacs.git Document new Emacs 24 faces in Lisp manual. * doc/lispref/display.texi (Basic Faces): New node. Document new faces. * doc/lispref/modes.texi (Major Mode Conventions): Move some text there. (Mode Help): Remove major-mode var, duplicated in Major Modes. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 57dde5ac4cb..37689c16e59 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2011-08-30 Chong Yidong + + * display.texi (Basic Faces): New node. Document new faces. + + * modes.texi (Major Mode Conventions): Move some text there. + (Mode Help): Remove major-mode var, duplicated in Major Modes. + 2011-08-29 Chong Yidong * modes.texi (Basic Major Modes): New node. Callers updated. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index cfe4b8298fb..68291319ef1 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1833,9 +1833,10 @@ particular face name a special meaning in one frame if you wish. * Face Attributes:: What is in 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. +* Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. @@ -2687,6 +2688,62 @@ For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call. @end defvar +@node Basic Faces +@subsection Basic Faces + +If your Emacs Lisp program needs to assign some faces to text, it is +often a good idea to use certain existing faces or inherit from them, +rather than defining entirely new faces. This way, if other users +have customized the basic faces to give Emacs a certain look, your +program will ``fit in'' without additional customization. + + Some of the basic faces defined in Emacs are listed below. In +addition to these, you might want to make use of the Font Lock faces +for syntactic highlighting, if highlighting is not already handled by +Font Lock mode, or if some Font Lock faces are not in use. +@xref{Faces for Font Lock}. + +@table @code +@item default +The default face, whose attributes are all specified. All other faces +implicitly inherit from it: any unspecified attribute defaults to the +attribute on this face (@pxref{Face Attributes}). + +@item bold +@itemx italic +@itemx bold-italic +@itemx underline +@itemx fixed-pitch +@itemx variable-pitch +These have the attributes indicated by their names (e.g. @code{bold} +has a bold @code{:weight} attribute), with all other attributes +unspecified (and so given by @code{default}). + +@item shadow +For ``dimmed out'' text. For example, it is used for the ignored +part of a filename in the minibuffer (@pxref{Minibuffer File,, +Minibuffers for File Names, emacs, The GNU Emacs Manual}). + +@item link +@itemx link-visited +For clickable text buttons that send the user to a different +buffer or ``location''. + +@item highlight +For stretches of text that should temporarily stand out. For example, +it is commonly assigned to the @code{mouse-face} property for cursor +highlighting (@pxref{Special Properties}). + +@item match +For text matching a search command. + +@item error +@itemx warning +@itemx success +For text concerning errors, warnings, or successes. For example, +these are used for messages in @samp{*Compilation*} buffers. +@end table + @node Font Selection @subsection Font Selection diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a19af903027..bcf6d3318ef 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1308,6 +1308,7 @@ Faces * Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 586fc0bbbfb..eb81ebc4acb 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -225,9 +225,9 @@ several major modes, in files such as @file{text-mode.el}, study these libraries to see how modes are written. @defopt major-mode -The buffer-local value of this variable is a symbol naming the buffer's -current major mode. Its default value holds the default major mode for -new buffers. The standard default value is @code{fundamental-mode}. +The buffer-local value of this variable holds the symbol for the current +major mode. Its default value holds the default major mode for new +buffers. The standard default value is @code{fundamental-mode}. If the default value is @code{nil}, then whenever Emacs creates a new buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the @@ -403,28 +403,7 @@ setting up a buffer-local value for the variable @item Each face that the mode defines should, if possible, inherit from an -existing Emacs face. This reduces the chance of conflicting with a -user's face customizations. Useful faces include: - -@table @asis -@item @code{highlight} -for stretches of text that should temporarily stand out. - -@item @code{match} -for text matching a search command. - -@item @code{link} and @code{link-visited} -for clickable text buttons that send the user to a different buffer or -``location''. - -@item @code{button} -for clickable text buttons that perform other actions. - -@item @asis{Font Lock faces} -for other kinds of syntactic highlighting, if highlighting is not -handled by Font Lock mode or some Font Lock faces are not in use. -@xref{Faces for Font Lock}, for how to assign Font Lock faces. -@end table +existing Emacs face. @xref{Basic Faces}, and @ref{Faces for Font Lock}. @item The mode should specify how Imenu should find the definitions or @@ -702,8 +681,8 @@ init file.) The @code{describe-mode} function is provides information about major modes. It is normally bound to @kbd{C-h m}. It uses the value of the -variable @code{major-mode} (which is why every major mode command needs -to set this variable). +variable @code{major-mode} (@pxref{Major Modes}), which is why every +major mode command needs to set that variable. @deffn Command describe-mode This function displays the documentation of the current major mode. @@ -714,14 +693,6 @@ displays the documentation string of the major mode command. (@xref{Accessing Documentation}.) @end deffn -@defvar major-mode -This buffer-local variable holds the symbol for the current buffer's -major mode. This symbol should have a function definition that is the -command to switch to that major mode. The @code{describe-mode} -function uses the documentation string of the function as the -documentation of the major mode. -@end defvar - @node Derived Modes @subsection Defining Derived Modes @cindex derived mode diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index c192e3bf4b7..1275628cc94 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -1329,6 +1329,7 @@ Faces * Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 8e78a5fb5ca..3d849fa2dcf 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -1328,6 +1328,7 @@ Faces * Face Remapping:: Remapping faces to alternative definitions. * Face Functions:: How to define and examine faces. * Auto Faces:: Hook for automatic face assignment. +* Basic Faces:: Faces that are defined by default. * Font Selection:: Finding the best available font for a face. * Font Lookup:: Looking up the names of available fonts and information about them. diff --git a/etc/NEWS b/etc/NEWS index bbaa46c7222..dbeca0b521b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -239,6 +239,7 @@ theme when Emacs is built with GTK. *** Emacs uses GTK tooltips by default if built with GTK. You can turn that off by customizing x-gtk-use-system-tooltips. ++++ ** New basic faces `error', `warning', `success' are available to highlight strings that indicate failure, caution or successful operation.