@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, 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
@deffn Command yank &optional arg
@cindex inserting killed text
-This command inserts before point the text at the front of the
-kill ring. It positions the mark at the beginning of that text, and
-point at the end.
+This command inserts before point the text at the front of the kill
+ring. It sets the mark at the beginning of that text, using
+@code{push-mark} (@pxref{The Mark}), and puts point at the end.
If @var{arg} is a non-@code{nil} list (which occurs interactively when
the user types @kbd{C-u} with no digits), then @code{yank} inserts the
text as described above, but puts point before the yanked text and
-puts the mark after it.
+sets the mark after it.
If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
most recently killed text---the @var{arg}th element of the kill ring
@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
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
-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
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 hook is to set the window system's primary
-selection (and first cut buffer) from the newly killed text.
+The normal use of this function is to set the window system's primary
+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
@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
-Interactively, when @var{region} is non-@code{nil} in Transient Mark
-mode and the mark is active, this command calls @code{fill-region}
-on the active region.
+
+When @var{region} is non-@code{nil}, then if Transient Mark mode is
+enabled and the mark is active, this command calls @code{fill-region}
+to fill all the paragraphs in the region, instead of filling only the
+current paragraph. When this command is called interactively,
+@var{region} is @code{t}.
@end deffn
@deffn Command fill-region start end &optional justify nosqueeze to-eop
@end defopt
@defvar fill-paragraph-function
-This variable provides a way for major modes to override the filling of
-paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
-this function to do the work. If the function returns a non-@code{nil}
+This variable provides a way to override the filling of paragraphs.
+If its value is non-@code{nil}, @code{fill-paragraph} calls this
+function to do the work. If the function returns a non-@code{nil}
value, @code{fill-paragraph} assumes the job is done, and immediately
returns that value.
@end example
@end defvar
+@defvar fill-forward-paragraph-function
+This variable provides a way to override how the filling functions,
+such as @code{fill-region} and @code{fill-paragraph}, move forward to
+the next paragraph. Its value should be a function, which is called
+with a single argument @var{n}, the number of paragraphs to move, and
+should return the difference between @var{n} and the number of
+paragraphs actually moved. The default value of this variable is
+@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
+Manual}.
+@end defvar
+
@defvar use-hard-newlines
If this variable is non-@code{nil}, the filling functions do not delete
newlines that have the @code{hard} text property. These ``hard
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.
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
-* Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
* 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
@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 old,
+deprecated equivalents for @code{(:foreground @var{color-name})} and
+@code{(:background @var{color-name})}. Please convert code that uses
+them.
@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)}
-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}.
-
-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-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.
-This property is new in Emacs 22.1.
+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)}
@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)}
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
@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text
+@cindex follow links
+@cindex mouse-1
@dfn{Clickable text} is text that can be clicked, with either the
-the mouse or via keyboard commands, to produce some result. Many
-major modes use clickable text to implement features such as
-hyper-links. The @code{button} package provides an easy way to insert
-and manipulate clickable text. @xref{Buttons}.
-
- In this section, we will explain how to manually set up clickable
-text in a buffer using text properties. This involves two things: (1)
-indicating clickability when the mouse moves over the text, and (2)
-making @kbd{RET} or a mouse click on that text do something.
-
- Indicating clickability usually involves highlighting the text, and
-often involves displaying helpful information about the action, such
-as which mouse button to press, or a short summary of the action.
-This can be done with the @code{mouse-face} and @code{help-echo}
-text properties. @xref{Special Properties}.
-Here is an example of how Dired does it:
+mouse or via a keyboard command, to produce some result. Many major
+modes use clickable text to implement textual hyper-links, or
+@dfn{links} for short.
+
+ The easiest way to insert and manipulate links is to use the
+@code{button} package. @xref{Buttons}. In this section, we will
+explain how to manually set up clickable text in a buffer, using text
+properties. For simplicity, we will refer to the clickable text as a
+@dfn{link}.
+
+ Implementing a link involves three separate steps: (1) indicating
+clickability when the mouse moves over the link; (2) making @kbd{RET}
+or @kbd{Mouse-2} on that link do something; and (3) setting up a
+@code{follow-link} condition so that the link obeys
+@code{mouse-1-click-follows-link}.
+
+ To indicate clickability, add the @code{mouse-face} text property to
+the text of the link; then Emacs will highlight the link when the
+mouse moves over it. In addition, you should define a tooltip or echo
+area message, using the @code{help-echo} text property. @xref{Special
+Properties}. For instance, here is how Dired indicates that file
+names are clickable:
@smallexample
-(condition-case nil
- (if (dired-move-to-filename)
- (add-text-properties
- (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- '(mouse-face highlight
- help-echo "mouse-2: visit this file in other window")))
- (error nil))
+ (if (dired-move-to-filename)
+ (add-text-properties
+ (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ '(mouse-face highlight
+ help-echo "mouse-2: visit this file in other window")))
@end smallexample
-@noindent
-The first two arguments to @code{add-text-properties} specify the
-beginning and end of the text.
-
- The usual way to make the mouse do something when you click it
-on this text is to define @code{mouse-2} in the major mode's
-keymap. The job of checking whether the click was on clickable text
-is done by the command definition. Here is how Dired does it:
+ To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
+commands that perform the desired action. Each command should check
+to see whether it was called on a link, and act accordingly. For
+instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
+following command:
@smallexample
(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 smallexample
@noindent
-The reason for the @code{save-excursion} construct is to avoid
-changing the current buffer. In this case,
-Dired uses the functions @code{posn-window} and @code{posn-point}
-to determine which buffer the click happened in and where, and
-in that buffer, @code{dired-get-file-for-visit} to determine which
-file to visit.
+This command uses the functions @code{posn-window} and
+@code{posn-point} to determine where the click occurred, and
+@code{dired-get-file-for-visit} to determine which file to visit.
- Instead of defining a mouse command for the major mode, you can define
-a key binding for the clickable text itself, using the @code{keymap}
-text property:
+ Instead of binding the mouse command in a major mode keymap, you can
+bind it within the link text, using the @code{keymap} text property
+(@pxref{Special Properties}). For instance:
@example
(let ((map (make-sparse-keymap)))
(define-key map [mouse-2] 'operate-this-button)
- (put-text-property (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- 'keymap map))
+ (put-text-property link-start link-end 'keymap map))
@end example
@noindent
-This method makes it possible to define different commands for various
-clickable pieces of text. Also, the major mode definition (or the
-global definition) remains available for the rest of the text in the
-buffer.
-
-@node Links and Mouse-1
-@subsection Links and Mouse-1
-@cindex follow links
-@cindex mouse-1
-
- The normal Emacs command for activating text in read-only buffers is
-@key{Mouse-2}, which includes following textual links. However, most
-graphical applications use @key{Mouse-1} for following links. For
-compatibility, @key{Mouse-1} follows links in Emacs too, when you
-click on a link quickly without moving the mouse. The user can
-customize this behavior through the variable
-@code{mouse-1-click-follows-link}.
-
- To define text as a link at the Lisp level, you should bind the
-@code{mouse-2} event to a command to follow the link. Then, to indicate that
-@key{Mouse-1} should also follow the link, you should specify a
-@code{follow-link} condition either as a text property or as a key
-binding:
-
-@table @asis
-@item @code{follow-link} property
-If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
-property, that specifies the condition.
-
-@item @code{follow-link} event
-If there is a binding for the @code{follow-link} event, either on the
-clickable text or in the local keymap, the binding is the condition.
-@end table
-
- Regardless of how you set the @code{follow-link} condition, its
-value is used as follows to determine whether the given position is
-inside a link, and (if so) to compute an @dfn{action code} saying how
-@key{Mouse-1} should handle the link.
+With this method, you can easily define different commands for
+different links. Furthermore, the global definition of @key{RET} and
+@kbd{Mouse-2} remain available for the rest of the text in the buffer.
+
+@vindex mouse-1-click-follows-link
+ The basic Emacs command for clicking on links is @kbd{Mouse-2}.
+However, for compatibility with other graphical applications, Emacs
+also recognizes @kbd{Mouse-1} clicks on links, provided the user
+clicks on the link quickly without moving the mouse. This behavior is
+controlled by the user option @code{mouse-1-click-follows-link}.
+@xref{Mouse References,,, emacs, The GNU Emacs Manual}.
+
+ To set up the link so that it obeys
+@code{mouse-1-click-follows-link}, you must either (1) apply a
+@code{follow-link} text or overlay property to the link text, or (2)
+bind the @code{follow-link} event to a keymap (which can be a major
+mode keymap or a local keymap specified via the @code{keymap} text
+property). The value of the @code{follow-link} property, or the
+binding for the @code{follow-link} event, acts as a ``condition'' for
+the link action. This condition tells Emacs two things: the
+circumstances under which a @kbd{Mouse-1} click should be regarded as
+occurring ``inside'' the link, and how to compute an ``action code''
+that says what to translate the @kbd{Mouse-1} click into. The link
+action condition can be one of the following:
@table @asis
@item @code{mouse-face}
-If the condition is @code{mouse-face}, a position is inside a link if
-there is a non-@code{nil} @code{mouse-face} property at that position.
-The action code is always @code{t}.
+If the condition is the symbol @code{mouse-face}, a position is inside
+a link if there is a non-@code{nil} @code{mouse-face} property at that
+position. The action code is always @code{t}.
For example, here is how Info mode handles @key{Mouse-1}:
@end smallexample
@item a function
-If the condition is a valid function, @var{func}, then a position
-@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
-to non-@code{nil}. The value returned by @var{func} serves as the
-action code.
+If the condition is a function, @var{func}, then a position @var{pos}
+is inside a link if @code{(@var{func} @var{pos})} evaluates to
+non-@code{nil}. The value returned by @var{func} serves as the action
+code.
-For example, here is how pcvs enables @key{Mouse-1} to follow links on
+For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
file names only:
@smallexample
@item anything else
If the condition value is anything else, then the position is inside a
-link and the condition itself is the action code. Clearly you should
-only specify this kind of condition on the text that constitutes a
-link.
+link and the condition itself is the action code. Clearly, you should
+specify this kind of condition only when applying the condition via a
+text or property overlay on the link text (so that it does not apply
+to the entire buffer).
@end table
@noindent
-The action code tells @key{Mouse-1} how to follow the link:
+The action code tells @kbd{Mouse-1} how to follow the link:
@table @asis
@item a string or vector
-If the action code is a string or vector, the @key{Mouse-1} event is
+If the action code is a string or vector, the @kbd{Mouse-1} event is
translated into the first element of the string or vector; i.e., the
-action of the @key{Mouse-1} click is the local or global binding of
+action of the @kbd{Mouse-1} click is the local or global binding of
that character or symbol. Thus, if the action code is @code{"foo"},
-@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
-@key{Mouse-1} translates into @key{foo}.
+@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
+@kbd{Mouse-1} translates into @key{foo}.
@item anything else
-For any other non-@code{nil} action code, the @code{mouse-1} event is
-translated into a @code{mouse-2} event at the same position.
+For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
+translated into a @kbd{Mouse-2} event at the same position.
@end table
- To define @key{Mouse-1} to activate a button defined with
+ To define @kbd{Mouse-1} to activate a button defined with
@code{define-button-type}, give the button a @code{follow-link}
-property with a value as specified above to determine how to follow
-the link. For example, here is how Help mode handles @key{Mouse-1}:
+property. The property value should be a link action condition, as
+described above. @xref{Buttons}. For example, here is how Help mode
+handles @kbd{Mouse-1}:
@smallexample
(define-button-type 'help-xref
'action #'help-button-action)
@end smallexample
- To define @key{Mouse-1} on a widget defined with
-@code{define-widget}, give the widget a @code{:follow-link} property
-with a value as specified above to determine how to follow the link.
-
-For example, here is how the @code{link} widget specifies that
+ To define @kbd{Mouse-1} on a widget defined with
+@code{define-widget}, give the widget a @code{:follow-link} property.
+The property value should be a link action condition, as described
+above. For example, here is how the @code{link} widget specifies that
a @key{Mouse-1} click shall be translated to @key{RET}:
@smallexample
@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 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
HCoop / bpt / emacs.git / blobdiff