@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Text
@chapter Text
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
-* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
* Base 64:: Conversion to or from base 64 encoding.
* Checksum/Hash:: Computing cryptographic hashes.
* Parsing HTML/XML:: Parsing HTML and XML.
@defun buffer-string
This function returns the contents of the entire accessible portion of
-the current buffer as a string. It is equivalent to
-@w{@code{(buffer-substring (point-min) (point-max))}}.
+the current buffer, as a string.
@end defun
@defun filter-buffer-substring start end &optional delete
@code{filter-buffer-substring-functions}, and returns the result. The
obsolete variable @code{buffer-substring-filters} is also consulted.
If both of these variables are @code{nil}, the value is the unaltered
-text from the buffer, i.e.@: what @code{buffer-substring} would
+text from the buffer, i.e., what @code{buffer-substring} would
return.
If @var{delete} is non-@code{nil}, this function deletes the text
copied out of the buffer.
@end defun
+@c FIXME: `filter-buffer-substring-function' should be documented.
@defvar filter-buffer-substring-functions
This variable is a wrapper hook (@pxref{Running Hooks}), whose members
should be functions that accept four arguments: @var{fun},
@code{filter-buffer-substring}.
The first hook function is passed a @var{fun} that is equivalent to
-the default operation of @code{filter-buffer-substring}, i.e. it
+the default operation of @code{filter-buffer-substring}, i.e., it
returns the buffer-substring between @var{start} and @var{end}
(processed by any @code{buffer-substring-filters}) and optionally
deletes the original text from the buffer. In most cases, the hook
the inserted text, regardless of the markers' insertion type.
Insertion functions signal an error if the current buffer is
-read-only or if they insert within read-only text.
+read-only (@pxref{Read Only Buffers}) or if they insert within
+read-only text (@pxref{Special Properties}).
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
overlay.
@end defun
-@defun insert-char character count &optional inherit
-This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} should be an
-integer, and @var{character} must be a character. The value is @code{nil}.
+@deffn Command insert-char character &optional count inherit
+This command inserts @var{count} instances of @var{character} into the
+current buffer before point. The argument @var{count} must be an
+integer, and @var{character} must be a character.
+
+If called interactively, this command prompts for @var{character}
+using its Unicode name or its code point. @xref{Inserting Text,,,
+emacs, The GNU Emacs Manual}.
This function does not convert unibyte character codes 128 through 255
to multibyte characters, not even if the current buffer is a multibyte
buffer. @xref{Converting Representations}.
-If @var{inherit} is non-@code{nil}, then the inserted characters inherit
+If @var{inherit} is non-@code{nil}, the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. @xref{Sticky Properties}.
-@end defun
+@end deffn
@defun insert-buffer-substring from-buffer-or-name &optional start end
This function inserts a portion of buffer @var{from-buffer-or-name}
-(which must already exist) into the current buffer before point. The
-text inserted is the region between @var{start} and @var{end}. (These
-arguments default to the beginning and end of the accessible portion of
-that buffer.) This function returns @code{nil}.
+into the current buffer before point. The text inserted is the region
+between @var{start} (inclusive) and @var{end} (exclusive). (These
+arguments default to the beginning and end of the accessible portion
+of that buffer.) This function returns @code{nil}.
In this example, the form is executed with buffer @samp{bar} as the
current buffer. We assume that buffer @samp{bar} is initially empty.
In an interactive call, @var{count} is the numeric prefix argument.
+@c FIXME: This variable is obsolete since 23.1.
Self-insertion translates the input character through
@code{translation-table-for-input}. @xref{Translation of Characters}.
blank lines immediately following it.
A blank line is defined as a line containing only tabs and spaces.
+@c and the Newline character?
@code{delete-blank-lines} returns @code{nil}.
@end deffn
@node Yanking
@subsection Yanking
- Yanking means inserting text from the kill ring, but it does
-not insert the text blindly. Yank commands and some other commands
-use @code{insert-for-yank} to perform special processing on the
-text that they copy into the buffer.
+ Yanking means inserting text from the kill ring, but it does not
+insert the text blindly. The @code{yank} command, and related
+commands, use @code{insert-for-yank} to perform special processing on
+the text before it is inserted.
@defun insert-for-yank string
-This function normally works like @code{insert} except that it doesn't
-insert the text properties (@pxref{Text Properties}) in the list
-variable @code{yank-excluded-properties}. However, if any part of
-@var{string} has a non-@code{nil} @code{yank-handler} text property,
-that property can do various special processing on that part of the
-text being inserted.
+This function works like @code{insert}, except that it processes the
+text in @var{string} according to the @code{yank-handler} text
+property, as well as the variables @code{yank-handled-properties} and
+@code{yank-excluded-properties} (see below), before inserting the
+result into the current buffer.
@end defun
@defun insert-buffer-substring-as-yank buf &optional start end
-This function resembles @code{insert-buffer-substring} except that it
-doesn't insert the text properties in the
-@code{yank-excluded-properties} list.
+This function resembles @code{insert-buffer-substring}, except that it
+processes the text according to @code{yank-handled-properties} and
+@code{yank-excluded-properties}. (It does not handle the
+@code{yank-handler} property, which does not normally occur in buffer
+text anyway.)
@end defun
- You can put a @code{yank-handler} text property on all or part of
-the text to control how it will be inserted if it is yanked. The
-@code{insert-for-yank} function looks for that property. The property
-value must be a list of one to four elements, with the following
-format (where elements after the first may be omitted):
+@c FIXME: Add an index for yank-handler.
+ If you put a @code{yank-handler} text property on all or part of a
+string, that alters how @code{insert-for-yank} inserts the string. If
+different parts of the string have different @code{yank-handler}
+values (comparison being done with @code{eq}), each substring is
+handled separately. The property value must be a list of one to four
+elements, with the following format (where elements after the first
+may be omitted):
@example
(@var{function} @var{param} @var{noexclude} @var{undo})
@table @var
@item function
-When @var{function} is present and non-@code{nil}, it is called instead of
-@code{insert} to insert the string. @var{function} takes one
-argument---the string to insert.
+When @var{function} is non-@code{nil}, it is called instead of
+@code{insert} to insert the string, with one argument---the string to
+insert.
@item param
If @var{param} is present and non-@code{nil}, it replaces @var{string}
-(or the part of @var{string} being processed) as the object passed to
-@var{function} (or @code{insert}); for example, if @var{function} is
-@code{yank-rectangle}, @var{param} should be a list of strings to
-insert as a rectangle.
+(or the substring of @var{string} being processed) as the object
+passed to @var{function} (or @code{insert}). For example, if
+@var{function} is @code{yank-rectangle}, @var{param} should be a list
+of strings to insert as a rectangle.
@item noexclude
-If @var{noexclude} is present and non-@code{nil}, the normal removal of the
-yank-excluded-properties is not performed; instead @var{function} is
-responsible for removing those properties. This may be necessary
-if @var{function} adjusts point before or after inserting the object.
+If @var{noexclude} is present and non-@code{nil}, that disables the
+normal action of @code{yank-handled-properties} and
+@code{yank-excluded-properties} on the inserted string.
@item undo
If @var{undo} is present and non-@code{nil}, it is a function that will be
@end table
@cindex yanking and text properties
+@defopt yank-handled-properties
+This variable specifies special text property handling conditions for
+yanked text. It takes effect after the text has been inserted (either
+normally, or via the @code{yank-handler} property), and prior to
+@code{yank-excluded-properties} taking effect.
+
+The value should be an alist of elements @code{(@var{prop}
+. @var{fun})}. Each alist element is handled in order. The inserted
+text is scanned for stretches of text having text properties @code{eq}
+to @var{prop}; for each such stretch, @var{fun} is called with three
+arguments: the value of the property, and the start and end positions
+of the text.
+@end defopt
+
@defopt yank-excluded-properties
-Yanking discards certain text properties from the yanked text, as
-described above. The value of this variable is the list of properties
-to discard. Its default value contains properties that might lead to
-annoying results, such as causing the text to respond to the mouse or
-specifying key bindings.
+The value of this variable is the list of properties to remove from
+inserted text. Its default value contains properties that might lead
+to annoying results, such as causing the text to respond to the mouse
+or specifying key bindings. It takes effect after
+@code{yank-handled-properties}.
@end defopt
+
@node Yank Commands
@subsection Functions for Yanking
@defvar buffer-undo-list
This buffer-local variable's value is the undo list of the current
-buffer. A value of @code{t} disables the recording of undo information.
+buffer. A value of @code{t} disables the recording of undo information.
@end defvar
Here are the kinds of elements an undo list can have:
positive, point was at the beginning of the deleted text, otherwise it
was at the end.
-@item (t @var{high} . @var{low})
+@item (t . @var{time-flag})
This kind of element indicates that an unmodified buffer became
-modified. The elements @var{high} and @var{low} are two integers, each
-recording 16 bits of the visited file's modification time as of when it
-was previously visited or saved. @code{primitive-undo} uses those
+modified. A @var{time-flag} of the form
+@code{(@var{sec-high} @var{sec-low} @var{microsec}
+@var{picosec})} represents the visited file's modification time as of
+when it was previously visited or saved, using the same format as
+@code{current-time}; see @ref{Time of Day}.
+A @var{time-flag} of 0 means the buffer does not correspond to any file;
+@minus{}1 means the visited file previously did not exist.
+@code{primitive-undo} uses these
values to determine whether to mark the buffer as unmodified once again;
-it does so only if the file's modification time matches those numbers.
+it does so only if the file's status matches that of @var{time-flag}.
@item (nil @var{property} @var{value} @var{beg} . @var{end})
This kind of element records a change in a text property.
@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
This is an extensible undo item, which records a change limited to the
range @var{beg} to @var{end}, which increased the size of the buffer
-by @var{delta}. It is undone by calling @var{funname} with arguments
-@var{args}.
+by @var{delta} characters. It is undone by calling @var{funname} with
+arguments @var{args}.
This kind of element enables undo limited to a region to determine
whether the element pertains to that region.
the undo list of @var{buffer-or-name} is already disabled, this function
has no effect.
-This function returns @code{nil}.
+In an interactive call, BUFFER-OR-NAME is the current buffer. You
+cannot specify any other buffer. This function returns @code{nil}.
@end deffn
As editing continues, undo lists get longer and longer. To prevent
a regular expression; if it matches the beginning of a line, that line
is treated as a citation marker.
+@c FIXME: "That mode" is confusing. It isn't a major/minor mode.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
@code{fill-individual-varying-indent} is non-@code{nil}, then only
@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
-newlines'' act as paragraph separators.
+newlines'' act as paragraph separators. @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@end defvar
@node Margins
@section Margins for Filling
+@cindex margins, filling
@defopt fill-prefix
This buffer-local variable, if non-@code{nil}, specifies a string of
@cindex filling, automatic
@cindex Auto Fill mode
+@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
Auto Fill mode is a minor mode that fills lines automatically as text
is inserted. This section describes the hook used by Auto Fill mode.
For a description of functions that you can call explicitly to fill and
@group
(sort-subr reverse
(function
- (lambda ()
- (while (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))))
+ (lambda ()
+ (while (and (not (eobp))
+ (looking-at paragraph-separate))
+ (forward-line 1))))
'forward-paragraph)
@end group
@end example
When called interactively, @var{column} is the value of prefix numeric
argument. If @var{column} is not an integer, an error is signaled.
+@c This behavior used to be documented until 2013/08.
+@ignore
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.
+@end ignore
If it is impossible to move to column @var{column} because that is in
the middle of a multicolumn character such as a tab, point moves to the
For example, if @var{count} is 3, this command adds 3 columns of
indentation to each of the lines beginning in the region specified.
+@c FIXME: I suggest using message-indent-citation as the example, or
+@c just remove this paragraph. --xfq
In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
@code{indent-rigidly} to indent the text copied from the message being
replied to.
@end group
@group
-(capitalize-region 1 44)
+(capitalize-region 1 37)
@result{} nil
---------- Buffer: foo ----------
Do not rely on the return value of this function.
@end defun
- The easiest way to make a string with text properties
-is with @code{propertize}:
+@defun add-face-text-property start end face &optional appendp object
+This function acts on the text between @var{start} and @var{end},
+adding the face @var{face} to the @code{face} text property.
+@var{face} should be a valid value for the @code{face} property
+(@pxref{Special Properties}), such as a face name or an anonymous face
+(@pxref{Faces}).
+
+If any text in the region already has a non-nil @code{face} property,
+those face(s) are retained. This function sets the @code{face}
+property to a list of faces, with @var{face} as the first element (by
+default) and the pre-existing faces as the remaining elements. If the
+optional argument @var{append} is non-@code{nil}, @var{face} is
+appended to the end of the list instead. Note that in a face list,
+the first occurring value for each attribute takes precedence.
+
+For example, the following code would assign a italicized green face
+to the text between @var{start} and @var{end}:
+
+@example
+(add-face-text-property @var{start} @var{end} 'italic)
+(add-face-text-property @var{start} @var{end} '(:foreground "red"))
+(add-face-text-property @var{start} @var{end} '(:foreground "green"))
+@end example
+
+The optional argument @var{object}, if non-@code{nil}, specifies a
+buffer or string to act on, rather than the current buffer. If
+@var{object} is a string, then @var{start} and @var{end} are
+zero-based indices into the string.
+@end defun
+
+ The easiest way to make a string with text properties is with
+@code{propertize}:
@defun propertize string &rest properties
This function returns a copy of @var{string} which has the text
@table @code
@cindex property category of text character
+@c FIXME: Isn't @kindex for keyboard commands?
@kindex category @r{(text property)}
@item category
If a character has a @code{category} property, we call it the
@item face
@cindex face codes of text
@kindex face @r{(text property)}
-The @code{face} property controls the appearance of the character,
-such as its font and color. @xref{Faces}. The value of the property
-can be the following:
+The @code{face} property controls the appearance of the character
+(@pxref{Faces}). The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
-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
-time you want to specify a particular attribute for certain text.
-@xref{Face Attributes}.
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
@item
-A list of faces. This specifies a face which is an aggregate of the
+A list of faces. Each list element should be either a face name or an
+anonymous face. This specifies a face which is an aggregate of the
attributes of each of the listed faces. Faces occurring earlier in
-the list have higher priority. Each list element must have one of the
-two above forms (i.e.@: either a face name or a property list of face
-attributes).
+the list have higher priority.
+
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}. This
+form is supported for backward compatibility only, and should be
+avoided.
@end itemize
Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by
dynamically updating the @code{face} property of characters based on
the context.
+The @code{add-face-text-property} function provides a convenient way
+to set this text property. @xref{Changing Properties}.
+
@item font-lock-face
@kindex font-lock-face @r{(text property)}
This property specifies a value for the @code{face} property that Font
@code{mouse-face} property value.
Emacs ignores all face attributes from the @code{mouse-face} property
-that alter the text size (e.g. @code{:height}, @code{:weight}, and
+that alter the text size (e.g., @code{:height}, @code{:weight}, and
@code{:slant}). Those attributes are always the same as for the
unhighlighted text.
@node Sticky Properties
@subsection Stickiness of Text Properties
@cindex sticky text properties
-@cindex inheritance of text properties
+@cindex inheritance, text property
Self-inserting characters normally take on the same properties as the
preceding character. This is called @dfn{inheritance} of properties.
Insertion of text at the border between intervals also raises
questions that have no satisfactory answer.
- However, it is easy to arrange for editing to behave consistently for
-questions of the form, ``What are the properties of this character?''
-So we have decided these are the only questions that make sense; we have
-not implemented asking questions about where intervals start or end.
+ However, it is easy to arrange for editing to behave consistently
+for questions of the form, ``What are the properties of text at this
+buffer or string position?'' So we have decided these are the only
+questions that make sense; we have not implemented asking questions
+about where intervals start or end.
In practice, you can usually use the text property search functions in
place of explicit interval boundaries. You can think of them as finding
This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer.
+@c FIXME: Mention frameset here.
@item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a position
to jump to in the current buffer.
@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
+signaled if a character in the region is multibyte, i.e., in a
multibyte buffer the region must contain only characters from the
charsets @code{ascii}, @code{eight-bit-control} and
@code{eight-bit-graphic}.
Emacs has built-in support for computing @dfn{cryptographic hashes}.
A cryptographic hash, or @dfn{checksum}, is a digital ``fingerprint''
-of a piece of data (e.g.@: a block of text) which can be used to check
+of a piece of data (e.g., a block of text) which can be used to check
that you have an unaltered copy of that data.
@cindex message digest
SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the
oldest of these algorithms, and is commonly used in @dfn{message
digests} to check the integrity of messages transmitted over a
-network. MD5 is not ``collision resistant'' (i.e.@: it is possible to
+network. MD5 is not ``collision resistant'' (i.e., it is possible to
deliberately design different pieces of data which have the same MD5
hash), so you should not used it for anything security-related. A
similar theoretical weakness also exists in SHA-1. Therefore, for
modification. Each function receives three arguments: the beginning
and end of the region just changed, and the length of the text that
existed before the change. All three arguments are integers. The
-buffer has been changed is always the current buffer.
+buffer that has been changed is always the current buffer.
The length of the old text is the difference between the buffer
positions before and after that text as it was before the change. As