X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/2c302df3a13236bfbf8ea1b771d13618fcda8d71..4c0078d4ab7fa8c234fa8098ec3a9686199edbff:/doc/lispref/text.texi diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 45d358366d..2348e3706d 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-2011 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/text @node Text, Non-ASCII Characters, Markers, Top @@ -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. @@ -2203,11 +2200,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 @@ -2808,9 +2805,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 @@ -2980,8 +2977,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 @@ -2994,17 +2990,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 @@ -3012,20 +3001,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 @@ -3274,15 +3268,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 @@ -3295,15 +3302,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 @@ -4097,17 +4095,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: @@ -4136,12 +4133,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