@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2000, 2001, 2004
+@c 2000, 2001, 2004, 2005
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@end smallexample
@end deffn
-@deffn Command just-one-space
+@deffn Command just-one-space &optional n
@comment !!SourceFile simple.el
This command replaces any spaces and tabs around point with a single
-space. It returns @code{nil}.
+space, or @var{n} spaces if @var{n} is specified. It returns
+@code{nil}.
@end deffn
@deffn Command delete-blank-lines
(put-text-property @var{beg} @var{end} @var{property} @var{value})
@end example
+@item (apply @var{funname} . @var{args})
+This kind of element records a change that can be undone by evaluating
+(@code{apply} @var{funname} @var{args}).
+
+@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
+This kind of element records a change that can be undone by evaluating
+(@code{apply} @var{funname} @var{args}). The integer values @var{beg}
+and @var{end} is buffer positions of the range affected by this change
+and @var{delta} is an integer value which is the number of bytes added
+or deleted in that range by this change. This kind of element
+enables undo limited to a region to determine whether the element
+pertains to that region.
+
@item (@var{marker} . @var{adjustment})
This kind of element records the fact that the marker @var{marker} was
relocated due to deletion of surrounding text, and that it moved
@end deffn
@deffn Command buffer-disable-undo &optional buffer-or-name
-@deffnx Command buffer-flush-undo &optional buffer-or-name
@cindex disable undo
This function discards the undo list of @var{buffer-or-name}, and disables
further recording of undo information. As a result, it is no longer
has no effect.
This function returns @code{nil}.
-
-The name @code{buffer-flush-undo} is not considered obsolete, but the
-preferred name is @code{buffer-disable-undo}.
@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
them back to size limits you can set. (For this purpose, the ``size''
of an undo list measures the cons cells that make up the list, plus the
-strings of deleted text.) Two variables control the range of acceptable
-sizes: @code{undo-limit} and @code{undo-strong-limit}.
+strings of deleted text.) Three variables control the range of acceptable
+sizes: @code{undo-limit}, @code{undo-strong-limit} and
+@code{undo-outer-limit}.
-@defvar undo-limit
+@defopt undo-limit
This is the soft limit for the acceptable size of an undo list. The
change group at which this size is exceeded is the last one kept.
-@end defvar
+@end defopt
-@defvar undo-strong-limit
+@defopt undo-strong-limit
This is the upper limit for the acceptable size of an undo list. The
change group at which this size is exceeded is discarded itself (along
with all older change groups). There is one exception: the very latest
-change group is never discarded no matter how big it is.
-@end defvar
+change group is only discarded if it exceeds @code{undo-outer-limit}.
+@end defopt
+
+@defopt undo-outer-limit
+If at garbage collection time the undo info for the current command
+exceeds this limit, Emacs discards the info and displays a warning.
+This is a last ditch limit to prevent memory overflow.
+@end defopt
@node Filling
@comment node-name, next, previous, up
avoid breaking the line at such a place.
@end defopt
+@defopt sentence-end-without-period
+If this variable is non-@code{nil}, a sentence can end without a
+period. This is used for languages like Thai, where sentences end
+with a double space but without a period.
+@end defopt
+
+@defopt sentence-end-without-space
+If this variable is non-@code{nil}, it should be a string of
+characters that can end a sentence without following spaces.
+@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
@end defvar
@defvar 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 function. This function is
-called during filling, with no arguments and with point located at the
-place where a break is being considered. If the function returns
-non-@code{nil}, then the line won't be broken there.
+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, but a
+single function is also supported for compatibility. 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
@node Adaptive Fill
@deffn Command sort-numeric-fields field start end
This command sorts lines in the region between @var{start} and
-@var{end}, comparing them numerically by the @var{field}th field of each
-line. The specified field must contain a number in each line of the
-region. Fields are separated by whitespace and numbered starting from
-1. If @var{field} is negative, sorting is by the
-@w{@minus{}@var{field}th} field from the end of the line. This command
-is useful for sorting tables.
+@var{end}, comparing them numerically by the @var{field}th field of
+each line. Fields are separated by whitespace and numbered starting
+from 1. The specified field must contain a number in each line of the
+region. Numbers starting with 0 are treated as octal, and numbers
+starting with @samp{0x} are treated as hexadecimal.
+
+If @var{field} is negative, sorting is by the
+@w{@minus{}@var{field}th} field from the end of the line. This
+command is useful for sorting tables.
@end deffn
+@defopt sort-numeric-base
+This variable specifies the default radix for
+@code{sort-numeric-fields} to parse numbers.
+@end defopt
+
@deffn Command sort-columns reverse &optional beg end
This command sorts the lines in the region between @var{beg} and
-@var{end}, comparing them alphabetically by a certain range of columns.
-The column positions of @var{beg} and @var{end} bound the range of
-columns to sort on.
+@var{end}, comparing them alphabetically by a certain range of
+columns. The column positions of @var{beg} and @var{end} bound the
+range of columns to sort on.
If @var{reverse} is non-@code{nil}, the sort is in reverse order.
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
-* Enabling Mouse-1 to Follow Links::
- How to make @key{mouse-1} follow a link.
+* 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
@end defun
@defun remove-list-of-text-properties start end list-of-properties &optional object
-Like @code{remove-list-properties} except that
+Like @code{remove-text-properties} except that
@var{list-of-properties} is a list property names only, not an
-alternating list of property values.
+alternating list of property names and values.
@end defun
@defun set-text-properties start end props &optional object
property; rather, it is implemented in Font Lock mode using
@code{char-property-alias-alist}. @xref{Examining Properties}.
-This property is new in Emacs 21.4.
+This property is new in Emacs 22.1.
@item mouse-face
@kindex mouse-face @r{(text property)}
If the value of the @code{help-echo} property is a function, that
function is called with three arguments, @var{window}, @var{object} and
-@var{position} and should return a help string or @var{nil} for
+@var{pos} and should return a help string or @code{nil} for
none. The first argument, @var{window} is the window in which
the help was found. The second, @var{object}, is the buffer, overlay or
-string which had the @code{help-echo} property. The @var{position}
+string which had the @code{help-echo} property. The @var{pos}
argument is as follows:
@itemize @bullet{}
@item hard
If a newline character has this property, it is a ``hard'' newline.
The fill commands do not alter hard newlines and do not move words
-across them. However, this property takes effect only if the variable
-@code{use-hard-newlines} is non-@code{nil}.
+across them. However, this property takes effect only if the
+@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@item right-margin
This property specifies an extra right margin for filling this part of the
global definition) remains available for the rest of the text in the
buffer.
-@node Enabling Mouse-1 to Follow Links
-@subsection Enabling Mouse-1 to Follow Links
+@node Links and Mouse-1
+@subsection Links and Mouse-1
@cindex follow links
-
- Traditionally, Emacs uses a @key{mouse-1} click to set point and a
-@key{mouse-2} click to follow a link, whereas most other applications
-use a @key{mouse-1} click for both purposes, depending on whether you
-click outside or inside a link.
-
- Starting with Emacs release 21.4, the user visible behaviour of a
-@key{mouse-1} click on a link has been changed to match this
-context-sentitive dual behaviour. The user can customize this
-behaviour through the variable @code{mouse-1-click-follows-link}.
-
- However, at the Lisp level, @key{mouse-2} is still used as the
-action for the clickable text corresponding to the link, and the
-clickable text must be explicitly marked as a link for a @key{mouse-1}
-click to follow the link.
-
- There are several methods that can be used to identify a clickable
-text as a link:
+@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 behaviour 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 follow-link property
-
- If the clickable text has a non-nil @code{follow-link} text or overlay
-property, the value of that property determines what to do.
+@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 follow-link event
+@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
- If there is a binding for the @code{follow-link} event, either on
-the clickable text or in the local keymap, the binding of that event
-determines whether the mouse click position is inside a link:
+ 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.
@table @asis
-@item mouse-face
+@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 binding is @code{mouse-face}, the mouse click position is
-inside a link if there is a non-nil @code{mouse-face} property at
-that position. A value of @code{t} is used to determine what to do next.
-
-For example, here is how @key{mouse-1} are setup in info mode:
+For example, here is how Info mode handles @key{Mouse-1}:
@example
(define-key Info-mode-map [follow-link] 'mouse-face)
@end example
@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 binding is a function, @var{func}, the mouse click position,
-@var{pos}, is inside a link if the call @code{(@var{func} @var{pos})}
-returns non-@code{nil}. The return value from that call determines
-what to do next.
-
-For example, here is how pcvs enables @key{mouse-1} on file names only:
+For example, here is how pcvs enables @key{Mouse-1} to follow links on
+file names only:
@example
(define-key map [follow-link]
(if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
@end example
-@item anthing else
-
- If the binding is anything else, the binding determines what to do.
-@end table
-
+@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.
@end table
@noindent
-The resulting value determined above is interpreted as follows:
+The action code tells @key{Mouse-1} how to follow the link:
@table @asis
-@item a string
-
- If the value is a string, the @key{mouse-1} event is translated into
-the first character of the string, i.e. the action of the @key{mouse-1}
-click is the local or global binding of that character.
-
-@item a vector
+@item a string or vector
+If the action code is a string or vector, the @key{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
+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}.
+
+@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.
+@end table
- If the value is is a vector, the @key{mouse-1} event is translated
-into the first element of that vector, i.e. the action of the
-@key{mouse-1} click is the local or global binding of that event.
+ To define @key{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}:
-@item anthing else
+@smallexample
+(define-button-type 'help-xref
+ 'follow-link t
+ 'action #'help-button-action)
+@end smallexample
- For any other non-nil valule, the @key{mouse-1} event is translated
-into a @key{mouse-2} event at the same position.
-@end table
+ 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.
- To use @key{mouse-1} on 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 the @code{link} widget specifies that
+a @key{Mouse-1} click shall be translated to @key{RET}:
- To use @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.
+@smallexample
+(define-widget 'link 'item
+ "An embedded link."
+ :button-prefix 'widget-link-prefix
+ :button-suffix 'widget-link-suffix
+ :follow-link "\C-m"
+ :help-echo "Follow the link."
+ :format "%[%t%]")
+@end smallexample
@defun mouse-on-link-p pos
@tindex mouse-on-link-p
-Return non-@code{nil} if @var{pos} is on a link in the current buffer.
+This function returns non-@code{nil} if position @var{pos} in the
+current buffer is on a link.
@end defun
@node Fields
described above in this section, as well as the hooks attached to
certain special text properties (@pxref{Special Properties}) and overlay
properties (@pxref{Overlay Properties}).
-
-This variable is available starting in Emacs 21.
@end defvar
@ignore
HCoop / bpt / emacs.git / blobdiff