@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/text
@node Text, Non-ASCII Characters, Markers, Top
* The Kill Ring:: Where removed text sometimes is saved for later use.
* Undo:: Undoing changes to the text of a buffer.
* Maintaining Undo:: How to enable and disable undo information.
- How to control how much information is kept.
+ How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context.
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
* Kill Functions:: Functions that kill text.
* Yanking:: How yanking is done.
* Yank Commands:: Commands that access the kill ring.
-* Low-Level Kill Ring:: Functions and variables for kill ring access.
+* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill ring data.
@end menu
@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
command stops at such a boundary, and successive undo commands undo
to earlier and earlier boundaries. This function returns @code{nil}.
-The editor command loop automatically creates an undo boundary before
-each key sequence is executed. Thus, each undo normally undoes the
-effects of one command. Self-inserting input characters are an
-exception. The command loop makes a boundary for the first such
-character; the next 19 consecutive self-inserting input characters do
-not make boundaries, and then the 20th does, and so on as long as
-self-inserting characters continue.
+The editor command loop automatically calls @code{undo-boundary} just
+before executing each key sequence, so that each undo normally undoes
+the effects of one command. As an exception, the command
+@code{self-insert-command}, which produces self-inserting input
+characters (@pxref{Commands for Insertion}), may remove the boundary
+inserted by the command loop: a boundary is accepted for the first
+such character, the next 19 consecutive self-inserting input
+characters do not have boundaries, and then the 20th does; and so on
+as long as the self-inserting characters continue. Hence, sequences
+of consecutive character insertions can be undone as a group.
All buffer modifications add a boundary whenever the previous undoable
change was made in some other buffer. This is to ensure that
read, you should set @code{fill-column} to no more than 70. Otherwise
the line will be too long for people to read comfortably, and this can
make the text seem clumsy.
-@end defopt
-
-@defvar default-fill-column
-The value of this variable is the default value for @code{fill-column} in
-buffers that do not override it. This is the same as
-@code{(default-value 'fill-column)}.
-The default value for @code{default-fill-column} is 70.
-@end defvar
+The default value for @code{fill-column} is 70.
+@end defopt
@deffn Command set-left-margin from to margin
This sets the @code{left-margin} property on the text from @var{from} to
is value of @code{indent-line-function} in Paragraph-Indent Text mode.
@end defun
-@defvar left-margin
+@defopt left-margin
This variable specifies the base left margin column. In Fundamental
mode, @kbd{C-j} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
-@end defvar
+@end defopt
-@defvar fill-nobreak-predicate
+@defopt fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line
at certain places. Its value should be a list of functions. Whenever
filling considers breaking the line at a certain place in the buffer,
it calls each of these functions with no arguments and with point
located at that place. If any of the functions returns
non-@code{nil}, then the line won't be broken there.
-@end defvar
+@end defopt
@node Adaptive Fill
@section Adaptive Fill Mode
@code{count-lines} in @ref{Text Lines}.
@end defun
-@defun move-to-column column &optional force
+@deffn Command move-to-column column &optional force
This function moves point to @var{column} in the current line. The
calculation of @var{column} takes into account the widths of the
displayed representations of the characters between the start of the
line and point.
-If column @var{column} is beyond the end of the line, point moves to the
-end of the line. If @var{column} is negative, point moves to the
+When called interactively, @var{column} is the value of prefix numeric
+argument. If @var{column} is not an integer, an error is signaled.
+
+If column @var{column} is beyond the end of the line, point moves to
+the end of the line. If @var{column} is negative, point moves to the
beginning of the line.
If it is impossible to move to column @var{column} because that is in
enough to reach column @var{column}; if it is @code{t}, that means to
add whitespace at the end of the line to reach that column.
-If @var{column} is not an integer, an error is signaled.
-
The return value is the column number actually moved to.
-@end defun
+@end deffn
@node Indentation
@section Indentation
indent the current line in a way appropriate for the current major mode.
@end deffn
-@deffn Command indent-for-tab-command
-This command calls the function in @code{indent-line-function} to indent
-the current line; however, if that function is
-@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
-is a trivial command that inserts a tab character.)
+@deffn Command indent-for-tab-command &optional rigid
+This command calls the function in @code{indent-line-function} to
+indent the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead.
+(That is a trivial command that inserts a tab character.) If
+@var{rigid} is non-@code{nil}, this function also rigidly indents the
+entire balanced expression that starts at the beginning of the current
+line, to reflect change in indentation of the current line.
@end deffn
@deffn Command newline-and-indent
-@comment !!SourceFile simple.el
This function inserts a newline, then indents the new line (the one
following the newline just inserted) according to the major mode.
This section describes commands that indent all the lines in the
region. They return unpredictable values.
-@deffn Command indent-region start end to-column
+@deffn Command indent-region start end &optional to-column
This command indents each nonblank line starting between @var{start}
(inclusive) and @var{end} (exclusive). If @var{to-column} is
@code{nil}, @code{indent-region} indents each nonblank line by calling
@end defvar
@deffn Command indent-rigidly start end count
-@comment !!SourceFile indent.el
This command indents all lines starting between @var{start}
(inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
This ``preserves the shape'' of the affected region, moving it as a
replied to.
@end deffn
-@defun indent-code-rigidly start end columns &optional nochange-regexp
+@deffn Command indent-code-rigidly start end columns &optional nochange-regexp
This is like @code{indent-rigidly}, except that it doesn't alter lines
that start within strings or comments.
In addition, it doesn't alter a line if @var{nochange-regexp} matches at
the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
-@end defun
+@end deffn
@node Relative Indent
@subsection Indentation Relative to Previous Lines
@menu
* Examining Properties:: Looking at the properties of one character.
-* Changing Properties:: Setting the properties of a range of text.
-* Property Search:: Searching for where a property changes value.
-* Special Properties:: Particular properties with special meanings.
+* Changing Properties:: Setting the properties of a range of text.
+* Property Search:: Searching for where a property changes value.
+* Special Properties:: Particular properties with special meanings.
* Format Properties:: Properties for representing formatting of text.
* Sticky Properties:: How inserted text gets properties from
neighboring text.
do something when you click on them.
* Fields:: The @code{field} property defines
fields within the buffer.
-* Not Intervals:: Why text properties do not use
- Lisp-visible text intervals.
+* Not Intervals:: Why text properties do not use
+ Lisp-visible text intervals.
@end menu
@node Examining Properties
@item
A cons cell with the form @code{(foreground-color . @var{color-name})}
-or @code{(background-color . @var{color-name})}. These are older,
+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.
property when Font Lock mode is enabled. 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
+The @code{font-lock-face} property is useful for special modes that
implement their own highlighting. @xref{Precalculated Fontification}.
@item mouse-face
@item cursor
@kindex cursor @r{(text property)}
Normally, the cursor is displayed at the end of any overlay and text
-property strings present at the current window position. You can
+property strings present at the current buffer position. You can
place the cursor on any desired character of these strings by giving
-that character a non-@code{nil} @var{cursor} text property.
+that character a non-@code{nil} @code{cursor} text property. In
+addition, if the value of the @code{cursor} property of an overlay
+string is an integer number, it specifies the number of buffer's
+character positions associated with the overlay string; this way,
+Emacs will display the cursor on the character with that property
+regardless of whether the current buffer position is actually covered
+by the overlay. Specifically, if the value of the @code{cursor}
+property of a character is the number @var{n}, the cursor will be
+displayed on this character for any buffer position in the range
+@code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the
+starting buffer position covered by the overlay (@pxref{Managing
+Overlays}).
@item pointer
@kindex pointer @r{(text property)}
(defun dired-mouse-find-file-other-window (event)
"In Dired, visit the file or directory name you click on."
(interactive "e")
- (let (window pos file)
- (save-excursion
- (setq window (posn-window (event-end event))
- pos (posn-point (event-end event)))
- (if (not (windowp window))
- (error "No file chosen"))
- (set-buffer (window-buffer window))
+ (let ((window (posn-window (event-end event)))
+ (pos (posn-point (event-end event)))
+ file)
+ (if (not (windowp window))
+ (error "No file chosen"))
+ (with-current-buffer (window-buffer window)
(goto-char pos)
(setq file (dired-get-file-for-visit)))
(if (file-directory-p file)
@end example
@end defun
-@defun translate-region start end table
+@deffn Command translate-region start end table
This function applies a translation table to the characters in the
buffer between positions @var{start} and @var{end}.
characters that were actually changed by the translation. This does
not count characters that were mapped into themselves in the
translation table.
-@end defun
+@end deffn
@node Registers
@section Registers
This command displays what is contained in register @var{reg}.
@end deffn
-@ignore
-@deffn Command point-to-register reg
-This command stores both the current location of point and the current
-buffer in register @var{reg} as a marker.
-@end deffn
-
-@deffn Command jump-to-register reg
-@deffnx Command register-to-point reg
-@comment !!SourceFile register.el
-This command restores the status recorded in register @var{reg}.
-
-If @var{reg} contains a marker, it moves point to the position stored in
-the marker. Since both the buffer and the location within the buffer
-are stored by the @code{point-to-register} function, this command can
-switch you to another buffer.
-
-If @var{reg} contains a window configuration or a frame configuration.
-@code{jump-to-register} restores that configuration.
-@end deffn
-@end ignore
-
@deffn Command insert-register reg &optional beforep
This command inserts contents of register @var{reg} into the current
buffer.
changed in the future.
@end deffn
-@ignore
-@deffn Command copy-to-register reg start end &optional delete-flag
-This command copies the region from @var{start} to @var{end} into
-register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
-the region from the buffer after copying it into the register.
-@end deffn
-
-@deffn Command prepend-to-register reg start end &optional delete-flag
-This command prepends the region from @var{start} to @var{end} into
-register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes
-the region from the buffer after copying it to the register.
-@end deffn
-
-@deffn Command append-to-register reg start end &optional delete-flag
-This command appends the region from @var{start} to @var{end} to the
-text already in register @var{reg}. If @var{delete-flag} is
-non-@code{nil}, it deletes the region from the buffer after copying it
-to the register.
-@end deffn
-
-@deffn Command copy-rectangle-to-register reg start end &optional delete-flag
-This command copies a rectangular region from @var{start} to @var{end}
-into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it
-deletes the region from the buffer after copying it to the register.
-@end deffn
-
-@deffn Command window-configuration-to-register reg
-This function stores the window configuration of the selected frame in
-register @var{reg}.
-@end deffn
-
-@deffn Command frame-configuration-to-register reg
-This function stores the current frame configuration in register
-@var{reg}.
-@end deffn
-@end ignore
-
@node Transposition
@section Transposition of Text
}2045. This section describes the functions for
converting to and from this code.
-@defun base64-encode-region beg end &optional no-line-break
+@deffn Command base64-encode-region beg end &optional no-line-break
This function converts the region from @var{beg} to @var{end} into base
64 code. It returns the length of the encoded text. An error is
signaled if a character in the region is multibyte, i.e.@: in a
text, to avoid overlong lines. However, if the optional argument
@var{no-line-break} is non-@code{nil}, these newlines are not added, so
the output is just one long line.
-@end defun
+@end deffn
-@defun base64-encode-string string &optional no-line-break
+@deffn Command base64-encode-string string &optional no-line-break
This function converts the string @var{string} into base 64 code. It
returns a string containing the encoded text. As for
@code{base64-encode-region}, an error is signaled if a character in the
text, to avoid overlong lines. However, if the optional argument
@var{no-line-break} is non-@code{nil}, these newlines are not added, so
the result string is just one long line.
-@end defun
+@end deffn
@defun base64-decode-region beg end
This function converts the region from @var{beg} to @var{end} from base
coding instead.
@end defun
+@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.
+
+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.
+
+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.
+
@node Atomic Changes
@section Atomic Change Groups
@cindex atomic changes