@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Text
@chapter Text
word on the same line is acceptable.
@end defun
-@defun thing-at-point thing
+@defun thing-at-point thing &optional no-properties
Return the @var{thing} around or next to point, as a string.
The argument @var{thing} is a symbol which specifies a kind of syntactic
@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others.
+When the optional argument @var{no-properties} is non-@code{nil}, this
+function strips text properties from the return value.
+
@example
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
@code{delete-blank-lines} returns @code{nil}.
@end deffn
-@deffn Command delete-trailing-whitespace start end
+@deffn Command delete-trailing-whitespace &optional start end
Delete trailing whitespace in the region defined by @var{start} and
@var{end}.
@defopt left-margin
This variable specifies the base left margin column. In Fundamental
-mode, @kbd{RET} indents to this column. This variable automatically
+mode, @key{RET} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defopt
columns, counting from 0 at the left margin. The column position is the
sum of the widths of all the displayed representations of the characters
between the start of the current line and point.
-
-For an example of using @code{current-column}, see the description of
-@code{count-lines} in @ref{Text Lines}.
@end defun
@deffn Command move-to-column column &optional force
@code{buffer-substring-no-properties}, which copies text from the
buffer but does not copy its properties.
+@findex with-silent-modifications
+ If you wish to add or remove text properties to a buffer without
+marking the buffer as modified, you can wrap the calls above in the
+@code{with-silent-modifications} macro.
+
@node Property Search
@subsection Text Property Search Functions
@cindex searching text properties
@item help-echo
@kindex help-echo @r{(text property)}
-@cindex tooltip
+@cindex tooltip for help strings
@anchor{Text help-echo}
If text has a string as its @code{help-echo} property, then when you
move the mouse onto that text, Emacs displays that string in the echo
-area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs
-Manual}).
+area, or in the tooltip window (@pxref{Tooltips}).
If the value of the @code{help-echo} property is a function, that
function is called with three arguments, @var{window}, @var{object} and
@code{intangible} properties, they belong to separate groups; each
group is separately treated as described above.
-When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
-the @code{intangible} property is ignored.
+When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}
+(as it is by default), the @code{intangible} property is ignored.
Beware: this property operates at a very low level, and affects a lot of code
in unexpected ways. So use it with extreme caution. A common misuse is to put
an intangible property on invisible text, which is actually unnecessary since
the command loop will move point outside of the invisible text at the end of
-each command anyway. @xref{Adjusting Point}.
+each command anyway. @xref{Adjusting Point}. For these reasons, this
+property is obsolete; use the @code{cursor-intangible} property instead.
+
+@item cursor-intangible
+@kindex cursor-intangible @r{(text property)}
+@findex cursor-intangible-mode
+When the minor mode @code{cursor-intangible-mode} is turned on, point
+is moved away of any position that has a non-@code{nil}
+@code{cursor-intangible} property, just before redisplay happens.
@item field
@kindex field @r{(text property)}
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}.
+The variable @code{inhibit-point-motion-hooks} by default inhibits
+running the @code{point-left} and @code{point-entered} hooks, see
+@ref{Inhibit point motion hooks}.
+
+These properties are obsolete; please use
+@code{cursor-sensor-functions} instead.
+
+@item cursor-sensor-functions
+@kindex cursor-sensor-functions @r{(text property)}
+@findex cursor-sensor-mode
+This special property records a list of functions that react to cursor
+motion. Each function in the list is called, just before redisplay,
+with 3 arguments: the affected window, the previous known position of
+the cursor, and one of the symbols @code{entered} or @code{left},
+depending on whether the cursor is entering the text that has this
+property or leaving it. The functions are called only when the minor
+mode @code{cursor-sensor-mode} is turned on.
@item composition
@kindex composition @r{(text property)}
@end table
@defvar inhibit-point-motion-hooks
-@anchor{Inhibit point motion hooks} When this variable is
+@anchor{Inhibit point motion hooks} When this obsolete 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}.
+this variable globally; bind it with @code{let}. Since the affected
+properties are obsolete, this variable's default value is @code{t}, to
+effectively disable them.
@end defvar
@defvar show-help-function
Implementing a link involves three separate steps: (1) indicating
clickability when the mouse moves over the link; (2) making @key{RET}
-or @kbd{Mouse-2} on that link do something; and (3) setting up a
+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}.
help-echo "mouse-2: visit this file in other window")))
@end smallexample
- To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
+ 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
+instance, Dired's major mode keymap binds @kbd{mouse-2} to the
following command:
@smallexample
@noindent
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.
+@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}.
+ 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
+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}.
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
+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
+that says what to translate the @kbd{mouse-1} click into. The link
action condition can be one of the following:
@table @asis
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}:
+For example, here is how Info mode handles @key{mouse-1}:
@smallexample
(define-key Info-mode-map [follow-link] 'mouse-face)
non-@code{nil}. The value returned by @var{func} serves as the action
code.
-For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
+For example, here is how pcvs enables @kbd{mouse-1} to follow links on
file names only:
@smallexample
@end table
@noindent
-The action code tells @kbd{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 @kbd{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 @kbd{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"},
-@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
-@kbd{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 @kbd{Mouse-1} event is
-translated into a @kbd{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 @kbd{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. 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}:
+handles @kbd{mouse-1}:
@smallexample
(define-button-type 'help-xref
'action #'help-button-action)
@end smallexample
- To define @kbd{Mouse-1} on a widget defined with
+ 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}:
+a @key{mouse-1} click shall be translated to @key{RET}:
@smallexample
(define-widget 'link 'item
coding instead.
@end defun
+@defun buffer-hash &optional buffer-or-name
+Return a hash of @var{buffer-or-name}. If @code{nil}, this defaults
+to the current buffer. As opposed to @code{secure-hash}, this
+function computes the hash based on the internal representation of the
+buffer, disregarding any coding systems. It's therefore only useful
+when comparing two buffers running in the same Emacs, and is not
+guaranteed to return the same hash between different Emacs versions.
+It should be somewhat more efficient on larger buffers than
+@code{secure-hash} is, and should not allocate more memory.
+@c Note that we do not document what hashing function we're using, or
+@c even whether it's a cryptographic hash, since that may change
+@c according to what we find useful.
+@end defun
+
@node Parsing HTML/XML
@section Parsing HTML and XML
@cindex parsing html