(Completion Styles): New node.

[gnu-emacs] / doc / lispref / text.texi

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 5b935bc6e23c536d8601c3a301bf26373b2d038c..72a2feda6831034835624db80021a2802811f260 100644 (file)
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,

-@c   2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/text
 @node Text, Non-ASCII Characters, Markers, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/text
 @node Text, Non-ASCII Characters, Markers, Top


@@ -1057,12 +1057,14 @@ If @var{n} is zero, indicating a request for the latest kill,
 @code{current-kill} calls the value of
 @code{interprogram-paste-function} (documented below) before
 consulting the kill ring.  If that value is a function and calling it
 @code{current-kill} calls the value of
 @code{interprogram-paste-function} (documented below) before
 consulting the kill ring.  If that value is a function and calling it

-returns a string, @code{current-kill} pushes that string onto the kill
-ring and returns it.  It also sets the yanking pointer to point to
-that new entry, regardless of the value of @var{do-not-move}.
-Otherwise, @code{current-kill} does not treat a zero value for @var{n}
-specially: it returns the entry pointed at by the yanking pointer and
-does not move the yanking pointer.
+returns a string or a list of several string, @code{current-kill}
+pushes the strings onto the kill ring and returns the first string.
+It also sets the yanking pointer to point to the kill-ring entry of
+the first string returned by @code{interprogram-paste-function},
+regardless of the value of @var{do-not-move}.  Otherwise,
+@code{current-kill} does not treat a zero value for @var{n} specially:
+it returns the entry pointed at by the yanking pointer and does not
+move the yanking pointer.

 @end defun
 
 @defun kill-new string &optional replace yank-handler
 @end defun
 
 @defun kill-new string &optional replace yank-handler


@@ -1105,9 +1107,19 @@ If the value is a function, @code{current-kill} calls it to get the
 then that value is used as the ``most recent kill.''  If it returns
 @code{nil}, then the front of the kill ring is used.
 
 then that value is used as the ``most recent kill.''  If it returns
 @code{nil}, then the front of the kill ring is used.
 

-The normal use of this hook is to get the window system's primary
+To facilitate support for window systems that support multiple
+selections, this function may also return a list of strings.  In that
+case, the first string is used as the ``most recent kill'', and all
+the other strings are pushed onto the kill ring, for easy access by
+@code{yank-pop}.
+
+The normal use of this function is to get the window system's primary

 selection as the most recent kill, even if the selection belongs to
 selection as the most recent kill, even if the selection belongs to

-another application.  @xref{Window System Selections}.
+another application.  @xref{Window System Selections}.  However, if
+the selection was provided by the current Emacs session, this function
+should return @code{nil}.  (If it is hard to tell whether Emacs or
+some other program provided the selection, it should be good enough to
+use @code{string=} to compare it with the last text Emacs provided.)

 @end defvar
 
 @defvar interprogram-cut-function
 @end defvar
 
 @defvar interprogram-cut-function


@@ -1121,7 +1133,7 @@ The second, optional, argument has the same meaning as the @var{push}
 argument to @code{x-set-cut-buffer} (@pxref{Definition of
 x-set-cut-buffer}) and only affects the second and later cut buffers.
 
 argument to @code{x-set-cut-buffer} (@pxref{Definition of
 x-set-cut-buffer}) and only affects the second and later cut buffers.
 

-The normal use of this hook is to set the window system's primary
+The normal use of this function is to set the window system's primary

 selection (and first cut buffer) from the newly killed text.
 @xref{Window System Selections}.
 @end defvar
 selection (and first cut buffer) from the newly killed text.
 @xref{Window System Selections}.
 @end defvar


@@ -2990,31 +3002,28 @@ time you want to specify a particular attribute for certain text.
 @xref{Face Attributes}.
 
 @item
 @xref{Face Attributes}.
 
 @item

