buffer. This is similar to @code{(char-after (point))}. However, if
point is at the end of the buffer, then @code{following-char} returns 0.
-Remember that point is always between characters, and the terminal
-cursor normally appears over the character following point. Therefore,
-the character returned by @code{following-char} is the character the
+Remember that point is always between characters, and the cursor
+normally appears over the character following point. Therefore, the
+character returned by @code{following-char} is the character the
cursor is over.
In this example, point is between the @samp{a} and the @samp{c}.
is the numeric prefix argument.
@end deffn
-@deffn Command split-line
-This command splits the current line, moving the portion of the line
-after point down vertically so that it is on the next line directly
-below where it was before. Whitespace is inserted as needed at the
-beginning of the lower line, using the @code{indent-to} function.
-@code{split-line} returns the position of point.
-
-Programs hardly ever use this function.
-@end deffn
-
@defvar overwrite-mode
This variable controls whether overwrite mode is in effect. The value
should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
@comment node-name, next, previous, up
@subsection Functions for Yanking
- @dfn{Yanking} means reinserting an entry of previously killed text
-from the kill ring. The text properties are copied too.
+ This section describes higher-level commands for yanking, which are
+intended primarily for the user but useful also in Lisp programs.
+Both @code{yank} and @code{yank-pop} honor the
+@code{yank-excluded-properties} variable and @code{yank-handler} text
+property (@pxref{Yanking}).
@deffn Command yank &optional arg
@cindex inserting killed text
to the buffer's text so that they can be undone. (The buffers that
don't have one are usually special-purpose buffers for which Emacs
assumes that undoing is not useful. In particular, any buffer whose
-name begins with a space has its undo recording off by default,
+name begins with a space has its undo recording off by default;
see @ref{Buffer Names}.) All the primitives that modify the
text in the buffer automatically add elements to the front of the undo
list, which is in the variable @code{buffer-undo-list}.
@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
-the rest of @var{list}. You could write this function in Lisp,
-but it is convenient to have it in C.
+the rest of @var{list}.
@code{primitive-undo} adds elements to the buffer's undo list when it
changes the buffer. Undo commands avoid confusion by saving the undo
of an undo list measures the cons cells that make up the list, plus the
strings of deleted text.) Three variables control the range of acceptable
sizes: @code{undo-limit}, @code{undo-strong-limit} and
-@code{undo-outer-limit}.
+@code{undo-outer-limit}. In these variables, size is counted as the
+number of bytes occupied, which includes both saved text and other
+data.
@defopt undo-limit
This is the soft limit for the acceptable size of an undo list. The
This is a last ditch limit to prevent memory overflow.
@end defopt
+@defopt undo-ask-before-discard
+If this variable is non-@code{nil}, when the undo info exceeds
+@code{undo-outer-limit}, Emacs asks in the echo area whether to
+discard the info. The default value is @code{nil}, which means to
+discard it automatically.
+
+This option is mainly intended for debugging. Garbage collection is
+inhibited while the question is asked, which means that Emacs might
+leak memory if the user waits too long before answering the question.
+@end defopt
+
@node Filling
@comment node-name, next, previous, up
@section Filling
between paragraphs are removed. This function justifies as well as
filling when @var{justify} is non-@code{nil}.
-In an interactive call, any prefix argument requests justification.
-
If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
other than line breaks untouched. If @var{squeeze-after} is
non-@code{nil}, it specifies a position in the region, and means don't
@defun current-justification
This function returns the proper justification style to use for filling
the text around point.
+
+This returns the value of the @code{justification} text property at
+point, or the variable @var{default-justification} if there is no such
+text property. However, it returns @code{nil} rather than @code{none}
+to mean ``don't justify''.
@end defun
@defopt sentence-end-double-space
@section Margins for Filling
@defopt fill-prefix
-This buffer-local variable specifies a string of text that appears at
-the beginning
-of normal text lines and should be disregarded when filling them. Any
-line that fails to start with the fill prefix is considered the start of
-a paragraph; so is any line that starts with the fill prefix followed by
-additional whitespace. Lines that start with the fill prefix but no
-additional whitespace are ordinary text lines that can be filled
-together. The resulting filled lines also start with the fill prefix.
+This buffer-local variable, if non-@code{nil}, specifies a string of
+text that appears at the beginning of normal text lines and should be
+disregarded when filling them. Any line that fails to start with the
+fill prefix is considered the start of a paragraph; so is any line
+that starts with the fill prefix followed by additional whitespace.
+Lines that start with the fill prefix but no additional whitespace are
+ordinary text lines that can be filled together. The resulting filled
+lines also start with the fill prefix.
The fill prefix follows the left margin whitespace, if any.
@end defopt
@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 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.
+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
@node Adaptive Fill
starting after the left margin whitespace (if any) on a line; the
characters it matches are that line's candidate for the fill prefix.
-@w{@code{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+@w{@code{"[ \t]*\\([-!|#%;>*·•‣⁃◦]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
default value. This matches a number enclosed in parentheses or
followed by a period, or certain punctuation characters, or any
sequence of these intermingled with whitespace. In particular, it
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
- (sort-subr reverse 'forward-line 'end-of-line))))
+ (let ((inhibit-field-text-motion t))
+ (sort-subr reverse 'forward-line 'end-of-line)))))
@end group
@end example
containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.
-Note that @code{sort-columns} uses the @code{sort} utility program,
-and so cannot work properly on text containing tab characters. Use
-@kbd{M-x untabify} to convert tabs to spaces before sorting.
+Note that @code{sort-columns} rejects text that contains tabs, because
+tabs could be split across the specified columns. Use @kbd{M-x
+untabify} to convert tabs to spaces before sorting.
+
+When possible, this command actually works by calling the @code{sort}
+utility program.
@end deffn
@node Columns
affect the display of tab characters in the buffer (@pxref{Usual
Display}). Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.
+@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
@deffn Command tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab
@cindex keymap of character
@kindex keymap @r{(text property)}
The @code{keymap} property specifies an additional keymap for
-commands. The property's value for the character before point applies
-if it is non-@code{nil} and rear-sticky, and the property's value for
-the character after point applies if it is non-@code{nil} and
+commands. When this keymap applies, it is used for key lookup before
+the minor mode keymaps and before the buffer's local map.
+@xref{Active Keymaps}. If the property value is a symbol, the
+symbol's function definition is used as the keymap.
+
+The property's value for the character before point applies if it is
+non-@code{nil} and rear-sticky, and the property's value for the
+character after point applies if it is non-@code{nil} and
front-sticky. (For mouse clicks, the position of the click is used
-instead of the position of point.) If the property value is a symbol,
-the symbol's function definition is used as the keymap.
-
-When this keymap applies, it is used for key lookup before the minor
-mode keymaps and before the buffer's local map. @xref{Active
-Keymaps}.
+instead of the position of point.)
@item local-map
@kindex local-map @r{(text property)}
This property works like @code{keymap} except that it specifies a
keymap to use @emph{instead of} the buffer's local map. For most
-purposes (perhaps all purposes), the @code{keymap} is superior.
+purposes (perhaps all purposes), it is better to use the @code{keymap}
+property.
@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
@subsection Defining Clickable Text
@cindex clickable text
- There are two parts of setting up @dfn{clickable text} in a buffer:
-(1) to make that text highlight when the mouse moves over it, and (2)
-to make a mouse button do something when you click on that text.
+ @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.
- For highlighting, use the @code{mouse-face} text property. Here is
-an example of how Dired does it:
+ 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:
@smallexample
(condition-case nil
(if (dired-move-to-filename)
- (put-text-property (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- 'mouse-face 'highlight))
+ (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))
@end smallexample
@noindent
-The first two arguments to @code{put-text-property} specify the
+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
@smallexample
(defun dired-mouse-find-file-other-window (event)
- "In dired, visit the file or directory name you click on."
+ "In Dired, visit the file or directory name you click on."
(interactive "e")
- (let (file)
+ (let (window pos file)
(save-excursion
- (set-buffer (window-buffer (posn-window (event-end event))))
- (save-excursion
- (goto-char (posn-point (event-end event)))
- (setq file (dired-get-filename))))
- (select-window (posn-window (event-end event)))
- (find-file-other-window (file-name-sans-versions file t))))
+ (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))
+ (goto-char pos)
+ (setq file (dired-get-file-for-visit)))
+ (if (file-directory-p file)
+ (or (and (cdr dired-subdir-alist)
+ (dired-goto-subdir file))
+ (progn
+ (select-window window)
+ (dired-other-window file)))
+ (select-window window)
+ (find-file-other-window (file-name-sans-versions file t)))))
@end smallexample
@noindent
-The reason for the outer @code{save-excursion} construct is to avoid
-changing the current buffer; the reason for the inner one is to avoid
-permanently altering point in the buffer you click on. In this case,
-Dired uses the function @code{dired-get-filename} to determine which
-file to visit, based on the position found in the event.
+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.
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}