@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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@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
undo individual replacements one by one.
@end defun
+@defvar undo-in-progress
+This variable is normally @code{nil}, but the undo commands bind it to
+@code{t}. This is so that various kinds of change hooks can tell when
+they're being called for the sake of undoing.
+@end defvar
+
@defun primitive-undo count list
This is the basic function for undoing elements of an undo list.
It undoes the first @var{count} elements of @var{list}, returning
undo operations use and update the saved value. The new elements added
by undoing are not part of this saved value, so they don't interfere with
continuing to undo.
+
+This function does not bind @code{undo-in-progress}.
@end defun
@node Maintaining Undo
@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
@end defun
@defopt sentence-end-double-space
+@anchor{Definition of sentence-end-double-space}
If this variable is non-@code{nil}, a period followed by just one space
does not count as the end of a sentence, and the filling functions
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.
+* 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
A face name (a symbol or string).
@item
-Starting in Emacs 21, a property list of face attributes. This has the
+A property list of face attributes. This has the
form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
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
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{}
A newline can have a @code{line-spacing} text or overlay property that
controls the height of the display line ending with that newline. The
property value overrides the default frame line spacing and the buffer
-local @code{line-spacing} variable. We will call the property value
-@var{line-spacing}.
-
-If @var{line-spacing} is a positive integer, the value specifies
-additional vertical space, below the display line, in pixels.
-
-If @var{line-spacing} is a floating point number or cons, the
-additional vertical space is the product of @var{line-spacing} and the
-default frame line height.
-
-If the @var{line-spacing} value is a cons @code{(total .
-@var{spacing})} where @var{spacing} is any of the forms described
-above, the value of @var{spacing} specifies the total displayed height
-of the line, regardless of the height of the characters in it. This
-is equivalent to using the @code{line-height} property.
+local @code{line-spacing} variable. @xref{Line Height}.
@item line-height
@kindex line-height @r{(text property)}
A newline can have a @code{line-height} text or overlay property that
controls the total height of the display line ending in that newline.
-We will call the property value @var{line-height}.
-
-If @var{line-height} is 0, the height of the line is determined solely
-from its contents; nothing is added. Any @code{line-spacing} property
-on this newline is ignored. This case is useful for tiling small
-images or image slices without adding blank areas between the images.
-
-If @var{line-height} is a positive integer, the value specifies the
-minimum line height in pixels. The line's ascent height is
-increased as necessary to achieve the specified height.
-
-If @var{line-height} is a floating point number, the minimum line
-height is the product of @var{line-height} and the default frame line
-height.
-
-If @var{line-height} is a cons @code{(@var{ratio} . @var{face})}, the
-minimum line height is calculated as @var{ratio} times the height of
-face @var{face}. The @var{ratio} is an integer or a floating point
-number. If @var{face} is @code{t}, it refers to the current face.
+@xref{Line Height}.
@item modification-hooks
@cindex change hooks for a character
@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 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 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 @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.
+
+@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}.
+
+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.
+
+For example, here is how pcvs enables @key{Mouse-1} to follow links on
+file names only:
+
+@example
+(define-key map [follow-link]
+ (lambda (pos)
+ (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
+@end example
+
+@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 action code tells @key{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
+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
+
+ 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}:
+
+@smallexample
+(define-button-type 'help-xref
+ 'follow-link t
+ '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
+a @key{Mouse-1} click shall be translated to @key{RET}:
+
+@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
+This function returns non-@code{nil} if position @var{pos} in the
+current buffer is on a link.
+@end defun
+
@node Fields
@subsection Defining and Using Fields
@cindex fields
This function applies a translation table to the characters in the
buffer between positions @var{start} and @var{end}.
-The translation table @var{table} is a string; @code{(aref @var{table}
-@var{ochar})} gives the translated character corresponding to
-@var{ochar}. If the length of @var{table} is less than 256, any
+The translation table @var{table} is a string or a char-table;
+@code{(aref @var{table} @var{ochar})} gives the translated character
+corresponding to @var{ochar}. If @var{table} is a string, any
characters with codes larger than the length of @var{table} are not
altered by the translation.
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