X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/0c382083b6b550c26fad8ac7f59b1ba09663e728..acaf905b1130aae80fa59d2c861ffd4c8eb75486:/doc/lispref/text.texi diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 04e1e71413..b75c013298 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,8 +1,6 @@ @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, 2008, 2009, 2010 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/text @node Text, Non-ASCII Characters, Markers, Top @@ -87,7 +85,7 @@ buffer is @samp{@@}: @example @group -(char-to-string (char-after 1)) +(string (char-after 1)) @result{} "@@" @end group @end example @@ -122,9 +120,9 @@ but there is no peace. @end group @group -(char-to-string (preceding-char)) +(string (preceding-char)) @result{} "a" -(char-to-string (following-char)) +(string (following-char)) @result{} "c" @end group @end example @@ -366,14 +364,13 @@ after point. Some insertion functions leave point before the inserted text, while other functions leave it after. We call the former insertion @dfn{after point} and the latter insertion @dfn{before point}. - Insertion relocates markers that point at positions after the -insertion point, so that they stay with the surrounding text -(@pxref{Markers}). When a marker points at the place of insertion, -insertion may or may not relocate the marker, depending on the marker's -insertion type (@pxref{Marker Insertion Types}). Certain special -functions such as @code{insert-before-markers} relocate all such markers -to point after the inserted text, regardless of the markers' insertion -type. + Insertion moves markers located at positions after the insertion +point, so that they stay with the surrounding text (@pxref{Markers}). +When a marker points at the place of insertion, insertion may or may +not relocate the marker, depending on the marker's insertion type +(@pxref{Marker Insertion Types}). Certain special functions such as +@code{insert-before-markers} relocate all such markers to point after +the inserted text, regardless of the markers' insertion type. Insertion functions signal an error if the current buffer is read-only or if they insert within read-only text. @@ -866,7 +863,7 @@ adds it to the most recent element. It determines automatically (using @code{last-command}) whether the previous command was a kill command, and if so appends the killed text to the most recent entry. -@deffn Command kill-region start end &optional yank-handler +@deffn Command kill-region start end This function kills the text in the region defined by @var{start} and @var{end}. The text is deleted but saved in the kill ring, along with its text properties. The value is always @code{nil}. @@ -874,17 +871,10 @@ its text properties. The value is always @code{nil}. In an interactive call, @var{start} and @var{end} are point and the mark. -@c Emacs 19 feature If the buffer or text is read-only, @code{kill-region} modifies the kill ring just the same, then signals an error without modifying the buffer. This is convenient because it lets the user use a series of kill commands to copy text from a read-only buffer into the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} text property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any -@code{yank-handler} properties present on the killed text are copied -onto the kill ring, like other text properties. @end deffn @defopt kill-read-only-ok @@ -901,10 +891,10 @@ from the buffer. It returns @code{nil}. The command does not set @code{this-command} to @code{kill-region}, so a subsequent kill command does not append to the same kill ring entry. -Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to -support Emacs 18. For newer Emacs versions, it is better to use -@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill -Ring}. +@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then? +@c Why is it used in many places in Emacs? +In Lisp programs, it is better to use @code{kill-new} or +@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}. @end deffn @node Yanking @@ -917,10 +907,11 @@ text that they copy into the buffer. @defun insert-for-yank string This function normally works like @code{insert} except that it doesn't -insert the text properties in the @code{yank-excluded-properties} -list. However, if any part of @var{string} has a non-@code{nil} -@code{yank-handler} text property, that property can do various -special processing on that part of the text being inserted. +insert the text properties (@pxref{Text Properties}) in the list +variable @code{yank-excluded-properties}. However, if any part of +@var{string} has a non-@code{nil} @code{yank-handler} text property, +that property can do various special processing on that part of the +text being inserted. @end defun @defun insert-buffer-substring-as-yank buf &optional start end @@ -968,6 +959,15 @@ region. @var{function} can set @code{yank-undo-function} to override the @var{undo} value. @end table +@cindex yanking and text properties +@defopt yank-excluded-properties +Yanking discards certain text properties from the yanked text, as +described above. The value of this variable is the list of properties +to discard. Its default value contains properties that might lead to +annoying results, such as causing the text to respond to the mouse or +specifying key bindings. +@end defopt + @node Yank Commands @comment node-name, next, previous, up @subsection Functions for Yanking @@ -1042,8 +1042,8 @@ text property, if there is one. @subsection Low-Level Kill Ring These functions and variables provide access to the kill ring at a -lower level, but still convenient for use in Lisp programs, because they -take care of interaction with window system selections +lower level, but are still convenient for use in Lisp programs, +because they take care of interaction with window system selections (@pxref{Window System Selections}). @defun current-kill n &optional do-not-move @@ -1069,7 +1069,7 @@ 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 +@defun kill-new string &optional replace This function pushes the text @var{string} onto the kill ring and makes the yanking pointer point to it. It discards the oldest entry if appropriate. It also invokes the value of @@ -1078,25 +1078,15 @@ if appropriate. It also invokes the value of If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the first element of the kill ring with @var{string}, rather than pushing @var{string} onto the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then -@code{kill-new} copies any @code{yank-handler} properties present on -@var{string} onto the kill ring, as it does with other text properties. @end defun -@defun kill-append string before-p &optional yank-handler +@defun kill-append string before-p This function appends the text @var{string} to the first entry in the kill ring and makes the yanking pointer point to the combined entry. Normally @var{string} goes at the end of the entry, but if @var{before-p} is non-@code{nil}, it goes at the beginning. This function also invokes the value of @code{interprogram-cut-function} -(see below). This handles @var{yank-handler} just like -@code{kill-new}, except that if @var{yank-handler} is different from -the @code{yank-handler} property of the first entry of the kill ring, -@code{kill-append} pushes the concatenated string onto the kill ring, -instead of replacing the original first entry with it. +(see below). @end defun @defvar interprogram-paste-function @@ -2220,11 +2210,11 @@ The functions in this section return unpredictable values. @defvar indent-line-function This variable's value is the function to be used by @key{TAB} (and various commands) to indent the current line. The command -@code{indent-according-to-mode} does no more than call this function. +@code{indent-according-to-mode} does little more than call this function. In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. -The default value is @code{indent-relative}. +The default value is @code{indent-relative}. @xref{Auto-Indentation}. @end defvar @deffn Command indent-according-to-mode @@ -2825,9 +2815,9 @@ construct each part with @code{propertize} and then combine them with @end smallexample @end defun - See also the function @code{buffer-substring-no-properties} -(@pxref{Buffer Contents}) which copies text from the buffer -but does not copy its properties. + @xref{Buffer Contents}, for the function +@code{buffer-substring-no-properties}, which copies text from the +buffer but does not copy its properties. @node Property Search @subsection Text Property Search Functions @@ -2997,8 +2987,7 @@ character. You can use the property @code{face} to control the font and color of text. @xref{Faces}, for more information. -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities; +@code{face} can be the following: @itemize @bullet @item @@ -3011,17 +3000,10 @@ 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}. - -@item -A cons cell with the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. These are old, -deprecated equivalents for @code{(:foreground @var{color-name})} and -@code{(:background @var{color-name})}. Please convert code that uses -them. @end itemize -It works to use the latter two forms directly as the value -of the @code{face} property. +@code{face} can also be a list, where each element uses one of the +forms listed above. Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by dynamically updating the @code{face} property of characters based on @@ -3029,20 +3011,25 @@ the context. @item font-lock-face @kindex font-lock-face @r{(text property)} -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, +This property specifies a value for the @code{face} property that Font +Lock mode should apply to the underlying text. It is one of the +fontification methods used by Font Lock mode, and is useful for +special modes that implement their own highlighting. +@xref{Precalculated Fontification}. When Font Lock mode is disabled, @code{font-lock-face} has no effect. -The @code{font-lock-face} property is useful for special modes that -implement their own highlighting. @xref{Precalculated Fontification}. - @item mouse-face @kindex mouse-face @r{(text property)} -The property @code{mouse-face} is used instead of @code{face} when the -mouse is on or near the character. For this purpose, ``near'' means -that all text between the character and where the mouse is have the same +This property is used instead of @code{face} when the mouse is on or +near the character. For this purpose, ``near'' means that all text +between the character and where the mouse is have the same @code{mouse-face} property value. +Emacs ignores all face attributes from the @code{mouse-face} property +that alter the text size (e.g. @code{:height}, @code{:weight}, and +@code{:slant}). Those attributes are always the same as for the +unhighlighted text. + @item fontified @kindex fontified @r{(text property)} This property says whether the text is ready for display. If @@ -3158,6 +3145,12 @@ group is separately treated as described above. When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, the @code{intangible} property is ignored. +Beware: this property operates at a very low level, and affects a lot of code +in unexpected ways. So use it with extreme caution. A common misuse is to put +an intangible property on invisible text, which is actually unnecessary since +the command loop will move point outside of the invisible text at the end of +each command anyway. @xref{Adjusting Point}. + @item field @kindex field @r{(text property)} Consecutive characters with the same @code{field} property constitute a @@ -3204,10 +3197,12 @@ controls the total height of the display line ending in that newline. @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 +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}. +never used). It may be a string or an image (@pxref{Other Display +Specs}), or a stretch of whitespace such as specified by the +@code{:width} or @code{:align-to} display properties (@pxref{Specified +Space}). A wrap-prefix may also be specified for an entire buffer using the @code{wrap-prefix} buffer-local variable (however, a @@ -3216,9 +3211,11 @@ 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}. +be added at display time to the beginning of every non-continuation +line. It may be a string or an image (@pxref{Other Display +Specs}), or a stretch of whitespace such as specified by the +@code{:width} or @code{:align-to} display properties (@pxref{Specified +Space}). A line-prefix may also be specified for an entire buffer using the @code{line-prefix} buffer-local variable (however, a @@ -3291,15 +3288,28 @@ functions (which may be the same function). In any case, all the @code{point-left} functions are called first, followed by all the @code{point-entered} functions. -It is possible with @code{char-after} to examine characters at various +It is possible to use @code{char-after} to examine characters at various buffer positions without moving point to those positions. Only an actual change in the value of point runs these hook functions. +The variable @code{inhibit-point-motion-hooks} can inhibit running the +@code{point-left} and @code{point-entered} hooks, see @ref{Inhibit +point motion hooks}. + +@item composition +@kindex composition @r{(text property)} +This text property is used to display a sequence of characters as a +single glyph composed from components. But the value of the property +itself is completely internal to Emacs and should not be manipulated +directly by, for instance, @code{put-text-property}. + +@end table + @defvar inhibit-point-motion-hooks -When this variable is non-@code{nil}, @code{point-left} and -@code{point-entered} hooks are not run, and the @code{intangible} -property has no effect. Do not set this variable globally; bind it with -@code{let}. +@anchor{Inhibit point motion hooks} When this variable is +non-@code{nil}, @code{point-left} and @code{point-entered} hooks are +not run, and the @code{intangible} property has no effect. Do not set +this variable globally; bind it with @code{let}. @end defvar @defvar show-help-function @@ -3312,15 +3322,6 @@ string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs Manual}) provides an example. @end defvar -@item composition -@kindex composition @r{(text property)} -This text property is used to display a sequence of characters as a -single glyph composed from components. But the value of the property -itself is completely internal to Emacs and should not be manipulated -directly by, for instance, @code{put-text-property}. - -@end table - @node Format Properties @subsection Formatted Text Properties @@ -3771,7 +3772,7 @@ Additionally, if two fields are separated by another field with the special value @code{boundary}, then any point within this special field is also considered to be ``on the boundary.'' -Commands like @kbd{C-a} with no argumemt, that normally move backward +Commands like @kbd{C-a} with no argument, that normally move backward to a specific kind of location and stay there once there, probably should specify @code{nil} for @var{escape-from-edge}. Other motion commands that check fields should probably pass @code{t}. @@ -4114,17 +4115,16 @@ coding instead. @node Parsing HTML @section Parsing HTML @cindex parsing html -@cindex parsing xml -Emacs provides an interface to the @code{libxml2} library via two -functions: @code{html-parse-buffer} and @code{xml-parse-buffer}. The -HTML function will parse ``real world'' HTML and try to return a -sensible parse tree, while the XML function is somewhat stricter about -syntax. +@defun libxml-parse-html-region start end &optional base-url +This function provides HTML parsing via the @code{libxml2} library. +It parses ``real world'' HTML and tries to return a sensible parse tree +regardless. -They both take a two optional parameter. The first is a buffer, and -the second is a base URL to be used to expand relative URLs in the -document, if any. +In addition to @var{start} and @var{end} (specifying the start and end +of the region to act on), it takes an optional parameter, +@var{base-url}, which is used to expand relative URLs in the document, +if any. Here's an example demonstrating the structure of the parsed data you get out. Given this HTML document: @@ -4153,12 +4153,21 @@ values. Attributes are coded the same way as child nodes, but with @samp{:} as the first character. +@end defun + +@cindex parsing xml +@defun libxml-parse-xml-region start end &optional base-url + +This is much the same as @code{libxml-parse-html-region} above, but +operates on XML instead of HTML, and is correspondingly stricter about +syntax. +@end defun @node Atomic Changes @section Atomic Change Groups @cindex atomic changes - In data base terminology, an @dfn{atomic} change is an indivisible + In database terminology, an @dfn{atomic} change is an indivisible change---it can succeed entirely or it can fail entirely, but it cannot partly succeed. A Lisp program can make a series of changes to one or several buffers as an @dfn{atomic change group}, meaning that @@ -4323,7 +4332,3 @@ If you do want modification hooks to be run in a particular piece of code that is itself run from a modification hook, then rebind locally @code{inhibit-modification-hooks} to @code{nil}. @end defvar - -@ignore - arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b -@end ignore