@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
position stored in a register.
* Base 64:: Conversion to or from base 64 encoding.
* MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
+* Parsing HTML:: Parsing HTML and XML.
* Atomic Changes:: Installing several buffer changes "atomically".
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@example
@group
-(char-to-string (char-after 1))
+(string (char-after 1))
@result{} "@@"
@end group
@end example
@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
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.
@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}.
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
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
@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
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
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
@defvar interprogram-cut-function
This variable provides a way of communicating killed text to other
programs, when you are using a window system. Its value should be
-@code{nil} or a function of one required and one optional argument.
+@code{nil} or a function of one required argument.
If the value is a function, @code{kill-new} and @code{kill-append} call
-it with the new first element of the kill ring as the first argument.
-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.
+it with the new first element of the kill ring as the argument.
The normal use of this function is to set the window system's primary
-selection (and first cut buffer) from the newly killed text.
+selection from the newly killed text.
@xref{Window System Selections}.
@end defvar
@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
@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
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
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
@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-mode} 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
@cindex hooks for changing a character
@kindex modification-hooks @r{(text property)}
If a character has the property @code{modification-hooks}, then its
-value should be a list of functions; modifying that character calls all
-of those functions. Each function receives two arguments: the beginning
-and end of the part of the buffer being modified. Note that if a
-particular modification hook function appears on several characters
-being modified by a single primitive, you can't predict how many times
-the function will be called.
+value should be a list of functions; modifying that character calls
+all of those functions before the actual modification. Each function
+receives two arguments: the beginning and end of the part of the
+buffer being modified. Note that if a particular modification hook
+function appears on several characters being modified by a single
+primitive, you can't predict how many times the function will
+be called.
+Furthermore, insertion will not modify any existing character, so this
+hook will only be run when removing some characters, replacing them
+with others, or changing their text-properties.
If these functions modify the buffer, they should bind
@code{inhibit-modification-hooks} to @code{t} around doing so, to
@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
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
coding instead.
@end defun
+@node Parsing HTML
+@section Parsing HTML
+@cindex parsing html
+
+@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.
+
+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:
+
+@example
+<html><hEad></head><body width=101><div class=thing>Foo<div>Yes
+@end example
+
+You get this parse tree:
+
+@example
+(html
+ (head)
+ (body
+ (:width . "101")
+ (div
+ (:class . "thing")
+ (text . "Foo")
+ (div
+ (text . "Yes\n")))))
+@end example
+
+It's a simple tree structure, where the @code{car} for each node is
+the name of the node, and the @code{cdr} is the value, or the list of
+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
@code{inhibit-modification-hooks} to @code{nil}.
@end defvar
-@ignore
- arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
-@end ignore
+