-A cons cell with the form @code{(foreground-color . @var{color-name})} or
-@code{(background-color . @var{color-name})}.  These elements specify
-just the foreground color or just the background color.  @xref{Color
-Names}, for the supported forms of @var{color-name}.
-
-A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to
-specifying @code{(:foreground @var{color-name})}; likewise for the
-background.
+A cons cell with the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}.  These are older,
+deprecated equivalents for @code{(:foreground @var{color-name})} and
+@code{(:background @var{color-name})}.  Please convert code that uses
+them.

 @end itemize
 
 @end itemize
 

-You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
-update @code{face} properties based on the contents of the text.
+It works to use the latter two forms directly as the value
+of the @code{face} property.
+
+Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
+dynamically updating the @code{face} property of characters based on
+the context.

 
 @item font-lock-face
 @kindex font-lock-face @r{(text property)}
 
 @item font-lock-face
 @kindex font-lock-face @r{(text property)}

-The @code{font-lock-face} property is the same in all respects as the
-@code{face} property, but its state of activation is controlled by
-@code{font-lock-mode}.  This can be advantageous for special buffers
-which are not intended to be user-editable, or for static areas of
-text which are always fontified in the same way.
-@xref{Precalculated Fontification}.
+The @code{font-lock-face} property is equivalent to the @code{face}
+property when Font Lock mode is enabled.  When Font Lock mode is disabled,
+@code{font-lock-face} has no effect.

 
 

-Strictly speaking, @code{font-lock-face} is not a built-in text
-property; rather, it is implemented in Font Lock mode using
-@code{char-property-alias-alist}.  @xref{Examining Properties}.
+The @code{font-lock-mode} property is useful for special modes that
+implement their own highlighting.  @xref{Precalculated Fontification}.

 
 This property is new in Emacs 22.1.
 
 
 This property is new in Emacs 22.1.
 


@@ -3173,6 +3182,29 @@ A newline can have a @code{line-height} text or overlay property that
 controls the total height of the display line ending in that newline.
 @xref{Line Height}.
 
 controls the total height of the display line ending in that newline.
 @xref{Line Height}.
 

+@item wrap-prefix
+If text has a @code{wrap-prefix} property, the prefix it defines will
+be added at display-time to the beginning of every continuation line
+due to text wrapping (so if lines are truncated, the wrap-prefix is
+never used).  It may be a string, an image, or a stretch-glyph such as
+used by the @code{display} text-property.  @xref{Display Property}.
+
+A wrap-prefix may also be specified for an entire buffer using the
+@code{wrap-prefix} buffer-local variable (however, a
+@code{wrap-prefix} text-property takes precedence over the value of
+the @code{wrap-prefix} variable).  @xref{Truncation}.
+
+@item line-prefix
+If text has a @code{line-prefix} property, the prefix it defines will
+be added at display-time to the beginning of every non-continuation
+line.  It may be a string, an image, or a stretch-glyph such as used
+by the @code{display} text-property.  @xref{Display Property}.
+
+A line-prefix may also be specified for an entire buffer using the
+@code{line-prefix} buffer-local variable (however, a
+@code{line-prefix} text-property takes precedence over the value of
+the @code{line-prefix} variable).  @xref{Truncation}.
+

 @item modification-hooks
 @cindex change hooks for a character
 @cindex hooks for changing a character
 @item modification-hooks
 @cindex change hooks for a character
 @cindex hooks for changing a character


@@ -3634,7 +3666,7 @@ a @key{Mouse-1} click shall be translated to @key{RET}:
 @defun mouse-on-link-p pos
 This function returns non-@code{nil} if position @var{pos} in the
 current buffer is on a link.  @var{pos} can also be a mouse event
 @defun mouse-on-link-p pos
 This function returns non-@code{nil} if position @var{pos} in the
 current buffer is on a link.  @var{pos} can also be a mouse event

-location, as returned by @code{event-start} (@pxref{Accessing Events}).
+location, as returned by @code{event-start} (@pxref{Accessing Mouse}).

 @end defun
 
 @node Fields
 @end defun
 
 @node Fields