File: text.texi

package info (click to toggle)
elisp-manual-ja 20-2.5-jp-4
links: PTS
area: main
in suites: sarge
size: 3,996 kB
ctags: 239
sloc: lisp: 2,837; perl: 182; makefile: 45; sh: 16
file content (5302 lines) | stat: -rw-r--r-- 254,287 bytes
parent folder | download | duplicates (2)
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
@c @chapter Text
@chapter $B%F%-%9%H(B
@c @cindex text
@cindex $B%F%-%9%H(B

@c   This chapter describes the functions that deal with the text in a
@c buffer.  Most examine, insert, or delete text in the current buffer,
@c often in the vicinity of point.  Many are interactive.  All the
@c functions that change the text provide for undoing the changes
@c (@pxref{Undo}).
$BK\>O$G$O!"%P%C%U%!Fb$N%F%-%9%H$r07$&4X?t$K$D$$$F=R$Y$^$9!#(B
$B$=$l$i$N$[$H$s$I$O!"%+%l%s%H%P%C%U%!Fb$N%F%-%9%H$r(B
$BD4$Y$?$jA^F~$7$?$j:o=|$7$^$9$,!"$7$P$7$P%]%$%s%HIU6a$G9T$$$^$9!#(B
$BB?$/$OBPOCE*$K;H$($^$9!#(B
$B%F%-%9%H$rJQ99$9$k$9$Y$F$N4X?t$O!"JQ99$r<h$j>C$;$^$9!J(B@pxref{Undo}$B!K!#(B

@c   Many text-related functions operate on a region of text defined by two
@c buffer positions passed in arguments named @var{start} and @var{end}.
@c These arguments should be either markers (@pxref{Markers}) or numeric
@c character positions (@pxref{Positions}).  The order of these arguments
@c does not matter; it is all right for @var{start} to be the end of the
@c region and @var{end} the beginning.  For example, @code{(delete-region 1
@c 10)} and @code{(delete-region 10 1)} are equivalent.  An
@c @code{args-out-of-range} error is signaled if either @var{start} or
@c @var{end} is outside the accessible portion of the buffer.  In an
@c interactive call, point and the mark are used for these arguments.
$B%F%-%9%H4XO"$NB?$/$N4X?t$O!"(B@var{start}$B$H(B@var{end}$B$H$$$&L>A0$N0z?t$GEO$5$l$?(B
2$B$D$N%P%C%U%!Fb0LCV$GDj5A$5$l$k%F%-%9%H$NNN0h$K:nMQ$7$^$9!#(B
$B$3$l$i$N0z?t$O!"%^!<%+!J(B@pxref{Markers}$B!K$G$"$k$+(B
$BJ8;z$N0LCV$rI=$9?tCM!J(B@pxref{Positions}$B!K$G$"$kI,MW$,$"$j$^$9!#(B
$B$3$l$i$N0z?t$N=gHV$O4X78$J$/!"(B@var{start}$B$,NN0h$N=*N;0LCV$G(B
@var{end}$B$,3+;O0LCV$G$"$C$F$b$^$C$?$/LdBj$"$j$^$;$s!#(B
$B$?$H$($P!"(B@code{(delete-region 1 10)}$B$H(B@code{(delete-region 10 1)}$B$OF1CM$G$9!#(B
@var{start}$B$d(B@var{end}$B$,%P%C%U%!$N;2>H2DG=ItJ,$N30B&$K$"$k$H(B
$B%(%i!<(B@code{args-out-of-range}$B$rDLCN$7$^$9!#(B
$BBPOCE*$J8F$S=P$7$G$O!"%]%$%s%H$H%^!<%/$r$3$l$i$N0z?t$H$7$F;H$$$^$9!#(B

@c @cindex buffer contents
@cindex $B%P%C%U%!$NFbMF(B
@c   Throughout this chapter, ``text'' refers to the characters in the
@c buffer, together with their properties (when relevant).
$BK\>O$G$O!"%P%C%U%!Fb$NJ8;z$r!J4X78$"$k$H$-$K$O!K(B
$B$=$l$i$N%F%-%9%HB0@-$r4^$a$F!X%F%-%9%H!Y$H8F$S$^$9!#(B

@menu
* Near Point::       Examining text in the vicinity of point.
* Buffer Contents::  Examining text in a general fashion.
* Comparing Text::   Comparing substrings of buffers.
* Insertion::        Adding new text to a buffer.
* Commands for Insertion::  User-level commands to insert text.
* Deletion::         Removing text from a buffer.
* User-Level Deletion::     User-level commands to delete text.
* The Kill Ring::    Where removed text sometimes is saved for later use.
* Undo::             Undoing changes to the text of a buffer.
* Maintaining Undo:: How to enable and disable undo information.
			How to control how much information is kept.
* Filling::          Functions for explicit filling.
* Margins::          How to specify margins for filling commands.
* Adaptive Fill::    Adaptive Fill mode chooses a fill prefix from context.
* Auto Filling::     How auto-fill mode is implemented to break lines.
* Sorting::          Functions for sorting parts of the buffer.
* Columns::          Computing horizontal positions, and using them.
* Indentation::      Functions to insert or adjust indentation.
* 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.
* Change Hooks::     Supplying functions to be run when text is changed.
@end menu

@node Near Point
@c @section Examining Text Near Point
@section $B%]%$%s%HIU6a$N%F%-%9%H$rD4$Y$k(B

@c   Many functions are provided to look at the characters around point.
@c Several simple functions are described here.  See also @code{looking-at}
@c in @ref{Regexp Search}.
$BB?$/$N4X?t$O!"%]%$%s%HIU6a$NJ8;z$rD4$Y$k$?$a$N$b$N$G$9!#(B
$B$3$3$G$O!"?t8D$NC1=c$J4X?t$K$D$$$F=R$Y$^$9!#(B
@ref{Regexp Search}$B$N(B@code{looking-at}$B$b;2>H$7$F$/$@$5$$!#(B

@defun char-after &optional position
@c This function returns the character in the current buffer at (i.e.,
@c immediately after) position @var{position}.  If @var{position} is out of
@c range for this purpose, either before the beginning of the buffer, or at
@c or beyond the end, then the value is @code{nil}.  The default for
@c @var{position} is point.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!Fb$N0LCV(B@var{position}$B$K$"$k(B
$B!J$D$^$jD>8e$N!KJ8;z$rJV$9!#(B
@var{position}$B$,%P%C%U%!$N@hF,$N$^$($dKvHx$N$&$7$m$K$"$k$J$I$7$F(B
$B$3$NL\E*$KE,$7$?HO0O$N30B&$K$"$k$H!"CM$O(B@code{nil}$B$G$"$k!#(B
@var{position}$B$N%G%U%)%k%H$O%]%$%s%H$G$"$k!#(B

@c In the following example, assume that the first character in the
@c buffer is @samp{@@}:
$B$D$.$NNc$G$O!"%P%C%U%!$N:G=i$NJ8;z$O(B@samp{@@}$B$G$"$k$H2>Dj$9$k!#(B

@example
@group
(char-to-string (char-after 1))
     @result{} "@@"
@end group
@end example
@end defun

@defun char-before &optional position
@c This function returns the character in the current buffer immediately
@c before position @var{position}.  If @var{position} is out of range for
@c this purpose, either before the beginning of the buffer, or at or beyond
@c the end, then the value is @code{nil}.  The default for
@c @var{position} is point.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!Fb$N0LCV(B@var{position}$B$N$^$($K$"$kJ8;z$rJV$9!#(B
@var{position}$B$,%P%C%U%!$N@hF,$N$^$($dKvHx$N$&$7$m$K$"$k$J$I$7$F(B
$B$3$NL\E*$KE,$7$?HO0O$N30B&$K$"$k$H!"CM$O(B@code{nil}$B$G$"$k!#(B
@var{position}$B$N%G%U%)%k%H$O%]%$%s%H$G$"$k!#(B
@end defun

@defun following-char
@c This function returns the character following point in the current
@c buffer.  This is similar to @code{(char-after (point))}.  However, if
@c point is at the end of the buffer, then @code{following-char} returns 0.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N%]%$%s%H$N$&$7$m$K$"$kJ8;z$rJV$9!#(B
$B$3$l$O(B@code{(char-after (point))}$B$HF1MM$G$"$k!#(B
$B$7$+$7!"%]%$%s%H$,%P%C%U%!$NKvHx$K$"$k$H!"(B
@code{following-char}$B$O(B0$B$rJV$9!#(B

@c Remember that point is always between characters, and the terminal
@c cursor normally appears over the character following point.  Therefore,
@c the character returned by @code{following-char} is the character the
@c cursor is over.
$B%]%$%s%H$O$D$M$KJ8;z$N$"$$$@$K$"$j!"(B
$BC<Kv$N%+!<%=%k$O%]%$%s%H$ND>8e$NJ8;z$K=E$M$FI=<($5$l$k$3$H$KCm0U$7$F$[$7$$!#(B
$B$7$?$,$C$F!"(B@code{following-char}$B$,JV$9J8;z$O!"(B
$B%+!<%=%k$,=E$J$C$F$$$kJ8;z$G$"$k!#(B

@c In this example, point is between the @samp{a} and the @samp{c}.
$B$D$.$NNc$G$O!"%]%$%s%H$O(B@samp{a}$B$H(B@samp{c}$B$N$"$$$@$K$"$k!#(B

@example
@group
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------
@end group

@group
(char-to-string (preceding-char))
     @result{} "a"
(char-to-string (following-char))
     @result{} "c"
@end group
@end example
@end defun

@defun preceding-char
@c This function returns the character preceding point in the current
@c buffer.  See above, under @code{following-char}, for an example.  If
@c point is at the beginning of the buffer, @code{preceding-char} returns
@c 0.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N%]%$%s%H$N$^$($NJ8;z$rJV$9!#(B
$BNc$K$D$$$F$O>e5-$N(B@code{following-char}$B$r;2>H!#(B
$B%]%$%s%H$,%P%C%U%!$N@hF,$K$"$k$H!"(B@code{preceding-char}$B$O(B0$B$rJV$9!#(B
@end defun

@defun bobp
@c This function returns @code{t} if point is at the beginning of the
@c buffer.  If narrowing is in effect, this means the beginning of the
@c accessible portion of the text.  See also @code{point-min} in
@c @ref{Point}.
$B$3$N4X?t$O!"%]%$%s%H$,%P%C%U%!$N@hF,$K$"$k$H(B@code{t}$B$rJV$9!#(B
$B%J%m%$%s%0$7$F$$$k$H!"$3$l$O%P%C%U%!$N;2>H2DG=ItJ,$N@hF,$r0UL#$9$k!#(B
@ref{Point}$B$N(B@code{point-min}$B$b;2>H!#(B
@end defun

@defun eobp
@c This function returns @code{t} if point is at the end of the buffer.
@c If narrowing is in effect, this means the end of accessible portion of
@c the text.  See also @code{point-max} in @xref{Point}.
$B$3$N4X?t$O!"%]%$%s%H$,%P%C%U%!$NKvHx$K$"$k$H(B@code{t}$B$rJV$9!#(B
$B%J%m%$%s%0$7$F$$$k$H!"$3$l$O%P%C%U%!$N;2>H2DG=ItJ,$NKvHx$r0UL#$9$k!#(B
@ref{Point}$B$N(B@code{point-max}$B$b;2>H!#(B
@end defun

@defun bolp
@c This function returns @code{t} if point is at the beginning of a line.
@c @xref{Text Lines}.  The beginning of the buffer (or of its accessible
@c portion) always counts as the beginning of a line.
$B$3$N4X?t$O!"%]%$%s%H$,9TF,$K$"$k$H(B@code{t}$B$rJV$9!#(B
@pxref{Text Lines}$B!#(B
$B%P%C%U%!!J$"$k$$$O$=$N;2>H2DG=ItJ,!K$N@hF,$O!"(B
$B$D$M$K9TF,$H$_$J$9!#(B
@end defun

@defun eolp
@c This function returns @code{t} if point is at the end of a line.  The
@c end of the buffer (or of its accessible portion) is always considered
@c the end of a line.
$B$3$N4X?t$O!"%]%$%s%H$,9TKv$K$"$k$H(B@code{t}$B$rJV$9!#(B
@pxref{Text Lines}$B!#(B
$B%P%C%U%!!J$"$k$$$O$=$N;2>H2DG=ItJ,!K$NKvHx$O!"(B
$B$D$M$K9TKv$H$_$J$9!#(B
@end defun

@node Buffer Contents
@c @section Examining Buffer Contents
@section $B%P%C%U%!$NFbMF$rD4$Y$k(B

@c   This section describes two functions that allow a Lisp program to
@c convert any portion of the text in the buffer into a string.
$BK\@a$G$O!"(BLisp$B%W%m%0%i%`$G%P%C%U%!Fb$NG$0U$NItJ,$N%F%-%9%H$rJ8;zNs$KJQ49$9$k(B
$B$?$a$N(B2$B$D$N4X?t$K$D$$$F=R$Y$^$9!#(B

@defun buffer-substring start end
@c This function returns a string containing a copy of the text of the
@c region defined by positions @var{start} and @var{end} in the current
@c buffer.  If the arguments are not positions in the accessible portion of
@c the buffer, @code{buffer-substring} signals an @code{args-out-of-range}
@c error.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N(B@var{start}$B$H(B@var{end}$B$N0LCV$GDj5A$5$l$k(B
$BNN0h$N%F%-%9%H$N%3%T!<$r4^$s$@J8;zNs$rJV$9!#(B
$B0z?t$,%P%C%U%!$N;2>H2DG=ItJ,$NFbB&$N0LCV$G$J$$$H!"(B
@code{buffer-substring}$B$O%(%i!<(B@code{args-out-of-range}$B$rDLCN$9$k!#(B

@c It is not necessary for @var{start} to be less than @var{end}; the
@c arguments can be given in either order.  But most often the smaller
@c argument is written first.
@var{start}$B$,(B@var{end}$B$h$j>.$5$$I,MW$O$J$/!"0z?t$N=gHV$O$I$A$i$G$b$h$$!#(B
$B$7$+$7!"$[$H$s$I$N>l9g!">.$5$$0z?t$r@h$K=q$/!#(B

@c If the text being copied has any text properties, these are copied into
@c the string along with the characters they belong to.  @xref{Text
@c Properties}.  However, overlays (@pxref{Overlays}) in the buffer and
@c their properties are ignored, not copied.
$B%3%T!<$5$l$k%F%-%9%H$K%F%-%9%HB0@-$,$"$k>l9g!"(B
$B%F%-%9%HB0@-$b$=$l$,B0$9$kJ8;z$H$H$b$KJ8;zNs$X%3%T!<$5$l$k!#(B
@pxref{Text Properties}$B!#(B
$B$7$+$7!"%P%C%U%!$N%*!<%P%l%$!J(B@pxref{Overlays}$B!K$H$=$l$i$NB0@-$O(B
$BL5;k$5$l%3%T!<$5$l$J$$!#(B

@example
@group
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------
@end group

@group
(buffer-substring 1 10)
@result{} "This is t"
@end group
@group
(buffer-substring (point-max) 10)
@result{} "he contents of buffer foo
"
@end group
@end example
@end defun

@defun buffer-substring-no-properties start end
@c This is like @code{buffer-substring}, except that it does not copy text
@c properties, just the characters themselves.  @xref{Text Properties}.
$B$3$N4X?t$O(B@code{buffer-substring}$B$HF1MM$G$"$k$,!"(B
$B%F%-%9%HB0@-$r%3%T!<$;$:$KJ8;z$@$1$r%3%T!<$9$kE@$,0[$J$k!#(B
@pxref{Text Properties}$B!#(B
@end defun

@defun buffer-string
@c This function returns the contents of the entire accessible portion of
@c the current buffer as a string.  It is equivalent to
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N;2>H2DG=ItJ,A4BN$NFbMF$rJ8;zNs$H$7$FJV$9!#(B
$B$3$l$O!"$D$.$HEy2A$G$"$k!#(B

@example
(buffer-substring (point-min) (point-max))
@end example

@example
@group
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-string)
     @result{} "This is the contents of buffer foo
"
@end group
@end example
@end defun

@defun thing-at-point thing
@c Return the @var{thing} around or next to point, as a string.
$B%]%$%s%H$N<~$j$d$=$N$&$7$m$K$"$k(B@var{thing}$B$rJ8;zNs$H$7$FJV$9!#(B

@c The argument @var{thing} is a symbol which specifies a kind of syntactic
@c entity.  Possibilities include @code{symbol}, @code{list}, @code{sexp},
@c @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@c @code{whitespace}, @code{line}, @code{page}, and others.
$B0z?t(B@var{thing}$B$O!"9=J8>e$NMWAG$N<oN`$r;XDj$9$k%7%s%\%k$G$"$k!#(B
$B2DG=$JCM$O!"(B@code{symbol}$B!"(B@code{list}$B!"(B@code{sexp}$B!"(B
@code{defun}$B!"(B@code{filename}$B!"(B@code{url}$B!"(B@code{word}$B!"(B@code{sentence}$B!"(B
@code{whitespace}$B!"(B@code{line}$B!"(B@code{page}$B$J$I$G$"$k!#(B

@example
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
     @result{} "Peace"
(thing-at-point 'line)
     @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     @result{} nil
@end example
@end defun

@node Comparing Text
@c @section Comparing Text
@section $B%F%-%9%H$NHf3S(B
@c @cindex comparing buffer text
@cindex $B%P%C%U%!%F%-%9%H$NHf3S(B

@c   This function lets you compare portions of the text in a buffer, without
@c copying them into strings first.
$B$3$N4X?t$K$h$j!"%P%C%U%!Fb$N%F%-%9%H$NItJ,F1;N$r(B
$BJ8;zNs$K%3%T!<$;$:$KHf3S$G$-$^$9!#(B

@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
@c This function lets you compare two substrings of the same buffer or two
@c different buffers.  The first three arguments specify one substring,
@c giving a buffer and two positions within the buffer.  The last three
@c arguments specify the other substring in the same way.  You can use
@c @code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
@c current buffer.
$B$3$N4X?t$O!"F10l%P%C%U%!Fb$N(B2$B$D$NItJ,J8;zNs!"$"$k$$$O!"(B
$B0[$J$k(B2$B$D$N%P%C%U%!$NItJ,J8;zNs$rHf3S$9$k!#(B
$B;O$a$N(B3$B$D$N0z?t$O!"%P%C%U%!$H$=$N%P%C%U%!Fb$N(B2$B$D$N0LCV$rM?$(!"(B
1$B$D$NItJ,J8;zNs$r;XDj$9$k!#(B
$B;D$j$N(B3$B$D$N0z?t$bF1MM$K$7$FJL$NItJ,J8;zNs$r;XDj$9$k!#(B
$B%+%l%s%H%P%C%U%!$rI=$9$?$a$K!"(B
@var{buffer1}$B$H(B@var{buffer2}$B$N$$$:$l$+!"$"$k$$$O!"(B
$BN>J}$K(B@code{nil}$B$r;XDj$G$-$k!#(B

@c The value is negative if the first substring is less, positive if the
@c first is greater, and zero if they are equal.  The absolute value of
@c the result is one plus the index of the first differing characters
@c within the substrings.
$B;O$a$NJ8;zNs$N$[$&$,>.$5$1$l$PCM$OIi$G$"$j!"(B
$B;O$a$N$[$&$,Bg$-$1$l$PCM$O@5$G$"$j!"Ey$7$1$l$P(B0$B$G$"$k!#(B
$B7k2L$N@dBPCM$O!"ItJ,J8;zNs$NCf$G:G=i$K0[$J$kJ8;z$NE:;zB-$9(B1$B$G$"$k!#(B

@c This function ignores case when comparing characters
@c if @code{case-fold-search} is non-@code{nil}.  It always ignores
@c text properties.
$B$3$N4X?t$O!"(B@code{case-fold-search}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BJ8;z$NHf3S$G$OBgJ8;z>.J8;z$r6hJL$7$J$$!#(B
$B%F%-%9%HB0@-$O$D$M$KL5;k$9$k!#(B

@c Suppose the current buffer contains the text @samp{foobarbar
@c haha!rara!}; then in this example the two substrings are @samp{rbar }
@c and @samp{rara!}.  The value is 2 because the first substring is greater
@c at the second character.
$B%+%l%s%H%P%C%U%!$K$O%F%-%9%H(B@samp{foobarbar haha!rara!}$B$,$"$k$H$9$k!#(B
$B$9$k$H!"$3$NNc$N(B2$B$D$NItJ,J8;zNs$O(B@samp{rbar }$B$H(B@samp{rara!}$B$G$"$k!#(B
2$BHVL\$NJ8;z$G:G=i$NJ8;zNs$N$[$&$,Bg$-$$$N$G!"7k2L$O(B2$B$G$"$k!#(B

@example
(compare-buffer-substring nil 6 11 nil 16 21)
     @result{} 2
@end example
@end defun

@node Insertion
@c @section Inserting Text
@section $B%F%-%9%H$NA^F~(B
@c @cindex insertion of text
@c @cindex text insertion
@cindex $B%F%-%9%H$NA^F~(B
@cindex $BA^F~!"%F%-%9%H(B

@c @cindex insertion before point
@c @cindex before point, insertion
@cindex $B%]%$%s%H$N$^$($XA^F~(B
@cindex $BA^F~!"%]%$%s%H$N$^$((B
@c   @dfn{Insertion} means adding new text to a buffer.  The inserted text
@c goes at point---between the character before point and the character
@c after point.  Some insertion functions leave point before the inserted
@c text, while other functions leave it after.  We call the former
@c insertion @dfn{after point} and the latter insertion @dfn{before point}.
@dfn{$BA^F~(B}$B!J(Binsertion$B!K$H$O!"%P%C%U%!$K?7$?$J%F%-%9%H$rDI2C$9$k$3$H$G$9!#(B
$BA^F~$5$l$?%F%-%9%H$O%]%$%s%H0LCV$K!"$D$^$j!"(B
$B%]%$%s%H$N$^$($NJ8;z$H%]%$%s%H$N$"$H$NJ8;z$N$"$$$@$KF~$j$^$9!#(B
$BA^F~$5$l$?%F%-%9%H$N$^$($K%]%$%s%H$rN1$a$k4X?t$b$"$l$P!"(B
$B$=$N$&$7$m$KN1$a$k4X?t$b$"$j$^$9!#(B
$BA0<T$r(B@dfn{$B%]%$%s%H$N$&$7$m$X(B}$BA^F~$H8F$S!"(B
$B8e<T$r(B@dfn{$B%]%$%s%H$N$^$($X(B}$BA^F~$H8F$S$^$9!#(B

@c   Insertion relocates markers that point at positions after the
@c insertion point, so that they stay with the surrounding text
@c (@pxref{Markers}).  When a marker points at the place of insertion,
@c insertion may or may not relocate the marker, depending on the marker's
@c insertion type (@pxref{Marker Insertion Types}).  Certain special
@c functions such as @code{insert-before-markers} relocate all such markers
@c to point after the inserted text, regardless of the markers' insertion
@c type.
$BA^F~$K$h$j!"A^F~2U=j$h$j$&$7$m$N0LCV$r;X$9%^!<%+$O:FG[CV$5$l$F(B
$BF1$8<~$j$NJ8;z$KN1$^$j$^$9!J(B@pxref{Markers}$B!K!#(B
$B%^!<%+$,A^F~2U=j$r;X$7$F$$$k>l9g$K$O!"(B
$B%^!<%+$NA^F~7?!J(B@pxref{Marker Insertion Types}$B!K$K0MB8$7$F!"(B
$BA^F~$9$k$H%^!<%+$,:FG[CV$5$l$?$j$5$l$J$+$C$?$j$7$^$9!#(B
@code{insert-before-markers}$B$J$I$NFCDj$NFC<l$J4X?t$O!"(B
$B%^!<%+$NA^F~7?$K4X$o$i$:!"(B
$BA^F~$5$l$?%F%-%9%H$N$&$7$m$r;X$9$h$&$K(B
$B$=$N$h$&$J$9$Y$F$N%^!<%+$r:FG[CV$7$^$9!#(B

@c   Insertion functions signal an error if the current buffer is
@c read-only.
$B%+%l%s%H%P%C%U%!$,FI$_=P$7@lMQ$G$"$k$H!"A^F~4X?t$O%(%i!<$rDLCN$7$^$9!#(B

@c   These functions copy text characters from strings and buffers along
@c with their properties.  The inserted characters have exactly the same
@c properties as the characters they were copied from.  By contrast,
@c characters specified as separate arguments, not part of a string or
@c buffer, inherit their text properties from the neighboring text.
$B$3$l$i$N4X?t$O!"%F%-%9%H$NJ8;z72$r$=$l$i$NB0@-$H$H$b$K(B
$BJ8;zNs$+$i%P%C%U%!$X%3%T!<$7$^$9!#(B
$BA^F~$5$l$?J8;z72$O!"%3%T!<$5$l$k$^$($H$^$C$?$/F1$8B0@-$r;}$A$^$9!#(B
$BBP>HE*$K!"J8;zNs$d%P%C%U%!$N0lIt$G$O$J$$8IN)$7$?0z?t$H$7$F(B
$B;XDj$5$l$?J8;z72$O!"<~$j$N%F%-%9%H$+$i%F%-%9%HB0@-$r7Q>5$7$^$9!#(B

@c   The insertion functions convert text from unibyte to multibyte in
@c order to insert in a multibyte buffer, and vice versa---if the text
@c comes from a string or from a buffer.  However, they do not convert
@c unibyte character codes 128 through 255 to multibyte characters, not
@c even if the current buffer is a multibyte buffer.  @xref{Converting
@c Representations}.
$BA^F~4X?t$O!"J8;zNsM3Mh$d%P%C%U%!M3Mh$N%F%-%9%H$N>l9g$K$O!"(B
$B%^%k%A%P%$%H%P%C%U%!$XA^F~$9$k$?$a$K(B
$B%f%K%P%$%H$+$i%^%k%A%P%$%H$X%F%-%9%H$rJQ49$7!"5U8~$-$NJQ49$b9T$$$^$9!#(B
$B$7$+$7!"%+%l%s%H%P%C%U%!$,$?$H$(%^%k%A%P%$%H%P%C%U%!$G$"$C$F$b!"(B
128$B$+$i(B255$B$N%f%K%P%$%HJ8;z%3!<%I$O%^%k%A%P%$%HJ8;z$K$OJQ49$7$^$;$s!#(B
@xref{Converting Representations}$B!#(B

@defun insert &rest args
@c This function inserts the strings and/or characters @var{args} into the
@c current buffer, at point, moving point forward.  In other words, it
@c inserts the text before point.  An error is signaled unless all
@c @var{args} are either strings or characters.  The value is @code{nil}.
$B$3$N4X?t$O!"J8;zNs$dJ8;z72(B@var{args}$B$r%+%l%s%H%P%C%U%!$N%]%$%s%H0LCV$KA^F~$7!"(B
$B%]%$%s%H$r@h$X?J$a$k!#(B
$B$$$$$+$($l$P!"%]%$%s%H$N$^$($K%F%-%9%H$rA^F~$9$k!#(B
@var{args}$B$,J8;zNs$G$bJ8;z$G$b$J$$$H!"%(%i!<$rDLCN$9$k!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B
@end defun

@defun insert-before-markers &rest args
@c This function inserts the strings and/or characters @var{args} into the
@c current buffer, at point, moving point forward.  An error is signaled
@c unless all @var{args} are either strings or characters.  The value is
@c @code{nil}.
$B$3$N4X?t$O!"J8;zNs$dJ8;z72(B@var{args}$B$r%+%l%s%H%P%C%U%!$N%]%$%s%H0LCV$KA^F~$7!"(B
$B%]%$%s%H$r@h$X?J$a$k!#(B
@var{args}$B$,J8;zNs$G$bJ8;z$G$b$J$$$H!"%(%i!<$rDLCN$9$k!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B

@c This function is unlike the other insertion functions in that it
@c relocates markers initially pointing at the insertion point, to point
@c after the inserted text.  If an overlay begins the insertion point, the
@c inserted text falls outside the overlay; if a nonempty overlay ends at
@c the insertion point, the inserted text falls inside that overlay.
$BA^F~2U=j$r;X$7$F$$$?%^!<%+$rA^F~$5$l$?%F%-%9%H$N$&$7$m$r;X$9$h$&$K:FG[CV(B
$B$9$kE@$G!"$3$N4X?t$OB>$NA^F~4X?t$H0[$J$k!#(B
$BA^F~2U=j$G%*!<%P%l%$$,;O$^$k$H$-$K$O!"(B
$BA^F~$5$l$?%F%-%9%H$O%*!<%P%l%$$NHO0O30$K=P$k!#(B
$B6u$G$J$$%*!<%P%l%$$,A^F~2U=j$G=*$k$H$-$K$O!"(B
$BA^F~$5$l$?%F%-%9%H$O%*!<%P%l%$$NHO0OFb$KF~$k!#(B
@end defun

@defun insert-char character &optional count inherit
@c This function inserts @var{count} instances of @var{character} into the
@c current buffer before point.  The argument @var{count} should be a
@c number (@code{nil} means 1), and @var{character} must be a character.
@c The value is @code{nil}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N%]%$%s%H$N$^$($K(B
$BJ8;z(B@var{character}$B$r(B@var{count}$B8DA^F~$9$k!#(B
$B0z?t(B@var{count}$B$O?t!J(B@code{nil}$B$O(B1$B$r0UL#$9$k!K$G$"$j!"(B
@var{character}$B$OJ8;z$G$"$k$3$H!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B

@c This function does not convert unibyte character codes 128 through 255
@c to multibyte characters, not even if the current buffer is a multibyte
@c buffer.  @xref{Converting Representations}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$,$?$H$(%^%k%A%P%$%H%P%C%U%!$G$"$C$F$b!"(B
128$B$+$i(B255$B$N%f%K%P%$%HJ8;z%3!<%I$O%^%k%A%P%$%HJ8;z$K$OJQ49$7$J$$!#(B
@pxref{Converting Representations}$B!#(B

@c If @var{inherit} is non-@code{nil}, then the inserted characters inherit
@c sticky text properties from the two characters before and after the
@c insertion point.  @xref{Sticky Properties}.
@var{inherit}$B$,(B@code{nil}$B0J30$G$"$k$H!"A^F~$5$l$?J8;z$O!"(B
$BA^F~2U=j$NA08e$N(B2$B$D$NJ8;z$+$i%9%F%#%C%-%F%-%9%HB0@-$r7Q>5$9$k!#(B
@end defun

@defun insert-buffer-substring from-buffer-or-name &optional start end
@c This function inserts a portion of buffer @var{from-buffer-or-name}
@c (which must already exist) into the current buffer before point.  The
@c text inserted is the region from @var{start} and @var{end}.  (These
@c arguments default to the beginning and end of the accessible portion of
@c that buffer.)  This function returns @code{nil}.
$B$3$N4X?t$O!"%P%C%U%!(B@var{from-buffer-or-name}$B!J4{B8$G$"$k$3$H!K$NItJ,$r(B
$B%+%l%s%H%P%C%U%!$N%]%$%s%H$N$^$($XA^F~$9$k!#(B
$BA^F~$5$l$k%F%-%9%H$O(B@var{start}$B$+$i(B@var{end}$B$^$G$NNN0h$G$"$k!#(B
$B!J$3$l$i$N0z?t$N%G%U%)%k%H$O!"Ev3:%P%C%U%!$N;2>H2DG=ItJ,$N@hF,$HKvHx$G$"$k!#!K(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c In this example, the form is executed with buffer @samp{bar} as the
@c current buffer.  We assume that buffer @samp{bar} is initially empty.
$B$3$NNc$G$O!"%P%C%U%!(B@samp{bar}$B$r%+%l%s%H%P%C%U%!$H$7$F%U%)!<%`$r<B9T$9$k!#(B
$B%P%C%U%!(B@samp{bar}$B$O:G=i$O6u$G$"$k$H2>Dj$9$k!#(B

@example
@group
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------
@end group

@group
(insert-buffer-substring "foo" 1 20)
     @result{} nil

---------- Buffer: bar ----------
We hold these truth@point{}
---------- Buffer: bar ----------
@end group
@end example
@end defun

@c   @xref{Sticky Properties}, for other insertion functions that inherit
@c text properties from the nearby text in addition to inserting it.
@c Whitespace inserted by indentation functions also inherits text
@c properties.
$BA^F~$K2C$($F<~$j$N%F%-%9%H$+$i%F%-%9%HB0@-$r7Q>5$9$kB>$N4X?t$K$D$$$F$O!"(B
@xref{Sticky Properties}$B!#(B
$B;z2<$24X?t$,A^F~$7$?GrJ8;z$b%F%-%9%HB0@-$r7Q>5$7$^$9!#(B

@node Commands for Insertion
@c @section User-Level Insertion Commands
@section $B%f!<%6!<%l%Y%k$NA^F~%3%^%s%I(B

@c   This section describes higher-level commands for inserting text,
@c commands intended primarily for the user but useful also in Lisp
@c programs.
$BK\@a$G$O!"%F%-%9%H$rA^F~$9$k>e0L%l%Y%k$N%3%^%s%I$K$D$$$F=R$Y$^$9!#(B
$B$3$l$i$O(BLisp$B%W%m%0%i%`$G$bM-MQ$G$9$,<g$K%f!<%6!<8~$1$N%3%^%s%I$G$9!#(B

@c @deffn Command insert-buffer from-buffer-or-name
@deffn $B%3%^%s%I(B insert-buffer from-buffer-or-name
@c This command inserts the entire contents of @var{from-buffer-or-name}
@c (which must exist) into the current buffer after point.  It leaves
@c the mark after the inserted text.  The value is @code{nil}.
$B$3$N%3%^%s%I$O!"(B@var{from-buffer-or-name}$B!J4{B8$G$"$k$3$H!K$NA4FbMF$r(B
$B%+%l%s%H%P%C%U%!$N%]%$%s%H$N$&$7$m$KA^F~$9$k!#(B
$BA^F~$5$l$?%F%-%9%H$N$&$7$m$K%^!<%/$rCV$/!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B
@end deffn

@c @deffn Command self-insert-command count
@deffn $B%3%^%s%I(B self-insert-command count
@c @cindex character insertion
@c @cindex self-insertion
@cindex $BJ8;z$NA^F~(B
@cindex $B<+8JA^F~(B
@c This command inserts the last character typed; it does so @var{count}
@c times, before point, and returns @code{nil}.  Most printing characters
@c are bound to this command.  In routine use, @code{self-insert-command}
@c is the most frequently called function in Emacs, but programs rarely use
@c it except to install it on a keymap.
$B$3$N%3%^%s%I$O!":G8e$KBG$?$l$?J8;z$rA^F~$9$k!#(B
$B%]%$%s%H$N$^$($K(B@var{count}$B2sA^F~$7$F(B@code{nil}$B$rJV$9!#(B
$B$[$H$s$I$N0u;zJ8;z$O$3$N%3%^%s%I$K%P%$%s%I$5$l$F$$$k!#(B
$BIaDL$N>u67$G$O!"(B@code{self-insert-command}$B$O(B
Emacs$B$K$*$$$F$b$C$H$bIQHK$K8F$S=P$5$l$k4X?t$G$"$k$,!"(B
$B%W%m%0%i%`$G$O%-!<%^%C%W$KEPO?$9$k0J30$K$O$[$H$s$I;H$o$J$$!#(B

@c In an interactive call, @var{count} is the numeric prefix argument.
$BBPOCE*$K8F$P$l$k$H!"(B@var{count}$B$O?tCMA0CV0z?t$G$"$k!#(B

@c This command calls @code{auto-fill-function} whenever that is
@c non-@code{nil} and the character inserted is a space or a newline
@c (@pxref{Auto Filling}).
$B$3$N%3%^%s%I$O!"A^F~$7$?J8;z$,6uGr$d2~9T$G$"$k$H!"(B
@code{auto-fill-function}$B$,(B@code{nil}$B0J30$G$"$k$H(B
@code{auto-fill-function}$B$r8F$S=P$9(B
$B!J(B@pxref{Auto Filling}$B!K!#(B

@c @c Cross refs reworded to prevent overfull hbox.  --rjc 15mar92
@c This command performs abbrev expansion if Abbrev mode is enabled and
@c the inserted character does not have word-constituent
@c syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
$B$3$N%3%^%s%I$O!"N,8l!J(Babbrev$B!K%b!<%I$,%*%s$G$"$j!"$+$D!"(B
$BA^F~$7$?J8;z$,C18l9=@.9=J8$G$J$$$H!"N,8lE83+$r9T$&!#(B
$B!J(B@ref{Abbrevs}$B$H(B@pxref{Syntax Class Table}$B!#!K(B

@c This is also responsible for calling @code{blink-paren-function} when
@c the inserted character has close parenthesis syntax (@pxref{Blinking}).
$BA^F~$7$?J8;z$,JD$83g8L9=J8$G$"$k$H$-$K(B
@code{blink-paren-function}$B$r8F$S=P$9@UG$$b;}$D(B
$B!J(B@pxref{Blinking}$B!K!#(B
@end deffn

@c @deffn Command newline &optional number-of-newlines 
@deffn $B%3%^%s%I(B newline &optional number-of-newlines 
@c This command inserts newlines into the current buffer before point.
@c If @var{number-of-newlines} is supplied, that many newline characters
@c are inserted.
$B$3$N%3%^%s%I$O!"%+%l%s%H%P%C%U%!$N%]%$%s%H$N$^$($K2~9T$rA^F~$9$k!#(B
@var{number-of-newlines}$B$r;XDj$9$k$H!"$=$N8D?t$@$12~9TJ8;z$rA^F~$9$k!#(B

@c @cindex newline and Auto Fill mode
@cindex $B2~9T$H<+F05M$a9~$_!J(Bauto-fill$B!K%b!<%I(B
@c This function calls @code{auto-fill-function} if the current column
@c number is greater than the value of @code{fill-column} and
@c @var{number-of-newlines} is @code{nil}.  Typically what
@c @code{auto-fill-function} does is insert a newline; thus, the overall
@c result in this case is to insert two newlines at different places: one
@c at point, and another earlier in the line.  @code{newline} does not
@c auto-fill if @var{number-of-newlines} is non-@code{nil}.
$B$3$N4X?t$O!"8=:_$N%3%i%`HV9f$,(B@code{fill-column}$B$NCM$h$j$bBg$-$/(B
@var{number-of-newlines}$B$,(B@code{nil}$B$G$"$k$H(B
@code{auto-fill-function}$B$r8F$S=P$9!#(B
@code{auto-fill-function}$B$NE57?E*$J;E;v$O2~9T$rA^F~$9$k$3$H$G$"$k!#(B
$B$3$3$G$NA4BN$H$7$F$N8z2L$O!"2~9T$r(B2$B$D$N0[$J$k0LCV!"$D$^$j!"(B
$B%]%$%s%H0LCV$H9T$N$^$($N2U=j$KA^F~$9$k$3$H$G$"$k!#(B
@code{newline}$B$O!"(B@var{number-of-newlines}$B$,(B@code{nil}$B0J30$G$"$k$H(B
$B<+F05M$a9~$_$r9T$o$J$$!#(B

@c This command indents to the left margin if that is not zero.
@c @xref{Margins}.
$B$3$N%3%^%s%I$O!":8C<$NM>Gr$,(B0$B0J30$G$"$k$H$=$NJ,$@$1;z2<$2$9$k!#(B
@pxref{Margins}$B!#(B

@c The value returned is @code{nil}.  In an interactive call, @var{count}
@c is the numeric prefix argument.
$BLa$jCM$O(B@code{nil}$B$G$"$k!#(B
$BBPOCE*$K8F$P$l$k$H!"(B@var{count}$B$O?tCMA0CV0z?t$G$"$k!#(B
@end deffn

@c @deffn Command split-line
@deffn $B%3%^%s%I(B split-line
@c This command splits the current line, moving the portion of the line
@c after point down vertically so that it is on the next line directly
@c below where it was before.  Whitespace is inserted as needed at the
@c beginning of the lower line, using the @code{indent-to} function.
@c @code{split-line} returns the position of point.
$B$3$N%3%^%s%I$O!"9T$N%]%$%s%H$N$&$7$m$NItJ,$r?bD>$K9_$m$7$F(B
$BJQ99A0$N??2<$K9T$r0\F0$9$k$3$H$G8=:_9T$rJ,3d$9$k!#(B
$B4X?t(B@code{indent-to}$B$rMQ$$$F!"9_$m$7$?9T$N@hF,$KI,MW$K1~$8$FGrJ8;z$rA^F~$9$k!#(B

@c Programs hardly ever use this function.
$B%W%m%0%i%`$G$O$^$C$?$/$3$N4X?t$r;H$o$J$$!#(B
@end deffn

@defvar overwrite-mode
@c This variable controls whether overwrite mode is in effect.  The value
@c should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
@c or @code{nil}.  @code{overwrite-mode-textual} specifies textual
@c overwrite mode (treats newlines and tabs specially), and
@c @code{overwrite-mode-binary} specifies binary overwrite mode (treats
@c newlines and tabs like any other characters).
$B$3$NJQ?t$O!">e=q$-!J(Boverwrite$B!K%b!<%I$,%*%s$+$I$&$+$r@)8f$9$k!#(B
$B$3$NCM$O!"(B@code{overwrite-mode-textual}$B!"(B@code{overwrite-mode-binary}$B!"(B
@code{nil}$B$N$$$:$l$+$G$"$k$3$H!#(B
@code{overwrite-mode-textual}$B$O!"%F%-%9%H$N>e=q$-%b!<%I(B
$B!J2~9T$H%?%V$rFCJL$K07$&!K$r;XDj$7!"(B
@code{overwrite-mode-binary}$B$O!"%P%$%J%j$N>e=q$-%b!<%I(B
$B!J2~9T$d%?%V$bB>$NJ8;z$HF1MM$K07$&!K$r;XDj$9$k!#(B
@end defvar

@node Deletion
@c @section Deleting Text
@section $B%F%-%9%H$N:o=|(B

@c @cindex deletion vs killing
@cindex $B:o=|$H%-%k(B
@c   Deletion means removing part of the text in a buffer, without saving
@c it in the kill ring (@pxref{The Kill Ring}).  Deleted text can't be
@c yanked, but can be reinserted using the undo mechanism (@pxref{Undo}).
@c Some deletion functions do save text in the kill ring in some special
@c cases.
$B:o=|$H$O!"%P%C%U%!Fb$N%F%-%9%H$N$"$kItJ,$r%-%k%j%s%0(B
$B!J(B@pxref{The Kill Ring}$B!K$KJ]B8$;$:$K<h$j$5$k$3$H$G$9!#(B
$B:o=|$7$?%F%-%9%H$O%d%s%/$O$G$-$^$;$s$,!"(B
$B%"%s%I%%5!9=!J(B@pxref{Undo}$B!K$r;H$C$F:FEYA^F~$G$-$^$9!#(B
$BFCJL$J>l9g$K$O%-%k%j%s%0$K%F%-%9%H$rJ]B8$9$k:o=|4X?t$b$"$j$^$9!#(B

@c   All of the deletion functions operate on the current buffer, and all
@c return a value of @code{nil}.
$B$9$Y$F$N:o=|4X?t$O%+%l%s%H%P%C%U%!$K:nMQ$7!"(B@code{nil}$B$NCM$rJV$7$^$9!#(B

@c @deffn Command erase-buffer
@deffn $B%3%^%s%I(B erase-buffer
@c This function deletes the entire text of the current buffer, leaving it
@c empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
@c error.  Otherwise, it deletes the text without asking for any
@c confirmation.  It returns @code{nil}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$+$iA4%F%-%9%H$r:o=|$7$F6u$K$9$k!#(B
$B%P%C%U%!$,FI$_=P$7@lMQ$G$"$k$H!"%(%i!<(B@code{buffer-read-only}$B$rDLCN$9$k!#(B
$B$5$b$J$1$l$P!"$$$C$5$$3NG'$r<h$i$:$K%F%-%9%H$r:o=|$9$k!#(B
@code{nil}$B$rJV$9!#(B

@c Normally, deleting a large amount of text from a buffer inhibits further
@c auto-saving of that buffer ``because it has shrunk''.  However,
@c @code{erase-buffer} does not do this, the idea being that the future
@c text is not really related to the former text, and its size should not
@c be compared with that of the former text.
$B%P%C%U%!$+$iB?NL$N%F%-%9%H$r:o=|$9$k$H!"DL>o!"(B
$B!X%P%C%U%!$,=L>.$7$?!Y$H$7$F$=$N%P%C%U%!$N<+F0J]B8$r6X;_$9$k!#(B
$B$7$+$7!"(B@code{erase-buffer}$B$O$3$&$7$J$$!#(B
$B$3$l$^$G$N%F%-%9%H$H>-Mh$N%F%-%9%H$K$O4XO"$,$J$/!"(B
$B$3$l$^$G$N%F%-%9%H$N%5%$%:$HHf3S$9$Y$-$G$J$$$H9M$($k$+$i$G$"$k!#(B
@end deffn

@c @deffn Command delete-region start end
@deffn $B%3%^%s%I(B delete-region start end
@c This command deletes the text in the current buffer in the region
@c defined by @var{start} and @var{end}.  The value is @code{nil}.  If
@c point was inside the deleted region, its value afterward is @var{start}.
@c Otherwise, point relocates with the surrounding text, as markers do.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$k%+%l%s%H%P%C%U%!$N(B
$B%F%-%9%H$r:o=|$9$k!#(B
$BLa$jCM$O(B@code{nil}$B$G$"$k!#(B
$B:o=|$5$l$?NN0h$NFbB&$K%]%$%s%H$,$"$k$H!"(B
$B$=$NCM$O:o=|8e$K$O(B@var{start}$B$K$J$k!#(B
$B$5$b$J$1$l$P!"%^!<%+$HF1MM$K%]%$%s%H$O(B
$B<~$j$N%F%-%9%H$KN1$^$k$h$&$K:FG[CV$5$l$k!#(B
@end deffn

@c @deffn Command delete-char count &optional killp
@deffn $B%3%^%s%I(B delete-char count &optional killp
@c This command deletes @var{count} characters directly after point, or
@c before point if @var{count} is negative.  If @var{killp} is
@c non-@code{nil}, then it saves the deleted characters in the kill ring.
$B$3$N%3%^%s%I$O!"%]%$%s%H$ND>8e$N!"$"$k$$$O!"(B
@var{count}$B$,Ii$G$"$k$H%]%$%s%H$ND>A0$N(B@var{count}$B8D$NJ8;z$r:o=|$9$k!#(B
@var{killp}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B:o=|$7$?J8;z$r%-%k%j%s%0$KJ]B8$9$k!#(B

@c In an interactive call, @var{count} is the numeric prefix argument, and
@c @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
@c argument is supplied, the text is saved in the kill ring.  If no prefix
@c argument is supplied, then one character is deleted, but not saved in
@c the kill ring.
$BBPOCE*$K8F$P$l$k$H!"(B@var{count}$B$O?tCMA0CV0z?t$G$"$j!"(B
@var{killp}$B$OL$=hM}$NA0CV0z?t$G$"$k!#(B
$B$D$^$j!"A0CV0z?t$r;XDj$9$k$H!"%F%-%9%H$r%-%k%j%s%0$KJ]B8$9$k!#(B
$BA0CV0z?t$r;XDj$7$J$$$H(B1$BJ8;z$@$1$r:o=|$9$k$,!"(B
$B%-%k%j%s%0$K$OJ]B8$7$J$$!#(B

@c The value returned is always @code{nil}.
$BLa$jCM$O$D$M$K(B@code{nil}$B$G$"$k!#(B
@end deffn

@c @deffn Command delete-backward-char count &optional killp
@deffn $B%3%^%s%I(B delete-backward-char count &optional killp
@c @cindex delete previous char
@cindex $BD>A0$NJ8;z$r:o=|(B
@c This command deletes @var{count} characters directly before point, or
@c after point if @var{count} is negative.  If @var{killp} is
@c non-@code{nil}, then it saves the deleted characters in the kill ring.
$B$3$N%3%^%s%I$O!"%]%$%s%H$ND>A0$N!"$"$k$$$O!"(B
@var{count}$B$,Ii$G$"$k$H%]%$%s%H$ND>8e$N(B@var{count}$B8D$NJ8;z$r:o=|$9$k!#(B
@var{killp}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B:o=|$7$?J8;z$r%-%k%j%s%0$KJ]B8$9$k!#(B

@c In an interactive call, @var{count} is the numeric prefix argument, and
@c @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
@c argument is supplied, the text is saved in the kill ring.  If no prefix
@c argument is supplied, then one character is deleted, but not saved in
@c the kill ring.
$BBPOCE*$K8F$P$l$k$H!"(B@var{count}$B$O?tCMA0CV0z?t$G$"$j!"(B
@var{killp}$B$OL$=hM}$NA0CV0z?t$G$"$k!#(B
$B$D$^$j!"A0CV0z?t$r;XDj$9$k$H!"%F%-%9%H$r%-%k%j%s%0$KJ]B8$9$k!#(B
$BA0CV0z?t$r;XDj$7$J$$$H(B1$BJ8;z$@$1$r:o=|$9$k$,!"(B
$B%-%k%j%s%0$K$OJ]B8$7$J$$!#(B

@c The value returned is always @code{nil}.
$BLa$jCM$O$D$M$K(B@code{nil}$B$G$"$k!#(B
@end deffn

@c @deffn Command backward-delete-char-untabify count &optional killp
@deffn $B%3%^%s%I(B backward-delete-char-untabify count &optional killp
@c @cindex tab deletion
@cindex $B%?%V$N:o=|(B
@c This command deletes @var{count} characters backward, changing tabs
@c into spaces.  When the next character to be deleted is a tab, it is
@c first replaced with the proper number of spaces to preserve alignment
@c and then one of those spaces is deleted instead of the tab.  If
@c @var{killp} is non-@code{nil}, then the command saves the deleted
@c characters in the kill ring.
$B$3$N%3%^%s%I$O!"%?%V$r6uGr$K$+$($J$,$i8e8~$-$K(B@var{count}$B8D$NJ8;z$r:o=|$9$k!#(B
$B$D$.$K:o=|$9$kJ8;z$,%?%V$G$"$k$H!"$^$:%?%V$rG[CV$rJ]$D$@$1$NEy2A$J8D?t$N(B
$B6uGr$KCV49$7$F$+$i!"%?%V$N$+$o$j$K$=$l$i$N6uGr$r:o=|$9$k!#(B
@var{killp}$B$,(B@code{nil}$B0J30$G$"$k$H!"$3$N%3%^%s%I$O(B
$B:o=|$7$?J8;z$r%-%k%j%s%0$KJ]B8$9$k!#(B

@c Conversion of tabs to spaces happens only if @var{count} is positive.
@c If it is negative, exactly @minus{}@var{count} characters after point
@c are deleted.
@var{count}$B$,@5$G$"$k>l9g$K8B$C$F!"%?%V$r6uGr$KJQ49$9$k!#(B
@var{count}$B$,Ii$G$"$k$H!"%]%$%s%H$N$&$7$m$N$A$g$&$I(B
@minus{}@var{count}$B8D$NJ8;z$r:o=|$9$k!#(B

@c In an interactive call, @var{count} is the numeric prefix argument, and
@c @var{killp} is the unprocessed prefix argument.  Therefore, if a prefix
@c argument is supplied, the text is saved in the kill ring.  If no prefix
@c argument is supplied, then one character is deleted, but not saved in
@c the kill ring.
$BBPOCE*$K8F$P$l$k$H!"(B@var{count}$B$O?tCMA0CV0z?t$G$"$j!"(B
@var{killp}$B$OL$=hM}$NA0CV0z?t$G$"$k!#(B
$B$D$^$j!"A0CV0z?t$r;XDj$9$k$H!"%F%-%9%H$r%-%k%j%s%0$KJ]B8$9$k!#(B
$BA0CV0z?t$r;XDj$7$J$$$H(B1$BJ8;z$@$1$r:o=|$9$k$,!"(B
$B%-%k%j%s%0$K$OJ]B8$7$J$$!#(B

@c The value returned is always @code{nil}.
$BLa$jCM$O$D$M$K(B@code{nil}$B$G$"$k!#(B
@end deffn

@defopt backward-delete-char-untabify-method
@tindex backward-delete-char-untabify-method
@c This option specifies how @code{backward-delete-char-untabify} should
@c deal with whitespace.  Possible values include @code{untabify}, the
@c default, meaning convert a tab to many spaces and delete one;
@c @code{hungry}, meaning delete all the whitespace characters before point
@c with one command, and @code{nil}, meaning do nothing special for
@c whitespace characters.
$B$3$N%*%W%7%g%s$O!"(B@code{backward-delete-char-untabify}$B$G$N(B
$BGrJ8;z$N07$$J}$r;XDj$9$k!#(B
$B2DG=$JCM$O!"%?%V$r6uGr$KJQ49$7$F$+$i6uGr$r:o=|$9$k$3$H$r0UL#$9$k(B
$B%G%U%)%k%H$N(B@code{untabify}$B!"(B
1$B2s$N8F$S=P$7$G%]%$%s%H$N$^$($K$"$kGrJ8;z$r$9$Y$F:o=|$9$k$3$H$r0UL#$9$k(B
@code{hungry}$B!"(B
$BGrJ8;z$KBP$7$FFCJL$J$3$H$r$7$J$$$3$H$r0UL#$9$k(B@code{nil}$B$G$"$k!#(B
@end defopt

@node User-Level Deletion
@c @section User-Level Deletion Commands
@section $B%f!<%6!<%l%Y%k$N:o=|%3%^%s%I(B

@c   This section describes higher-level commands for deleting text,
@c commands intended primarily for the user but useful also in Lisp
@c programs.
$BK\@a$G$O!"%F%-%9%H$r:o=|$9$k>e0L%l%Y%k$N%3%^%s%I$K$D$$$F=R$Y$^$9!#(B
$B$3$l$i$O(BLisp$B%W%m%0%i%`$G$bM-MQ$G$9$,<g$K%f!<%6!<8~$1$N%3%^%s%I$G$9!#(B

@c @deffn Command delete-horizontal-space
@deffn $B%3%^%s%I(B delete-horizontal-space
@c @cindex deleting whitespace
@cindex $BGrJ8;z$N:o=|(B
@c This function deletes all spaces and tabs around point.  It returns
@c @code{nil}.
$B$3$N4X?t$O!"%]%$%s%H$N<~$j$N6uGr$d%?%V$r$9$Y$F:o=|$9$k!#(B
@code{nil}$B$rJV$9!#(B

@c In the following examples, we call @code{delete-horizontal-space} four
@c times, once on each line, with point between the second and third
@c characters on the line each time.
$B$D$.$NNc$G$O!"Kh2s%]%$%s%H$r(B2$BHVL\$H(B3$BHVL\$NJ8;z$N$"$$$@$KCV$$$F!"(B
$B3F9T$K$D$-(B1$B2s$:$D(B@code{delete-horizontal-space}$B$r7W(B4$B2s8F$S=P$9!#(B

@example
@group
---------- Buffer: foo ----------
I @point{}thought
I @point{}     thought
We@point{} thought
Yo@point{}u thought
---------- Buffer: foo ----------
@end group

@group
(delete-horizontal-space)   ; @r{Four times.}
     @result{} nil

---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------
@end group
@end example
@end deffn

@c @deffn Command delete-indentation &optional join-following-p 
@deffn $B%3%^%s%I(B delete-indentation &optional join-following-p 
@c This function joins the line point is on to the previous line, deleting
@c any whitespace at the join and in some cases replacing it with one
@c space.  If @var{join-following-p} is non-@code{nil},
@c @code{delete-indentation} joins this line to the following line
@c instead.  The function returns @code{nil}.
$B$3$N4X?t$O!"%]%$%s%H$,$"$k9T$r$=$N$^$($N9T$KO"7k$9$k!#(B
$BO"7k2U=j$NGrJ8;z$O:o=|$7!">l9g$K$h$C$F$O6uGr(B1$B8D$KCV$-49$($k!#(B
@var{join-following-p}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{delete-indentation}$B$O!"$3$N9T$r8eB3$N9T$KO"7k$9$k!#(B
$B4X?t$O(B@code{nil}$B$rJV$9!#(B

@c If there is a fill prefix, and the second of the lines being joined
@c starts with the prefix, then @code{delete-indentation} deletes the
@c fill prefix before joining the lines.  @xref{Margins}.
$B5M$a9~$_@\F,<-$,$"$j!"$+$D!"O"7kBP>]$N(B2$BHVL\$N9T$,(B
$B$=$N@\F,<-$G;O$^$C$F$$$k>l9g$K$O!"(B
@code{delete-indentation}$B$OO"7k$9$k$^$($K5M$a9~$_@\F,<-$r:o=|$9$k!#(B
@pxref{Margins}$B!#(B

@c In the example below, point is located on the line starting
@c @samp{events}, and it makes no difference if there are trailing spaces
@c in the preceding line.
$B0J2<$NNc$G$O!"%]%$%s%H$O(B@samp{events}$B$G;O$^$k9T$K$"$j!"(B
$B$=$N$^$($N9T$N9TKv$K6uGr$,$"$C$F$b0c$$$O$J$$!#(B

@smallexample
@group
---------- Buffer: foo ----------
When in the course of human
@point{}    events, it becomes necessary
---------- Buffer: foo ----------
@end group

(delete-indentation)
     @result{} nil

@group
---------- Buffer: foo ----------
When in the course of human@point{} events, it becomes necessary
---------- Buffer: foo ----------
@end group
@end smallexample

@c After the lines are joined, the function @code{fixup-whitespace} is
@c responsible for deciding whether to leave a space at the junction.
$B9T$rO"7k$7$?$"$H!"(B
$B4X?t(B@code{fixup-whitespace}$B$K$O!"(B
$BO"7k2U=j$K6uGr$rCV$/$+$I$&$+$r7hDj$9$k@UG$$,$"$k!#(B
@end deffn

@defun fixup-whitespace
@c This function replaces all the whitespace surrounding point with either
@c one space or no space, according to the context.  It returns @code{nil}.
$B$3$N4X?t$O!"J8L.$K1~$8$F!"(B
$B%]%$%s%H$r0O$`GrJ8;z$9$Y$F$r(B1$B$D$N6uGr$KCV49$9$k$+$^$C$?$/$J$/$9!#(B
@code{nil}$B$rJV$9!#(B

@c At the beginning or end of a line, the appropriate amount of space is
@c none.  Before a character with close parenthesis syntax, or after a
@c character with open parenthesis or expression-prefix syntax, no space is
@c also appropriate.  Otherwise, one space is appropriate.  @xref{Syntax
@c Class Table}.
$B9T$N@hF,$dKvHx$G$O!"6uGr$NE,@Z$JNL$O(B0$B$G$"$k!#(B
$BJD$83g8L9=J8$NJ8;z$N$^$($d!"(B
$B3+$-3g8L9=J8$d<0A0CV;R9=J8$NJ8;z$N$&$7$m$G$b6uGr$O$J$$$[$&$,E,$7$F$$$k!#(B
$B$=$l0J30$G$O!"6uGr(B1$B8D$,E,$7$F$$$k!#(B
@pxref{Syntax Class Table}$B!#(B

@c In the example below, @code{fixup-whitespace} is called the first time
@c with point before the word @samp{spaces} in the first line.  For the
@c second invocation, point is directly after the @samp{(}.
$B0J2<$NNc$G$O!":G=i$N9T$NC18l(B@samp{spaces}$B$N$^$($K%]%$%s%H$,$"$k$H$-$K(B
$B:G=i$K(B@code{fixup-whitespace}$B$,8F$P$l$k!#(B
2$BEYL\$K8F$P$l$k$H$-$K$O!"%]%$%s%H$O(B@samp{(}$B$ND>8e$K$"$k!#(B

@smallexample
@group
---------- Buffer: foo ----------
This has too many     @point{}spaces
This has too many spaces at the start of (@point{}   this list)
---------- Buffer: foo ----------
@end group

@group
(fixup-whitespace)
     @result{} nil
(fixup-whitespace)
     @result{} nil
@end group

@group
---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
@end group
@end smallexample
@end defun

@c @deffn Command just-one-space
@deffn $B%3%^%s%I(B just-one-space
@comment !!SourceFile simple.el
@c This command replaces any spaces and tabs around point with a single
@c space.  It returns @code{nil}.
$B$3$N%3%^%s%I$O!"%]%$%s%H$N<~$j$N$9$Y$F$N6uGr$d%?%V$r(B1$B8D$N6uGr$KCV$-49$($k!#(B
@code{nil}$B$rJV$9!#(B
@end deffn

@c @deffn Command delete-blank-lines
@deffn $B%3%^%s%I(B delete-blank-lines
@c This function deletes blank lines surrounding point.  If point is on a
@c blank line with one or more blank lines before or after it, then all but
@c one of them are deleted.  If point is on an isolated blank line, then it
@c is deleted.  If point is on a nonblank line, the command deletes all
@c blank lines following it.
$B$3$N4X?t$O!"%]%$%s%H$r0O$`6u9T$r:o=|$9$k!#(B
$BA08e$KJ#?t$N6u9T$,$"$k6u9T$K%]%$%s%H$,$"$k>l9g!"(B
1$B$D$N6u9T$r;D$7$F$=$l0J30$O$9$Y$F:o=|$9$k!#(B
$B8IN)$7$?(B1$B$D$N6u9T$K%]%$%s%H$,$"$k>l9g$K$O!"$=$N9T$r:o=|$9$k!#(B
$B6u9T$G$J$$9T$K%]%$%s%H$,$"$k>l9g$K$O!"(B
$B$=$N9T$N$&$7$m$K$"$k6u9T$r$9$Y$F:o=|$9$k!#(B

@c A blank line is defined as a line containing only tabs and spaces.
$B6u9T$H$O!"%?%V$d6uGr$N$_$+$i@.$k9T$HDj5A$9$k!#(B

@c @code{delete-blank-lines} returns @code{nil}.
@code{delete-blank-lines}$B$O(B@code{nil}$B$rJV$9!#(B
@end deffn

@node The Kill Ring
@c @section The Kill Ring
@section $B%-%k%j%s%0(B
@c @cindex kill ring
@cindex $B%-%k%j%s%0(B

@c   @dfn{Kill functions} delete text like the deletion functions, but save
@c it so that the user can reinsert it by @dfn{yanking}.  Most of these
@c functions have @samp{kill-} in their name.  By contrast, the functions
@c whose names start with @samp{delete-} normally do not save text for
@c yanking (though they can still be undone); these are ``deletion''
@c functions.
@dfn{$B%-%k4X?t(B}$B$O:o=|4X?t$N$h$&$K%F%-%9%H$r:o=|$7$^$9$,!"(B
$B%f!<%6!<$,(B@dfn{$B%d%s%/(B}$B!J(Byank$B!K$G:FEYA^F~$G$-$k$h$&$KJ]B8$7$^$9!#(B
$B$3$l$i$N4X?t$NB?$/$O!"$=$NL>A0$K(B@samp{kill-}$B$,$"$j$^$9!#(B
$BBP>HE*$K!"(B@samp{delete-}$B$G;O$^$kL>A0$N4X?t$O!"(B
$B%d%s%/$G$-$k$h$&$K%F%-%9%H$rJ]B8$7$^$;$s!J%"%s%I%%$O$G$-$k!K!#(B
$B$=$l$i$O!X:o=|!Y4X?t$G$9!#(B

@c   Most of the kill commands are primarily for interactive use, and are
@c not described here.  What we do describe are the functions provided for
@c use in writing such commands.  You can use these functions to write
@c commands for killing text.  When you need to delete text for internal
@c purposes within a Lisp function, you should normally use deletion
@c functions, so as not to disturb the kill ring contents.
@c @xref{Deletion}.
$B%-%k%3%^%s%I$NB?$/$O<g$KBPOCE*$K;H$&$b$N$G$"$j!"(B
$B$3$3$G$O$=$l$i$K$D$$$F$O=R$Y$^$;$s!#(B
$B$3$3$G=R$Y$k$N$O!"$=$N$h$&$J%3%^%s%I$r=q$/$?$a$K;H$&4X?t$K$D$$$F$G$9!#(B
$B$3$l$i$N4X?t$OFI<T$,%F%-%9%H$r%-%k$9$k%3%^%s%I$r=q$/$?$a$K;H$($^$9!#(B
Lisp$B4X?t$K$*$$$FFbItL\E*$N$?$a$K%F%-%9%H$r:o=|$9$kI,MW$,$"$k$H$-$K$O!"(B
$B%-%k%j%s%0$NFbMF$rMp$5$J$$$h$&$KIaDL$O:o=|4X?t$rMQ$$$k$Y$-$G$9!#(B
@xref{Deletion}$B!#(B

@c   Killed text is saved for later yanking in the @dfn{kill ring}.  This
@c is a list that holds a number of recent kills, not just the last text
@c kill.  We call this a ``ring'' because yanking treats it as having
@c elements in a cyclic order.  The list is kept in the variable
@c @code{kill-ring}, and can be operated on with the usual functions for
@c lists; there are also specialized functions, described in this section,
@c that treat it as a ring.
$B%-%k$7$?%F%-%9%H$O$"$H$G%d%s%/$G$-$k$h$&$K(B
@dfn{$B%-%k%j%s%0(B}$B!J(Bkill ring$B!K$KJ]B8$5$l$^$9!#(B
$B$3$l$O!":G8e$K%-%k$7$?%F%-%9%H$@$1$G$J$/!"(B
$B:G6a%-%k$7$?$b$N$rB??tJ];}$9$k%j%9%H$G$9!#(B
$B$3$l$r!X%j%s%0!Y$H8F$V$N$O!"(B
$BMWAG$,=[4D$7$F$$$k$h$&$K%d%s%/$,07$&$+$i$G$9!#(B
$B$3$N%j%9%H$OJQ?t(B@code{kill-ring}$B$KJ];}$5$l$F$$$F!"(B
$B%j%9%H8~$1$NDL>o$N4X?t$GA`:n$G$-$^$9$,!"(B
$BK\@a$G=R$Y$k$h$&$K!"$=$l$r%j%s%0$H$7$F07$&FCJL$J4X?t$b$"$j$^$9!#(B

@c   Some people think this use of the word ``kill'' is unfortunate, since
@c it refers to operations that specifically @emph{do not} destroy the
@c entities ``killed''.  This is in sharp contrast to ordinary life, in
@c which death is permanent and ``killed'' entities do not come back to
@c life.  Therefore, other metaphors have been proposed.  For example, the
@c term ``cut ring'' makes sense to people who, in pre-computer days, used
@c scissors and paste to cut up and rearrange manuscripts.  However, it
@c would be difficult to change the terminology now.
$BC18l!X%-%k!Y$N;H$$J}$,ITE,Ev$@$H9M$($k?M!9$,$$$^$9!#(B
$B!X%-%k!Y$7$?$b$N$rFC$KGK2u(B@emph{$B$7$J$$(B}$BA`:n$rI=$9$?$a$K;H$C$F$$$k$+$i$G$9!#(B
$BF|>o@83h$K>H$i$7$F$_$k$H!";`$O915WE*$G$"$j!X%-%k!Y$7$?$b$N$,(B
$B@8$-JV$k$3$H$O$"$j$^$;$s!#(B
$B$7$?$,$C$F!"JL$N1#SH$bDs0F$5$l$F$$$^$9!#(B
$B$?$H$($P!"869F$rnw$G@Z$jE=$j$9$k$3$H$K47$l$F$$$?A07W;;5!@$Be$N?M!9$K$O(B
$B!X%+%C%H%j%s%0!Y$N$[$&$,0UL#$,DL$8$k$G$7$g$&!#(B
$B$7$+$7!"$$$^$5$iMQ8l$rJQ99$9$k$N$O:$Fq$G$9!#(B

@menu
* Kill Ring Concepts::     What text looks like in the kill ring.
* Kill Functions::         Functions that kill text.
* Yank Commands::          Commands that access the kill ring.
* Low-Level Kill Ring::	   Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
@end menu

@node Kill Ring Concepts
@comment  node-name,  next,  previous,  up
@c @subsection Kill Ring Concepts
@subsection $B%-%k%j%s%0$N35G0(B

@c   The kill ring records killed text as strings in a list, most recent
@c first.  A short kill ring, for example, might look like this:
$B%-%k%j%s%0$O!"$b$C$H$b:G6a$K%-%k$5$l$?$b$N$r@hF,$K$7$F!"(B
$B%-%k$5$l$?%F%-%9%H$rJ8;zNs$H$7$F%j%9%H$K5-O?$7$^$9!#(B
$B$?$H$($P!"C;$$%-%k%j%s%0$O$D$.$N$h$&$K$J$j$^$9!#(B

@example
("some text" "a different piece of text" "even older text")
@end example

@noindent
@c When the list reaches @code{kill-ring-max} entries in length, adding a
@c new entry automatically deletes the last entry.
$B%j%9%H$ND9$5$,(B@code{kill-ring-max}$B$KC#$9$k$H!"(B
$B?7$?$J9`L\$rDI2C$9$k$H<+F0E*$K:G8e$N9`L\$r:o=|$7$^$9!#(B

@c   When kill commands are interwoven with other commands, each kill
@c command makes a new entry in the kill ring.  Multiple kill commands in
@c succession build up a single kill-ring entry, which would be yanked as a
@c unit; the second and subsequent consecutive kill commands add text to
@c the entry made by the first one.
$B%-%k%3%^%s%I$,B>$N%3%^%s%I$H:.:_$9$k>l9g!"(B
$B3F%-%k%3%^%s%I$O%-%k%j%s%0$K?7$?$J9`L\$rDI2C$7$^$9!#(B
$BO"B3$7$?J#?t$N%-%k%3%^%s%I$O!"%-%k%j%s%0$K(B1$B$D$N9`L\$r:n$j$"$2!"(B
$B$=$l$r(B1$B8D$H$7$F%d%s%/$G$-$^$9!#(B
2$BHVL\0J9_$NO"B3$7$?%-%k%3%^%s%I$O!":G=i$N%-%k%3%^%s%I$,:n$C$?(B
$B9`L\$K%F%-%9%H$rDI2C$7$F$$$-$^$9!#(B

@c   For yanking, one entry in the kill ring is designated the ``front'' of
@c the ring.  Some yank commands ``rotate'' the ring by designating a
@c different element as the ``front.''  But this virtual rotation doesn't
@c change the list itself---the most recent entry always comes first in the
@c list.
$B%d%s%/$G$O!"%-%k%j%s%0$N(B1$B$D$N9`L\$r%j%s%0$N!X@hF,!Y$H$7$F6hJL$7$^$9!#(B
$B%j%s%0$NJL$N9`L\$r!X@hF,!Y$H;XDj$9$k$3$H$G%j%s%0$r!X2sE>!Y$9$k(B
$B%3%^%s%I$b$"$j$^$9!#(B

@node Kill Functions
@comment  node-name,  next,  previous,  up
@c @subsection Functions for Killing
@subsection $B%-%k8~$1$N4X?t(B

@c   @code{kill-region} is the usual subroutine for killing text.  Any
@c command that calls this function is a ``kill command'' (and should
@c probably have @samp{kill} in its name).  @code{kill-region} puts the
@c newly killed text in a new element at the beginning of the kill ring or
@c adds it to the most recent element.  It determines automatically (using
@c @code{last-command}) whether the previous command was a kill command,
@c and if so appends the killed text to the most recent entry.
@code{kill-region}$B$O!"%F%-%9%H$r%-%k$9$k$?$a$NIaDL$N%5%V%k!<%F%#%s$G$9!#(B
$B$3$N4X?t$r8F$S=P$9G$0U$N%3%^%s%I$O!X%-%k%3%^%s%I!Y$G$9(B
$B!J$=$NL>A0$K$O(B@samp{kill}$B$,$"$k$O$:!K!#(B
@code{kill-region}$B$O!"?7$?$K%-%k$5$l$?%F%-%9%H$r(B
$B%-%k%j%s%0$N@hF,$K?7$?$J9`L\$H$7$FDI2C$7$?$j!"(B
$B$b$C$H$b:G6a$N9`L\$K2C$($^$9!#(B
$B$^$($N%3%^%s%I$,%-%k%3%^%s%I$G$"$k$+$I$&$+$r(B
$B!J(B@code{last-command}$B$r;H$C$F!K<+F0E*$KH=Dj$7!"(B
$B$b$7$=$&$J$i$P!"%-%k$5$l$?%F%-%9%H$r$b$C$H$b:G6a$N9`L\$K2C$($^$9!#(B

@c @deffn Command kill-region start end
@deffn $B%3%^%s%I(B kill-region start end
@c This function kills the text in the region defined by @var{start} and
@c @var{end}.  The text is deleted but saved in the kill ring, along with
@c its text properties.  The value is always @code{nil}.
$B$3$N4X?t$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0h$N%F%-%9%H$r%-%k$9$k!#(B
$B%F%-%9%H$O:o=|$5$l$k$,!"%F%-%9%HB0@-$H$H$b$K%-%k%j%s%0$KJ]B8$5$l$k!#(B
$BCM$O$D$M$K(B@code{nil}$B$G$"$k!#(B

@c In an interactive call, @var{start} and @var{end} are point and
@c the mark.
$BBPOCE*$K8F$P$l$k$H!"(B@var{start}$B$H(B@var{end}$B$O%]%$%s%H$H%^!<%/$G$"$k!#(B

@c @c Emacs 19 feature
@c If the buffer is read-only, @code{kill-region} modifies the kill ring
@c just the same, then signals an error without modifying the buffer.  This
@c is convenient because it lets the user use all the kill commands to copy
@c text into the kill ring from a read-only buffer.
$B%P%C%U%!$,FI$_=P$7@lMQ$G$"$k$H!"(B
@code{kill-region}$B$O%-%k%j%s%0$rF1MM$KJQ99$9$k$,!"(B
$B%P%C%U%!$rJQ99$;$:$K%(%i!<$rDLCN$9$k!#(B
$BFI$_=P$7@lMQ%P%C%U%!$+$i%-%k%j%s%0$X%F%-%9%H$r%3%T!<$9$k$?$a$K!"(B
$B%f!<%6!<$O$9$Y$F$N%-%k%3%^%s%I$r;H$($k$N$G$3$l$OJXMx$G$"$k!#(B
@end deffn

@defopt kill-read-only-ok
@c If this option is non-@code{nil}, @code{kill-region} does not get an
@c error if the buffer is read-only.  Instead, it simply returns, updating
@c the kill ring but not changing the buffer.
$B$3$N%*%W%7%g%s$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{kill-region}$B$O!"%P%C%U%!$,FI$_=P$7@lMQ$G$"$C$F$b%(%i!<$H$7$J$$!#(B
$B$=$N$+$o$j$K!"%-%k%j%s%0$r99?7$7%P%C%U%!$OJQ99$;$:$KLa$k!#(B
@end defopt

@c @deffn Command copy-region-as-kill start end
@deffn $B%3%^%s%I(B copy-region-as-kill start end
@c This command saves the region defined by @var{start} and @var{end} on
@c the kill ring (including text properties), but does not delete the text
@c from the buffer.  It returns @code{nil}.  It also indicates the extent
@c of the text copied by moving the cursor momentarily, or by displaying a
@c message in the echo area.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0h$r(B
$B!J%F%-%9%HB0@-$H$H$b$K!K%-%k%j%s%0$KJ]B8$9$k$,!"(B
$B%P%C%U%!$+$i%F%-%9%H$r:o=|$7$J$$!#(B
@code{nil}$B$rJV$9!#(B
$B$^$?!"%+!<%=%k$r0l;~E*$K0\F0$7$F%3%T!<$7$?%F%-%9%H$NHO0O$r<($9$+!"(B
$B$"$k$$$O!"%(%3!<NN0h$K%a%C%;!<%8$rI=<($9$k!#(B

@c The command does not set @code{this-command} to @code{kill-region}, so a
@c subsequent kill command does not append to the same kill ring entry.
$B$3$N%3%^%s%I$O(B@code{this-command}$B$K(B@code{kill-region}$B$r@_Dj$7$J$$$N$G!"(B
$B$3$l0J9_$N%-%k%3%^%s%I$O%-%k%j%s%0$NF1$89`L\$K$O2C$($J$$!#(B

@c Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
@c support Emacs 18.  For newer Emacs versions, it is better to use
@c @code{kill-new} or @code{kill-append} instead.  @xref{Low-Level Kill
@c Ring}.
Emacs 18$BHG$G$b;H$&$D$b$j$,$J$$8B$j!"(B
Lisp$B%W%m%0%i%`$+$i$O(B@code{copy-region-as-kill}$B$r8F$P$J$$$3$H!#(B
Emacs$B$N?7$7$$HG$G$O!"$=$N$+$o$j$K(B@code{kill-new}$B$d(B@code{kill-append}$B$r(B
$B;H$&$[$&$,$h$$!#(B
@pxref{Low-Level Kill Ring}$B!#(B
@end deffn

@node Yank Commands
@comment  node-name,  next,  previous,  up
@c @subsection Functions for Yanking
@subsection $B%d%s%/8~$1$N4X?t(B

@c   @dfn{Yanking} means reinserting an entry of previously killed text
@c from the kill ring.  The text properties are copied too.
@dfn{$B%d%s%/(B}$B!J(Byank$B!K$H$O!"%-%k%j%s%0$+$i$^$($K%-%k$5$l$?%F%-%9%H$N9`L\$r(B
$B:FEYA^F~$9$k$3$H$G$9!#(B

@c @deffn Command yank &optional arg
@deffn $B%3%^%s%I(B yank &optional arg
@c @cindex inserting killed text
@cindex $B%-%k$5$l$?%F%-%9%H$NA^F~(B
@c This command inserts before point the text in the first entry in the
@c kill ring.  It positions the mark at the beginning of that text, and
@c point at the end.
$B$3$N%3%^%s%I$O!"%-%k%j%s%0$N@hF,9`L\$N%F%-%9%H$r(B
$B%]%$%s%H$N$^$($KA^F~$9$k!#(B
$B$=$N%F%-%9%H$N@hF,$K%^!<%/$rKvHx$K%]%$%s%H$rCV$/!#(B

@c If @var{arg} is a list (which occurs interactively when the user
@c types @kbd{C-u} with no digits), then @code{yank} inserts the text as
@c described above, but puts point before the yanked text and puts the mark
@c after it.
@var{arg}$B$,%j%9%H!JBPOCE*$J8F$S=P$7$G$O%f!<%6!<$,?t;zJ8;z$J$7$K(B
@kbd{C-u}$B$rBG$C$?$H$-!K$G$"$k$H!"(B@code{yank}$B$O>e$K=R$Y$?$h$&$K(B
$B%F%-%9%H$rA^F~$9$k$,!"%d%s%/$7$?%F%-%9%H$N@hF,$K%]%$%s%H$r(B
$BKvHx$K%^!<%/$rCV$/!#(B

@c If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
@c recently killed text---the @var{arg}th element of the kill ring list.
@var{arg}$B$,?t$G$"$k$H!"(B@code{yank}$B$O(B@var{arg}$BHVL\$N$b$C$H$b:G6a$K(B
$B%-%k$5$l$?%F%-%9%H!"$D$^$j!"%-%k%j%s%0%j%9%H$N(B@var{arg}$BHVL\$N9`L\$r(B
$BA^F~$9$k!#(B

@c @code{yank} does not alter the contents of the kill ring or rotate it.
@c It returns @code{nil}.
@code{yank}$B$O%-%k%j%s%0$NFbMF$rJQ99$7$?$j2sE>$7$J$$!#(B
@code{nil}$B$rJV$9!#(B
@end deffn

@c @deffn Command yank-pop arg
@deffn $B%3%^%s%I(B yank-pop arg
@c This command replaces the just-yanked entry from the kill ring with a
@c different entry from the kill ring.
$B$3$N%3%^%s%I$O!"%-%k%j%s%0$+$i%d%s%/$7$?9`L\$r(B
$B%-%k%j%s%0$NJL$N9`L\$GCV$-49$($k!#(B

@c This is allowed only immediately after a @code{yank} or another
@c @code{yank-pop}.  At such a time, the region contains text that was just
@c inserted by yanking.  @code{yank-pop} deletes that text and inserts in
@c its place a different piece of killed text.  It does not add the deleted
@c text to the kill ring, since it is already in the kill ring somewhere.
$B$3$l$O(B@code{yank}$B$dJL$N(B@code{yank-pop}$B$ND>8e$G$N$_5v$5$l$k!#(B
$B$=$N$h$&$J>l9g!"%j!<%8%g%s$K$O%d%s%/$7$?$P$+$j$N%F%-%9%H$,4^$^$l$k!#(B
@code{yank-pop}$B$O$=$N%F%-%9%H$r:o=|$7!"(B
$B$=$N0LCV$K%-%k$5$l$?JL$N%F%-%9%H$rA^F~$9$k!#(B
$B:o=|$7$?%F%-%9%H$O$9$G$K%-%k%j%s%0$N$I$3$+$K$"$k$N$G!"(B
$B%-%k%j%s%0$K$ODI2C$7$J$$!#(B

@c If @var{arg} is @code{nil}, then the replacement text is the previous
@c element of the kill ring.  If @var{arg} is numeric, the replacement is
@c the @var{arg}th previous kill.  If @var{arg} is negative, a more recent
@c kill is the replacement.
@var{arg}$B$,(B@code{nil}$B$G$"$k$H!"%-%k%j%s%0$N8E$$9`L\$GCV$-49$($k!#(B
@var{arg}$B$,?t$G$"$k$H!"(B@var{arg}$BHV8E$$%-%k$GCV$-49$($k!#(B
@var{arg}$B$,Ii$G$"$k$H!"$h$j:G6a$N%-%k$GCV$-49$($k!#(B

@c The sequence of kills in the kill ring wraps around, so that after the
@c oldest one comes the newest one, and before the newest one goes the
@c oldest.
$B%-%k%j%s%0Fb$G$N%-%k$N=gHV$O!"(B
$B:G8E$N$b$N$N$D$.$K:G?7$N$b$N$,$"$j!"(B
$B:G?7$N$b$N$N$^$($K:G8E$N$b$N$,$"$k$h$&$K@^$jJV$5$l$F$$$k!#(B

@c The return value is always @code{nil}.
$BLa$jCM$O$D$M$K(B@code{nil}$B$G$"$k!#(B
@end deffn

@node Low-Level Kill Ring
@c @subsection Low-Level Kill Ring
@subsection $B2<0L%l%Y%k$N%-%k%j%s%0(B

@c   These functions and variables provide access to the kill ring at a
@c lower level, but still convenient for use in Lisp programs, because they
@c take care of interaction with window system selections
@c (@pxref{Window System Selections}).
$B$3$l$i$N4X?t$HJQ?t$O!"2<0L%l%Y%k$G%-%k%j%s%0$r;2>H$9$k$?$a$N$b$N$G$9$,!"(B
Lisp$B%W%m%0%i%`$G;H$C$F$bJXMx$G$9!#(B
$B$3$l$i$O%&%#%s%I%&%7%9%F%`$N%;%l%/%7%g%s!J(B@pxref{Window System Selections}$B!K(B
$B$H$NAj8_:nMQ$NLLE]$r$_$F$/$l$k$+$i$G$9!#(B

@defun current-kill n &optional do-not-move
@c The function @code{current-kill} rotates the yanking pointer, which
@c designates the ``front'' of the kill ring, by @var{n} places (from newer
@c kills to older ones), and returns the text at that place in the ring.
$B4X?t(B@code{current-kill}$B$O!"%-%k%j%s%0$N!X@hF,!Y$H$7$F6hJL$9$k(B
$B%d%s%/%]%$%s%?$r!J?7$7$$%-%k$+$i8E$$%-%k$X8~$1$F!K(B@var{n}$B8DJ,2sE>$7!"(B
$B%j%s%0$N$=$N0LCV$N%F%-%9%H$rJV$9!#(B

@c If the optional second argument @var{do-not-move} is non-@code{nil},
@c then @code{current-kill} doesn't alter the yanking pointer; it just
@c returns the @var{n}th kill, counting from the current yanking pointer.
$B>JN,2DG=$JBh(B2$B0z?t(B@var{do-not-move}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{current-kill}$B$O!"%d%s%/%]%$%s%?$OJQ99$;$:$K!"(B
$B8=:_$N%d%s%/%]%$%s%?$+$i?t$($F(B@var{n}$BHVL\$N%-%k$rJV$9!#(B

@c If @var{n} is zero, indicating a request for the latest kill,
@c @code{current-kill} calls the value of
@c @code{interprogram-paste-function} (documented below) before consulting
@c the kill ring.
@var{n}$B$,(B0$B$G$"$k$H!"$b$C$H$b:G6a$N%-%k$rMW5a$9$k$3$H$rI=$7!"(B
@code{current-kill}$B$O!"%-%k%j%s%0$rD4$Y$k$^$($K(B
$B!J0J2<$K=R$Y$k!K(B@code{interprogram-paste-function}$B$NCM$r8F$S=P$9!#(B
@end defun

@defun kill-new string
@c This function puts the text @var{string} into the kill ring as a new
@c entry at the front of the ring.  It discards the oldest entry if
@c appropriate.  It also invokes the value of
@c @code{interprogram-cut-function} (see below).
$B$3$N4X?t$O!"%F%-%9%H(B@var{string}$B$r?7$?$J9`L\$H$7$F(B
$B%-%k%j%s%0$N@hF,$KCV$/!#(B
$BI,MW$J$i$P:G8E$N9`L\$rGK4~$9$k!#(B
@code{interprogram-cut-function}$B!J2<5-;2>H!K$NCM$b5/F0$9$k!#(B
@end defun

@defun kill-append string before-p
@c This function appends the text @var{string} to the first entry in the
@c kill ring.  Normally @var{string} goes at the end of the entry, but if
@c @var{before-p} is non-@code{nil}, it goes at the beginning.  This
@c function also invokes the value of @code{interprogram-cut-function} (see
@c below).
$B$3$N4X?t$O!"%-%k%j%s%0$N@hF,9`L\$K%F%-%9%H(B@var{string}$B$rDI2C$9$k!#(B
$BDL>o!"(B@var{string}$B$O$=$N9`L\$NKvHx$K2C$o$k$,!"(B
@var{before-p}$B$,(B@code{nil}$B0J30$G$"$k$H$=$N9`L\$N@hF,$K2C$o$k!#(B
$B$3$N4X?t$O!"(B@code{interprogram-cut-function}$B!J2<5-;2>H!K$NCM$b5/F0$9$k!#(B
@end defun

@defvar interprogram-paste-function
@c This variable provides a way of transferring killed text from other
@c programs, when you are using a window system.  Its value should be
@c @code{nil} or a function of no arguments.
$B$3$NJQ?t$O!"%&%#%s%I%&%7%9%F%`$r;H$C$F$$$k$H$-$K(B
$BJL$N%W%m%0%i%`$+$i%-%k$5$l$?%F%-%9%H$rE>Aw$9$kJ}K!$rDs6!$9$k!#(B
$B$=$NCM$O!"(B@code{nil}$B$G$"$k$+!"0z?t$J$7$N4X?t$G$"$k$3$H!#(B

@c If the value is a function, @code{current-kill} calls it to get the
@c ``most recent kill''.  If the function returns a non-@code{nil} value,
@c then that value is used as the ``most recent kill''.  If it returns
@c @code{nil}, then the first element of @code{kill-ring} is used.
$BCM$,4X?t$G$"$k$H!"(B
$B!X$b$C$H$b:G6a$N%-%k!Y$rF@$k$?$a$K(B@code{current-kill}$B$,8F$S=P$9!#(B
$B4X?t$,(B@code{nil}$B0J30$NCM$rJV$9$H!"(B
$B$=$NCM$O!X$b$C$H$b:G6a$N%-%k!Y$H$7$F;H$o$l$k!#(B
@code{nil}$B$rJV$;$P!"(B@code{kill-ring}$B$N@hF,9`L\$,;H$o$l$k!#(B

@c The normal use of this hook is to get the window system's primary
@c selection as the most recent kill, even if the selection belongs to
@c another application.  @xref{Window System Selections}.
$B$3$N%U%C%/$NIaDL$NMQES$O!"(B
$B%;%l%/%7%g%s$,JL$N%"%W%j%1!<%7%g%s$KB0$9$k>l9g$G$"$C$F$b!"(B
$B%&%#%s%I%&%7%9%F%`$N0l<!%;%l%/%7%g%s$r(B
$B$b$C$H$b:G6a$N%-%k$H$7$FF@$k$3$H$G$"$k!#(B
@pxref{Window System Selections}$B!#(B
@end defvar

@defvar interprogram-cut-function
@c This variable provides a way of communicating killed text to other
@c programs, when you are using a window system.  Its value should be
@c @code{nil} or a function of one argument.
$B$3$NJQ?t$O!"%&%#%s%I%&%7%9%F%`$r;H$C$F$$$k$H$-$K(B
$B%-%k$5$l$?%F%-%9%H$rJL$N%W%m%0%i%`$XE>Aw$9$kJ}K!$rDs6!$9$k!#(B
$B$=$NCM$O!"(B@code{nil}$B$G$"$k$+!"0z?t$J$7$N4X?t$G$"$k$3$H!#(B

@c If the value is a function, @code{kill-new} and @code{kill-append} call
@c it with the new first element of the kill ring as an argument.
$BCM$,4X?t$G$"$k$H!"(B@code{kill-new}$B$H(B@code{kill-append}$B$,(B
$B%-%k%j%s%0$N?7$?$J@hF,9`L\$r0z?t$H$7$F8F$S=P$9!#(B

@c The normal use of this hook is to set the window system's primary
@c selection from the newly killed text.  @xref{Window System Selections}.
$B$3$N%U%C%/$NIaDL$NMQES$O!"(B
$B?7$?$K%-%k$5$l$?%F%-%9%H$r(B
$B%&%#%s%I%&%7%9%F%`$N0l<!%;%l%/%7%g%s$K$9$k$3$H$G$"$k!#(B
@pxref{Window System Selections}$B!#(B
@end defvar

@node Internals of Kill Ring
@comment  node-name,  next,  previous,  up
@c @subsection Internals of the Kill Ring
@subsection $B%-%k%j%s%0$NFbIt(B

@c   The variable @code{kill-ring} holds the kill ring contents, in the
@c form of a list of strings.  The most recent kill is always at the front
@c of the list. 
$BJQ?t(B@code{kill-ring}$B$O!"J8;zNs$N%j%9%H$N7A$G%-%k%j%s%0$NFbMF$rJ];}$7$^$9!#(B
$B$b$C$H$b:G6a$N%-%k$,$D$M$K%j%9%H$N@hF,$K$"$j$^$9!#(B

@c   The @code{kill-ring-yank-pointer} variable points to a link in the
@c kill ring list, whose @sc{car} is the text to yank next.  We say it
@c identifies the ``front'' of the ring.  Moving
@c @code{kill-ring-yank-pointer} to a different link is called
@c @dfn{rotating the kill ring}.  We call the kill ring a ``ring'' because
@c the functions that move the yank pointer wrap around from the end of the
@c list to the beginning, or vice-versa.  Rotation of the kill ring is
@c virtual; it does not change the value of @code{kill-ring}.
$BJQ?t(B@code{kill-ring-yank-pointer}$B$O!"(B
@sc{car}$B$,$D$.$K%d%s%/$9$Y$-%F%-%9%H$G$"$k$h$&$J(B
$B%-%k%j%s%0%j%9%H$N9`L\$r;X$7$F$$$^$9!#(B
$B$3$NJQ?t$,%j%s%0$N!X@hF,!Y$r<1JL$9$k$H$$$$$^$9!#(B
@code{kill-ring-yank-pointer}$B$rJL$N9`L\$XF0$+$9$3$H$r(B
@dfn{$B%-%k%j%s%0$r2sE>$9$k(B}$B$H8F$S$^$9!#(B
$B%d%s%/%]%$%s%?$rF0$+$94X?t$O!"(B
$B%j%9%H$NKvHx$+$i%j%9%H$N@hF,$X@^$jJV$7$=$N5U$b9T$&$N$G!"(B
$B%-%k%j%s%0$r!X%j%s%0!Y$H8F$V$N$G$9!#(B
$B%j%s%0$N2sE>$O2>A[E*$J$b$N$G$"$j!"(B
@code{kill-ring}$B$NCM$OJQ99$7$^$;$s!#(B

@c   Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp
@c variables whose values are normally lists.  The word ``pointer'' in the
@c name of the @code{kill-ring-yank-pointer} indicates that the variable's
@c purpose is to identify one element of the list for use by the next yank
@c command.
@code{kill-ring}$B$b(B@code{kill-ring-yank-pointer}$B$b(BLisp$BJQ?t$G$"$j!"(B
$B$=$l$i$NCM$OIaDL$N%j%9%H$G$9!#(B
@code{kill-ring-yank-pointer}$B$NL>A0$NC18l!X%]%$%s%?!Y$O!"(B
$B$D$.$N%d%s%/%3%^%s%I$G;H$&%j%9%H$N9`L\$r<1JL$9$k$3$H$,(B
$BJQ?t$NL\E*$G$"$k$3$H$rI=$7$^$9!#(B

@c   The value of @code{kill-ring-yank-pointer} is always @code{eq} to one
@c of the links in the kill ring list.  The element it identifies is the
@c @sc{car} of that link.  Kill commands, which change the kill ring, also
@c set this variable to the value of @code{kill-ring}.  The effect is to
@c rotate the ring so that the newly killed text is at the front.
@code{kill-ring-yank-pointer}$B$NCM$O!"%-%k%j%s%0%j%9%H$N(B
1$B$D$N9`L\$H$D$M$K(B@code{eq}$B$G$9!#(B
$B$3$l$,<1JL$9$k9`L\$O!"$=$N9`L\$N(B@sc{car}$B$G$9!#(B
$B%-%k%j%s%0$rJQ99$9$k%-%k%3%^%s%I$b!"(B
@code{kill-ring}$B$NCM$r$3$NJQ?t$NCM$H$7$^$9!#(B
$B$=$N8z2L$O!"?7$?$K%-%k$5$l$?%F%-%9%H$,@hF,$K$/$k$h$&$K(B
$B%j%s%0$r2sE>$9$k$3$H$G$9!#(B

@c   Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
@c pointing to the second entry in the kill ring @code{("some text" "a
@c different piece of text" "yet older text")}.  
$B%-%k%j%s%0(B@code{("some text" "a different piece of text" "yet older text")}$B$N(B
$BBh(B2$B9`L\$rJQ?t(B@code{kill-ring-yank-pointer}$B$,;X$7$F$$$k$h$&$9$r$D$.$K<($7$^$9!#(B

@example
@group
kill-ring                  ---- kill-ring-yank-pointer
  |                       |
  |                       v
  |     --- ---          --- ---      --- ---
   --> |   |   |------> |   |   |--> |   |   |--> nil
        --- ---          --- ---      --- ---
         |                |            |            
         |                |            |            
         |                |             -->"yet older text" 
         |                |
         |                 --> "a different piece of text" 
         |
          --> "some text"
@end group
@end example

@noindent
@c This state of affairs might occur after @kbd{C-y} (@code{yank})
@c immediately followed by @kbd{M-y} (@code{yank-pop}).
@kbd{C-y}$B!J(B@code{yank}$B!K$ND>8e$K(B@kbd{M-y}$B!J(B@code{yank-pop}$B!K$r;H$&$H(B
$B$3$N>uBV$K$J$j$^$9!#(B

@defvar kill-ring
@c This variable holds the list of killed text sequences, most recently
@c killed first.
$B$3$NJQ?t$O!"$b$C$H$b:G6a$K%-%k$5$l$?$b$N$r:G=i$K$7$F(B
$B%-%k$5$l$?%F%-%9%H$r=g$KJB$Y$?%j%9%H$rJ];}$9$k!#(B
@end defvar

@defvar kill-ring-yank-pointer
@c This variable's value indicates which element of the kill ring is at the
@c ``front'' of the ring for yanking.  More precisely, the value is a tail
@c of the value of @code{kill-ring}, and its @sc{car} is the kill string
@c that @kbd{C-y} should yank.
$B$3$NJQ?t$NCM$O!"%-%k%j%s%0$N$I$NMWAG$,(B
$B%d%s%/$9$k$?$a$N%j%s%0$N!X@hF,!Y$G$"$k$+$rI=$9!#(B
$B$h$j@53N$K$O!"$=$NCM$O(B@code{kill-ring}$B$N%j%9%H$N0lIt$G$"$j!"(B
$B$=$N(B@sc{car}$B$O(B@kbd{C-y}$B$,%d%s%/$9$k%-%k$5$l$?J8;zNs$G$"$k!#(B
@end defvar

@defopt kill-ring-max
@c The value of this variable is the maximum length to which the kill
@c ring can grow, before elements are thrown away at the end.  The default
@c value for @code{kill-ring-max} is 30.
$B$3$NJQ?t$NCM$O!"KvHx$NMWAG$,GK4~$5$l$k$^$G$K(B
$B%-%k%j%s%0$,A}Bg$G$-$k:GBg$ND9$5$G$"$k!#(B
@code{kill-ring-max}$B$N%G%U%)%k%HCM$O(B30$B$G$"$k!#(B
@end defopt

@node Undo
@comment  node-name,  next,  previous,  up
@c @section Undo
@section $B%"%s%I%%(B
@c @cindex redo
@cindex $B%j%I%%(B

@c   Most buffers have an @dfn{undo list}, which records all changes made
@c to the buffer's text so that they can be undone.  (The buffers that
@c don't have one are usually special-purpose buffers for which Emacs
@c assumes that undoing is not useful.)  All the primitives that modify the
@c text in the buffer automatically add elements to the front of the undo
@c list, which is in the variable @code{buffer-undo-list}.
$B$[$H$s$I$N%P%C%U%!$K$O!"%P%C%U%!$N%F%-%9%H$KBP$9$kJQ99$r%"%s%I%%!J$b$H$KLa$9!K(B
$B$G$-$k$h$&$K$9$Y$F$NJQ99$r5-O?$9$k(B
@dfn{$B%"%s%I%%%j%9%H(B}$B!J(Bundo list$B!K$,$"$j$^$9!#(B
$B!J%"%s%I%%%j%9%H$N$J$$%P%C%U%!$O!"(B
Emacs$B$,%"%s%I%%$OM-MQ$G$O$J$$$H2>Dj$9$kFC<lL\E*$N%P%C%U%!$G$"$k!#!K(B
$B%P%C%U%!$N%F%-%9%H$rJQ99$9$k$9$Y$F$N4pK\4X?t$O!"(B
$BJQ?t(B@code{buffer-undo-list}$B$K<}$a$?%"%s%I%%%j%9%H$N@hF,$K(B
$B<+F0E*$KMWAG$rDI2C$7$^$9!#(B

@defvar buffer-undo-list
@c This variable's value is the undo list of the current buffer.
@c A value of @code{t} disables the recording of undo information.
$B$3$NJQ?t$NCM$O!"%+%l%s%H%P%C%U%!$N%"%s%I%%%j%9%H$G$"$k!#(B
$BCM(B@code{t}$B$O%"%s%I%%>pJs$N5-O?$r6X;_$9$k!#(B
@end defvar

@c Here are the kinds of elements an undo list can have:
$B%"%s%I%%%j%9%H$NMWAG$H$7$F2DG=$J$b$N$r$D$.$K<($7$^$9!#(B

@table @code
@item @var{position}
@c This kind of element records a previous value of point; undoing this
@c element moves point to @var{position}.  Ordinary cursor motion does not
@c make any sort of undo record, but deletion operations use these entries
@c to record where point was before the command.
$B$3$N<o$NMWAG$O!"$^$($N%]%$%s%HCM$r5-O?$9$k!#(B
$B$3$NMWAG$r%"%s%I%%$9$k$H%]%$%s%H$r(B@var{position}$B$X0\F0$9$k!#(B
$BDL>o$N%+!<%=%k0\F0$G$O!"$$$+$J$k<oN`$N%"%s%I%%5-O?$b:n$i$J$$$,!"(B
$B:o=|A`:n$G$O%3%^%s%I<B9TA0$N%]%$%s%H0LCV$r5-O?$9$k$?$a$K$3$N9`L\$r:n$k!#(B

@item (@var{beg} . @var{end})
@c This kind of element indicates how to delete text that was inserted.
@c Upon insertion, the text occupied the range @var{beg}--@var{end} in the 
@c buffer.
$B$3$N<o$NMWAG$O!"A^F~$5$l$?%F%-%9%H$r:o=|$9$kJ}K!$rI=$9!#(B
$BA^F~$5$l$?%F%-%9%H$O%P%C%U%!$N(B@var{beg}$B$+$i(B@var{end}$B$^$G$NHO0O$r@j$a$k!#(B

@item (@var{text} . @var{position})
@c This kind of element indicates how to reinsert text that was deleted.
@c The deleted text itself is the string @var{text}.  The place to
@c reinsert it is @code{(abs @var{position})}.
$B$3$N<o$NMWAG$O!":o=|$5$l$?%F%-%9%H$r:FEYA^F~$9$kJ}K!$rI=$9!#(B
$B:o=|$5$l$?%F%-%9%H$=$N$b$N$OJ8;zNs(B@var{text}$B$G$"$k!#(B
$B:FEYA^F~$9$k0LCV$O(B@code{(abs @var{position})}$B$G$"$k!#(B

@item (t @var{high} . @var{low})
@c This kind of element indicates that an unmodified buffer became
@c modified.  The elements @var{high} and @var{low} are two integers, each
@c recording 16 bits of the visited file's modification time as of when it
@c was previously visited or saved.  @code{primitive-undo} uses those
@c values to determine whether to mark the buffer as unmodified once again;
@c it does so only if the file's modification time matches those numbers.
$B$3$N<o$NMWAG$O!"L$JQ99$N%P%C%U%!$,JQ99$5$l$?$3$H$rI=$9!#(B
@var{high}$B$H(B@var{low}$B$O(B2$B$D$N@0?t$G$"$j!"$=$l$>$l!"(B
$B$^$($KK,Ld$7$?$H$-$dJ]B8$7$?$H$-$NK,Ld$7$F$$$k%U%!%$%k$N99?7;~9o$N(B
16$B%S%C%H$r5-O?$7$F$$$k!#(B
@code{primitive-undo}$B$O$3$l$i$NCM$rMQ$$$F!"(B
$B%P%C%U%!$r:FEYL$JQ99$H0u$rIU$1$k$+$I$&$+H=Dj$9$k!#(B
$B%U%!%$%k$N99?7;~9o$,$3$l$K0lCW$9$k$H$-$K$N$_:FEYL$JQ99$H$9$k!#(B

@item (nil @var{property} @var{value} @var{beg} . @var{end})
@c This kind of element records a change in a text property.
@c Here's how you might undo the change:
$B$3$N<o$NMWAG$O!"%F%-%9%HB0@-$NJQ99$r5-O?$9$k!#(B
$BJQ99$r%"%s%I%%$9$k$K$O$D$.$N$h$&$K$9$k!#(B

@example
(put-text-property @var{beg} @var{end} @var{property} @var{value})
@end example

@item (@var{marker} . @var{adjustment})
@c This kind of element records the fact that the marker @var{marker} was
@c relocated due to deletion of surrounding text, and that it moved
@c @var{adjustment} character positions.  Undoing this element moves
@c @var{marker} @minus{} @var{adjustment} characters.
$B$3$N<o$NMWAG$O!"<~$j$N%F%-%9%H$,:o=|$5$l$?$?$a$K(B
$B%^!<%+(B@var{marker}$B$r:FG[CV$7(B
@var{adjustment}$BJ8;zJ,0LCV$r0\F0$7$?$3$H$r5-O?$9$k!#(B
$B$3$NMWAG$r%"%s%I%%$9$k$H!"(B
@var{marker} @minus{} @var{adjustment}$BJ8;z$K0\F0$9$k!#(B

@item nil
@c This element is a boundary.  The elements between two boundaries are
@c called a @dfn{change group}; normally, each change group corresponds to
@c one keyboard command, and undo commands normally undo an entire group as
@c a unit.
$B$3$NMWAG$O6-3&$G$"$k!#(B
2$B$D$N6-3&$N$"$$$@$NMWAG72$r(B@dfn{$BJQ99%0%k!<%W(B}$B!J(Bchange group$B!K$H8F$V!#(B
$BDL>o!"3FJQ99%0%k!<%W$O(B1$B$D$N%-!<%\!<%I%3%^%s%I$KBP1~$7!"(B
$B%"%s%I%%%3%^%s%I$O%0%k!<%WA4BN$r(B1$B8D$H$7$F%"%s%I%%$9$k!#(B
@end table

@defun undo-boundary
@c This function places a boundary element in the undo list.  The undo
@c command stops at such a boundary, and successive undo commands undo
@c to earlier and earlier boundaries.  This function returns @code{nil}.
$B$3$N4X?t$O!"%"%s%I%%%j%9%H$K6-3&MWAG$rCV$/!#(B
$B%"%s%I%%%3%^%s%I$O$=$N$h$&$J6-3&$GDd;_$7!"(B
$BO"B3$7$?%"%s%I%%%3%^%s%I$O$h$j$^$($N6-3&$^$G%"%s%I%%$9$k!#(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c The editor command loop automatically creates an undo boundary before
@c each key sequence is executed.  Thus, each undo normally undoes the
@c effects of one command.  Self-inserting input characters are an
@c exception.  The command loop makes a boundary for the first such
@c character; the next 19 consecutive self-inserting input characters do
@c not make boundaries, and then the 20th does, and so on as long as
@c self-inserting characters continue.
$B%(%G%#%?%3%^%s%I%k!<%W$O!"(B
$B3F%-!<Ns$r<B9T$9$k$^$($K%"%s%I%%$N6-3&$r<+F0E*$K:n$k!#(B
$B$7$?$,$C$F!"3F%"%s%I%%$O!"(B1$B$D$N%3%^%s%I$N8z2L$rIaDL$O<h$j>C$9!#(B
$B<+8JA^F~$NF~NOJ8;z$ONc30$G$"$k!#(B
$B%3%^%s%I%k!<%W$O$=$N$h$&$J:G=i$NJ8;z$K6-3&$r:n$j!"(B
$B$D$.$N(B19$B8D$NO"B3$9$k<+8JA^F~$NF~NOJ8;z$G$O6-3&$r:n$i$:!"(B
20$BHVL\$G6-3&$r:n$k$H$$$&$3$H$r<+8JA^F~$NF~NOJ8;z$,B3$/8B$j9T$&!#(B

@c All buffer modifications add a boundary whenever the previous undoable
@c change was made in some other buffer.  This is to ensure that
@c each command makes a boundary in each buffer where it makes changes.
$BJL$N%P%C%U%!$G%"%s%I%%2DG=$JJQ99$r9T$&$?$S$K(B
$B%P%C%U%!$N$9$Y$F$NJQ99$G6-3&$rDI2C$9$k!#(B
$B$3$l$O!"3F%3%^%s%I$,JQ99$7$?2U=j$G3F%P%C%U%!$K6-3&$r:n$k$3$H$r(B
$BJ]>Z$9$k$?$a$G$"$k!#(B

@c Calling this function explicitly is useful for splitting the effects of
@c a command into more than one unit.  For example, @code{query-replace}
@c calls @code{undo-boundary} after each replacement, so that the user can
@c undo individual replacements one by one.
1$B$D$N%3%^%s%I$N8z2L$rJ#?t$KJ,$1$k$?$a$K$3$N4X?t$rD>@\8F$V$3$H$OM-MQ$G$"$k!#(B
$B$?$H$($P!"(B@code{query-replace}$B$O3FCV49$N$"$H$G(B@code{undo-boundary}$B$r8F$S=P$7!"(B
$B%f!<%6!<$,8D!9$NCV49$r(B1$B$D(B1$B$D%"%s%I%%$G$-$k$h$&$K$9$k!#(B
@end defun

@defun primitive-undo count list
@c This is the basic function for undoing elements of an undo list.
@c It undoes the first @var{count} elements of @var{list}, returning
@c the rest of @var{list}.  You could write this function in Lisp,
@c but it is convenient to have it in C.
$B$3$l$O!"%"%s%I%%%j%9%H$NMWAG$r%"%s%I%%$9$k4pK\E*$J4X?t$G$"$k!#(B
@var{list}$B$N@hF,$N(B@var{count}$B8D$NMWAG$r%"%s%I%%$7!"(B@var{list}$B$N;D$j$rJV$9!#(B
$B$3$N4X?t$r(BLisp$B$G=q$/$3$H$b$G$-$k$,!"(BC$B$G=q$$$?$[$&$,JXMx$G$"$k!#(B

@c @code{primitive-undo} adds elements to the buffer's undo list when it
@c changes the buffer.  Undo commands avoid confusion by saving the undo
@c list value at the beginning of a sequence of undo operations.  Then the
@c undo operations use and update the saved value.  The new elements added
@c by undoing are not part of this saved value, so they don't interfere with
@c continuing to undo.
@code{primitive-undo}$B$O!"%P%C%U%!$rJQ99$9$k$H(B
$B%P%C%U%!$N%"%s%I%%%j%9%H$KMWAG$rDI2C$9$k!#(B
$B%"%s%I%%%3%^%s%I$O0lO"$N%"%s%I%%A`:n$r;O$a$k$H$-$K(B
$B%"%s%I%%%j%9%H$rJ]B8$7$F:.Mp$rHr$1$k!#(B
$B%"%s%I%%A`:n$G$O!"J]B8$7$F$*$$$?CM$r;H$$99?7$9$k!#(B
$B%"%s%I%%$K$h$C$FDI2C$5$l$k?7$?$JMWAG$O$3$NJ]B8$5$l$?CM$N0lIt$G$O$J$$$N$G!"(B
$B$=$l$i$O%"%s%I%%$rB39T$7$F$b43>D$7$J$$!#(B
@end defun

@node Maintaining Undo
@c @section Maintaining Undo Lists
@section $B%"%s%I%%%j%9%H$N4IM}(B

@c   This section describes how to enable and disable undo information for
@c a given buffer.  It also explains how the undo list is truncated
@c automatically so it doesn't get too big.
$BK\@a$G$O!";XDj$5$l$?%P%C%U%!$G%"%s%I%%>pJs$N5-O?$r%*%s!?%*%U$9$k(B
$BJ}K!$K$D$$$F=R$Y$^$9!#(B
$B$^$?!"%"%s%I%%%j%9%H$,Bg$-$/$J$j$9$.$J$$$h$&$K(B
$B<+F0E*$K@Z$j5M$a$kJ}K!$K$D$$$F$b@bL@$7$^$9!#(B

@c   Recording of undo information in a newly created buffer is normally
@c enabled to start with; but if the buffer name starts with a space, the
@c undo recording is initially disabled.  You can explicitly enable or
@c disable undo recording with the following two functions, or by setting
@c @code{buffer-undo-list} yourself.
$B?7$?$K:n@.$5$l$?%P%C%U%!$N%"%s%I%%>pJs$N5-O?$OIaDL$O;O$a%*%s$G$9$,!"(B
$B%P%C%U%!L>$,6uGr$G;O$^$k>l9g$O:G=i$+$i%*%U$G$9!#(B
$B$D$.$N(B2$B$D$N4X?t$r;H$&$+!"FI<T<+?H$,(B@code{buffer-undo-list}$B$K@_Dj$9$l$P!"(B
$B%"%s%I%%5-O?$rL@<(E*$K%*%s!?%*%U$G$-$^$9!#(B

@c @deffn Command buffer-enable-undo &optional buffer-or-name
@deffn $B%3%^%s%I(B buffer-enable-undo &optional buffer-or-name
@c This command enables recording undo information for buffer
@c @var{buffer-or-name}, so that subsequent changes can be undone.  If no
@c argument is supplied, then the current buffer is used.  This function
@c does nothing if undo recording is already enabled in the buffer.  It
@c returns @code{nil}.
$B$3$N%3%^%s%I$O!"%P%C%U%!(B@var{buffer-or-name}$B$G$N%"%s%I%%5-O?$r%*%s$K$7!"(B
$B0J9_$NJQ99$r<h$j>C$;$k$h$&$K$9$k!#(B
$B0z?t$r;XDj$7$J$$$H!"%+%l%s%H%P%C%U%!$r;H$&!#(B
$BEv3:%P%C%U%!$G%"%s%I%%5-O?$,$9$G$K%*%s$G$"$k$H!"(B
$B$3$N4X?t$O$J$K$b$7$J$$!#(B
@code{nil}$B$rJV$9!#(B

@c In an interactive call, @var{buffer-or-name} is the current buffer.
@c You cannot specify any other buffer.
$BBPOCE*$K8F$P$l$k$H!"(B@var{buffer-or-name}$B$O%+%l%s%H%P%C%U%!$G$"$k!#(B
$BB>$N%P%C%U%!$r;XDj$G$-$J$$!#(B
@end deffn

@c @deffn Command buffer-disable-undo &optional buffer
@deffn $B%3%^%s%I(B buffer-disable-undo &optional buffer
@c @deffnx Command buffer-flush-undo &optional buffer
@deffnx $B%3%^%s%I(B buffer-flush-undo &optional buffer
@c @cindex disable undo
@cindex $B%"%s%I%%$N%*%U(B
@c This function discards the undo list of @var{buffer}, and disables
@c further recording of undo information.  As a result, it is no longer
@c possible to undo either previous changes or any subsequent changes.  If
@c the undo list of @var{buffer} is already disabled, this function
@c has no effect.
$B$3$N4X?t$O%P%C%U%!(B@var{buffer}$B$N%"%s%I%%%j%9%H$rGK4~$7!"(B
$B0J9_$N%"%s%I%%>pJs$N5-O?$r%*%U$K$9$k!#(B
$B$=$N7k2L!"$3$l0JA0$NJQ99$b0J9_$NJQ99$b<h$j>C$9$3$H$O$G$-$J$$!#(B
@var{buffer}$B$N%"%s%I%%%j%9%H$,$9$G$K%*%U$G$"$k$H!"(B
$B$3$N4X?t$K$O$J$s$N8z2L$b$J$$!#(B

@c This function returns @code{nil}.
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c The name @code{buffer-flush-undo} is not considered obsolete, but the
@c preferred name is @code{buffer-disable-undo}.
$BL>A0(B@code{buffer-flush-undo}$B$OGQ$l$F$$$k$H$O$_$J$5$J$$$,!"(B
$B9%$^$7$$L>A0$O(B@code{buffer-disable-undo}$B$G$"$k!#(B
@end deffn

@c   As editing continues, undo lists get longer and longer.  To prevent
@c them from using up all available memory space, garbage collection trims
@c them back to size limits you can set.  (For this purpose, the ``size''
@c of an undo list measures the cons cells that make up the list, plus the
@c strings of deleted text.)  Two variables control the range of acceptable
@c sizes: @code{undo-limit} and @code{undo-strong-limit}.
$BJT=8$rB3$1$k$K$7$?$,$C$F%"%s%I%%%j%9%H$O$I$s$I$sD9$/$J$j$^$9!#(B
$B$3$l$i$,%a%b%j$r;H$$?T$/$5$J$$$h$&$K!"(B
$BFI<T$,@_Dj$7$?>e8B%5%$%:$K%,%Y%C%8%3%l%/%7%g%s$,@Z$j5M$a$^$9!#(B
$B!J$3$NL\E*$K$*$$$F%"%s%I%%%j%9%H$N!X%5%$%:!Y$O!"(B
$B%j%9%H$r9=@.$9$k%3%s%9%;%k$N8D?t$H:o=|$5$l$?J8;zNs$NOB$G$"$k!#!K(B
2$B$D$NJQ?t(B@code{undo-limit}$B$H(B@code{undo-strong-limit}$B$O!"(B
$B5vMF$G$-$k%5%$%:$NHO0O$r@)8f$7$^$9!#(B

@defvar undo-limit
@c This is the soft limit for the acceptable size of an undo list.  The
@c change group at which this size is exceeded is the last one kept.
$B$3$l$O%"%s%I%%%j%9%H$N5vMF$G$-$k%5%$%:$N4K$$@)8B$G$"$k!#(B
$B$3$N%5%$%:$r1[$($k0LCV$K$"$kJQ99%0%k!<%W$OJ];}$5$l$k:G8E$N$b$N$G$"$k!#(B
@end defvar

@defvar undo-strong-limit
@c This is the upper limit for the acceptable size of an undo list.  The
@c change group at which this size is exceeded is discarded itself (along
@c with all older change groups).  There is one exception: the very latest
@c change group is never discarded no matter how big it is.
$B$3$l$O%"%s%I%%%j%9%H$N5vMF$G$-$k%5%$%:$N>e8B$G$"$k!#(B
$B$3$N%5%$%:$r1[$($k0LCV$K$"$kJQ99%0%k!<%W$O(B
$B!J$3$l$h$j8E$$$b$N$b4^$a$F!K:o=|$5$l$k!#(B
$BNc30$,(B1$B$D$"$j!":G?7$NJQ99%0%k!<%W$O(B
$B$=$l$,$I$l$[$IBg$-$/$F$b$1$C$7$FGK4~$7$J$$!#(B
@end defvar

@node Filling
@comment  node-name,  next,  previous,  up
@c @section Filling
@section $B5M$a9~$_(B
@c @cindex filling, explicit
@cindex $B5M$a9~$_!"L@<(E*(B

@c   @dfn{Filling} means adjusting the lengths of lines (by moving the line
@c breaks) so that they are nearly (but no greater than) a specified
@c maximum width.  Additionally, lines can be @dfn{justified}, which means
@c inserting spaces to make the left and/or right margins line up
@c precisely.  The width is controlled by the variable @code{fill-column}.
@c For ease of reading, lines should be no longer than 70 or so columns.
@dfn{$B5M$a9~$_(B}$B!J(Bfill$B!K$H$O!";XDj$5$l$F$$$k:GBgI}(B
$B!J$r1[$($:!K$K$[$\<}$^$k$h$&$K!J9TJ,$10LCV$r0\F0$7$F!K(B
$B9T$ND9$5$rD4@0$9$k$3$H$G$9!#(B
$B$5$i$K!"9T$r(B@dfn{$BI}B7$((B}$B!J(Bjustify$B!K$9$k$3$H$b$G$-$^$9!#(B
$B$D$^$j!":81&$NN>C<$dJRB&$NM>Gr$r$-$A$s$HB7$($k$?$a(B
$B6uGr$rA^F~$9$k$3$H$G$9!#(B
$BI}$OJQ?t(B@code{fill-column}$B$G@)8f$7$^$9!#(B
$BFI$_$d$9$$$h$&$K!"9T$O(B70$B%3%i%`DxEY$K<}$a$k$Y$-$G$9!#(B

@c   You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
@c automatically as you insert it, but changes to existing text may leave
@c it improperly filled.  Then you must fill the text explicitly.
$B%F%-%9%H$rA^F~$9$k$K$D$l$F<+F0E*$K%F%-%9%H$r5M$a9~$`$K$O!"(B
$B<+F05M$a9~$_!J(Bauto-fill$B!K%b!<%I!J(B@pxref{Auto Filling}$B!K$r;H$$$^$9$,!"(B
$B4{B8$N%F%-%9%H$rJQ99$7$F$b@5$7$/$J$$5M$a9~$_>uBV$N$^$^J|CV$5$l$^$9!#(B
$B$7$?$,$C$F!"$=$N$h$&$J%F%-%9%H$OL@<(E*$K5M$a9~$`I,MW$,$"$j$^$9!#(B

@c   Most of the commands in this section return values that are not
@c meaningful.  All the functions that do filling take note of the current
@c left margin, current right margin, and current justification style
@c (@pxref{Margins}).  If the current justification style is
@c @code{none}, the filling functions don't actually do anything.
$BK\@a$N$[$H$s$I$N4X?t$,JV$9CM$K$O0UL#$O$"$j$^$;$s!#(B
$B5M$a9~$_$r9T$&$9$Y$F$N4X?t$O!"8=:_$N:8C<M>Gr!"8=:_$N1&C<M>Gr!"(B
$B8=:_$NI}B7$(%9%?%$%k$KCm0U$r$O$i$$$^$9!J(B@pxref{Margins}$B!K!#(B
$B8=:_$NI}B7$(%9%?%$%k$,(B@code{none}$B$G$"$k$H!"(B
$B5M$a9~$_4X?t$O<B:]$K$O$J$K$b$7$^$;$s!#(B

@c   Several of the filling functions have an argument @var{justify}.
@c If it is non-@code{nil}, that requests some kind of justification.  It
@c can be @code{left}, @code{right}, @code{full}, or @code{center}, to
@c request a specific style of justification.  If it is @code{t}, that
@c means to use the current justification style for this part of the text
@c (see @code{current-justification}, below).  Any other value is treated
@c as @code{full}.
$B5M$a9~$_4X?t$K$O0z?t(B@var{justify}$B$r<h$k$b$N$b$"$j$^$9!#(B
$B$=$l$,(B@code{nil}$B0J30$G$"$k$H!"I}B7$($N<oN`$r;X<($7$^$9!#(B
$BFCDj$NI}B7$(%9%?%$%k$r;X<($9$k$b$N$O!"(B
@code{left}$B!"(B@code{right}$B!"(B@code{full}$B!"(B@code{center}$B$G$9!#(B
$B$=$l$,(B@code{t}$B$G$"$k$H!"(B
$B%F%-%9%H$NEv3:ItJ,$K$O8=:_$NI}B7$(%9%?%$%k$rMQ$$$k$3$H$r0UL#$7$^$9(B
$B!J2<5-$N(B@code{current-justification}$B$r;2>H!K!#(B
$B$3$l0J30$NCM$O(B@code{full}$B$H$7$F07$$$^$9!#(B

@c   When you call the filling functions interactively, using a prefix
@c argument implies the value @code{full} for @var{justify}.
$BBPOCE*$K5M$a9~$_4X?t$r8F$V$H$-$KA0CV0z?t$r;H$&$H!"(B
@var{justify}$B$H$7$FCM(B@code{full}$B$r0E$K;X<($7$^$9!#(B

@c @deffn Command fill-paragraph justify
@deffn $B%3%^%s%I(B fill-paragraph justify
@c @cindex filling a paragraph
@cindex $BCJMn$N5M$a9~$_(B
@cindex $B5M$a9~$_!"CJMn(B
@c This command fills the paragraph at or after point.  If
@c @var{justify} is non-@code{nil}, each line is justified as well.
@c It uses the ordinary paragraph motion commands to find paragraph
@c boundaries.  @xref{Paragraphs,,, emacs, The Emacs Manual}.
$B$3$N%3%^%s%I$O!"%]%$%s%H$,$"$kCJMn!"$"$k$$$O!"%]%$%s%H$N$"$H$NCJMn$r5M$a9~$`!#(B
@var{justify}$B$,(B@code{nil}$B0J30$G$"$k$H!"3F9T$NI}B7$($b9T$&!#(B
$BCJMn$N6-3&$rC5$9$?$a$KIaDL$NCJMn0\F0%3%^%s%I$rMQ$$$k!#(B
@pxref{Paragraphs,, $BCJMn(B, emacs, GNU Emacs $B%^%K%e%"%k(B}$B!#(B
@end deffn

@c @deffn Command fill-region start end &optional justify nosqueeze
@c = $B8m?"(B                                                           to-eop
@deffn $B%3%^%s%I(B fill-region start end &optional justify nosqueeze to-eop
@c This command fills each of the paragraphs in the region from @var{start}
@c to @var{end}.  It justifies as well if @var{justify} is
@c non-@code{nil}.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$+$i(B@var{end}$B$NNN0hFb$N3FCJMn$r5M$a9~$`!#(B
@var{justify}$B$,(B@code{nil}$B0J30$G$"$l$P!"I}B7$($b9T$&!#(B

@c If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
@c other than line breaks untouched.  If @var{to-eop} is non-@code{nil},
@c that means to keep filling to the end of the paragraph---or the next hard
@c newline, if @code{use-hard-newlines} is enabled (see below).
@var{nosqueeze}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B9TJ,$10J30$NGrJ8;z$K$O$U$l$J$$$3$H$r0UL#$9$k!#(B
@var{to-eop}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BCJMn$NKvHx$^$G!"$"$k$$$O!"(B
@code{use-hard-newlines}$B$,%*%s$J$i$P$D$.$N%O!<%I2~9T!J2<5-;2>H!K$^$G$r(B
$B5M$a9~$`$3$H$r0UL#$9$k!#(B

@c The variable @code{paragraph-separate} controls how to distinguish
@c paragraphs.  @xref{Standard Regexps}.
$BJQ?t(B@code{paragraph-separate}$B$O!"CJMn$N6hJLJ}K!$r@)8f$9$k!#(B
@pxref{Standard Regexps}$B!#(B
@end deffn

@c @deffn Command fill-individual-paragraphs start end &optional justify mail-flag
@deffn $B%3%^%s%I(B fill-individual-paragraphs start end &optional justify mail-flag
@c This command fills each paragraph in the region according to its
@c individual fill prefix.  Thus, if the lines of a paragraph were indented
@c with spaces, the filled paragraph will remain indented in the same
@c fashion.
$B$3$N%3%^%s%I$O!"NN0hFb$N3FCJMn$r3FCJMn$N5M$a9~$_@\F,<-$K=>$C$F5M$a9~$`!#(B
$B$7$?$,$C$F!"CJMn$N9T$,6uGr$G;z2<$2$5$l$F$$$k$H!"(B
$B5M$a9~$s$@$"$H$NCJMn$bF1$8$h$&$K;z2<$2$5$l$k!#(B

@c The first two arguments, @var{start} and @var{end}, are the beginning
@c and end of the region to be filled.  The third and fourth arguments,
@c @var{justify} and @var{mail-flag}, are optional.  If
@c @var{justify} is non-@code{nil}, the paragraphs are justified as
@c well as filled.  If @var{mail-flag} is non-@code{nil}, it means the
@c function is operating on a mail message and therefore should not fill
@c the header lines.
$B:G=i$N(B2$B$D$N0z?t(B@var{start}$B$H(B@var{end}$B$O!"(B
$B5M$a9~$`$Y$-HO0O$N@hF,$HKvHx$G$"$k!#(B
3$BHVL\$H(B4$BHVL\$N0z?t!"(B@var{justify}$B$H(B@var{mail-flag}$B$O>JN,$G$-$k!#(B
@var{justify}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BCJMn$N5M$a9~$_$K2C$($FI}B7$($b9T$&!#(B
@var{mail-flag}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%a%$%k%a%C%;!<%8$J$N$G%X%C%@9T$r5M$a9~$^$J$$$3$H$r0UL#$9$k!#(B

@c Ordinarily, @code{fill-individual-paragraphs} regards each change in
@c indentation as starting a new paragraph.  If
@c @code{fill-individual-varying-indent} is non-@code{nil}, then only
@c separator lines separate paragraphs.  That mode can handle indented
@c paragraphs with additional indentation on the first line.
$BDL>o!"(B@code{fill-individual-paragraphs}$B$O!"(B
$B;z2<$2$,JQ$o$k$H?7$7$$CJMn$N3+;O$H$_$J$9!#(B
@code{fill-individual-varying-indent}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B6h@Z$j9T$N$_$,CJMn$r6h@Z$k$H$_$J$9!#(B
$B$3$l$OCJMn$N@hF,9T$H8eB3$N9T$G;z2<$2$,0[$J$kCJMn$r=hM}$G$-$k!#(B
@end deffn

@defopt fill-individual-varying-indent
@c This variable alters the action of @code{fill-individual-paragraphs} as
@c described above.
$B$3$NJQ?t$O!">e$K=R$Y$?$h$&$K(B
@code{fill-individual-paragraphs}$B$NF0:n$rJQ$($k!#(B
@end defopt

@c @deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
@deffn $B%3%^%s%I(B fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
@c This command considers a region of text as a single paragraph and fills
@c it.  If the region was made up of many paragraphs, the blank lines
@c between paragraphs are removed.  This function justifies as well as
@c filling when @var{justify} is non-@code{nil}.
$B$3$N%3%^%s%I$O!"%F%-%9%H$NNN0h$r(B1$B$D$NCJMn$H$_$J$7$F5M$a9~$`!#(B
$BNN0h$KJ#?t$NCJMn$,$"$k$H!"CJMn$N$"$$$@$N6u9T$O<h$j$5$k!#(B
@var{justify}$B$,(B@code{nil}$B0J30$G$"$k$HI}B7$($b9T$&!#(B

@c In an interactive call, any prefix argument requests justification.
$BBPOCE*$J8F$S=P$7$G$O!"A0CV0z?t$GI}B7$($r;X<($9$k!#(B

@c If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
@c other than line breaks untouched.  If @var{squeeze-after} is
@c non-@code{nil}, it specifies a position in the region, and means don't
@c canonicalize spaces before that position.
@var{nosqueeze}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B9TJ,$10J30$NGrJ8;z$K$O$U$l$J$$$3$H$r0UL#$9$k!#(B
@var{squeeze-after}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$l$ONN0hFb$N0LCV$rI=$7!"(B
$B$=$N0LCV$h$j$^$($K$"$k6uGr$rJQ99$7$J$$$h$&$K;X<($9$k!#(B

@c In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
@c choose a fill prefix by default.  @xref{Adaptive Fill}.
$BE,1~7?5M$a9~$_!J(Badaptive-fill$B!K%b!<%I$G$O!"(B
$B%G%U%)%k%H$N5M$a9~$_@\F,<-$rA*$V$?$a$K(B
$B$3$N%3%^%s%I$O(B@code{fill-context-prefix}$B$r8F$S=P$9!#(B
@pxref{Adaptive Fill}$B!#(B
@end deffn

@c @deffn Command justify-current-line how eop nosqueeze
@deffn $B%3%^%s%I(B justify-current-line how eop nosqueeze
@c This command inserts spaces between the words of the current line so
@c that the line ends exactly at @code{fill-column}.  It returns
@c @code{nil}.
$B$3$N%3%^%s%I$O!"8=:_9T$NC18l$N$"$$$@$K6uGr$rA^F~$7!"(B
$B$A$g$&$I(B@code{fill-column}$B%3%i%`$G9T$,=*$k$h$&$K$9$k!#(B
@code{nil}$B$rJV$9!#(B

@c The argument @var{how}, if non-@code{nil} specifies explicitly the style
@c of justification.  It can be @code{left}, @code{right}, @code{full},
@c @code{center}, or @code{none}.  If it is @code{t}, that means to do
@c follow specified justification style (see @code{current-justification},
@c below).  @code{nil} means to do full justification.
$B0z?t(B@var{how}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BI}B7$(%9%?%$%k$r;XDj$9$k!#(B
$B2DG=$JCM$O!"(B@code{left}$B!"(B@code{right}$B!"(B@code{full}$B!"(B
@code{center}$B!"$^$?$O!"(B@code{none}$B$G$"$k!#(B
@code{t}$B$G$"$k$H!";XDj$5$l$F$$$kI}B7$(%9%?%$%k$K=>$&$3$H$r0UL#$9$k(B
$B!J2<5-$N(B@code{current-justification}$B$r;2>H!K!#(B
@code{nil}$B$O!"I}B7$($7$J$$$3$H$r0UL#$9$k!#(B

@c If @var{eop} is non-@code{nil}, that means do left-justification if
@c @code{current-justification} specifies full justification.  This is used
@c for the last line of a paragraph; even if the paragraph as a whole is
@c fully justified, the last line should not be.
@var{eop}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{current-justification}$B$,N>C<B7$($r;XDj$7$F$$$k$H$-$K$O(B
$B:8C<B7$($r9T$&$3$H$r0UL#$9$k!#(B
$B$3$l$OCJMn$N:G8e$N9T$KE,MQ$5$l$k!#(B
$BCJMnA4BN$H$7$FN>C<B7$($G$"$C$F$b!":G8e$N9T$O$=$&$9$Y$-$G$O$J$$!#(B

@c If @var{nosqueeze} is non-@code{nil}, that means do not change interior
@c whitespace.
@var{nosqueeze}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BFbB&$NGrJ8;z$rJQ99$7$J$$$3$H$r0UL#$9$k!#(B
@end deffn

@defopt default-justification
@c This variable's value specifies the style of justification to use for
@c text that doesn't specify a style with a text property.  The possible
@c values are @code{left}, @code{right}, @code{full}, @code{center}, or
@c @code{none}.  The default value is @code{left}.
$B$3$NJQ?t$NCM$O!"%F%-%9%HB0@-$GI}B7$(%9%?%$%k$r;XDj$7$F$$$J$$(B
$B%F%-%9%H$KBP$7$FMQ$$$kI}B7$(%9%?%$%k$r;XDj$9$k!#(B
$B2DG=$JCM$O!"(B@code{left}$B!"(B@code{right}$B!"(B@code{full}$B!"(B@code{center}$B!"(B
@code{none}$B$G$"$k!#(B
$B%G%U%)%k%HCM$O(B@code{left}$B$G$"$k!#(B
@end defopt

@defun current-justification
@c This function returns the proper justification style to use for filling
@c the text around point.
$B$3$N4X?t$O!"%]%$%s%H$N<~$j$N%F%-%9%H$r5M$a9~$`$H$-$K;H$&(B
$B@5$7$$I}B7$(%9%?%$%k$rJV$9!#(B
@end defun

@defopt sentence-end-double-space
@c If this variable is non-@code{nil}, a period followed by just one space
@c does not count as the end of a sentence, and the filling functions
@c avoid breaking the line at such a place.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BD>8e$K(B1$B$D$N6uGr$r=>$($?%T%j%*%I$rJ8Kv$H$_$J$5$:!"(B
$B5M$a9~$_4X?t$O$=$N$h$&$J2U=j$G9TJ,$1$7$J$$!#(B
@end defopt

@defvar fill-paragraph-function
@c This variable provides a way for major modes to override the filling of
@c paragraphs.  If the value is non-@code{nil}, @code{fill-paragraph} calls
@c this function to do the work.  If the function returns a non-@code{nil}
@c value, @code{fill-paragraph} assumes the job is done, and immediately
@c returns that value.
$B$3$NJQ?t$O!"CJMn$N5M$a9~$_$KM%@h$9$kJ}K!$r%a%8%c!<%b!<%I$KM?$($k!#(B
$BCM$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{fill-paragraph}$B$O5M$a9~$_=hM}$N$?$a$K$3$N4X?t$r8F$S=P$9!#(B
$B4X?t$,(B@code{nil}$B0J30$NCM$rJV$9$H!"(B
@code{fill-paragraph}$B$O=hM}$,40N;$7$?$H$_$J$7$FLa$jCM$r$?$@$A$KJV$9!#(B

@c The usual use of this feature is to fill comments in programming
@c language modes.  If the function needs to fill a paragraph in the usual
@c way, it can do so as follows:
$B$3$N5!G=$NIaDL$NMQES$O!"(B
$B%W%m%0%i%`8@8l8~$1$N%b!<%I$G%3%a%s%H$r5M$a9~$`$?$a$G$"$k!#(B
$B$3$N4X?t$GIaDL$NJ}K!$G5M$a9~$`I,MW$,$"$k>l9g$K$O!"$D$.$N$h$&$K$9$k!#(B

@example
(let ((fill-paragraph-function nil))
  (fill-paragraph arg))
@end example
@end defvar

@defvar use-hard-newlines
@c If this variable is non-@code{nil}, the filling functions do not delete
@c newlines that have the @code{hard} text property.  These ``hard
@c newlines'' act as paragraph separators.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B5M$a9~$_4X?t$O!"%F%-%9%HB0@-(B@code{hard}$B$r;}$D2~9T$r:o=|$7$J$$!#(B
$B$3$l$i$N!X%O!<%I2~9T!Y$OCJMn$N6h@Z$j$H$7$FF/$/!#(B
@end defvar

@node Margins
@c @section Margins for Filling
@section $B5M$a9~$_$N$?$a$NM>Gr(B

@defopt fill-prefix
@c This buffer-local variable specifies a string of text that appears at
@c the beginning
@c of normal text lines and should be disregarded when filling them.  Any
@c line that fails to start with the fill prefix is considered the start of
@c a paragraph; so is any line that starts with the fill prefix followed by
@c additional whitespace.  Lines that start with the fill prefix but no
@c additional whitespace are ordinary text lines that can be filled
@c together.  The resulting filled lines also start with the fill prefix.
$B$3$N%P%C%U%!%m!<%+%k$JJQ?t$O!"IaDL$N%F%-%9%H9T$N@hF,$K8=$l!"(B
$B5M$a9~$_;~$K$OL5;k$9$Y$-%F%-%9%H$NJ8;zNs!J5M$a9~$_@\F,<-!K$r;XDj$9$k!#(B
$B5M$a9~$_@\F,<-$G;O$^$i$J$$9T$OCJMn$N3+;O9T$H$_$J$9$?$a!"(B
$B5M$a9~$_@\F,<-$N$"$H$KM>J,$KGrJ8;z$,$"$k$H$=$l$i$bCJMn$N3+;O9T$H$_$J$9!#(B
$B5M$a9~$_@\F,<-$G;O$^$j$=$N$"$H$KM>J,$JGrJ8;z$,$J$$9T$O!"(B
$B$$$C$7$g$K5M$a9~$a$kIaDL$N%F%-%9%H9T$G$"$k!#(B

@c The fill prefix follows the left margin whitespace, if any.
$B:8C<M>Gr$,$"$k>l9g$K$O!":8C<M>Gr$N$"$H$K5M$a9~$_@\F,<-$,B3$/!#(B
@end defopt

@defopt fill-column
@c This buffer-local variable specifies the maximum width of filled lines.
@c Its value should be an integer, which is a number of columns.  All the
@c filling, justification, and centering commands are affected by this
@c variable, including Auto Fill mode (@pxref{Auto Filling}).
$B$3$N%P%C%U%!%m!<%+%k$JJQ?t$O!"5M$a9~$s$@9T$N:GBgI}$r;XDj$9$k!#(B
$B$3$NCM$O@0?t$G$"$j!"%3%i%`?t$G$"$k$3$H!#(B
$B<+F05M$a9~$_!J(Bauto-fill$B!K%b!<%I!J(B@pxref{Auto Filling}$B!K$r4^$a$F(B
$B$9$Y$F$N5M$a9~$_!?I}B7$(!?Cf1{B7$($r9T$&%3%^%s%I$O!"(B
$B$3$NJQ?t$K1F6A$5$l$k!#(B

@c As a practical matter, if you are writing text for other people to
@c read, you should set @code{fill-column} to no more than 70.  Otherwise
@c the line will be too long for people to read comfortably, and this can
@c make the text seem clumsy.
$BFC$KB>?M$N$?$a$K=q$$$F$$$k%F%-%9%H$G$O!"(B
@code{fill-column}$B$r(B70$BL$K~$K$9$k$Y$-$G$"$k!#(B
$B$5$b$J$$$H!"?M$K$h$C$F$O2wE,$KFI$`$K$O9T$,D9$9$.$F!"(B
$B%F%-%9%H$,IT3f9%$K8+$($k!#(B
@end defopt

@defvar default-fill-column
@c The value of this variable is the default value for @code{fill-column} in
@c buffers that do not override it.  This is the same as
@c @code{(default-value 'fill-column)}.
$B$3$NJQ?t$NCM$O!"%P%C%U%!$G(B@code{fill-column}$B$NCM$r@_Dj$7$F$$$J$$>l9g$N(B
@code{fill-column}$B$N%G%U%)%k%HCM$G$"$k!#(B
$B$3$l$O(B@code{(default-value 'fill-column)}$B$HF1$8$G$"$k!#(B

@c The default value for @code{default-fill-column} is 70.
@code{default-fill-column}$B$N%G%U%)%k%HCM$O(B70$B$G$"$k!#(B
@end defvar

@c @deffn Command set-left-margin from to margin
@deffn $B%3%^%s%I(B set-left-margin from to margin
@c This sets the @code{left-margin} property on the text from @var{from} to
@c @var{to} to the value @var{margin}.  If Auto Fill mode is enabled, this
@c command also refills the region to fit the new margin.
@var{from}$B$+$i(B@var{to}$B$^$G$N%F%-%9%H$N(B
$BB0@-(B@code{left-margin}$B$rCM(B@var{margin}$B$K$9$k!#(B
$B<+F05M$a9~$_!J(Bauto-fill$B!K%b!<%I$,%*%s$G$"$k$H!"(B
$B$3$N%3%^%s%I$O!"Ev3:NN0h$r:F5M$a9~$_$7$F?7$?$JM>Gr$KE,9g$9$k$h$&$K$9$k!#(B
@end deffn

@c @deffn Command set-right-margin from to margin
@deffn $B%3%^%s%I(B set-right-margin from to margin
@c This sets the @code{right-margin} property on the text from @var{from}
@c to @var{to} to the value @var{margin}.  If Auto Fill mode is enabled,
@c this command also refills the region to fit the new margin.
@var{from}$B$+$i(B@var{to}$B$^$G$N%F%-%9%H$N(B
$BB0@-(B@code{right-margin}$B$rCM(B@var{margin}$B$K$9$k!#(B
$B<+F05M$a9~$_!J(Bauto-fill$B!K%b!<%I$,%*%s$G$"$k$H!"(B
$B$3$N%3%^%s%I$O!"Ev3:NN0h$r:F5M$a9~$_$7$F?7$?$JM>Gr$KE,9g$9$k$h$&$K$9$k!#(B
@end deffn

@defun current-left-margin
@c This function returns the proper left margin value to use for filling
@c the text around point.  The value is the sum of the @code{left-margin}
@c property of the character at the start of the current line (or zero if
@c none), and the value of the variable @code{left-margin}.
$B$3$N4X?t$O!"%]%$%s%H$N<~$j$N%F%-%9%H$r5M$a9~$`$H$-$K;H$&(B
$B@5$7$$:8C<M>Gr$NCM$rJV$9!#(B
$B$=$NCM$O!"8=:_9T$N:G=i$NJ8;z$NB0@-(B@code{left-margin}$B$NCM!J$J$1$l$P(B0$B!K(B
$B$HJQ?t(B@code{left-margin}$B$NCM$NOB$G$"$k!#(B
@end defun

@defun current-fill-column
@c This function returns the proper fill column value to use for filling
@c the text around point.  The value is the value of the @code{fill-column}
@c variable, minus the value of the @code{right-margin} property of the
@c character after point.
$B$3$N4X?t$O!"%]%$%s%H$N<~$j$N%F%-%9%H$r5M$a9~$`$H$-$K;H$&(B
$B@5$7$$5M$a9~$_I}$rJV$9!#(B
$B$=$NCM$O!"JQ?t(B@code{fill-column}$B$NCM$+$i(B
$B%]%$%s%HD>8e$NJ8;z$NB0@-(B@code{right-margin}$B$NCM$r0z$$$?$b$N$G$"$k!#(B
@end defun

@c @deffn Command move-to-left-margin &optional n force
@deffn $B%3%^%s%I(B move-to-left-margin &optional n force
@c This function moves point to the left margin of the current line.  The
@c column moved to is determined by calling the function
@c @code{current-left-margin}.  If the argument @var{n} is non-@code{nil},
@c @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
$B$3$N4X?t$O!"%]%$%s%H$r8=:_9T$N:8C<M>Gr$X0\F0$9$k!#(B
$B0\F0@h$N%3%i%`0LCV$O4X?t(B@code{current-left-margin}$B$r8F$S=P$7$F7hDj$9$k!#(B
$B0z?t(B@var{n}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{move-to-left-margin}$B$O(B@var{n}@minus{}1$B@h$N9T$X$^$:0\F0$9$k!#(B

@c If @var{force} is non-@code{nil}, that says to fix the line's
@c indentation if that doesn't match the left margin value.
@var{force}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B9T$N;z2<$2$,:8C<M>Gr$NCM$K0lCW$7$J$$$H$-$K$O!"(B
$B;z2<$2$r=$@5$9$k$3$H$r;X<($9$k!#(B
@end deffn

@defun delete-to-left-margin from to
@c This function removes left margin indentation from the text
@c between @var{from} and @var{to}.  The amount of indentation
@c to delete is determined by calling @code{current-left-margin}.
@c In no case does this function delete non-whitespace.
$B$3$N4X?t$O!"(B@var{from}$B$+$i(B@var{to}$B$^$G$N%F%-%9%H$+$i(B
$B:8C<M>GrJ,$N;z2<$2$r<h$j$5$k!#(B
$B:o=|$9$k;z2<$2NL$O!"(B@code{current-left-margin}$B$r8F$S=P$7$F7hDj$9$k!#(B
$B$3$N4X?t$,GrJ8;z0J30$r:o=|$9$k$3$H$O@dBP$K$J$$!#(B
@end defun

@defun indent-to-left-margin
@c This is the default @code{indent-line-function}, used in Fundamental
@c mode, Text mode, etc.  Its effect is to adjust the indentation at the
@c beginning of the current line to the value specified by the variable
@c @code{left-margin}.  This may involve either inserting or deleting
@c whitespace.
$B$3$l$O!"4pK\!J(Bfundamental$B!K%b!<%I!"%F%-%9%H!J(Btext$B!K%b!<%I$J$I$,;H$&(B
$B%G%U%)%k%H$N(B@code{indent-line-function}$B$G$"$k!#(B
$B$=$N8z2L$O!"JQ?t(B@code{left-margin}$B$NCM$G;XDj$7$?0LCV$+$i(B
$B8=:_9T$,;O$^$k$h$&$K;z2<$2$rD4@0$9$k$3$H$G$"$k!#(B
$B$=$l$K$OGrJ8;z$NA^F~$d:o=|$,H<$&!#(B
@end defun

@defvar left-margin
@c This variable specifies the base left margin column.  In Fundamental
@c mode, @kbd{C-j} indents to this column.  This variable automatically
@c becomes buffer-local when set in any fashion.
$B$3$NJQ?t$O!":8C<M>Gr%3%i%`$N5/E@$r;XDj$9$k!#(B
$B4pK\!J(Bfundamental$B!K%b!<%I$G$O!"(B@kbd{C-j}$B$,$3$N%3%i%`0LCV$K;z2<$2$9$k!#(B
$B$3$NJQ?t$K@_Dj$9$k$H<+F0E*$K%P%C%U%!%m!<%+%k$K$J$k!#(B
@end defvar

@defvar fill-nobreak-predicate
@tindex fill-nobreak-predicate
@c This variable gives major modes a way to specify not to break a line at
@c certain places.  Its value should be a function.  This function is
@c called during filling, with no arguments and with point located at the
@c place where a break is being considered.  If the function returns
@c non-@code{nil}, then the line won't be broken there.
$B$3$NJQ?t$O!"FCDj$N2U=j$G$O9TJ,$1$7$J$$J}K!$r%a%8%c!<%b!<%I$KDs6!$9$k!#(B
$B$=$NCM$O4X?t$G$"$k$3$H!#(B
$B$3$N4X?t$O!"0z?t$J$7$G9TJ,$1M=Dj2U=j$K%]%$%s%H$rCV$$$F8F$S=P$5$l$k!#(B
$B$3$N4X?t$,(B@code{nil}$B0J30$rJV$9$H!"Ev3:2U=j$G$O9TJ,$1$7$J$$!#(B
@end defvar

@node Adaptive Fill
@c @section Adaptive Fill Mode
@section $BE,1~7?5M$a9~$_!J(Badaptive-fill$B!K%b!<%I(B
@c @cindex Adaptive Fill mode
@cindex $BE,1~7?5M$a9~$_!J(Badaptive-fill$B!K%b!<%I(B

@c   Adaptive Fill mode chooses a fill prefix automatically from the text
@c in each paragraph being filled.
$BE,1~7?5M$a9~$_%b!<%I!J(Badaptive-fill$B!K$G$O!"(B
$B5M$a9~$`$Y$-3FCJMn$N%F%-%9%H$+$i<+F0E*$K5M$a9~$_@\F,<-$rA*$S$^$9!#(B

@defopt adaptive-fill-mode
@c Adaptive Fill mode is enabled when this variable is non-@code{nil}.
@c It is @code{t} by default.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BE,1~7?5M$a9~$_%b!<%I!J(Badaptive-fill$B!K$,%*%s$G$"$k!#(B
$B%G%U%)%k%H$G$O(B@code{t}$B$G$"$k!#(B
@end defopt

@defun fill-context-prefix from to
@c This function implements the heart of Adaptive Fill mode; it chooses a
@c fill prefix based on the text between @var{from} and @var{to}.  It does
@c this by looking at the first two lines of the paragraph, based on the
@c variables described below.
$B$3$N4X?t$OE,1~7?5M$a9~$_%b!<%I!J(Badaptive-fill$B!K$NCf3K$r<BAu$9$k$b$N$G$"$j!"(B
@var{from}$B$+$i(B@var{to}$B$N$"$$$@$N%F%-%9%H$K4p$E$$$F5M$a9~$_@\F,<-$rA*$V!#(B
$B0J2<$K=R$Y$kJQ?t$K4p$E$$$F!"CJMn$N:G=i$N(B2$B9T$rD4$Y$F$3$l$r9T$&!#(B
@end defun

@defopt adaptive-fill-regexp
@c This variable holds a regular expression to control Adaptive Fill mode.
@c Adaptive Fill mode matches this regular expression against the text
@c starting after the left margin whitespace (if any) on a line; the
@c characters it matches are that line's candidate for the fill prefix.
$B$3$NJQ?t$O!"E,1~7?5M$a9~$_%b!<%I!J(Badaptive-fill$B!K$r@)8f$9$k(B
$B@55,I=8=$rJ];}$9$k!#(B
$BE,1~7?5M$a9~$_%b!<%I!J(Badaptive-fill$B!K$G$O!"(B
$B9T$N!J$"$l$P!K:8C<M>Gr$NGrJ8;z$N$&$7$m$+$i;O$^$k%F%-%9%H$KBP$7$F(B
$B$3$N@55,I=8=$N0lCW$r;n$_$k!#(B
$B0lCW$7$?J8;z72$,Ev3:9T$N5M$a9~$_@\F,<-$N8uJd$K$J$k!#(B
@end defopt

@defopt adaptive-fill-first-line-regexp
@c In a one-line paragraph, if the candidate fill prefix matches this
@c regular expression, or if it matches @code{comment-start-skip}, then it
@c is used---otherwise, spaces amounting to the same width are used
@c instead.
1$B9T$@$1$NCJMn$K$*$$$F!"5M$a9~$_@\F,<-$N8uJd$,$3$N@55,I=8=$K0lCW$9$k$+!"(B
@code{comment-start-skip}$B$K0lCW$9$k$H!"$=$N8uJd$r;H$&!#(B
$B$5$b$J$1$l$P!"F1$8I}$KAjEv$9$kGrJ8;z$r$+$o$j$K;H$&!#(B

@c However, the fill prefix is never taken from a one-line paragraph
@c if it would act as a paragraph starter on subsequent lines.
1$B9T$@$1$NCJMn$+$iA*$s$@5M$a9~$_@\F,<-$,8eB3$N9T$NCJMn$N;O$^$j$G$"$k>l9g$K$O!"(B
1$B9T$@$1$NCJMn$+$i$O$1$C$7$F5M$a9~$_@\F,<-$rA*$P$J$$!#(B
@end defopt

@defopt adaptive-fill-function
@c You can specify more complex ways of choosing a fill prefix
@c automatically by setting this variable to a function.  The function is
@c called when @code{adaptive-fill-regexp} does not match, with point after
@c the left margin of a line, and it should return the appropriate fill
@c prefix based on that line.  If it returns @code{nil}, that means it sees
@c no fill prefix in that line.
$B$3$NJQ?t$K4X?t$r;XDj$9$k$3$H$G!"(B
$B5M$a9~$_@\F,<-$N$h$jJ#;($J<+F0A*BrJ}K!$r;XDj$G$-$k!#(B
$B$3$N4X?t$O!"(B@code{adaptive-fill-regexp}$B$N0lCW$K<:GT$7$?$H$-$K!"(B
$B9T$N:8C<M>Gr$N$&$7$m$K%]%$%s%H$rCV$$$F8F$S=P$5$l!"(B
$BEv3:9T$K4p$E$$$FE,@Z$J5M$a9~$_@\F,<-$rJV$9$3$H!#(B
$B$=$l$,(B@code{nil}$B$rJV$9$H!"Ev3:9T$K$O5M$a9~$_@\F,<-$,$J$$$3$H$r0UL#$9$k!#(B
@end defopt

@node Auto Filling
@comment  node-name,  next,  previous,  up
@c @section Auto Filling
@section $B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I(B
@c @cindex filling, automatic
@c @cindex Auto Fill mode
@cindex $B5M$a9~$_!"<+F0(B
@cindex $B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I(B

@c   Auto Fill mode is a minor mode that fills lines automatically as text
@c is inserted.  This section describes the hook used by Auto Fill mode.
@c For a description of functions that you can call explicitly to fill and
@c justify existing text, see @ref{Filling}.
$B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$O!"%F%-%9%H$rA^F~$9$k$K$D$l$F(B
$B<+F0E*$K9T$r5M$a9~$`%^%$%J%b!<%I$G$9!#(B
$BK\@a$G$O!"<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$,;H$&%U%C%/$K$D$$$F=R$Y$^$9!#(B
$B4{B8$N%F%-%9%H$r5M$a9~$s$@$jI}B7$($9$k$?$a$K(B
$BL@<(E*$K8F$S=P$94X?t$K$D$$$F$O!"(B@ref{Filling}$B$r;2>H$7$F$/$@$5$$!#(B

@c   Auto Fill mode also enables the functions that change the margins and
@c justification style to refill portions of the text.  @xref{Margins}.
$B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$G$O!"(B
$B%F%-%9%H$N0lIt$r:F5M$a9~$`:]$N(B
$BM>Gr$dI}B7$(%9%?%$%k$rJQ99$9$k$?$a$N4X?t$b;H$($k$h$&$K$7$^$9!#(B
@xref{Margins}$B!#(B

@defvar auto-fill-function
@c The value of this variable should be a function (of no arguments) to be
@c called after self-inserting a space or a newline.  It may be @code{nil},
@c in which case nothing special is done in that case.
$B$3$NJQ?t$NCM$O!"(B
$B<+8JA^F~$5$l$k6uGr$d2~9T$N$"$H$G8F$S=P$5$l$k$Y$-(B
$B!J0z?t$J$7$N!K4X?t$G$"$k$3$H!#(B
$B$3$l$,(B@code{nil}$B$G$"$k$H!"$=$N$h$&$J>l9g$KFCJL$J$3$H$r9T$o$J$$!#(B

@c The value of @code{auto-fill-function} is @code{do-auto-fill} when
@c Auto-Fill mode is enabled.  That is a function whose sole purpose is to
@c implement the usual strategy for breaking a line.
$B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$,%*%s$G$"$k$H!"(B
@code{auto-fill-function}$B$NCM$O(B@code{do-auto-fill}$B$G$"$k!#(B
$B$3$N4X?t$NL\E*$O!"9TJ,$1$NDL>o$NJ}?K$r<BAu$9$k$3$H$G$"$k!#(B

@quotation
@c In older Emacs versions, this variable was named @code{auto-fill-hook},
@c but since it is not called with the standard convention for hooks, it
@c was renamed to @code{auto-fill-function} in version 19.
Emacs$B$N8E$$HG$G$O!"$3$NJQ?t$r(B@code{auto-fill-hook}$B$HL?L>$7$F$$$?$,!"(B
$B%U%C%/$NI8=`E*$J47=,$K=>$C$F8F$P$l$J$$$?$a(B
19$BHG$G(B@code{auto-fill-function}$B$H2~L>$7$?!#(B
@end quotation
@end defvar

@defvar normal-auto-fill-function
@c This variable specifies the function to use for
@c @code{auto-fill-function}, if and when Auto Fill is turned on.  Major
@c modes can set buffer-local values for this variable to alter how Auto
@c Fill works.
$B$3$NJQ?t$O!"<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$,%*%s$K$J$C$?$H$-!?$G$"$k$H$-$K(B
@code{auto-fill-function}$B$H$7$FMQ$$$k4X?t$r;XDj$9$k!#(B
$B%a%8%c!<%b!<%I$G$O!"$3$NJQ?t$N%P%C%U%!%m!<%+%k$JCM$K@_Dj$9$k$3$H$G(B
$B<+F05M$a9~$_!J(Bauto-filling$B!K%b!<%I$N$U$k$^$$$rJQ99$G$-$k!#(B
@end defvar

@node Sorting
@c @section Sorting Text
@section $B%F%-%9%H$N%=!<%H(B
@c @cindex sorting text
@cindex $B%F%-%9%H$N%=!<%H(B
@cindex $B%=!<%H!"%F%-%9%H(B

@c   The sorting functions described in this section all rearrange text in
@c a buffer.  This is in contrast to the function @code{sort}, which
@c rearranges the order of the elements of a list (@pxref{Rearrangement}).
@c The values returned by these functions are not meaningful.
$BK\@a$G=R$Y$k%=!<%H4X?t$9$Y$F$O!"%P%C%U%!Fb$N%F%-%9%H$rJB$YBX$($^$9!#(B
$B$3$l$O!"%j%9%HFb$NMWAG$N=gHV$rJB$YBX$($k4X?t(B@code{sort}
$B!J(B@pxref{Rearrangement}$B!K$HBP>HE*$G$9!#(B
$B$3$l$i$N4X?t$,JV$9CM$K$O0UL#$O$"$j$^$;$s!#(B

@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
@c This function is the general text-sorting routine that subdivides a
@c buffer into records and then sorts them.  Most of the commands in this
@c section use this function.
$B$3$N4X?t$O!"%P%C%U%!Fb$N%F%-%9%H$r%l%3!<%I$KJ,3d$7$F%=!<%H$9$k(B
$BHFMQ$N%F%-%9%H%=!<%H%k!<%F%#%s$G$"$k!#(B
$BK\@a$N%3%^%s%I$N$[$H$s$I$O!"$3$N4X?t$rMQ$$$k!#(B

@c To understand how @code{sort-subr} works, consider the whole accessible
@c portion of the buffer as being divided into disjoint pieces called
@c @dfn{sort records}.  The records may or may not be contiguous, but they
@c must not overlap.  A portion of each sort record (perhaps all of it) is
@c designated as the sort key.  Sorting rearranges the records in order by
@c their sort keys.
@code{sort-subr}$B$NF0:nJ}K!$rM}2r$9$k$?$a$O!"(B
$B%P%C%U%!$N;2>H2DG=ItJ,A4BN$,(B
@dfn{$B%=!<%H%l%3!<%I(B}$B!J(Bsort record$B!K$H8F$P$l$k(B
$B=E$J$j9g$$$N$J$$CGJR$KJ,3d$5$l$F$$$k$H9M$($k!#(B
$B%l%3!<%I$OO"B3$7$F$$$k$+$b$7$l$J$$$7!"$=$&$G$J$$$+$b$7$l$J$$$,!"(B
$B$1$C$7$F=E$J$j9g$o$J$$!#(B
$B3F%=!<%H%l%3!<%I$N0lItJ,!J$"$k$$$OA4BN!K$r%=!<%H%-!<$H$7$F6hJL$9$k!#(B
$B%=!<%H$G$O!"%=!<%H%-!<$N=g$KJB$V$h$&$K%l%3!<%I$rJB$SBX$($k!#(B

@c Usually, the records are rearranged in order of ascending sort key.
@c If the first argument to the @code{sort-subr} function, @var{reverse},
@c is non-@code{nil}, the sort records are rearranged in order of
@c descending sort key.
$BDL>o!"%l%3!<%I$r%=!<%H%-!<$N>:=g$KJB$YBX$($k!#(B
$B4X?t(B@code{sort-subr}$B$NBh(B1$B0z?t(B@var{reverse}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%=!<%H%-!<$N9_=g$K%l%3!<%I$rJB$YBX$($k!#(B

@c The next four arguments to @code{sort-subr} are functions that are
@c called to move point across a sort record.  They are called many times
@c from within @code{sort-subr}.
@code{sort-subr}$B$N$D$.$N(B4$B$D$N0z?t$O!"(B
$B%=!<%H%l%3!<%I$r$^$?$$$G%]%$%s%H$r0\F0$9$k$?$a$K8F$P$l$k4X?t$G$"$k!#(B
$B$=$l$i$O!"(B@code{sort-subr}$B$GB??t2s8F$S=P$5$l$k!#(B

@enumerate
@item
@c @var{nextrecfun} is called with point at the end of a record.  This
@c function moves point to the start of the next record.  The first record
@c is assumed to start at the position of point when @code{sort-subr} is
@c called.  Therefore, you should usually move point to the beginning of
@c the buffer before calling @code{sort-subr}.
@var{nextrecfun}$B$O!"%l%3!<%I$NKvHx$K%]%$%s%H$rCV$$$F8F$S=P$5$l$k!#(B
$B$3$N4X?t$O!"$D$.$N%l%3!<%I$N@hF,$K%]%$%s%H$r0\F0$9$k!#(B
$B:G=i$N%l%3!<%I$N@hF,$O!"(B
@code{sort-subr}$B$r8F$S=P$7$?$H$-$N%]%$%s%H0LCV$G$"$k$H2>Dj$9$k!#(B
$B$7$?$,$C$F!"(B@code{sort-subr}$B$r8F$S=P$9$^$($K$O!"IaDL!"(B
$B%P%C%U%!$N@hF,$K%]%$%s%H$r0\F0$7$F$*$/$3$H!#(B

@c This function can indicate there are no more sort records by leaving
@c point at the end of the buffer.
$B$3$N4X?t$O!"%P%C%U%!$NKvHx$K%]%$%s%H$rCV$$$F$*$/$3$H$G!"(B
$B%=!<%H%l%3!<%I$,$J$/$J$C$?$3$H$rI=$;$k!#(B

@item
@c @var{endrecfun} is called with point within a record.  It moves point to
@c the end of the record.
@var{endrecfun}$B$O!"%l%3!<%IFb$K%]%$%s%H$rCV$$$F8F$S=P$5$l$k!#(B
$B%l%3!<%I$NKvHx$K%]%$%s%H$r0\F0$9$k!#(B

@item
@c @var{startkeyfun} is called to move point from the start of a record to
@c the start of the sort key.  This argument is optional; if it is omitted,
@c the whole record is the sort key.  If supplied, the function should
@c either return a non-@code{nil} value to be used as the sort key, or
@c return @code{nil} to indicate that the sort key is in the buffer
@c starting at point.  In the latter case, @var{endkeyfun} is called to
@c find the end of the sort key.
@var{startkeyfun}$B$O!"%l%3!<%I$N@hF,$+$i%=!<%H%-!<$N@hF,$X(B
$B%]%$%s%H$r0\F0$9$k$?$a$K8F$S=P$5$l$k!#(B
$B$3$N0z?t$O>JN,2DG=$G$"$j!">JN,$9$k$H%l%3!<%IA4BN$r%=!<%H%-!<$H$9$k!#(B
$B;XDj$7$?>l9g!"$=$N4X?t$O!"%=!<%H%-!<$H$7$FMQ$$$k(B@code{nil}$B0J30$NCM$rJV$9$+!"(B
$B%P%C%U%!$N%]%$%s%H0LCV$+$i%=!<%H%-!<$,;O$^$k$3$H$rI=$9(B@code{nil}$B$rJV$9$3$H!#(B
$B8e<T$N>l9g!"%=!<%H%-!<$NKvHx$rC5$9$?$a$K(B@var{endkeyfun}$B$,8F$P$l$k!#(B

@item
@c @var{endkeyfun} is called to move point from the start of the sort key
@c to the end of the sort key.  This argument is optional.  If
@c @var{startkeyfun} returns @code{nil} and this argument is omitted (or
@c @code{nil}), then the sort key extends to the end of the record.  There
@c is no need for @var{endkeyfun} if @var{startkeyfun} returns a
@c non-@code{nil} value.
@var{endkeyfun}$B$O!"%=!<%H%-!<$N@hF,$+$i%=!<%H%-!<$NKvHx$K(B
$B%]%$%s%H$r0\F0$9$k$?$a$K8F$S=P$5$l$k!#(B
$B$3$N0z?t$O>JN,2DG=$G$"$k!#(B
@var{startkeyfun}$B$,(B@code{nil}$B$rJV$7$3$N0z?t$,>JN,$5$l$F$$$k(B
$B!J$"$k$$$O(B@code{nil}$B$G$"$k!K$H!"%=!<%H%-!<$O%l%3!<%I$NKvHx$^$G$G$"$k!#(B
@var{startkeyfun}$B$,(B@code{nil}$B0J30$NCM$rJV$9$N$G$"$l$P!"(B
@var{endkeyfun}$B$OI,MW$J$$!#(B
@end enumerate

@c As an example of @code{sort-subr}, here is the complete function
@c definition for @code{sort-lines}:
@code{sort-subr}$B$NNc$H$7$F!"(B
@code{sort-lines}$B$N40A4$J4X?tDj5A$r<($9!#(B

@example
@group
@c ;; @r{Note that the first two lines of doc string}
@c ;; @r{are effectively one line when viewed by a user.}
;; @r{$B@bL@J8;zNs$N;O$a$N(B2$B9T$O!"%f!<%6!<$,8+$k$H$-$K$O(B}
;; @r{$B<B<AE*$K$O(B1$B9T$G$"$k$3$H$KCm0U(B}
(defun sort-lines (reverse beg end)
  "Sort lines in region alphabetically;\
 argument means descending order.
Called from a program, there are three arguments:
@end group
@group
REVERSE (non-nil means reverse order),\
 BEG and END (region to sort).
The variable `sort-fold-case' determines\
 whether alphabetic case affects
the sort order.
@end group
@group
  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (sort-subr reverse 'forward-line 'end-of-line))))
@end group
@end example

@c Here @code{forward-line} moves point to the start of the next record,
@c and @code{end-of-line} moves point to the end of record.  We do not pass
@c the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire
@c record is used as the sort key.
$B$3$3$G!"(B@code{forward-line}$B$O$D$.$N%l%3!<%I$N@hF,$K%]%$%s%H$r0\F0$7!"(B
@code{end-of-line}$B$O%l%3!<%I$NKvHx$K%]%$%s%H$r0\F0$9$k!#(B
$B%l%3!<%IA4BN$r%=!<%H%-!<$H$7$FMQ$$$k$?$a!"(B
$B0z?t(B@var{startkeyfun}$B$H(B@var{endkeyfun}$B$O;XDj$7$J$$!#(B

@c The @code{sort-paragraphs} function is very much the same, except that
@c its @code{sort-subr} call looks like this:
$B4X?t(B@code{sort-paragraphs}$B$b$[$\F1MM$G$"$k$,!"(B
$B$D$.$N$h$&$K(B@code{sort-subr}$B$r8F$S=P$9E@$,0[$J$k!#(B

@example
@group
(sort-subr reverse
           (function
             (lambda ()
               (while (and (not (eobp))
                      (looking-at paragraph-separate))
                 (forward-line 1))))
           'forward-paragraph)
@end group
@end example

@c Markers pointing into any sort records are left with no useful
@c position after @code{sort-subr} returns.
@code{sort-subr}$B$+$iLa$C$?$"$H$G$O!"(B
$B%=!<%H%l%3!<%I$r;X$7$F$$$k%^!<%+$O0UL#$N$"$k0LCV$r;X$7$F$$$J$$!#(B
@end defun

@defopt sort-fold-case
@c If this variable is non-@code{nil}, @code{sort-subr} and the other
@c buffer sorting functions ignore case when comparing strings.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{sort-subr}$B$dB>$N%P%C%U%!%=!<%H4X?t$O!"(B
$BJ8;zNs$NHf3S$K$*$$$FBgJ8;z>.J8;z$r6hJL$7$J$$!#(B
@end defopt

@c @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
@deffn $B%3%^%s%I(B sort-regexp-fields reverse record-regexp key-regexp start end
@c This command sorts the region between @var{start} and @var{end}
@c alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
@c If @var{reverse} is a negative integer, then sorting is in reverse
@c order.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$r(B
@var{record-regexp}$B$H(B@var{key-regexp}$B$N;XDj$K=>$C$F(B
$B%"%k%U%!%Y%C%H=g$K%=!<%H$9$k!#(B
@var{reverse}$B$,Ii$N@0?t$G$"$k$H!"5U=g$K%=!<%H$9$k!#(B

@c Alphabetical sorting means that two sort keys are compared by
@c comparing the first characters of each, the second characters of each,
@c and so on.  If a mismatch is found, it means that the sort keys are
@c unequal; the sort key whose character is less at the point of first
@c mismatch is the lesser sort key.  The individual characters are compared
@c according to their numerical character codes in the Emacs character set.
$B%"%k%U%!%Y%C%H=g$N%=!<%H$H$O!"(B
$B:G=i$NJ8;zF1;N!"(B2$BHVL\$NJ8;zF1;N$H$$$C$?6q9g$K(B
2$B$D$N%=!<%H%-!<$rHf3S$9$k$3$H$G$"$k!#(B
$BIT0lCW$,$_$D$+$k$H!"%=!<%H%-!<$,Ey$7$/$J$$$3$H$r0UL#$7!"(B
$B:G=i$NIT0lCW2U=j$NJ8;z$,>.$5$$$[$&$N%=!<%H%-!<$,>.$5$$!#(B
$B8D!9$NJ8;z$O!"(BEmacs$B$NJ8;z=89g$K$*$1$kJ8;z%3!<%I$N?tCM$K=>$C$FHf3S$9$k!#(B

@c The value of the @var{record-regexp} argument specifies how to divide
@c the buffer into sort records.  At the end of each record, a search is
@c done for this regular expression, and the text that matches it is taken
@c as the next record.  For example, the regular expression @samp{^.+$},
@c which matches lines with at least one character besides a newline, would
@c make each such line into a sort record.  @xref{Regular Expressions}, for
@c a description of the syntax and meaning of regular expressions.
$B0z?t(B@var{record-regexp}$B$NCM$O!"%P%C%U%!$r%=!<%H%l%3!<%I$K(B
$BJ,3d$9$kJ}K!$r;XDj$9$k!#(B
$B3F%l%3!<%I$NKvHx$K$*$$$F!"$3$N@55,I=8=$rC5:w$7(B
$B$=$l$K0lCW$7$?%F%-%9%H$r$D$.$N%l%3!<%I$H$9$k!#(B
$B$?$H$($P!"@55,I=8=(B@samp{^.+$}$B$O!"(B
$B>/$J$/$H$b(B1$B$D$NJ8;z$N$"$H$K2~9T$,$"$k$h$&$J9T$K0lCW$7!"(B
$B$=$N$h$&$J9T$r%=!<%H%l%3!<%I$H$9$k!#(B
$B@55,I=8=$N9=J8$H0UL#$K$D$$$F$O!"(B@pxref{Regular Expressions}$B!#(B

@c The value of the @var{key-regexp} argument specifies what part of each
@c record is the sort key.  The @var{key-regexp} could match the whole
@c record, or only a part.  In the latter case, the rest of the record has
@c no effect on the sorted order of records, but it is carried along when
@c the record moves to its new position.
$B0z?t(B@var{key-regexp}$B$NCM$O!"(B
$B%l%3!<%I$N$I$NItJ,$,%=!<%H%-!<$G$"$k$+$r;XDj$9$k!#(B
@var{key-regexp}$B$O!"%l%3!<%IA4BN$+$=$N0lItJ,$K0lCW$9$k!#(B
$B8e<T$N>l9g!"%l%3!<%I$N;D$j$NItJ,$O!"%l%3!<%I$NJB$SBX$(=g=x$K$O1F6A$7$J$$$,!"(B
$B%l%3!<%I$r$=$N?7$?$J0LCV$K0\F0$9$k$H$-$K$$$C$7$g$K0\F0$5$l$k!#(B

@c The @var{key-regexp} argument can refer to the text matched by a
@c subexpression of @var{record-regexp}, or it can be a regular expression
@c on its own.
$B0z?t(B@var{key-regexp}$B$G(B
@var{record-regexp}$B$NItJ,<0$K0lCW$7$?%F%-%9%H$r;2>H$7$F$b$h$$$7!"(B
$BFHN)$7$?@55,I=8=$G$b$h$$!#(B

@c If @var{key-regexp} is:
@var{key-regexp}$B$K$O$D$.$N2DG=@-$,$"$k!#(B

@table @asis
@item @samp{\@var{digit}}
@c then the text matched by the @var{digit}th @samp{\(...\)} parenthesis
@c grouping in @var{record-regexp} is the sort key.
@var{record-regexp}$B$N(B@var{digit}$BHVL\$N(B
$B3g8L$K$h$k%0%k!<%W2=(B@samp{\(...\)}$B$K0lCW$7$?%F%-%9%H$,%=!<%H%-!<$G$"$k!#(B

@item @samp{\&}
@c then the whole record is the sort key.
$B%l%3!<%IA4BN$,%=!<%H%-!<$G$"$k!#(B

@c @item a regular expression
@item $B@55,I=8=(B
@c then @code{sort-regexp-fields} searches for a match for the regular
@c expression within the record.  If such a match is found, it is the sort
@c key.  If there is no match for @var{key-regexp} within a record then
@c that record is ignored, which means its position in the buffer is not
@c changed.  (The other records may move around it.)
@code{sort-regexp-fields}$B$O%l%3!<%IFb$G$3$N@55,I=8=$K0lCW$9$k$b$N$rC5$9!#(B
$B0lCW$,$_$D$+$l$P!"$=$l$,%=!<%H%-!<$K$J$k!#(B
$B%l%3!<%IFb$G(B@var{key-regexp}$B$KBP$9$k0lCW$,$_$D$+$i$J$1$l$P!"(B
$B%l%3!<%I$rL5;k$9$k!#(B
$B$D$^$j!"%P%C%U%!Fb$G$NEv3:%l%3!<%I$N0LCV$rJQ99$7$J$$!#(B
$B!JJL$N%l%3!<%I$,<~$j$K0\F0$7$F$/$k$+$b$7$l$J$$!#!K(B
@end table

@c For example, if you plan to sort all the lines in the region by the
@c first word on each line starting with the letter @samp{f}, you should
@c set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to
@c @samp{\<f\w*\>}.  The resulting expression looks like this:
$B$?$H$($P!"NN0hFb$N$9$Y$F$N9T$r3F9T$N(B@samp{f}$B$G;O$^$k:G=i$NC18l$G(B
$B%=!<%H$9$k$K$O!"(B@var{record-regexp}$B$K(B@samp{^.*$}$B!"(B
@var{key-regexp}$B$K(B@samp{\<f\w*\>}$B$r;XDj$9$k!#(B
$B$D$^$j!"$D$.$N$h$&$J<0$K$J$k!#(B

@example
@group
(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
                    (region-beginning)
                    (region-end))
@end group
@end example

@c If you call @code{sort-regexp-fields} interactively, it prompts for
@c @var{record-regexp} and @var{key-regexp} in the minibuffer.
@code{sort-regexp-fields}$B$rBPOCE*$K8F$S=P$9$H!"(B
$B%_%K%P%C%U%!$G(B@var{record-regexp}$B$H(B@var{key-regexp}$B$rLd$$9g$o$;$k!#(B
@end deffn

@c @deffn Command sort-lines reverse start end
@deffn $B%3%^%s%I(B sort-lines reverse start end
@c This command alphabetically sorts lines in the region between
@c @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
@c is in reverse order.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$N9T$r(B
$B%"%k%U%!%Y%C%H=g$K%=!<%H$9$k!#(B
@var{reverse}$B$,(B@code{nil}$B0J30$G$"$k$H!"5U=g$K%=!<%H$9$k!#(B
@end deffn

@c @deffn Command sort-paragraphs reverse start end
@deffn $B%3%^%s%I(B sort-paragraphs reverse start end
@c This command alphabetically sorts paragraphs in the region between
@c @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
@c is in reverse order.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$NCJMn$r(B
$B%"%k%U%!%Y%C%H=g$K%=!<%H$9$k!#(B
@var{reverse}$B$,(B@code{nil}$B0J30$G$"$k$H!"5U=g$K%=!<%H$9$k!#(B
@end deffn

@c @deffn Command sort-pages reverse start end
@deffn $B%3%^%s%I(B sort-pages reverse start end
@c This command alphabetically sorts pages in the region between
@c @var{start} and @var{end}.  If @var{reverse} is non-@code{nil}, the sort
@c is in reverse order.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$N%Z!<%8$r(B
$B%"%k%U%!%Y%C%H=g$K%=!<%H$9$k!#(B
@var{reverse}$B$,(B@code{nil}$B0J30$G$"$k$H!"5U=g$K%=!<%H$9$k!#(B
@end deffn

@c @deffn Command sort-fields field start end
@deffn $B%3%^%s%I(B sort-fields field start end
@c This command sorts lines in the region between @var{start} and
@c @var{end}, comparing them alphabetically by the @var{field}th field
@c of each line.  Fields are separated by whitespace and numbered starting
@c from 1.  If @var{field} is negative, sorting is by the
@c @w{@minus{}@var{field}th} field from the end of the line.  This command
@c is useful for sorting tables.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$N9T$r(B
$B3F9T$N(B@var{field}$BHVL\$N%U%#!<%k%IF1;N$r%"%k%U%!%Y%C%H=g$KHf3S$7$F%=!<%H$9$k!#(B
$B%U%#!<%k%I$OGrJ8;z$G6h@Z$i$l!"(B1$B$+$i?t$($k!#(B
@var{field}$B$,Ii$G$"$k$H!"(B
$B9TKv$+$i(B@minus{}@var{field}$BHVL\$N%U%#!<%k%I$G%=!<%H$9$k!#(B
$B$3$N%3%^%s%I$O!"I=$r%=!<%H$9$k$N$KM-MQ$G$"$k!#(B
@end deffn

@c @deffn Command sort-numeric-fields field start end
@deffn $B%3%^%s%I(B sort-numeric-fields field start end
@c This command sorts lines in the region between @var{start} and
@c @var{end}, comparing them numerically by the @var{field}th field of each
@c line.  The specified field must contain a number in each line of the
@c region.  Fields are separated by whitespace and numbered starting from
@c 1.  If @var{field} is negative, sorting is by the
@c @w{@minus{}@var{field}th} field from the end of the line.  This command
@c is useful for sorting tables.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$N9T$r(B
$B3F9T$N(B@var{field}$BHVL\$N%U%#!<%k%IF1;N$r?tCM$H$7$FHf3S$7$F%=!<%H$9$k!#(B
$BNN0hFb$N3F9T$N;XDj$7$?%U%#!<%k%I$K$O?t$,$"$k$3$H!#(B
$B%U%#!<%k%I$OGrJ8;z$G6h@Z$i$l!"(B1$B$+$i?t$($k!#(B
@var{field}$B$,Ii$G$"$k$H!"(B
$B9TKv$+$i(B@minus{}@var{field}$BHVL\$N%U%#!<%k%I$G%=!<%H$9$k!#(B
$B$3$N%3%^%s%I$O!"I=$r%=!<%H$9$k$N$KM-MQ$G$"$k!#(B
@end deffn

@c @deffn Command sort-columns reverse &optional beg end
@deffn $B%3%^%s%I(B sort-columns reverse &optional beg end
@c This command sorts the lines in the region between @var{beg} and
@c @var{end}, comparing them alphabetically by a certain range of columns.
@c The column positions of @var{beg} and @var{end} bound the range of
@c columns to sort on.
$B$3$N%3%^%s%I$O!"(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NNN0h$N9T$r(B
$BFCDjHO0O$N%3%i%`$r%"%k%U%!%Y%C%H=g$KHf3S$7$F%=!<%H$9$k!#(B
@var{beg}$B$H(B@var{end}$B$N%3%i%`0LCV$O!"%=!<%HBP>]$N%3%i%`$NHO0O$r6h@Z$k!#(B

@c If @var{reverse} is non-@code{nil}, the sort is in reverse order.
@var{reverse}$B$,(B@code{nil}$B0J30$G$"$k$H!"5U=g$K%=!<%H$9$k!#(B

@c One unusual thing about this command is that the entire line
@c containing position @var{beg}, and the entire line containing position
@c @var{end}, are included in the region sorted.
$B$3$N%3%^%s%I$NIaDL$G$J$$E@$O!"(B
$B0LCV(B@var{beg}$B$r4^$`9TA4BN$H0LCV(B@var{end}$B$r4^$`9TA4BN$b(B
$B%=!<%HBP>]$NNN0h$K4^$^$l$k$3$H$G$"$k!#(B

@c Note that @code{sort-columns} uses the @code{sort} utility program,
@c and so cannot work properly on text containing tab characters.  Use
@c @kbd{M-x untabify} to convert tabs to spaces before sorting.
@code{sort-columns}$B$O!"%f!<%F%#%j%F%#%W%m%0%i%`(B@code{sort}$B$r;H$&$?$a!"(B
$B%?%VJ8;z$r4^$`%F%-%9%H$r@5$7$/07$($J$$!#(B
$B%=!<%H$9$k$^$($K(B@kbd{M-x untabify}$B$r;H$C$F%?%V$r6uGr$KJQ49$9$k$3$H!#(B
@end deffn

@node Columns
@comment  node-name,  next,  previous,  up
@c @section Counting Columns
@section $B%3%i%`$r?t$($k(B
@c @cindex columns
@c @cindex counting columns
@c @cindex horizontal position
@cindex $B%3%i%`(B
@cindex $B%3%i%`$r?t$($k(B
@cindex $B?eJ?0LCV(B

@c   The column functions convert between a character position (counting
@c characters from the beginning of the buffer) and a column position
@c (counting screen characters from the beginning of a line).
$B%3%i%`4X?t$O!"!J%P%C%U%!$N@hF,$+$iJ8;z$r?t$($?!KJ8;z0LCV$r(B
$B!J%9%/%j!<%s$N9TF,$+$iJ8;z$r?t$($?!K%3%i%`0LCV$KJQ49$7$^$9!#(B

@c   These functions count each character according to the number of
@c columns it occupies on the screen.  This means control characters count
@c as occupying 2 or 4 columns, depending upon the value of
@c @code{ctl-arrow}, and tabs count as occupying a number of columns that
@c depends on the value of @code{tab-width} and on the column where the tab
@c begins.  @xref{Usual Display}.
$B$3$l$i$N4X?t$O!"3FJ8;z$r$=$l$,%9%/%j!<%s>e$G@j$a$k%3%i%`?t$r4p$K?t$($k!#(B
$B$D$^$j!"(B@code{ctl-arrow}$B$NCM$K0MB8$7$F%3%s%H%m!<%kJ8;z$O!"(B
2$B%3%i%`$+(B4$B%3%i%`@j$a$k$H?t$(!"(B
$B%?%VJ8;z$O!"%?%V$N3+;O%3%i%`$H(B@code{tab-width}$B$NCM$K0MB8$9$k(B
$B%3%i%`?t$r@j$a$k$H?t$($k$3$H$r0UL#$7$^$9!#(B
@xref{Usual Display}$B!#(B

@c   Column number computations ignore the width of the window and the
@c amount of horizontal scrolling.  Consequently, a column value can be
@c arbitrarily high.  The first (or leftmost) column is numbered 0.
$B%3%i%`HV9f$N7W;;$G$O!"%&%#%s%I%&$NI}$d?eJ?%9%/%m!<%kNL$rL5;k$7$^$9!#(B
$B$=$N7k2L!"%3%i%`CM$OG$0U$NBg$-$5$K$J$j$($^$9!#(B
$B:G=i$N!J%9%/%j!<%s:8C<$N!K%3%i%`$NHV9f$O(B0$B$G$9!#(B

@defun current-column
@c This function returns the horizontal position of point, measured in
@c columns, counting from 0 at the left margin.  The column position is the
@c sum of the widths of all the displayed representations of the characters
@c between the start of the current line and point.
$B$3$N4X?t$O!":8C<$r(B0$B$H$7$F%3%i%`?t$G?t$($?%]%$%s%H$N?eJ?0LCV$rJV$9!#(B
$B%3%i%`0LCV$O!"8=:_9T$N@hF,$+$i%]%$%s%H0LCV$^$G$NJ8;z$9$Y$F$N(B
$BI=<(>e$NI=5-$NI}$NAmOB$G$"$k!#(B

@c For an example of using @code{current-column}, see the description of
@c @code{count-lines} in @ref{Text Lines}.
@code{current-column}$B$N;HMQNc$K$D$$$F$O!"(B
@ref{Text Lines}$B$N(B@code{count-lines}$B$r;2>H!#(B
@end defun

@defun move-to-column column &optional force
@c This function moves point to @var{column} in the current line.  The
@c calculation of @var{column} takes into account the widths of the
@c displayed representations of the characters between the start of the
@c line and point.
$B$3$N4X?t$O!"%]%$%s%H$r8=:_9T$N(B@var{column}$B$X0\F0$9$k!#(B
@var{column}$B$N7W;;$G$O!"8=:_9T$N@hF,$+$i%]%$%s%H0LCV$^$G$N(B
$BJ8;z$9$Y$F$NI=<(>e$NI=5-$NI}$r9MN8$9$k!#(B

@c If column @var{column} is beyond the end of the line, point moves to the
@c end of the line.  If @var{column} is negative, point moves to the
@c beginning of the line.
$B%3%i%`(B@var{column}$B$,9TKv$r1[$($k>l9g!"%]%$%s%H$r9TKv$X0\F0$9$k!#(B
@var{column}$B$,Ii$G$"$k$H!"%]%$%s%H$r9TF,$X0\F0$9$k!#(B

@c If it is impossible to move to column @var{column} because that is in
@c the middle of a multicolumn character such as a tab, point moves to the
@c end of that character.  However, if @var{force} is non-@code{nil}, and
@c @var{column} is in the middle of a tab, then @code{move-to-column}
@c converts the tab into spaces so that it can move precisely to column
@c @var{column}.  Other multicolumn characters can cause anomalies despite
@c @var{force}, since there is no way to split them.
$B%3%i%`(B@var{column}$B$,%?%V$J$I$NJ#?t%3%i%`$r@j$a$kJ8;z$NCf$[$I$K$"$k$?$a$K(B
$B$=$3$X0\F0$G$-$J$$>l9g$K$O!"(B
$B%]%$%s%H$rEv3:J8;z$NKvHx$X0\F0$9$k!#(B
$B$7$+$7!"(B@var{force}$B$,(B@code{nil}$B0J30$G$"$j(B
@var{column}$B$,%?%V$NCf$[$I$G$"$k$H!"(B
$B%3%i%`(B@var{column}$B$K@53N$K0\F0$G$-$k$h$&$K%?%V$r6uGr$KJQ49$9$k!#(B
$BJ#?t%3%i%`$r@j$a$k$=$NB>$NJ8;z$G$O!"$=$l$i$rJ,3d$9$kJ}K!$,$J$$$?$a!"(B
@var{force}$B$r;XDj$7$F$bJQB'E*$K$J$k!#(B

@c The argument @var{force} also has an effect if the line isn't long
@c enough to reach column @var{column}; in that case, it says to add
@c whitespace at the end of the line to reach that column.
$B%3%i%`(B@var{column}$B$KE~C#$G$-$k$[$I9T$,D9$/$J$$>l9g$K$b(B
$B0z?t(B@var{force}$B$K$O8z2L$,$"$k!#(B
$B$=$N$h$&$J>l9g!";XDj%3%i%`$KC#$9$k$h$&$K9TKv$KGrJ8;z$rDI2C$9$k!#(B

@c If @var{column} is not an integer, an error is signaled.
@var{column}$B$,@0?t$G$J$$$H!"%(%i!<$rDLCN$9$k!#(B

@c The return value is the column number actually moved to.
$BLa$jCM$O!"<B:]$N0\F0@h$N%3%i%`HV9f$G$"$k!#(B
@end defun

@node Indentation
@c @section Indentation
@section $B;z2<$2(B
@c @cindex indentation
@cindex $B;z2<$2(B

@c   The indentation functions are used to examine, move to, and change
@c whitespace that is at the beginning of a line.  Some of the functions
@c can also change whitespace elsewhere on a line.  Columns and indentation
@c count from zero at the left margin.
$B;z2<$24X?t$O!"9TF,$N6uGr$rD4$Y$?$j!"$=$3$X0\F0$7$?$j!"(B
$BJQ99$9$k$?$a$K;H$$$^$9!#(B
$B9T$NB>$NGrJ8;z$rJQ99$9$k$b$N$b$"$j$^$9!#(B
$B%3%i%`4X?t$H;z2<$24X?t$O:8C<$r(B0$B$H?t$($^$9!#(B

@menu
* Primitive Indent::      Functions used to count and insert indentation.
* Mode-Specific Indent::  Customize indentation for different modes.
* Region Indent::         Indent all the lines in a region.
* Relative Indent::       Indent the current line based on previous lines.
* Indent Tabs::           Adjustable, typewriter-like tab stops.
* Motion by Indent::      Move to first non-blank character.
@end menu

@node Primitive Indent
@c @subsection Indentation Primitives
@subsection $B;z2<$24pK\4X?t(B

@c   This section describes the primitive functions used to count and
@c insert indentation.  The functions in the following sections use these
@c primitives.  @xref{Width}, for related functions.
$BK\@a$G$O!";z2<$2$r?t$($?$jA^F~$9$k$?$a$K;H$o$l$k4pK\4X?t$K$D$$$F=R$Y$^$9!#(B
$B8eB3$N@a$N4X?t72$O!"$3$l$i$N4pK\4X?t$r;H$C$F$$$^$9!#(B
$B4XO"$9$k4X?t$K$D$$$F$O!"(B@xref{Width}$B!#(B

@defun current-indentation
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
@c This function returns the indentation of the current line, which is
@c the horizontal position of the first nonblank character.  If the
@c contents are entirely blank, then this is the horizontal position of the
@c end of the line.
$B$3$N4X?t$O!"8=:_9T$N;z2<$2$rJV$9!#(B
$B$3$l$O:G=i$NGrJ8;z0J30$NJ8;z$N?eJ?0LCV$G$"$k!#(B
$B9TA4BN$,GrJ8;z$d6u$G$"$k>l9g$K$O!"9TKv$N?eJ?0LCV$rJV$9!#(B
@end defun

@c @deffn Command indent-to column &optional minimum
@deffn $B%3%^%s%I(B indent-to column &optional minimum
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
@c This function indents from point with tabs and spaces until @var{column}
@c is reached.  If @var{minimum} is specified and non-@code{nil}, then at
@c least that many spaces are inserted even if this requires going beyond
@c @var{column}.  Otherwise the function does nothing if point is already
@c beyond @var{column}.  The value is the column at which the inserted
@c indentation ends.
$B$3$N4X?t$O!"%]%$%s%H0LCV$+$i(B@var{column}$B$KC#$9$k$^$G%?%V$d6uGr$G;z2<$2$9$k!#(B
@var{minimum}$B$r;XDj$7(B@code{nil}$B0J30$G$"$k$H!"(B
@var{column}$B$r1[$($k>l9g$G$"$C$F$b:GDc(B@var{minimum}$B8D$N6uGr$rA^F~$9$k!#(B
$B$5$b$J$1$l$P!"%]%$%s%H$,(B@var{column}$B$r1[$($F$$$k>l9g$K$O!"(B
$B$3$N4X?t$O$J$K$b$7$J$$!#(B
$BLa$jCM$O!"A^F~$7$?;z2<$2$,=*$k2U=j$N%3%i%`$G$"$k!#(B

@c The inserted whitespace characters inherit text properties from the
@c surrounding text (usually, from the preceding text only).  @xref{Sticky
@c Properties}.
$BA^F~$5$l$?GrJ8;z$O<~$j$NJ8;z!JIaDL$O!"$^$($NJ8;z!K$+$i%F%-%9%HB0@-$r7Q>5$9$k!#(B
@pxref{Sticky Properties}$B!#(B
@end deffn

@defopt indent-tabs-mode
@comment !!SourceFile indent.c
@c If this variable is non-@code{nil}, indentation functions can insert
@c tabs as well as spaces.  Otherwise, they insert only spaces.  Setting
@c this variable automatically makes it buffer-local in the current buffer.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B;z2<$24X?t$O6uGr$K2C$($F%?%V$bA^F~$9$k!#(B
$B$5$b$J$1$l$P!"6uGr$N$_$rA^F~$9$k!#(B
$B$3$NJQ?t$K@_Dj$9$k$H!"%+%l%s%H%P%C%U%!$G%P%C%U%!%m!<%+%k$K$J$k!#(B
@end defopt

@node Mode-Specific Indent
@c @subsection Indentation Controlled by Major Mode
@subsection $B%a%8%c!<%b!<%I$N@)8f$K$h$k;z2<$2(B

@c   An important function of each major mode is to customize the @key{TAB}
@c key to indent properly for the language being edited.  This section
@c describes the mechanism of the @key{TAB} key and how to control it.
@c The functions in this section return unpredictable values.
$B3F%a%8%c!<%b!<%I$N=EMW$J5!G=$O!"(B
$B%-!<(B@key{TAB}$B$rJT=8BP>]$N8@8l$KE,$7$?;z2<$2$K%+%9%?%^%$%:$9$k$3$H$G$9!#(B
$BK\@a$G$O!"%-!<(B@key{TAB}$B$N5!9=$H$=$l$r@)8f$9$kJ}K!$K$D$$$F=R$Y$^$9!#(B
$BK\@a$N4X?t$O!"M=B,$G$-$J$$CM$rJV$7$^$9!#(B

@defvar indent-line-function
@c This variable's value is the function to be used by @key{TAB} (and
@c various commands) to indent the current line.  The command
@c @code{indent-according-to-mode} does no more than call this function.
$B$3$NJQ?t$NCM$O!"8=:_9T$r;z2<$2$9$k$?$a$K(B
@key{TAB}$B!J$d$5$^$6$^$J%3%^%s%I!K$,;H$&4X?t$G$"$k!#(B
$B%3%^%s%I(B@code{indent-according-to-mode}$B$O!"(B
$B$3$N4X?t$r8F$V$3$H0J>e$N$3$H$O$7$J$$!#(B

@c In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C
@c mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}.
@c In Fundamental mode, Text mode, and many other modes with no standard
@c for indentation, the value is @code{indent-to-left-margin} (which is the
@c default value).
lisp$B%b!<%I$G$OCM$O%7%s%\%k(B@code{lisp-indent-line}$B!"(B
C$B%b!<%I$G$O(B@code{c-indent-line}$B!"(B
fortran$B%b!<%I$G$O(B@code{fortran-indent-line}$B$G$"$k!#(B
$BI8=`E*$J;z2<$2$,$J$$4pK\!J(Bfundamental$B!K%b!<%I!"(B
$B%F%-%9%H!J(Btext$B!K%b!<%I!"B>$NB?$/$N%b!<%I$G$O!"(B
$BCM$O(B@code{indent-to-left-margin}$B!J%G%U%)%k%HCM!K$G$"$k(B
@end defvar

@c @deffn Command indent-according-to-mode
@deffn $B%3%^%s%I(B indent-according-to-mode
@c This command calls the function in @code{indent-line-function} to
@c indent the current line in a way appropriate for the current major mode.
$B$3$N%3%^%s%I$O!"8=:_$N%a%8%c!<%b!<%I$KE,$7$?J}K!$G8=:_9T$r;z2<$2$9$k$?$a$K(B
@code{indent-line-function}$B$G;XDj$5$l$k4X?t$r8F$S=P$9!#(B
@end deffn

@c @deffn Command indent-for-tab-command
@deffn $B%3%^%s%I(B indent-for-tab-command
@c This command calls the function in @code{indent-line-function} to indent
@c the current line; however, if that function is
@c @code{indent-to-left-margin}, @code{insert-tab} is called instead.  (That
@c is a trivial command that inserts a tab character.)
$B$3$N%3%^%s%I$O!"8=:_9T$r;z2<$2$9$k$?$a$K(B
@code{indent-line-function}$B$G;XDj$5$l$k4X?t$r8F$S=P$9$,!"(B
$B$=$N4X?t$,(B@code{indent-to-left-margin}$B$G$"$k$H!"(B
$B$+$o$j$K(B@code{insert-tab}$B$r8F$S=P$9!#(B
$B!J$3$l$O%?%VJ8;z$rA^F~$9$kC1=c$J%3%^%s%I$G$"$k!#!K(B
@end deffn

@c @deffn Command newline-and-indent
@deffn $B%3%^%s%I(B newline-and-indent
@comment !!SourceFile simple.el
@c This function inserts a newline, then indents the new line (the one
@c following the newline just inserted) according to the major mode.
$B$3$N4X?t$O!"2~9T$rA^F~$7$F$+$i!"(B
$B!J2~9T$rA^F~$7$?$P$+$j$N9T$KB3$/!K?7$?$J9T$r(B
$B%a%8%c!<%b!<%I$K4p$E$$$F;z2<$2$9$k!#(B

@c It does indentation by calling the current @code{indent-line-function}.
@c In programming language modes, this is the same thing @key{TAB} does,
@c but in some text modes, where @key{TAB} inserts a tab,
@c @code{newline-and-indent} indents to the column specified by
@c @code{left-margin}.
$B8=:_$N(B@code{indent-line-function}$B$r8F$S=P$7$F;z2<$2$r9T$&!#(B
$B%W%m%0%i%`8@8l8~$1$N%b!<%I$G$O!"$3$l$O(B@key{TAB}$B$,9T$&$3$H$HF1$8$G$"$k$,!"(B
@key{TAB}$B$,%?%V$rA^F~$9$k%F%-%9%H8~$1$N%b!<%I$N0lIt$G$O!"(B
@code{newline-and-indent}$B$O(B@code{left-margin}$B$G;XDj$5$l$?%3%i%`$K;z2<$2$9$k!#(B
@end deffn

@c @deffn Command reindent-then-newline-and-indent
@deffn $B%3%^%s%I(B reindent-then-newline-and-indent
@comment !!SourceFile simple.el
@c This command reindents the current line, inserts a newline at point,
@c and then indents the new line (the one following the newline just
@c inserted).
$B$3$N%3%^%s%I$O!"8=:_9T$r;z2<$2$7D>$7!"%]%$%s%H0LCV$K2~9T$rA^F~$7!"(B
$B!J2~9T$rA^F~$7$?$P$+$j$N9T$KB3$/!K?7$?$J9T$r;z2<$2$9$k!#(B

@c This command does indentation on both lines according to the current
@c major mode, by calling the current value of @code{indent-line-function}.
@c In programming language modes, this is the same thing @key{TAB} does,
@c but in some text modes, where @key{TAB} inserts a tab,
@c @code{reindent-then-newline-and-indent} indents to the column specified
@c by @code{left-margin}.
$B$3$N%3%^%s%I$O!"(B@code{indent-line-function}$B$N8=:_$NCM$r8F$S=P$9$3$H$G!"(B
$B$I$A$i$N9T$b8=:_$N%a%8%c!<%b!<%I$K4p$E$$$F;z2<$2$9$k!#(B
$B%W%m%0%i%`8@8l8~$1$N%b!<%I$G$O!"$3$l$O(B@key{TAB}$B$,9T$&$3$H$HF1$8$G$"$k$,!"(B
@key{TAB}$B$,%?%V$rA^F~$9$k%F%-%9%H8~$1$N%b!<%I$N0lIt$G$O!"(B
@code{reindent-then-newline-and-indent}$B$O!"(B
@code{left-margin}$B$G;XDj$5$l$k%3%i%`$K;z2<$2$9$k!#(B
@end deffn

@node Region Indent
@c @subsection Indenting an Entire Region
@subsection $BNN0hA4BN$N;z2<$2(B

@c   This section describes commands that indent all the lines in the
@c region.  They return unpredictable values.
$BK\@a$G$O!"NN0hFb$N$9$Y$F$N9T$r;z2<$2$9$k%3%^%s%I$K$D$$$F=R$Y$^$9!#(B
$B$3$l$i$OM=B,$G$-$J$$CM$rJV$7$^$9!#(B

@c @deffn Command indent-region start end to-column
@deffn $B%3%^%s%I(B indent-region start end to-column
@c This command indents each nonblank line starting between @var{start}
@c (inclusive) and @var{end} (exclusive).  If @var{to-column} is
@c @code{nil}, @code{indent-region} indents each nonblank line by calling
@c the current mode's indentation function, the value of
@c @code{indent-line-function}.
$B$3$N%3%^%s%I$O!"(B@var{start}$B!J$r4^$a$F!K$H(B
@var{end}$B!J$r4^$a$J$$!K$N$"$$$@$G;O$^$k6u$G$J$$3F9T$r;z2<$2$9$k!#(B
@var{to-column}$B$,(B@code{nil}$B$G$"$k$H!"(B
@code{indent-region}$B$O!"8=:_$N%b!<%I$N;z2<$24X?t!"(B
$B$D$^$j!"(B@code{indent-line-function}$B$NCM$r8F$S=P$7$F!"(B
$B6u$G$J$$3F9T$r;z2<$2$9$k!#(B

@c If @var{to-column} is non-@code{nil}, it should be an integer
@c specifying the number of columns of indentation; then this function
@c gives each line exactly that much indentation, by either adding or
@c deleting whitespace.
@var{to-column}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$l$O;z2<$2@h$N%3%i%`HV9f$r;XDj$9$k@0?t$G$"$k$3$H!#(B
$B$9$k$H!"$3$N4X?t$O!"GrJ8;z$rDI2C$9$k$+:o=|$7$F!"(B
$B3F9T$r;XDj$I$*$j$K;z2<$2$9$k!#(B

@c If there is a fill prefix, @code{indent-region} indents each line
@c by making it start with the fill prefix.
$B5M$a9~$_@\F,<-$,$"$k>l9g!"(B
@code{indent-region}$B$O5M$a9~$_@\F,<-$G9T$r;O$a$k$3$H$G3F9T$r;z2<$2$9$k!#(B
@end deffn

@defvar indent-region-function
@c The value of this variable is a function that can be used by
@c @code{indent-region} as a short cut.  It should take two arguments, the
@c start and end of the region.  You should design the function so
@c that it will produce the same results as indenting the lines of the
@c region one by one, but presumably faster.
$B$3$NJQ?t$NCM$O!"(B@code{indent-region}$B$NC;=LHG$H$7$FMxMQ2DG=$J4X?t$G$"$k!#(B
$BNN0h$N3+;O0LCV$H=*N;0LCV$N(B2$B$D$N0z?t$r$H$k!#(B
$BNN0h$N9T$r(B1$B$D(B1$B$D;z2<$2$9$k>l9g$HF1$87k2L$r@8$8$k$,!"(B
$B$h$jB.$/F0:n$9$k$3$H$r0U?^$7$F$3$N4X?t$r@_7W$9$k$Y$-$G$"$k!#(B

@c If the value is @code{nil}, there is no short cut, and
@c @code{indent-region} actually works line by line.
$BCM$,(B@code{nil}$B$G$"$k$HC;=LHG$O$J$/!"(B
@code{indent-region}$B$,<B:]$K(B1$B9T$:$D=hM}$9$k!#(B

@c A short-cut function is useful in modes such as C mode and Lisp mode,
@c where the @code{indent-line-function} must scan from the beginning of
@c the function definition: applying it to each line would be quadratic in
@c time.  The short cut can update the scan information as it moves through
@c the lines indenting them; this takes linear time.  In a mode where
@c indenting a line individually is fast, there is no need for a short cut.
$BC;=LHG4X?t$O(BC$B%b!<%I$d(Blisp$B%b!<%I$N$h$&$J%b!<%I$GM-MQ$G$"$k!#(B
$B$=$N$h$&$J%b!<%I$G$O!"(B@code{indent-line-function}$B$G4X?tDj5A$N;O$^$j$r(B
$BAv::$9$kI,MW$,$"$j!"$3$l$r3F9T$KE,MQ$9$k$H<+>h$N;~4V$,$+$+$k!#(B
$BC;=LHG$G$O!";z2<$2$7=*$($?4X?tDj5A$rDL2a$9$k$?$S$K(B
$BAv::>pJs$r99?7$G$-!"$3$l$K$O@~7A;~4V$+$+$k$@$1$G$"$k!#(B
$B8D!9$N9T$r9bB.$K;z2<$2$G$-$k%b!<%I$G$O!"C;=LHG$OI,MW$J$$!#(B

@c @code{indent-region} with a non-@code{nil} argument @var{to-column} has
@c a different meaning and does not use this variable.
$B0z?t(B@var{to-column}$B$K(B@code{nil}$B0J30$r;XDj$7$?(B@code{indent-region}$B$K$O(B
$BJL$N0UL#$,$"$j!"$3$NJQ?t$r;H$o$J$$!#(B
@end defvar

@c @deffn Command indent-rigidly start end count
@deffn $B%3%^%s%I(B indent-rigidly start end count
@comment !!SourceFile indent.el
@c This command indents all lines starting between @var{start}
@c (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
@c This ``preserves the shape'' of the affected region, moving it as a
@c rigid unit.  Consequently, this command is useful not only for indenting
@c regions of unindented text, but also for indenting regions of formatted
@c code.
$B$3$N%3%^%s%I$O!"(B@var{start}$B!J$r4^$a$F!K$H(B
@var{end}$B!J$r4^$a$J$$!K$N$"$$$@$G;O$^$k9T$9$Y$F$r(B
$B%3%i%`?t(B@var{count}$B$@$1;z2<$2$9$k!#(B
$B$3$l$O!"NN0h$r(B1$B$D$N2t$H$7$FF0$+$7$F$=$NNN0h$N!X7A$rJ]$D!Y!#(B
$B$3$N%3%^%s%I$O!";z2<$2$7$F$$$J$$%F%-%9%H$NNN0h$@$1$G$J$/!"(B
$B@07A:Q$_$NNN0h$r;z2<$2$9$k$?$a$K$bM-MQ$G$"$k!#(B

@c For example, if @var{count} is 3, this command adds 3 columns of
@c indentation to each of the lines beginning in the region specified.
$B$?$H$($P!"(B@var{count}$B$,(B3$B$G$"$k$H!"(B
$B$3$N%3%^%s%I$O;XDj$7$?NN0hFb$N3F9T$N9TF,$K(B3$B%3%i%`$N;z2<$2$rDI2C$9$k!#(B

@c In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
@c @code{indent-rigidly} to indent the text copied from the message being
@c replied to.
$B%a%$%k!J(Bmail$B!K%b!<%I$G$O!"(B@kbd{C-c C-y}$B!J(B@code{mail-yank-original}$B!K$,(B
$BJV?.BP>]$N%a%C%;!<%8$+$i%3%T!<$7$?%F%-%9%H$r;z2<$2$9$k$?$a$K(B
@code{indent-rigidly}$B$r;H$C$F$$$k!#(B
@end deffn

@defun indent-code-rigidly start end columns &optional nochange-regexp
@c This is like @code{indent-rigidly}, except that it doesn't alter lines
@c that start within strings or comments.
$B$3$N4X?t$O(B@code{indent-rigidly}$B$HF1MM$G$"$k$,!"(B
$BJ8;zNs$d%3%a%s%H$G;O$^$k9T$rJQ99$7$J$$E@$,0[$J$k!#(B

@c In addition, it doesn't alter a line if @var{nochange-regexp} matches at
@c the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
$B$5$i$K!"!J(B@var{nochange-regexp}$B$,(B@code{nil}$B0J30$N$H$-!K(B
$B9T$N@hF,$,(B@var{nochange-regexp}$B$K0lCW$9$k>l9g$K$b9T$rJQ99$7$J$$!#(B
@end defun

@node Relative Indent
@c @subsection Indentation Relative to Previous Lines
@subsection $B@h9T9TAjBP$N;z2<$2(B

@c   This section describes two commands that indent the current line
@c based on the contents of previous lines.
$BK\@a$G$O!"@h9T$9$k9T$NFbMF$K4p$E$$$F8=:_9T$r;z2<$2$9$k(B2$B$D$N(B
$B%3%^%s%I$K$D$$$F=R$Y$^$9!#(B

@c @deffn Command indent-relative &optional unindented-ok
@deffn $B%3%^%s%I(B indent-relative &optional unindented-ok
@c This command inserts whitespace at point, extending to the same
@c column as the next @dfn{indent point} of the previous nonblank line.  An
@c indent point is a non-whitespace character following whitespace.  The
@c next indent point is the first one at a column greater than the current
@c column of point.  For example, if point is underneath and to the left of
@c the first non-blank character of a line of text, it moves to that column
@c by inserting whitespace.
$B$3$N%3%^%s%I$O!"6uGr$G$J$$$^$($N9T$N$D$.$N(B@dfn{$B;z2<$20LCV(B}$B$N%3%i%`$K(B
$BC#$9$k$^$G!"%]%$%s%H0LCV$KGrJ8;z$rA^F~$9$k!#(B
$B;z2<$20LCV$H$O!"GrJ8;z$KB3$/GrJ8;z0J30$NJ8;z$G$"$k!#(B
$B$D$.$N;z2<$20LCV$H$O!"8=:_9T$N%]%$%s%H$N%3%i%`0LCV$h$jBg$-$J(B
$B:G=i$N;z2<$20LCV$N$3$H$G$"$k!#(B
$B$?$H$($P!"%F%-%9%H9T$NGrJ8;z0J30$N:G=i$NJ8;z$h$j:8B&$G!"(B
$B$=$N2<$N9T$K%]%$%s%H$,$"$k$H!"(B
$BGrJ8;z$rA^F~$7$F$=$N%3%i%`0LCV$K%]%$%s%H$r0\F0$9$k!#(B

@c If the previous nonblank line has no next indent point (i.e., none at a
@c great enough column position), @code{indent-relative} either does
@c nothing (if @var{unindented-ok} is non-@code{nil}) or calls
@c @code{tab-to-tab-stop}.  Thus, if point is underneath and to the right
@c of the last column of a short line of text, this command ordinarily
@c moves point to the next tab stop by inserting whitespace.
$B6uGr$G$J$$$^$($N9T$K!"$D$.$N;z2<$20LCV!J$D$^$j!"%]%$%s%H0LCV$h$j(B
$BBg$-$J%3%i%`!K$,$J$$$H!"(B@code{indent-relative}$B$O!"(B
$B!J(B@var{unindented-ok}$B$,(B@code{nil}$B0J30$G$"$l$P!K$J$K$b$7$J$$$+!"(B
@code{tab-to-tab-stop}$B$r8F$S=P$9!#(B
$B$7$?$,$C$F!"$^$($N%F%-%9%H9T$,C;$/$F$=$N9TKv$h$j1&B&$G!"(B
$B$=$N2<$N9T$K%]%$%s%H$,$"$k$H!"$3$N%3%^%s%I$O!"DL>o$I$*$j!"(B
$BGrJ8;z$rA^F~$7$F$D$.$N%?%V0LCV$X%]%$%s%H$r0\F0$9$k!#(B

@c The return value of @code{indent-relative} is unpredictable.
@code{indent-relative}$B$NLa$jCM$OM=B,$G$-$J$$!#(B

@c In the following example, point is at the beginning of the second
@c line:
$B$D$.$NNc$G$O!"%]%$%s%H$O(B2$B9TL\$N9TF,$K$"$k!#(B

@example
@group
            This line is indented twelve spaces.
@point{}The quick brown fox jumped.
@end group
@end example

@noindent
@c Evaluation of the expression @code{(indent-relative nil)} produces the
@c following:
$B<0(B@code{(indent-relative nil)}$B$rI>2A$9$k$H!"$D$.$N$h$&$K$J$k!#(B

@example
@group
            This line is indented twelve spaces.
            @point{}The quick brown fox jumped.
@end group
@end example

@c   In this next example, point is between the @samp{m} and @samp{p} of
@c @samp{jumped}:
$B$D$.$NNc$G$O!"%]%$%s%H$O(B@samp{jumped}$B$N(B@samp{m}$B$H(B@samp{p}$B$N$"$$$@$K$"$k!#(B

@example
@group
            This line is indented twelve spaces.
The quick brown fox jum@point{}ped.
@end group
@end example

@noindent
@c Evaluation of the expression @code{(indent-relative nil)} produces the
@c following:
$B<0(B@code{(indent-relative nil)}$B$rI>2A$9$k$H!"$D$.$N$h$&$K$J$k!#(B

@example
@group
            This line is indented twelve spaces.
The quick brown fox jum  @point{}ped.
@end group
@end example
@end deffn

@c @deffn Command indent-relative-maybe
@deffn $B%3%^%s%I(B indent-relative-maybe
@comment !!SourceFile indent.el
@c This command indents the current line like the previous nonblank line,
@c by calling @code{indent-relative} with @code{t} as the
@c @var{unindented-ok} argument.  The return value is unpredictable.
$B$3$N%3%^%s%I$O!"0z?t(B@var{unindented-ok}$B$K(B@code{t}$B$r;XDj$7$F(B
@code{indent-relative}$B$r8F$S=P$9$3$H$G!"(B
$B$^$($N9T$HF1MM$K;z2<$2$9$k!#(B
$BLa$jCM$OM=B,$G$-$J$$!#(B

@c If the previous nonblank line has no indent points beyond the current
@c column, this command does nothing.
$B6u9T$G$J$$$^$($N9T$K8=:_$N%3%i%`0LCV$r1[$($k;z2<$20LCV$,$J$1$l$P!"(B
$B$3$N%3%^%s%I$O$J$K$b$7$J$$!#(B
@end deffn

@node Indent Tabs
@comment  node-name,  next,  previous,  up
@c @subsection Adjustable ``Tab Stops''
@subsection $BD4@02DG=$J!X%?%V%9%H%C%W!Y(B
@c @cindex tabs stops for indentation
@cindex $B;z2<$2$N$?$a$N%?%V%9%H%C%W(B

@c   This section explains the mechanism for user-specified ``tab stops''
@c and the mechanisms that use and set them.  The name ``tab stops'' is
@c used because the feature is similar to that of the tab stops on a
@c typewriter.  The feature works by inserting an appropriate number of
@c spaces and tab characters to reach the next tab stop column; it does not
@c affect the display of tab characters in the buffer (@pxref{Usual
@c Display}).  Note that the @key{TAB} character as input uses this tab
@c stop feature only in a few major modes, such as Text mode.
$BK\@a$G$O!"%f!<%6!<;XDj$N!X%?%V%9%H%C%W!Y$N5!9=$H!"(B
$B$=$l$r;H$C$?$j@_Dj$9$k$?$a$N5!9=$K$D$$$F@bL@$7$^$9!#(B
$B!X%?%V%9%H%C%W!Y$H$$$&L>A0$r;H$&$N$O!"(B
$B$3$N5!9=$,%?%$%W%i%$%?$N%?%V%9%H%C%W$K;w$?5!G=$@$+$i$G$9!#(B
$B$3$N5!G=$O!"E,@Z$J8D?t$N6uGr$H%?%VJ8;z$rA^F~$7$F(B
$B$D$.$N%?%V%9%H%C%W$N%3%i%`$XE~C#$7$^$9$,!"(B
$B%P%C%U%!Fb$N%?%VJ8;z$NI=<($K1F6A$9$k$3$H$O$"$j$^$;$s(B
$B!J(B@pxref{Usual Display}$B!K!#(B
$B%F%-%9%H!J(Btext$B!K%b!<%I$J$I$N>/?t$N%a%8%c!<%b!<%I$G$N$_!"(B
$BF~NO$H$7$F$NJ8;z(B@key{TAB}$B$,$3$N%?%V%9%H%C%W5!G=$r;H$$$^$9!#(B

@c @deffn Command tab-to-tab-stop
@deffn $B%3%^%s%I(B tab-to-tab-stop
@c This command inserts spaces or tabs before point, up to the next tab
@c stop column defined by @code{tab-stop-list}.  It searches the list for
@c an element greater than the current column number, and uses that element
@c as the column to indent to.  It does nothing if no such element is
@c found.
$B$3$N%3%^%s%I$O!"(B@code{tab-stop-list}$B$GDj5A$5$l$?$D$.$N%?%V%9%H%C%W%3%i%`$^$G!"(B
$B%]%$%s%H$N$^$($K6uGr$d%?%V$rA^F~$9$k!#(B
$B$3$N%j%9%H$G8=:_$N%3%i%`HV9f$h$jBg$-$JMWAG$rC5$7!"(B
$B$=$NMWAG$r;z2<$20LCV$N%3%i%`$H$7$F;H$&!#(B
$B$=$N$h$&$JMWAG$,$J$1$l$P!"$3$N%3%^%s%I$O$J$$$b$7$J$$!#(B
@end deffn

@defopt tab-stop-list
@c This variable is the list of tab stop columns used by
@c @code{tab-to-tab-stops}.  The elements should be integers in increasing
@c order.  The tab stop columns need not be evenly spaced.
$B$3$NJQ?t$O!"(B@code{tab-to-tab-stops}$B$,;H$&%?%V%9%H%C%W%3%i%`$N%j%9%H$G$"$k!#(B
$B$=$l$i$NMWAG$O!">:=g$N@0?t$G$"$k$3$H!#(B
$B%?%V%9%H%C%W%3%i%`$N4V3V$O!"Ey4V3V$G$"$kI,MW$O$J$$!#(B

@c Use @kbd{M-x edit-tab-stops} to edit the location of tab stops
@c interactively.
$B%?%V%9%H%C%W$rBPOCE*$KJT=8$9$k$K$O(B@kbd{M-x edit-tab-stops}$B$r;H$&!#(B
@end defopt

@node Motion by Indent
@c @subsection Indentation-Based Motion Commands
@subsection $B;z2<$2$K4p$E$/0\F0%3%^%s%I(B

@c   These commands, primarily for interactive use, act based on the
@c indentation in the text.
$B$3$l$i$N%3%^%s%I$O!"<g$KBPOCE*$K;H$&$b$N$G!"(B
$B%F%-%9%H$N;z2<$2$K4p$E$$$FF0:n$7$^$9!#(B

@c @deffn Command back-to-indentation 
@deffn $B%3%^%s%I(B back-to-indentation 
@comment !!SourceFile simple.el
@c This command moves point to the first non-whitespace character in the
@c current line (which is the line in which point is located).  It returns
@c @code{nil}.
$B$3$N%3%^%s%I$O!"8=:_9T!J%]%$%s%H$,0LCV$9$k9T!K$N(B
$BGrJ8;z$G$J$$:G=i$NJ8;z$X%]%$%s%H$r0\F0$9$k!#(B
@code{nil}$B$rJV$9!#(B
@end deffn

@c @deffn Command backward-to-indentation arg
@deffn $B%3%^%s%I(B backward-to-indentation arg
@comment !!SourceFile simple.el
@c This command moves point backward @var{arg} lines and then to the
@c first nonblank character on that line.  It returns @code{nil}.
$B$3$N%3%^%s%I$O!"(B@var{arg}$B9T$@$1%]%$%s%H$r8eJ}$X0\F0$7$F$+$i!"(B
$BEv3:9T$NGrJ8;z$G$J$$:G=i$NJ8;z$X%]%$%s%H$r0\F0$9$k!#(B
@code{nil}$B$rJV$9!#(B
@end deffn

@c @deffn Command forward-to-indentation arg
@deffn $B%3%^%s%I(B forward-to-indentation arg
@comment !!SourceFile simple.el
@c This command moves point forward @var{arg} lines and then to the first
@c nonblank character on that line.  It returns @code{nil}.
$B$3$N%3%^%s%I$O!"(B@var{arg}$B9T$@$1%]%$%s%H$rA0J}$X0\F0$7$F$+$i!"(B
$BEv3:9T$NGrJ8;z$G$J$$:G=i$NJ8;z$X%]%$%s%H$r0\F0$9$k!#(B
@code{nil}$B$rJV$9!#(B
@end deffn

@node Case Changes
@comment  node-name,  next,  previous,  up
@c @section Case Changes
@section $BBgJ8;z>.J8;z$NJQ99(B
@c @cindex case conversion in buffers
@cindex $B%P%C%U%!Fb$G$NBgJ8;z>.J8;zJQ49(B

@c   The case change commands described here work on text in the current
@c buffer.  @xref{Case Conversion}, for case conversion functions that work
@c on strings and characters.  @xref{Case Tables}, for how to customize
@c which characters are upper or lower case and how to convert them.
$B$3$3$K=R$Y$kBgJ8;z>.J8;z$NJQ99%3%^%s%I$O!"(B
$B%+%l%s%H%P%C%U%!$N%F%-%9%H$K:nMQ$7$^$9!#(B
$BJ8;zNs$dJ8;z$NBgJ8;z>.J8;z$rJQ49$9$k4X?t$K$D$$$F$O!"(B
@xref{Case Conversion}$B!#(B
$B$I$NJ8;z$,BgJ8;z$G$I$NJ8;z$,>.J8;z$G$"$j!"$=$l$i$r$I$N$h$&$KJQ49$9$k$+$r(B
$B%+%9%?%^%$%:$9$kJ}K!$K$D$$$F$O!"(B@xref{Case Tables}$B!#(B

@c @deffn Command capitalize-region start end
@deffn $B%3%^%s%I(B capitalize-region start end
@c This function capitalizes all words in the region defined by
@c @var{start} and @var{end}.  To capitalize means to convert each word's
@c first character to upper case and convert the rest of each word to lower
@c case.  The function returns @code{nil}.
$B$3$N4X?t$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0hFb$N(B
$B$9$Y$F$NC18l$r%-%c%T%?%i%$%:!JBgJ8;z$G;O$^$k$h$&$K!K$9$k!#(B
$B$D$^$j!"3FC18l$N:G=i$NJ8;z$rBgJ8;z$K!";D$j$NJ8;z$r>.J8;z$KJQ49$9$k!#(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c If one end of the region is in the middle of a word, the part of the
@c word within the region is treated as an entire word.
$BNN0h$NC<$,C18l$NESCf$K$"$k$H!"(B
$B$=$NC18l$NNN0hFb$NItJ,$r(B1$B$D$NC18l$H$_$J$9!#(B

@c When @code{capitalize-region} is called interactively, @var{start} and
@c @var{end} are point and the mark, with the smallest first.
@code{capitalize-region}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{start}$B$H(B@var{end}$B$O%]%$%s%H$H%^!<%/$G$"$j!">.$5$$$[$&$,$5$-$K$/$k!#(B

@example
@group
---------- Buffer: foo ----------
This is the contents of the 5th foo.
---------- Buffer: foo ----------
@end group

@group
(capitalize-region 1 44)
@result{} nil

---------- Buffer: foo ----------
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------
@end group
@end example
@end deffn

@c @deffn Command downcase-region start end
@deffn $B%3%^%s%I(B downcase-region start end
@c This function converts all of the letters in the region defined by
@c @var{start} and @var{end} to lower case.  The function returns
@c @code{nil}.
$B$3$N4X?t$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0hFb$N(B
$B$9$Y$F$NJ8;z$r>.J8;z$KJQ49$9$k!#(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c When @code{downcase-region} is called interactively, @var{start} and
@c @var{end} are point and the mark, with the smallest first.
@code{downcase-region}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{start}$B$H(B@var{end}$B$O%]%$%s%H$H%^!<%/$G$"$j!">.$5$$$[$&$,@h$K$/$k!#(B
@end deffn

@c @deffn Command upcase-region start end
@deffn $B%3%^%s%I(B upcase-region start end
@c This function converts all of the letters in the region defined by
@c @var{start} and @var{end} to upper case.  The function returns
@c @code{nil}.
$B$3$N4X?t$O!"(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0hFb$N(B
$B$9$Y$F$NJ8;z$rBgJ8;z$KJQ49$9$k!#(B
$B$3$N4X?t$O(B@code{nil}$B$rJV$9!#(B

@c When @code{upcase-region} is called interactively, @var{start} and
@c @var{end} are point and the mark, with the smallest first.
@code{upcase-region}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{start}$B$H(B@var{end}$B$O%]%$%s%H$H%^!<%/$G$"$j!">.$5$$$[$&$,@h$K$/$k!#(B
@end deffn

@c @deffn Command capitalize-word count
@deffn $B%3%^%s%I(B capitalize-word count
@c This function capitalizes @var{count} words after point, moving point
@c over as it does.  To capitalize means to convert each word's first
@c character to upper case and convert the rest of each word to lower case.
@c If @var{count} is negative, the function capitalizes the
@c @minus{}@var{count} previous words but does not move point.  The value
@c is @code{nil}.
$B$3$N4X?t$O!"%]%$%s%H$N$&$7$m$N(B@var{count}$B8D$NC18l$r(B
$B%-%c%T%?%i%$%:!JBgJ8;z$G;O$^$k$h$&$K!K$7!"%]%$%s%H$r$=$l$i$NKvHx$K0\F0$9$k!#(B
$B$D$^$j!"3FC18l$N:G=i$NJ8;z$rBgJ8;z$K!";D$j$NJ8;z$r>.J8;z$KJQ49$9$k!#(B
@var{count}$B$,Ii$G$"$k$H!"$^$($N(B@minus{}@var{count}$B8D$NC18l$r(B
$BBgJ8;z$G;O$^$k$h$&$K$9$k$,!"%]%$%s%H$O0\F0$7$J$$!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B

@c If point is in the middle of a word, the part of the word before point
@c is ignored when moving forward.  The rest is treated as an entire word.
$B%]%$%s%H$,C18l$NESCf$K$"$k$H!"C18l$rA0J}$X0\F0$9$k$H$-$K$O(B
$B%]%$%s%H$h$j$^$($K$"$kC18l$NItJ,$rL5;k$9$k!#(B
$BC18l$N;D$j$NItJ,$r(B1$B$D$NC18l$H$7$F07$&!#(B

@c When @code{capitalize-word} is called interactively, @var{count} is
@c set to the numeric prefix argument.
@code{capitalize-word}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{count}$B$O?tCMA0CV0z?t$G$"$k!#(B
@end deffn

@c @deffn Command downcase-word count
@deffn $B%3%^%s%I(B downcase-word count
@c This function converts the @var{count} words after point to all lower
@c case, moving point over as it does.  If @var{count} is negative, it
@c converts the @minus{}@var{count} previous words but does not move point.
@c The value is @code{nil}.
$B$3$N4X?t$O!"%]%$%s%H$N$&$7$m$N(B@var{count}$B8D$NC18l$r(B
$B$9$Y$F>.J8;z$KBX$(!"%]%$%s%H$r$=$l$i$NKvHx$K0\F0$9$k!#(B
@var{count}$B$,Ii$G$"$k$H!"$^$($N(B@minus{}@var{count}$B8D$NC18l$r(B
$BJQ49$9$k$,!"%]%$%s%H$O0\F0$7$J$$!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B

@c When @code{downcase-word} is called interactively, @var{count} is set
@c to the numeric prefix argument.
@code{downcase-word}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{count}$B$O?tCMA0CV0z?t$G$"$k!#(B
@end deffn

@c @deffn Command upcase-word count
@deffn $B%3%^%s%I(B upcase-word count
@c This function converts the @var{count} words after point to all upper
@c case, moving point over as it does.  If @var{count} is negative, it
@c converts the @minus{}@var{count} previous words but does not move point.
@c The value is @code{nil}.
$B$3$N4X?t$O!"%]%$%s%H$N$&$7$m$N(B@var{count}$B8D$NC18l$r(B
$B$9$Y$FBgJ8;z$KBX$(!"%]%$%s%H$r$=$l$i$NKvHx$K0\F0$9$k!#(B
@var{count}$B$,Ii$G$"$k$H!"$^$($N(B@minus{}@var{count}$B8D$NC18l$r(B
$BJQ49$9$k$,!"%]%$%s%H$O0\F0$7$J$$!#(B
$BCM$O(B@code{nil}$B$G$"$k!#(B

@c When @code{upcase-word} is called interactively, @var{count} is set to
@c the numeric prefix argument.
@code{upcase-word}$B$rBPOCE*$K8F$S=P$9$H!"(B
@var{count}$B$O?tCMA0CV0z?t$G$"$k!#(B
@end deffn

@node Text Properties
@c @section Text Properties
@section $B%F%-%9%HB0@-(B
@c @cindex text properties
@c @cindex attributes of text
@c @cindex properties of text
@cindex $B%F%-%9%HB0@-(B
@cindex $BB0@-!"%F%-%9%H(B

@c   Each character position in a buffer or a string can have a @dfn{text
@c property list}, much like the property list of a symbol (@pxref{Property
@c Lists}).  The properties belong to a particular character at a
@c particular place, such as, the letter @samp{T} at the beginning of this
@c sentence or the first @samp{o} in @samp{foo}---if the same character
@c occurs in two different places, the two occurrences generally have
@c different properties.
$B%7%s%\%k$NB0@-%j%9%H!J(B@pxref{Property Lists}$B!K$N$h$&$K!"(B
$B%P%C%U%!$dJ8;zNs$N3FJ8;z$K$O(B@dfn{$B%F%-%9%HB0@-%j%9%H(B}
$B!J(Btext property list$B!K$r;}$F$^$9!#(B
$B$3$NB0@-$O!"!JK\@a$N86J8$N%?%$%H%k$N!KJ8;z(B@samp{T}$B$d(B
@samp{foo}$B$N:G=i$N(B@samp{o}$B$N$h$&$JFCDj$N2U=j$NFCDj$NJ8;z$KB0$7$^$9!#(B
$BF1$8J8;z$,0[$J$k2U=j$K8=$l$k$H$-!"(B
$B0lHL$K$O$=$l$>$l$K0[$J$kB0@-$r;}$F$^$9!#(B

@c   Each property has a name and a value.  Both of these can be any Lisp
@c object, but the name is normally a symbol.  The usual way to access the
@c property list is to specify a name and ask what value corresponds to it.
$B3FB0@-$K$O!"L>A0$HCM$,$"$j$^$9!#(B
$B$I$A$i$bG$0U$N(BLisp$B%*%V%8%'%/%H$G$+$^$$$^$;$s$,!"(B
$BL>A0$OIaDL$O%7%s%\%k$G$9!#(B
$BB0@-%j%9%H$r;2>H$9$kIaDL$NJ}K!$G$O!"(B
$BL>A0$r;XDj$7$F$=$l$KBP1~$9$kCM$rLd$$9g$o$;$^$9!#(B

@c   If a character has a @code{category} property, we call it the
@c @dfn{category} of the character.  It should be a symbol.  The properties
@c of the symbol serve as defaults for the properties of the character.
$BJ8;z$KB0@-(B@code{category}$B$,$"$k$H$-!"(B
$B$=$l$rJ8;z$N(B@dfn{$B%+%F%4%j(B}$B!J(Bcategory$B!K$H$$$$$^$9!#(B
$B$=$l$O%7%s%\%k$G$"$k$Y$-$G$9!#(B
$B$=$N%7%s%\%k$NB0@-$,!"J8;z$NB0@-$N%G%U%)%k%H$H$7$FF/$-$^$9!#(B

@c   Copying text between strings and buffers preserves the properties
@c along with the characters; this includes such diverse functions as
@c @code{substring}, @code{insert}, and @code{buffer-substring}.
$BJ8;zNs$H%P%C%U%!$N$"$$$@$G%F%-%9%H$r%3%T!<$9$k$H!"(B
$BJ8;z$H$H$b$K$=$NB0@-$bJ]$?$l$^$9!#(B
@code{substring}$B!"(B@code{insert}$B!"(B@code{buffer-substring}$B$J$I$N(B
$B$5$^$6$^$J4X?t$,$=$&$7$^$9!#(B

@menu
* Examining Properties::	Looking at the properties of one character.
* Changing Properties::		Setting the properties of a range of text.
* Property Search::		Searching for where a property changes value.
* Special Properties::		Particular properties with special meanings.
* Format Properties::           Properties for representing formatting of text.
* Sticky Properties::           How inserted text gets properties from
                                  neighboring text.
* Saving Properties::           Saving text properties in files, and reading
                                  them back.
* Lazy Properties::             Computing text properties in a lazy fashion
                                  only when text is examined.
* Clickable Text::              Using text properties to make regions of text
                                  do something when you click on them.
* Not Intervals::		Why text properties do not use
				  Lisp-visible text intervals.
@end menu

@node Examining Properties
@c @subsection Examining Text Properties
@subsection $B%F%-%9%HB0@-$rD4$Y$k(B

@c   The simplest way to examine text properties is to ask for the value of
@c a particular property of a particular character.  For that, use
@c @code{get-text-property}.  Use @code{text-properties-at} to get the
@c entire property list of a character.  @xref{Property Search}, for
@c functions to examine the properties of a number of characters at once.
$B%F%-%9%HB0@-$rD4$Y$k$b$C$H$b4JC1$JJ}K!$O!"(B
$BFCDj$NJ8;z$NFCDj$NB0@-$NCM$rLd$$9g$o$;$k$3$H$G$9!#(B
$B$=$l$K$O!"(B@code{get-text-property}$B$r;H$$$^$9!#(B
$BJ8;z$NB0@-%j%9%HA4BN$r<hF@$9$k$K$O(B@code{text-properties-at}$B$r;H$$$^$9!#(B
$BJ#?t$NJ8;z$NB0@-$r0lEY$KD4$Y$k$?$a$N4X?t$K$D$$$F$O!"(B
@xref{Property Search}$B!#(B

@c   These functions handle both strings and buffers.  Keep in mind that
@c positions in a string start from 0, whereas positions in a buffer start
@c from 1.
$B$3$l$i$N4X?t$O!"J8;zNs$H%P%C%U%!$NN>J}$r07$($^$9!#(B
$BJ8;zNsFb$N0LCV$O(B0$B$+$i;O$^$j!"(B
$B%P%C%U%!Fb$N0LCV$O(B1$B$+$i;O$^$k$3$H$KCm0U$7$F$/$@$5$$!#(B

@defun get-text-property pos prop &optional object
@c This function returns the value of the @var{prop} property of the
@c character after position @var{pos} in @var{object} (a buffer or
@c string).  The argument @var{object} is optional and defaults to the
@c current buffer.
$B$3$N4X?t$O!"(B@var{object}$B!J%P%C%U%!$+J8;zNs!KFb$N0LCV(B@var{pos}$B$N(B
$B$&$7$m$N(B1$BJ8;z$NB0@-(B@var{prop}$B$NCM$rJV$9!#(B
$B0z?t(B@var{object}$B$O>JN,$G$-!"(B
$B%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B

@c If there is no @var{prop} property strictly speaking, but the character
@c has a category that is a symbol, then @code{get-text-property} returns
@c the @var{prop} property of that symbol.
$B$=$NJ8;z$KB0@-(B@var{prop}$B$,$J$/$F$b%7%s%\%k$G$"$k%+%F%4%j$,$"$l$P!"(B
@code{get-text-property}$B$OEv3:%7%s%\%k$NB0@-(B@var{prop}$B$rJV$9!#(B
@end defun

@defun get-char-property pos prop &optional object
@c This function is like @code{get-text-property}, except that it checks
@c overlays first and then text properties.  @xref{Overlays}.
$B$3$N4X?t$O(B@code{get-text-property}$B$K;w$F$$$k$,!"(B
$B$^$:%*!<%P%l%$$rD4$Y$F$+$i%F%-%9%HB0@-$rD4$Y$k!#(B
@pxref{Overlays}$B!#(B

@c The argument @var{object} may be a string, a buffer, or a window.  If it
@c is a window, then the buffer displayed in that window is used for text
@c properties and overlays, but only the overlays active for that window
@c are considered.  If @var{object} is a buffer, then all overlays in that
@c buffer are considered, as well as text properties.  If @var{object} is a
@c string, only text properties are considered, since strings never have
@c overlays.
$B0z?t(B@var{object}$B$O!"J8;zNs!"%P%C%U%!!"%&%#%s%I%&$N$$$:$l$+$G$"$k!#(B
$B%&%#%s%I%&$G$"$k$H!"$=$N%&%#%s%I%&$KI=<($7$F$$$k%P%C%U%!$N(B
$B%F%-%9%HB0@-$H%*!<%P%l%$$rBP>]$K$9$k$,!"(B
$BBP>]$H$J$k%*!<%P%l%$$O$=$N%&%#%s%I%&$KBP$7$F3h@-$J$b$N$@$1$G$"$k!#(B
@var{object}$B$,%P%C%U%!$G$"$k$H!"%F%-%9%HB0@-$K2C$($F(B
$B$=$N%P%C%U%!$N$9$Y$F$N%*!<%P%l%$$rBP>]$K$9$k!#(B
@var{object}$B$,J8;zNs$G$"$k$H!"(B
$BJ8;zNs$K$O%*!<%P%l%$$O$J$$$N$G!"%F%-%9%HB0@-$N$_$rBP>]$K$9$k!#(B
@end defun

@defun text-properties-at position &optional object
@c This function returns the entire property list of the character at
@c @var{position} in the string or buffer @var{object}.  If @var{object} is
@c @code{nil}, it defaults to the current buffer.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N(B
$B0LCV(B@var{position}$B$K$"$k(B1$BJ8;z$NB0@-%j%9%HA4BN$rJV$9!#(B
@var{object}$B$,(B@code{nil}$B$G$"$k$H!"%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B
@end defun

@defvar default-text-properties
@c This variable holds a property list giving default values for text
@c properties.  Whenever a character does not specify a value for a
@c property, neither directly nor through a category symbol, the value
@c stored in this list is used instead.  Here is an example:
$B$3$NJQ?t$O!"%F%-%9%HB0@-$N%G%U%)%k%HCM$rM?$($kB0@-%j%9%H$rJ];}$9$k!#(B
$BD>@\E*$K$b%+%F%4%j%7%s%\%k$r2p$7$F4V@\E*$K$b(B
$BJ8;z$KB0@-$NCM$,;XDj$5$l$F$$$J$$$H!"(B
$B$3$N%j%9%H$K<}$a$?CM$r$+$o$j$K;H$&!#(B
$B$D$.$KNc$r<($9!#(B

@example
(setq default-text-properties '(foo 69))
@c ;; @r{Make sure character 1 has no properties of its own.}
;; @r{$B0LCV(B1$B$NJ8;z$KB0@-$,$J$$$3$H$rJ]>Z$9$k(B}
(set-text-properties 1 2 nil)
@c ;; @r{What we get, when we ask, is the default value.}
;; @r{$BLd$$9g$o$;$?$H$-$K8+$($k$N$O%G%U%)%k%HCM$G$"$k(B}
(get-text-property 1 'foo)
     @result{} 69
@end example
@end defvar

@node Changing Properties
@c @subsection Changing Text Properties
@subsection $B%F%-%9%HB0@-$NJQ99(B

@c   The primitives for changing properties apply to a specified range of
@c text in a buffer or string.  The function @code{set-text-properties}
@c (see end of section) sets the entire property list of the text in that
@c range; more often, it is useful to add, change, or delete just certain
@c properties specified by name.
$BB0@-$rJQ99$9$k4pK\4X?t$O!"%P%C%U%!$dJ8;zNs$N;XDj$7$?HO0O$K:nMQ$7$^$9!#(B
$B4X?t(B@code{set-text-properties}$B!JK\@a$N:G8e!K$O!"(B
$B$=$NHO0O$N%F%-%9%H$NB0@-%j%9%HA4BN$r@_Dj$7$^$9!#(B
$B$3$l$O!"L>A0$G;XDj$7$?FCDj$NB0@-$N$_$rDI2C!?JQ99!?:o=|$9$k$N$K(B
$B$7$P$7$PM-MQ$G$9!#(B

@c   Since text properties are considered part of the contents of the
@c buffer (or string), and can affect how a buffer looks on the screen, any
@c change in buffer text properties mark the buffer as modified.  Buffer
@c text property changes are undoable also (@pxref{Undo}).
$B%F%-%9%HB0@-$O%P%C%U%!!J$dJ8;zNs!K$N0lItJ,$G$"$k$H$_$J$5$l!"(B
$B%9%/%j!<%s>e$G$N%P%C%U%!$N8+$?L\$K1F6A$9$k$N$G!"(B
$B%P%C%U%!$N%F%-%9%HB0@-$rJQ99$9$k$H!"(B
$B%P%C%U%!$K$OJQ99:Q$_$N0u$rIU$1$^$9!#(B
$B%P%C%U%!$N%F%-%9%HB0@-$NJQ99$b%"%s%I%%!J(B@pxref{Undo}$B!K$G$-$^$9!#(B

@defun put-text-property start end prop value &optional object
@c This function sets the @var{prop} property to @var{value} for the text
@c between @var{start} and @var{end} in the string or buffer @var{object}.
@c If @var{object} is @code{nil}, it defaults to the current buffer.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N(B
@var{start}$B$H(B@var{end}$B$N$"$$$@$N%F%-%9%H$NB0@-(B@var{prop}$B$NCM$r(B
@var{value}$B$H$9$k!#(B
@var{object}$B$,(B@code{nil}$B$G$"$k$H!"%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B
@end defun

@defun add-text-properties start end props &optional object
@c This function adds or overrides text properties for the text between
@c @var{start} and @var{end} in the string or buffer @var{object}.  If
@c @var{object} is @code{nil}, it defaults to the current buffer.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N(B
@var{start}$B$H(B@var{end}$B$N$"$$$@$N%F%-%9%H$N(B
$B%F%-%9%HB0@-$KDI2C!?>e=q$-$9$k!#(B
@var{object}$B$,(B@code{nil}$B$G$"$k$H!"%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B

@c The argument @var{props} specifies which properties to add.  It should
@c have the form of a property list (@pxref{Property Lists}): a list whose
@c elements include the property names followed alternately by the
@c corresponding values.
$B0z?t(B@var{props}$B$GDI2C$9$kB0@-$r;XDj$9$k!#(B
$B$3$l$OB0@-%j%9%H!J(B@pxref{Property Lists}$B!K$N7A$G$"$k$3$H!#(B
$B$D$^$j!"B0@-L>$H$=$NCM$r8r8_$KJB$Y$?%j%9%H$G$"$k$3$H!#(B

@c The return value is @code{t} if the function actually changed some
@c property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
@c its values agree with those in the text).
$B$3$N4X?t$,B0@-$NCM$r$I$l$+<B:]$KJQ99$7$?$J$i$P!"La$jCM$O(B@code{t}$B$G$"$k!#(B
$B$5$b$J$1$l$P!J(B@var{props}$B$,(B@code{nil}$B$@$C$?$j!"(B
$B%F%-%9%HFb$NCM$HF1$8CM$G$"$k$H!K(B@code{nil}$B$G$"$k!#(B

@c For example, here is how to set the @code{comment} and @code{face}
@c properties of a range of text:
$B$?$H$($P!"%F%-%9%H$N$"$kHO0O$NB0@-(B@code{comment}$B$H(B@code{face}$B$r(B
$B@_Dj$9$k$K$O$D$.$N$h$&$K$9$k!#(B

@example
(add-text-properties @var{start} @var{end}
                     '(comment t face highlight))
@end example
@end defun

@defun remove-text-properties start end props &optional object
@c This function deletes specified text properties from the text between
@c @var{start} and @var{end} in the string or buffer @var{object}.  If
@c @var{object} is @code{nil}, it defaults to the current buffer.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N(B
@var{start}$B$H(B@var{end}$B$N$"$$$@$N%F%-%9%H$+$i(B
$B;XDj$7$?%F%-%9%HB0@-$r:o=|$9$k!#(B
@var{object}$B$,(B@code{nil}$B$G$"$k$H!"%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B

@c The argument @var{props} specifies which properties to delete.  It
@c should have the form of a property list (@pxref{Property Lists}): a list
@c whose elements are property names alternating with corresponding values.
@c But only the names matter---the values that accompany them are ignored.
@c For example, here's how to remove the @code{face} property.
$B0z?t(B@var{props}$B$G:o=|$9$kB0@-$r;XDj$9$k!#(B
$B$3$l$OB0@-%j%9%H!J(B@pxref{Property Lists}$B!K$N7A$G$"$k$3$H!#(B
$B$D$^$j!"B0@-L>$H$=$NCM$r8r8_$KJB$Y$?%j%9%H$G$"$k$3$H!#(B
$B$?$@$7!"0UL#$,$"$k$N$OL>A0$N$_$G$"$j!"$=$NCM$OL5;k$9$k!#(B
$B$?$H$($P!"B0@-(B@code{face}$B$r:o=|$9$k$K$O$D$.$N$h$&$K$9$k!#(B

@example
(remove-text-properties @var{start} @var{end} '(face nil))
@end example

@c The return value is @code{t} if the function actually changed some
@c property's value; @code{nil} otherwise (if @var{props} is @code{nil} or
@c if no character in the specified text had any of those properties).
$B$3$N4X?t$,B0@-$NCM$r$I$l$+<B:]$KJQ99$7$?$J$i$P!"La$jCM$O(B@code{t}$B$G$"$k!#(B
$B$5$b$J$1$l$P!J(B@var{props}$B$,(B@code{nil}$B$@$C$?$j!"(B
$B;XDj$7$?%F%-%9%HFb$NJ8;z$K$=$l$i$N$$$:$l$NB0@-$b$J$1$l$P!K(B
@code{nil}$B$G$"$k!#(B

@c To remove all text properties from certain text, use
@c @code{set-text-properties} and specify @code{nil} for the new property
@c list.
$BFCDj$N%F%-%9%H$+$i$9$Y$F$N%F%-%9%HB0@-$r:o=|$9$k$K$O!"(B
$B?7$?$JB0@-%j%9%H$H$7$F(B@code{nil}$B$r;XDj$7$F(B
@code{set-text-properties}$B$r;H$&!#(B
@end defun

@defun set-text-properties start end props &optional object
@c This function completely replaces the text property list for the text
@c between @var{start} and @var{end} in the string or buffer @var{object}.
@c If @var{object} is @code{nil}, it defaults to the current buffer.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N(B
@var{start}$B$H(B@var{end}$B$N$"$$$@$N%F%-%9%H$N%F%-%9%HB0@-$r40A4$KCV$-49$($k!#(B
@var{object}$B$,(B@code{nil}$B$G$"$k$H!"(B
$B%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B

@c The argument @var{props} is the new property list.  It should be a list
@c whose elements are property names alternating with corresponding values.
$B0z?t(B@var{props}$B$O?7$?$JB0@-%j%9%H$G$"$k!#(B
$B$3$l$O!"B0@-L>$H$=$NCM$r8r8_$KJB$Y$?%j%9%H$G$"$k$3$H!#(B

@c After @code{set-text-properties} returns, all the characters in the
@c specified range have identical properties.
@code{set-text-properties}$B$+$iLa$k$H!"(B
$B;XDj$7$?HO0O$N$9$Y$F$NJ8;z$OF10l$NB0@-$r;}$D$3$H$K$J$k!#(B

@c If @var{props} is @code{nil}, the effect is to get rid of all properties
@c from the specified range of text.  Here's an example:
@var{props}$B$,(B@code{nil}$B$G$"$k$H!"(B
$B%F%-%9%H$N;XDj$7$?HO0O$+$i$9$Y$F$NB0@-$r:o=|$9$k8z2L$,$"$k!#(B
$B$?$H$($P!"$D$.$N$h$&$K$9$k!#(B

@example
(set-text-properties @var{start} @var{end} nil)
@end example
@end defun

@c   See also the function @code{buffer-substring-no-properties}
@c (@pxref{Buffer Contents}) which copies text from the buffer
@c but does not copy its properties.
$B%P%C%U%!$+$i%F%-%9%H$r%3%T!<$9$k$,$=$NB0@-$O%3%T!<$7$J$$(B
$B4X?t(B@code{buffer-substring-no-properties}$B!J(B@pxref{Buffer Contents}$B!K$b(B
$B;2>H$7$F$/$@$5$$!#(B

@node Property Search
@c @subsection Text Property Search Functions
@subsection $B%F%-%9%HB0@-$rC5$94X?t(B

@c   In typical use of text properties, most of the time several or many
@c consecutive characters have the same value for a property.  Rather than
@c writing your programs to examine characters one by one, it is much
@c faster to process chunks of text that have the same property value.
$B%F%-%9%HB0@-$NE57?E*$JMQES$G$O!"(B
$B$[$H$s$I$N>l9gB?$/$NO"B3$7$?J8;z$N(B1$B$D$NB0@-$K$OF1$8CM$,$"$j$^$9!#(B
1$B$D$:$DJ8;z$rD4$Y$k$h$&$K%W%m%0%i%`$9$k$h$j$O!"(B
$BF1$8B0@-CM$r;}$D%F%-%9%H$N2t$r=hM}$9$k$[$&$,$H$F$bB.$$$G$9!#(B

@c   Here are functions you can use to do this.  They use @code{eq} for
@c comparing property values.  In all cases, @var{object} defaults to the
@c current buffer.
$B$3$N$?$a$K;H$($k4X?t$r$3$3$G@bL@$7$^$9!#(B
$B$3$l$i$OB0@-CM$NHf3S$K(B@code{eq}$B$r;H$$$^$9!#(B
@var{object}$B$N%G%U%)%k%H$O!"$9$Y$F$N>l9g$G%+%l%s%H%P%C%U%!$G$9!#(B

@c   For high performance, it's very important to use the @var{limit}
@c argument to these functions, especially the ones that search for a
@c single property---otherwise, they may spend a long time scanning to the
@c end of the buffer, if the property you are interested in does not change.
$B9b$$8zN($N$?$a$K$O!"$3$l$i$N4X?t$K0z?t(B@var{limit}$B$r;H$&$3$H$,=EMW$G$"$j!"(B
1$B$D$NB0@-$rC5$94X?t$K$OFC$K$"$F$O$^$j$^$9!#(B
$B$5$b$J$$$H!"FI<T$,K>$`B0@-$,JQ99$5$l$J$$$h$&$J>l9g!"(B
$B$=$l$i$N4X?t$O%P%C%U%!$NKvHx$^$GAv::$7$FD9$$;~4V$rHq$9$3$H$K$J$j$^$9!#(B

@c   These functions do not move point; instead, they return a position (or
@c @code{nil}).  Remember that a position is always between two characters;
@c the position returned by these functions is between two characters with
@c different properties.
$B$3$l$i$N4X?t$O%]%$%s%H$r0\F0$7$^$;$s$,!"$=$N$+$o$j$K(B
$B0LCV!J$"$k$$$O(B@code{nil}$B!K$rJV$7$^$9!#(B
$B0LCV$O$D$M$K(B2$B$D$NJ8;z$N$"$$$@$K$"$k$3$H$KCm0U$7$F$/$@$5$$!#(B
$B$3$l$i$N4X?t$,JV$90LCV$O!"0[$J$kB0@-$r;}$D(B2$B$D$NJ8;z$N$"$$$@$G$9!#(B

@defun next-property-change pos &optional object limit
@c The function scans the text forward from position @var{pos} in the
@c string or buffer @var{object} till it finds a change in some text
@c property, then returns the position of the change.  In other words, it
@c returns the position of the first character beyond @var{pos} whose
@c properties are not identical to those of the character just after
@c @var{pos}.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N0LCV(B@var{pos}$B$+$i(B
$B%F%-%9%HB0@-$N$$$:$l$+$,0[$J$k$^$G%F%-%9%H$rAv::$7!"$=$NJQ2=$9$k0LCV$rJV$9!#(B
$B$$$$$+$($l$P!"(B@var{pos}$B$ND>8e$NJ8;z$N%F%-%9%HB0@-$H$O0[$J$k(B
$BB0@-$r;}$D(B@var{pos}$B$N$"$H$K$"$k:G=i$NJ8;z$N0LCV$rJV$9!#(B

@c If @var{limit} is non-@code{nil}, then the scan ends at position
@c @var{limit}.  If there is no property change before that point, 
@c @code{next-property-change} returns @var{limit}.
@var{limit}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B@var{limit}$B$N0LCV$GAv::$r=*$($k!#(B
$B$=$N2U=j$^$G0[$J$kB0@-$,$J$$$H!"(B
@code{next-property-change}$B$O(B@var{limit}$B$rJV$9!#(B

@c The value is @code{nil} if the properties remain unchanged all the way
@c to the end of @var{object} and @var{limit} is @code{nil}.  If the value
@c is non-@code{nil}, it is a position greater than or equal to @var{pos}.
@c The value equals @var{pos} only when @var{limit} equals @var{pos}.
@var{limit}$B$,(B@code{nil}$B$G$"$j(B@var{object}$B$NKvHx$^$GB0@-$KJQ2=$,$J$$$H!"(B
$BCM$O(B@code{nil}$B$G$"$k!#(B
$BCM$,(B@code{nil}$B0J30$G$"$k$H!"$=$l$O(B@var{pos}$B$h$jBg$-$$$+Ey$7$$0LCV$G$"$k!#(B
$BCM$,(B@var{pos}$B$KEy$7$$$N$O!"(B@var{limit}$B$,(B@var{pos}$B$KEy$7$$>l9g$N$_$G$"$k!#(B

@c Here is an example of how to scan the buffer by chunks of text within
@c which all properties are constant:
$B%P%C%U%!$+$i$9$Y$F$NB0@-$,F1$8$G$"$k%F%-%9%H$N2t$r(B
$BAv::$9$kJ}K!$NNc$r$D$.$K<($9!#(B

@smallexample
(while (not (eobp))
  (let ((plist (text-properties-at (point)))
        (next-change
         (or (next-property-change (point) (current-buffer))
             (point-max))))
@c     @r{Process text from point to @var{next-change}@dots{}}
    @r{$B%]%$%s%H$+$i(B@var{next-change}$B$^$G$N%F%-%9%H$r=hM}$9$k(B@dots{}}
    (goto-char next-change)))
@end smallexample
@end defun

@defun next-single-property-change pos prop &optional object limit
@c The function scans the text forward from position @var{pos} in the
@c string or buffer @var{object} till it finds a change in the @var{prop}
@c property, then returns the position of the change.  In other words, it
@c returns the position of the first character beyond @var{pos} whose
@c @var{prop} property differs from that of the character just after
@c @var{pos}.
$B$3$N4X?t$O!"J8;zNs$d%P%C%U%!$G$"$k(B@var{object}$BFb$N0LCV(B@var{pos}$B$+$i(B
$BB0@-(B@var{prop}$B$,0[$J$k$^$G%F%-%9%H$rAv::$7!"$=$NJQ2=$9$k0LCV$rJV$9!#(B
$B$$$$$+$($l$P!"(B@var{pos}$B$ND>8e$NJ8;z$NB0@-(B@var{prop}$B$H$O0[$J$k(B
$BB0@-(B@var{prop}$B$r$b$D(B@var{pos}$B$N$"$H$K$"$k:G=i$NJ8;z$N0LCV$rJV$9!#(B

@c If @var{limit} is non-@code{nil}, then the scan ends at position
@c @var{limit}.  If there is no property change before that point, 
@c @code{next-single-property-change} returns @var{limit}.
@var{limit}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B@var{limit}$B$N0LCV$GAv::$r=*$($k!#(B
$B$=$N2U=j$^$G0[$J$kB0@-$,$J$$$H!"(B
@code{next-single-property-change}$B$O(B@var{limit}$B$rJV$9!#(B

@c The value is @code{nil} if the property remains unchanged all the way to
@c the end of @var{object} and @var{limit} is @code{nil}.  If the value is
@c non-@code{nil}, it is a position greater than or equal to @var{pos}; it
@c equals @var{pos} only if @var{limit} equals @var{pos}.
@var{limit}$B$,(B@code{nil}$B$G$"$j(B@var{object}$B$NKvHx$^$GB0@-$KJQ2=$,$J$$$H!"(B
$BCM$O(B@code{nil}$B$G$"$k!#(B
$BCM$,(B@code{nil}$B0J30$G$"$k$H!"$=$l$O(B@var{pos}$B$h$jBg$-$$$+Ey$7$$0LCV$G$"$k!#(B
$BCM$,(B@var{pos}$B$KEy$7$$$N$O!"(B@var{limit}$B$,(B@var{pos}$B$KEy$7$$>l9g$N$_$G$"$k!#(B
@end defun

@defun previous-property-change pos &optional object limit
@c This is like @code{next-property-change}, but scans back from @var{pos}
@c instead of forward.  If the value is non-@code{nil}, it is a position
@c less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
@c equals @var{pos}.
$B$3$l$O(B@code{next-property-change}$B$HF1MM$G$"$k$,!"(B
$BA0J}$X$G$O$J$/(B@var{pos}$B$+$i8eJ}$XAv::$9$k!#(B
$BCM$,(B@code{nil}$B0J30$G$"$k$H!"$=$l$O(B@var{pos}$B$h$j>.$5$$$+Ey$7$$0LCV$G$"$k!#(B
$BCM$,(B@var{pos}$B$KEy$7$$$N$O!"(B@var{limit}$B$,(B@var{pos}$B$KEy$7$$>l9g$N$_$G$"$k!#(B
@end defun

@defun previous-single-property-change pos prop &optional object limit
@c This is like @code{next-single-property-change}, but scans back from
@c @var{pos} instead of forward.  If the value is non-@code{nil}, it is a
@c position less than or equal to @var{pos}; it equals @var{pos} only if
@c @var{limit} equals @var{pos}.
$B$3$l$O(B@code{next-single-property-change}$B$HF1MM$G$"$k$,!"(B
$BA0J}$X$G$O$J$/(B@var{pos}$B$+$i8eJ}$XAv::$9$k!#(B
$BCM$,(B@code{nil}$B0J30$G$"$k$H!"$=$l$O(B@var{pos}$B$h$j>.$5$$$+Ey$7$$0LCV$G$"$k!#(B
$BCM$,(B@var{pos}$B$KEy$7$$$N$O!"(B@var{limit}$B$,(B@var{pos}$B$KEy$7$$>l9g$N$_$G$"$k!#(B
@end defun

@defun next-char-property-change position &optional limit
@tindex next-char-property-change
@c This is like @code{next-property-change} except that it considers
@c overlay properties as well as text properties.  There is no @var{object}
@c operand because this function operates only on the current buffer.  It
@c returns the next address at which either kind of property changes.
$B$3$l$O(B@code{next-property-change}$B$HF1MM$G$"$k$,!"(B
$B%F%-%9%HB0@-$K2C$($F%*!<%P%l%$$bBP>]$K$9$k!#(B
$B$3$N4X?t$O%+%l%s%H%P%C%U%!$K$N$_:nMQ$9$k$?$a!"(B
@var{object}$B$rI=$90z?t$O$J$$!#(B
$B$I$A$i$+$NB0@-$,0[$J$k$D$.$N0LCV$rJV$9!#(B
@end defun

@defun previous-char-property-change position &optional limit
@tindex previous-char-property-change
@c This is like @code{next-char-property-change}, but scans back from
@c @var{position} instead of forward.
$B$3$l$O(B@code{next-char-property-change}$B$HF1MM$G$"$k$,!"(B
$BA0J}$X$G$O$J$/(B@var{pos}$B$+$i8eJ}$XAv::$9$k!#(B
@end defun

@defun text-property-any start end prop value &optional object
@c This function returns non-@code{nil} if at least one character between
@c @var{start} and @var{end} has a property @var{prop} whose value is
@c @var{value}.  More precisely, it returns the position of the first such
@c character.  Otherwise, it returns @code{nil}.
@var{start}$B$H(B@var{end}$B$N$"$$$@$KB0@-(B@var{prop}$B$NCM$,(B@var{value}$B$G$"$k(B
$BJ8;z$,(B1$B$D$G$b$"$l$P!"$3$N4X?t$O(B@code{nil}$B0J30$rJV$9!#(B
$B$h$j@53N$K$O!"$=$N$h$&$J:G=i$NJ8;z$N0LCV$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@c The optional fifth argument, @var{object}, specifies the string or
@c buffer to scan.  Positions are relative to @var{object}.  The default
@c for @var{object} is the current buffer.
$B>JN,2DG=$J(B5$BHVL\$N0z?t(B@var{object}$B$O!"Av::$9$Y$-J8;zNs$d%P%C%U%!$r;XDj$9$k!#(B
$B0LCV$O(B@var{object}$B$KAjBP$G$"$k!#(B
@var{object}$B$N%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B
@end defun

@defun text-property-not-all start end prop value &optional object
@c This function returns non-@code{nil} if at least one character between
@c @var{start} and @var{end} does not have a property @var{prop} with value
@c @var{value}.  More precisely, it returns the position of the first such
@c character.  Otherwise, it returns @code{nil}.
@var{start}$B$H(B@var{end}$B$N$"$$$@$KB0@-(B@var{prop}$B$NCM$,(B@var{value}$B$G$J$$(B
$BJ8;z$,(B1$B$D$G$b$"$l$P!"$3$N4X?t$O(B@code{nil}$B0J30$rJV$9!#(B
$B$h$j@53N$K$O!"$=$N$h$&$J:G=i$NJ8;z$N0LCV$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B

@c The optional fifth argument, @var{object}, specifies the string or
@c buffer to scan.  Positions are relative to @var{object}.  The default
@c for @var{object} is the current buffer.
$B>JN,2DG=$J(B5$BHVL\$N0z?t(B@var{object}$B$O!"Av::$9$Y$-J8;zNs$d%P%C%U%!$r;XDj$9$k!#(B
$B0LCV$O(B@var{object}$B$KAjBP$G$"$k!#(B
@var{object}$B$N%G%U%)%k%H$O%+%l%s%H%P%C%U%!$G$"$k!#(B
@end defun

@node Special Properties
@c @subsection Properties with Special Meanings
@subsection $BFCJL$J0UL#$r;}$DB0@-(B

@c   Here is a table of text property names that have special built-in
@c meanings.  The following sections list a few additional special property
@c names that control filling and property inheritance.  All other names
@c have no standard meaning, and you can use them as you like.
$BFCJL$JAH$_9~$_$N0UL#$r;}$D%F%-%9%HB0@-L>$N0lMw$r0J2<$K<($7$^$9!#(B
$B0J9_$N@a$G$O!"5M$a9~$_$dB0@-$N7Q>5$r@)8f$9$kFCJL$JB0@-L>$b<($7$^$9!#(B
$B$=$l0J30$NL>A0$K$OI8=`E*$J0UL#$O$J$$$N$G!"(B
$BFI<T$O$=$l$i$r9%$-$J$h$&$K;H$C$F$+$^$$$^$;$s!#(B

@table @code
@c @cindex category of text character
@cindex $B%F%-%9%HJ8;z$N%+%F%4%j(B
@c @kindex category @r{(text property)}
@kindex category @r{$B!J%F%-%9%HB0@-!K(B}
@item category
@c If a character has a @code{category} property, we call it the
@c @dfn{category} of the character.  It should be a symbol.  The properties
@c of the symbol serve as defaults for the properties of the character.
$BJ8;z$KB0@-(B@code{category}$B$,$"$k$H$-!"(B
$B$3$l$rJ8;z$N(B@dfn{$B%+%F%4%j(B}$B!J(Bcategory$B!K$H8F$V!#(B
$B$3$l$O%7%s%\%k$G$"$k$3$H!#(B
$B$=$N%7%s%\%k$NB0@-$,!"J8;z$NB0@-$N%G%U%)%k%H$H$7$FF/$/!#(B

@item face
@c @cindex face codes of text
@cindex $B%F%-%9%H$N%U%'%$%9%3!<%I(B
@c @kindex face @r{(text property)}
@kindex face @r{$B!J%F%-%9%HB0@-!K(B}
@c You can use the property @code{face} to control the font and color of
@c text.  Its value is a face name or a list of face names.  @xref{Faces},
@c for more information.
$B%F%-%9%H$N%U%)%s%H$HI=<(?'$r@)8f$9$k$?$a$KB0@-(B@code{face}$B$r;H$&!#(B
$B$=$NCM$O%U%'%$%9L>$+%U%'%$%9L>$N%j%9%H$G$"$k!#(B
$B>\$7$/$O!"(B@pxref{Faces}$B!#(B

@c If the property value is a list, elements may also have the form
@c @code{(foreground-color . @var{color-name})} or @code{(background-color
@c . @var{color-name})}.  These elements specify just the foreground color
@c or just the background color; therefore, there is no need to create a
@c face for each color that you want to use.
$BB0@-CM$,%j%9%H$G$"$k$H!"$=$NMWAG$O!"(B
@code{(foreground-color . @var{color-name})}$B$d(B
@code{(background-color . @var{color-name})}$B$N7A$G$b$h$$!#(B
$B$3$l$i$NMWAG$O!"A07J?'$@$1$dGX7J?'$@$1$r;XDj$9$k!#(B
$B$7$?$,$C$F!";HMQ$9$k3F?'$rI=$9%U%'%$%9$r:n@.$9$kI,MW$O$J$$!#(B

@c @xref{Font Lock Mode}, for information on how to update @code{face}
@c properties automatically based on the contents of the text.
$B%F%-%9%H$NFbMF$K4p$E$$$FB0@-(B@code{face}$B$r<+F0E*$K99?7$9$kJ}K!$K4X$7$F$O!"(B
@pxref{Font Lock Mode}$B!#(B

@item mouse-face
@c @kindex mouse-face @r{(text property)}
@kindex mouse-face @r{$B!J%F%-%9%HB0@-!K(B}
@c The property @code{mouse-face} is used instead of @code{face} when the
@c mouse is on or near the character.  For this purpose, ``near'' means
@c that all text between the character and where the mouse is have the same
@c @code{mouse-face} property value.
$B%^%&%9$,J8;z$N>e$d$=$N6a$/$K$"$k$H!"B0@-(B@code{face}$B$N$+$o$j$K(B
$BB0@-(B@code{mouse-face}$B$,;H$o$l$k!#(B
$B$3$NL\E*$K$*$$$F!X6a$/!Y$H$O!"(B
$BJ8;z$H%^%&%9$N0LCV$N$"$$$@$N(B
$BB0@-(B@code{mouse-face}$B$NCM$,F1$8$G$"$k$9$Y$F$N%F%-%9%H$G$"$k!#(B

@item local-map
@c @cindex keymap of character
@cindex $BJ8;z$N%-!<%^%C%W(B
@cindex $B%-!<%^%C%W!"J8;z(B
@c @kindex local-map @r{(text property)}
@kindex local-map @r{$B!J%F%-%9%HB0@-!K(B}
@c You can specify a different keymap for some of the text in a buffer by
@c means of the @code{local-map} property.  The property's value for the
@c character after point, if non-@code{nil}, is used for key lookup instead
@c of the buffer's local map.  If the property value is a symbol, the
@c symbol's function definition is used as the keymap.  @xref{Active
@c Keymaps}.
$BB0@-(B@code{local-map}$B$rMQ$$$k$3$H$G!"(B
$B%P%C%U%!Fb$N%F%-%9%H$N0lItJ,$KBP$7$FJL$N%-!<%^%C%W$r;XDj$G$-$k!#(B
$B%]%$%s%H$N$&$7$m$NJ8;z$N$3$NB0@-$NCM$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B%P%C%U%!$N%m!<%+%k%^%C%W$N$+$o$j$K$=$NCM$r%-!<C5:w$K;H$&!#(B
$BB0@-CM$,%7%s%\%k$G$"$k$H!"%7%s%\%k$N4X?tDj5A$r%-!<%^%C%W$H$7$F;H$&!#(B
@pxref{Active Keymaps}$B!#(B

@item syntax-table
@c The @code{syntax-table} property overrides what the syntax table says
@c about this particular character.  @xref{Syntax Properties}.
$BB0@-(B@code{syntax-table}$B$O!"9=J8%F!<%V%k$,$3$NJ8;z$K;XDj$9$k$b$N$KM%@h$9$k!#(B
@pxref{Syntax Properties}$B!#(B

@item read-only
@c @cindex read-only character
@cindex $BFI$_=P$7@lMQJ8;z(B
@c @kindex read-only @r{(text property)}
@kindex read-only @r{$B!J%F%-%9%HB0@-!K(B}
@c If a character has the property @code{read-only}, then modifying that
@c character is not allowed.  Any command that would do so gets an error.
$BJ8;z$KB0@-(B@code{read-only}$B$,$"$k$H!"$=$NJ8;z$rJQ99$G$-$J$$!#(B
$BJQ99$9$k$I$N$h$&$J%3%^%s%I$b%(%i!<$K$J$k!#(B

@c Insertion next to a read-only character is an error if inserting
@c ordinary text there would inherit the @code{read-only} property due to
@c stickiness.  Thus, you can control permission to insert next to
@c read-only text by controlling the stickiness.  @xref{Sticky Properties}.
$BA^F~$5$l$k%F%-%9%H$,%9%F%#%C%-@-$N$?$a$KB0@-(B@code{read-only}$B$r(B
$B7Q>5$9$k>l9g$K$O!"FI$_=P$7@lMQJ8;z$N$D$.$K%F%-%9%H$rA^F~$9$k$H%(%i!<$K$J$k!#(B
$B$7$?$,$C$F!"%9%F%#%C%-@-$r@)8f$9$k$3$H$G!"(B
$BFI$_=P$7@lMQ%F%-%9%H$N$D$.$X$N%F%-%9%HA^F~$r5v$9$+$I$&$+$r@)8f$G$-$k!#(B
@pxref{Sticky Properties}$B!#(B

@c Since changing properties counts as modifying the buffer, it is not
@c possible to remove a @code{read-only} property unless you know the
@c special trick: bind @code{inhibit-read-only} to a non-@code{nil} value
@c and then remove the property.  @xref{Read Only Buffers}.
$BB0@-$rJQ99$9$k$H%P%C%U%!$rJQ99$7$?$H$_$J$9$?$a!"(B
$BFCJL$J%H%j%C%/$rCN$i$J$$8B$j!"B0@-$r(B@code{read-only}$B$r:o=|$G$-$J$$!#(B
$B$D$^$j!"(B@code{inhibit-read-only}$B$K(B@code{nil}$B0J30$NCM$rB+G{$7$F!"(B
$BB0@-$r:o=|$9$k!#(B
@pxref{Read Only Buffers}$B!#(B

@item invisible
@c @kindex invisible @r{(text property)}
@kindex invisible @r{$B!J%F%-%9%HB0@-!K(B}
@c A non-@code{nil} @code{invisible} property can make a character invisible
@c on the screen.  @xref{Invisible Text}, for details.
$BB0@-(B@code{invisible}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$NJ8;z$O%9%/%j!<%s$KI=<($5$l$J$$!#(B
$B>\$7$/$O!"(B@pxref{Invisible Text}$B!#(B

@item intangible
@c @kindex intangible @r{(text property)}
@kindex intangible @r{$B!J%F%-%9%HB0@-!K(B}
@c If a group of consecutive characters have equal and non-@code{nil}
@c @code{intangible} properties, then you cannot place point between them.
@c If you try to move point forward into the group, point actually moves to
@c the end of the group.  If you try to move point backward into the group,
@c point actually moves to the start of the group.
$BO"B3$9$kJ8;z$KB0@-(B@code{intangible}$B$N(B@code{nil}$B$G$J$$F1$8CM$,$"$k$H!"(B
$B$=$l$i$N$"$$$@$K%]%$%s%H$rCV$1$J$/$J$k!#(B
$BA0J}$K8~$1$F$3$l$i$NJ8;z$NCf$K%]%$%s%H$r0\F0$7$h$&$H$9$k$H!"(B
$B%]%$%s%H$O<B:]$K$O$=$l$i$NKvHx$X0\F0$9$k!#(B
$B8eJ}$K8~$1$F$3$l$i$NJ8;z$NCf$K%]%$%s%H$r0\F0$7$h$&$H$9$k$H!"(B
$B%]%$%s%H$O<B:]$K$O$=$l$i$N@hF,$X0\F0$9$k!#(B

@c When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
@c the @code{intangible} property is ignored.
$BJQ?t(B@code{inhibit-point-motion-hooks}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$BB0@-(B@code{intangible}$B$OL5;k$5$l$k!#(B

@item modification-hooks
@c @cindex change hooks for a character
@c @cindex hooks for changing a character
@cindex $BJ8;z$KBP$9$kJQ99%U%C%/(B
@cindex $BJ8;zJQ99$KBP$9$k%U%C%/(B
@c @kindex modification-hooks @r{(text property)}
@kindex modification-hooks @r{$B!J%F%-%9%HB0@-!K(B}
@c If a character has the property @code{modification-hooks}, then its
@c value should be a list of functions; modifying that character calls all
@c of those functions.  Each function receives two arguments: the beginning
@c and end of the part of the buffer being modified.  Note that if a
@c particular modification hook function appears on several characters
@c being modified by a single primitive, you can't predict how many times
@c the function will be called.
$BJ8;z$KB0@-(B@code{modification-hooks}$B$,$"$k>l9g!"$=$l$O4X?t$N%j%9%H$G$"$k$3$H!#(B
$B$=$NJ8;z$NJQ99$K$O$=$l$i$N4X?t$9$Y$F$,8F$S=P$5$l$k!#(B
$B3F4X?t$O(B2$B$D$N0z?t!"$D$^$j!"%P%C%U%!$NJQ99BP>]ItJ,$N@hF,$HKvHx$r<u$1<h$k!#(B
1$B$D$NA`:n$GJQ99$5$l$k0lO"$NJ8;z$KF1$8JQ99%U%C%/4X?t$,8=$l$k>l9g!"(B
$B4X?t$,<B:]$K2?2s8F$P$l$k$+M=B,$G$-$J$$$3$H$KCm0U$7$F$[$7$$!#(B

@item insert-in-front-hooks
@itemx insert-behind-hooks
@c @kindex insert-in-front-hooks @r{(text property)}
@c @kindex insert-behind-hooks @r{(text property)}
@kindex insert-in-front-hooks @r{$B!J%F%-%9%HB0@-!K(B}
@kindex insert-behind-hooks @r{$B!J%F%-%9%HB0@-!K(B}
@c The operation of inserting text in a buffer also calls the functions
@c listed in the @code{insert-in-front-hooks} property of the following
@c character and in the @code{insert-behind-hooks} property of the
@c preceding character.  These functions receive two arguments, the
@c beginning and end of the inserted text.  The functions are called
@c @emph{after} the actual insertion takes place.
$B%P%C%U%!$K%F%-%9%H$rA^F~$9$kA`:n$G$b!"(B
$BA^F~2U=j$N$&$7$m$NJ8;z$NB0@-(B@code{insert-in-front-hooks}$B$H(B
$B$^$($NJ8;z$NB0@-(B@code{insert-behind-hooks}$B$K;XDj$5$l$F$$$k(B
$B4X?t72$r8F$S=P$9!#(B
$B$3$l$i$N4X?t$O(B2$B$D$N0z?t!"$D$^$j!"A^F~$5$l$?%F%-%9%H$N@hF,$HKvHx$r<u$1<h$k!#(B
$B$3$l$i$N4X?t$,8F$P$l$k$N$O!"<B:]$NA^F~A`:n$r(B@emph{$B=*$($F$+$i(B}$B$G$"$k!#(B

@c See also @ref{Change Hooks}, for other hooks that are called
@c when you change text in a buffer.
$B%P%C%U%!Fb$N%F%-%9%H$rJQ99$9$k$H$-$K8F$S=P$5$l$kB>$N%U%C%/$K$D$$$F$O!"(B
@ref{Change Hooks}$B$b;2>H!#(B

@item point-entered
@itemx point-left
@c @cindex hooks for motion of point
@cindex $B%]%$%s%H0\F0$KBP$9$k%U%C%/(B
@c @kindex point-entered @r{(text property)}
@c @kindex point-left @r{(text property)}
@kindex point-entered @r{$B!J%F%-%9%HB0@-!K(B}
@kindex point-left @r{$B!J%F%-%9%HB0@-!K(B}
@c The special properties @code{point-entered} and @code{point-left}
@c record hook functions that report motion of point.  Each time point
@c moves, Emacs compares these two property values:
$BFCJL$JB0@-(B@code{point-entered}$B$H(B@code{point-left}$B$O!"(B
$B%]%$%s%H0\F0$rJs9p$9$k%U%C%/4X?t$rJ];}$9$k!#(B
$B%]%$%s%H$,F0$/$?$S$K!"(BEmacs$B$O$3$l$i$N(B2$B$D$NB0@-CM!"$D$^$j!"(B

@itemize @bullet
@item
@c the @code{point-left} property of the character after the old location,
@c and
$B0\F0A0$N%]%$%s%H$N$&$7$m$NJ8;z$NB0@-(B@code{point-left}$B$H(B
@item
@c the @code{point-entered} property of the character after the new
@c location.
$B0\F08e$N%]%$%s%H$N$&$7$m$NJ8;z$NB0@-(B@code{point-entered}
@end itemize

@noindent
@c If these two values differ, each of them is called (if not @code{nil})
@c with two arguments: the old value of point, and the new one.
$B$rHf3S$9$k!#(B
$B$3$l$i(B2$B$D$NCM$,0[$J$l$P!"(B
$B%]%$%s%H$N8E$$CM$H?7$7$$CM$N(B2$B$D$N0z?t$G!J(B@code{nil}$B$G$J$1$l$P!K(B
$B$=$l$>$l$r8F$S=P$9!#(B

@c The same comparison is made for the characters before the old and new
@c locations.  The result may be to execute two @code{point-left} functions
@c (which may be the same function) and/or two @code{point-entered}
@c functions (which may be the same function).  In any case, all the
@c @code{point-left} functions are called first, followed by all the
@c @code{point-entered} functions.
$BF1$8$3$H$r0\F0A08e$N%]%$%s%H$N$^$($NJ8;z$K$D$$$F$b9T$&!#(B
$B$=$N7k2L!"!JF1$8$+$b$7$l$J$$!K(B@code{point-left}$B$N4X?t$r(B2$B2s!"$+$D!?$"$k$$$O!"(B
$B!JF1$8$+$b$7$l$J$$!K(B@code{point-entered}$B$N4X?t$r(B2$B2s<B9T$9$k!#(B
$B$$$:$l$K$7$F$b!"(B@code{point-left}$B$N4X?t$,:G=i$K8F$P$l!"(B
$B$=$N$"$H$G(B@code{point-entered}$B$N4X?t$,8F$P$l$k!#(B

@c It is possible using @code{char-after} to examine characters at various
@c positions without moving point to those positions.  Only an actual
@c change in the value of point runs these hook functions.
$B$3$l$i$N4X?t$G$O!"(B@code{char-after}$B$r;H$C$F(B
$B%]%$%s%H$r0\F0$;$:$K$5$^$6$^$J2U=j$NJ8;z$rD4$Y$i$l$k!#(B
$B%]%$%s%H$NCM$,<B:]$KJQ$o$C$?$H$-$K$N$_!"$3$l$i$N%U%C%/4X?t$,<B9T$5$l$k!#(B
@end table

@defvar inhibit-point-motion-hooks
@c When this variable is non-@code{nil}, @code{point-left} and
@c @code{point-entered} hooks are not run, and the @code{intangible}
@c property has no effect.  Do not set this variable globally; bind it with
@c @code{let}.
$B$3$NJQ?t$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{point-left}$B$H(B@code{point-entered}$B$N%U%C%/4X?t$O<B9T$5$l$J$/$J$j!"(B
$BB0@-(B@code{intangible}$B$N8z2L$b$J$/$J$k!#(B
$B$3$NJQ?t$O%0%m!<%P%k$K@_Dj$;$:$K!"(B@code{let}$B$GB+G{$9$k$3$H!#(B
@end defvar

@node Format Properties
@c @subsection Formatted Text Properties
@subsection $B@07A:Q$_%F%-%9%H$NB0@-(B

@c   These text properties affect the behavior of the fill commands.  They
@c are used for representing formatted text.  @xref{Filling}, and
@c @ref{Margins}.
$B$3$l$i$N%F%-%9%HB0@-$O!"5M$a9~$_%3%^%s%I$N$U$k$^$$$K1F6A$7$^$9!#(B
$B$3$l$i$O@07A:Q$_$N%F%-%9%H$rI=8=$9$k$?$a$K;H$o$l$^$9!#(B
@ref{Filling}$B$H(B@xref{Margins}$B!#(B

@table @code
@item hard
@c If a newline character has this property, it is a ``hard'' newline.
@c The fill commands do not alter hard newlines and do not move words
@c across them.  However, this property takes effect only if the variable
@c @code{use-hard-newlines} is non-@code{nil}.
$B2~9TJ8;z$K$3$NB0@-$,$"$k$H!"!X%O!<%I!Y2~9T$G$"$k!#(B
$B5M$a9~$_%3%^%s%I$O!X%O!<%I!Y2~9T$rJQ99$;$:!"(B
$B$=$l$i$r$^$?$,$C$FC18l$r0\F0$7$J$$!#(B
$B$7$+$7!"$3$NB0@-$O(B@code{use-hard-newlines}$B$,(B
@code{nil}$B0J30$N>l9g$K$N$_8z2L$r;}$D!#(B

@item right-margin
@c This property specifies an extra right margin for filling this part of the
@c text.
$B%F%-%9%H$N$3$NItJ,$r5M$a9~$`$?$a$NM>J,$J1&C<M>Gr$r;XDj$9$k!#(B

@item left-margin
@c This property specifies an extra left margin for filling this part of the
@c text.
$B%F%-%9%H$N$3$NItJ,$r5M$a9~$`$?$a$NM>J,$J:8C<M>Gr$r;XDj$9$k!#(B

@item justification
@c This property specifies the style of justification for filling this part
@c of the text.
$B%F%-%9%H$N$3$NItJ,$r5M$a9~$`$?$a$NI}B7$(%9%?%$%k$r;XDj$9$k!#(B
@end table

@node Sticky Properties
@c @subsection Stickiness of Text Properties
@subsection $B%F%-%9%HB0@-$N%9%F%#%C%-@-(B
@c @cindex sticky text properties
@c @cindex inheritance of text properties
@cindex $B%9%F%#%C%-%F%-%9%HB0@-(B
@cindex $B%F%-%9%HB0@-$N7Q>5(B

@c   Self-inserting characters normally take on the same properties as the
@c preceding character.  This is called @dfn{inheritance} of properties.
$B<+8JA^F~J8;z$O!"DL>o!"@h9T$9$kJ8;z$HF1$8B0@-$r;}$A$^$9!#(B
$B$3$l$rB0@-$N(B@dfn{$B7Q>5(B}$B!J(Binheritance$B!K$H8F$S$^$9!#(B

@c   In a Lisp program, you can do insertion with inheritance or without,
@c depending on your choice of insertion primitive.  The ordinary text
@c insertion functions such as @code{insert} do not inherit any properties.
@c They insert text with precisely the properties of the string being
@c inserted, and no others.  This is correct for programs that copy text
@c from one context to another---for example, into or out of the kill ring.
@c To insert with inheritance, use the special primitives described in this
@c section.  Self-inserting characters inherit properties because they work
@c using these primitives.
Lisp$B%W%m%0%i%`$G$O!"A^F~4pK\4X?t$rA*$Y$P!"(B
$B7Q>5$7$FA^F~$7$?$j7Q>5$;$:$KA^F~$G$-$^$9!#(B
@code{insert}$B$J$I$NIaDL$N%F%-%9%HA^F~4X?t$O!"(B
$B$$$+$J$kB0@-$b7Q>5$7$^$;$s!#(B
$B$3$l$i$O!"A^F~$9$kJ8;zNs$NB0@-$r$=$N$^$^;}$C$?%F%-%9%H$rA^F~$7!"(B
$B$=$l0J30$NB0@-$O$"$j$^$;$s!#(B
$B%-%k%j%s%0$J$I$N$"$kJ8L.$+$iJL$NJ8L.$X%F%-%9%H$r%3%T!<$9$k%W%m%0%i%`$K$O!"(B
$B$3$l$O@5$7$$F0:n$G$9!#(B
$B7Q>5$7$FA^F~$9$k$K$O!"K\@a$G=R$Y$kFCJL$J4pK\4X?t$r;H$$$^$9!#(B
$B<+8JA^F~J8;z$O$3$l$i$N4pK\4X?t$r;H$C$F$$$k$N$G!"B0@-$r7Q>5$7$^$9!#(B

@c   When you do insertion with inheritance, @emph{which} properties are
@c inherited depends on two specific properties: @code{front-sticky} and
@c @code{rear-nonsticky}.
$B7Q>5$7$FA^F~$9$k$H$-!"(B@emph{$B$I$N(B}$BB0@-$r7Q>5$9$k$+$O!"(B
2$B$D$NFCJL$JB0@-(B@code{front-sticky}$B$H(B@code{rear-nonsticky}$B$K0MB8$7$^$9!#(B

@c   Insertion after a character inherits those of its properties that are
@c @dfn{rear-sticky}.  Insertion before a character inherits those of its
@c properties that are @dfn{front-sticky}.  By default, a text property is
@c rear-sticky but not front-sticky.  Thus, the default is to inherit all
@c the properties of the preceding character, and nothing from the
@c following character.  You can request different behavior by specifying
@c the stickiness of certain properties.
$BJ8;z$N$&$7$m$KA^F~$9$k$H!"$=$NJ8;z$N(B@dfn{$B8eB3%9%F%#%C%-(B}$B!J(Brear-sticky$B!K(B
$B$G$"$kB0@-$r7Q>5$7$^$9!#(B
$BJ8;z$N$^$($KA^F~$9$k$H!"$=$NJ8;z$N(B@dfn{$B@h9T%9%F%#%C%-(B}$B!J(Bfront-sticky$B!K(B
$B$G$"$kB0@-$r7Q>5$7$^$9!#(B
$B%G%U%)%k%H$G$O!"%F%-%9%HB0@-$O@h9T%9%F%#%C%-$G$O$J$/8eB3%9%F%#%C%-$G$9!#(B
$B$7$?$,$C$F!"%G%U%)%k%H$G$O!"$^$($NJ8;z$N$9$Y$F$NB0@-$r7Q>5$7$F!"(B
$B$&$7$m$NJ8;z$+$i$O$J$K$b7Q>5$7$^$;$s!#(B
$BFCDj$NB0@-$N%9%F%#%C%-@-$r;XDj$9$k$3$H$G!"0[$J$k$U$k$^$$$r;XDj$G$-$^$9!#(B

@c   If a character's @code{front-sticky} property is @code{t}, then all
@c its properties are front-sticky.  If the @code{front-sticky} property is
@c a list, then the sticky properties of the character are those whose
@c names are in the list.  For example, if a character has a
@c @code{front-sticky} property whose value is @code{(face read-only)},
@c then insertion before the character can inherit its @code{face} property
@c and its @code{read-only} property, but no others.
$BJ8;z$NB0@-(B@code{front-sticky}$B$,(B@code{t}$B$G$"$k$H!"(B
$B$=$NJ8;z$N$9$Y$F$NB0@-$O@h9T%9%F%#%C%-$G$9!#(B
$BB0@-(B@code{front-sticky}$B$,%j%9%H$G$"$k$H!"(B
$B%j%9%H$K8=$l$kL>A0$N$=$NJ8;z$NB0@-$O@h9T%9%F%#%C%-$G$9!#(B
$B$?$H$($P!"J8;z$NB0@-(B@code{front-sticky}$B$NCM$,(B@code{(face read-only)}$B$G$"$k$H!"(B
$B$3$NJ8;z$N$^$($KA^F~$9$k$H$3$NJ8;z$NB0@-(B@code{face}$B$H(B@code{read-only}$B$r(B
$B7Q>5$7$^$9$,!"$=$l0J30$K$O7Q>5$7$^$;$s!#(B

@c   The @code{rear-nonsticky} works the opposite way.  Every property is
@c rear-sticky by default, so the @code{rear-nonsticky} property says which
@c properties are @emph{not} rear-sticky.  If a character's
@c @code{rear-nonsticky} property is @code{t}, then none of its properties
@c are rear-sticky.  If the @code{rear-nonsticky} property is a list,
@c properties are rear-sticky @emph{unless} their names are in the list.
@code{rear-nonsticky}$B$OH?BP$NF/$-$r$7$^$9!#(B
$B$9$Y$F$NB0@-$O%G%U%)%k%H$G$O8eB3%9%F%#%C%-$G$9$+$i!"(B
$BB0@-(B@code{rear-nonsticky}$B$O$I$NB0@-$,(B
$B8eB3%9%F%#%C%-$G(B@emph{$B$J$$(B}$B$+$r;XDj$7$^$9!#(B
$BJ8;z$NB0@-(B@code{rear-nonsticky}$B$,(B@code{t}$B$G$"$k$H!"(B
$B$=$NJ8;z$K$O8eB3%9%F%#%C%-$G$"$kB0@-$O$"$j$^$;$s!#(B
$BB0@-(B@code{rear-nonsticky}$B$,%j%9%H$G$"$k$H!"(B
$B%j%9%H$KL>A0$,8=$l(B@emph{$B$J$$8B$j(B}$B!"(B
$BB0@-$O8eB3%9%F%#%C%-$G$9!#(B

@c   When you insert text with inheritance, it inherits all the rear-sticky
@c properties of the preceding character, and all the front-sticky
@c properties of the following character.  The previous character's
@c properties take precedence when both sides offer different sticky values
@c for the same property.
$B7Q>5$9$k$h$&$K%F%-%9%H$rA^F~$9$k$H!"(B
$B$^$($NJ8;z$+$i$O8eB3%9%F%#%C%-$G$"$k$9$Y$F$NB0@-$r7Q>5$7!"(B
$B$&$7$m$NJ8;z$+$i$O@h9T%9%F%#%C%-$G$"$k$9$Y$F$NB0@-$r7Q>5$7$^$9!#(B
$BN>B&$NJ8;z$K0[$J$k%9%F%#%C%-@-$NF1$8B0@-$,$"$k>l9g$K$O!"(B
$B$^$($NJ8;z$NB0@-$,M%@h$7$^$9!#(B

@c   Here are the functions that insert text with inheritance of properties:
$BB0@-$r7Q>5$7$F%F%-%9%H$rA^F~$9$k4X?t$O$D$.$N$H$*$j$G$9!#(B

@defun insert-and-inherit &rest strings
@c Insert the strings @var{strings}, just like the function @code{insert},
@c but inherit any sticky properties from the adjoining text.
$B4X?t(B@code{insert}$B$HF1MM$KJ8;zNs(B@var{strings}$B$rA^F~$9$k$,!"(B
$BA08e$N%F%-%9%H$+$iG$0U$N%9%F%#%C%-@-$NB0@-$r7Q>5$9$k!#(B
@end defun

@defun insert-before-markers-and-inherit &rest strings
@c Insert the strings @var{strings}, just like the function
@c @code{insert-before-markers}, but inherit any sticky properties from the
@c adjoining text.
$B4X?t(B@code{insert-before-markers}$B$HF1MM$KJ8;zNs(B@var{strings}$B$rA^F~$9$k$,!"(B
$BA08e$N%F%-%9%H$+$iG$0U$N%9%F%#%C%-@-$NB0@-$r7Q>5$9$k!#(B
@end defun

@c   @xref{Insertion}, for the ordinary insertion functions which do not
@c inherit.
$B7Q>5$7$J$$IaDL$NA^F~4X?t$K$D$$$F$O!"(B@xref{Insertion}$B!#(B

@node Saving Properties
@c @subsection Saving Text Properties in Files
@subsection $B%F%-%9%HB0@-$r%U%!%$%k$XJ]B8$9$k(B
@c @cindex text properties in files
@c @cindex saving text properties
@cindex $B%U%!%$%kFb$N%F%-%9%HB0@-(B
@cindex $B%F%-%9%HB0@-!"%U%!%$%kFb(B
@cindex $B%F%-%9%HB0@-$NJ]B8(B
@cindex $BJ]B8!"%F%-%9%HB0@-(B

@c   You can save text properties in files (along with the text itself),
@c and restore the same text properties when visiting or inserting the
@c files, using these two hooks:
$B$D$.$N(B2$B$D$N%U%C%/$r;H$C$F!"(B
$B%F%-%9%HB0@-$r!J%F%-%9%H$=$N$b$N$H$H$b$K!K%U%!%$%k$KJ]B8$7$F$*$-!"(B
$B%U%!%$%k$rK,Ld$7$?$jA^F~$9$k$H$-$KF1$8%F%-%9%HB0@-$rI|85$G$-$^$9!#(B

@defvar write-region-annotate-functions
@c This variable's value is a list of functions for @code{write-region} to
@c run to encode text properties in some fashion as annotations to the text
@c being written in the file.  @xref{Writing to Files}.
$B$3$NJQ?t$NCM$O!"%U%!%$%k$X=q$-9~$`%F%-%9%H$KBP$9$kCm5-$N7A$G(B
$B%F%-%9%HB0@-$rId9f2=$9$k$?$a$K(B@code{write-region}$B$,8F$S=P$94X?t$N(B
$B%j%9%H$G$"$k!#(B
@pxref{Writing to Files}$B!#(B

@c Each function in the list is called with two arguments: the start and
@c end of the region to be written.  These functions should not alter the
@c contents of the buffer.  Instead, they should return lists indicating
@c annotations to write in the file in addition to the text in the
@c buffer.
$B%j%9%HFb$N3F4X?t$O(B2$B$D$N0z?t!"$D$^$j!"(B
$B=q$-9~$`NN0h$N@hF,$HKvHx$G8F$S=P$5$l$k!#(B
$B$3$l$i$N4X?t$O%P%C%U%!$NFbMF$rJQ99$7$J$$$3$H!#(B
$B$=$N$+$o$j$K!"%P%C%U%!$N%F%-%9%H$K2C$($F%U%!%$%k$K=q$-9~$`$Y$-(B
$BCm5-$rI=$9%j%9%H$rJV$9$Y$-$G$"$k!#(B

@c Each function should return a list of elements of the form
@c @code{(@var{position} . @var{string})}, where @var{position} is an
@c integer specifying the relative position within the text to be written,
@c and @var{string} is the annotation to add there.
$B3F4X?t$O!"(B@code{(@var{position} . @var{string})}$B$N7A$NMWAG$+$i@.$k(B
$B%j%9%H$rJV$9$Y$-$G$"$k!#(B
$B$3$3$G!"(B@var{position}$B$O=q$-9~$^$l$k%F%-%9%HFb$NAjBP0LCV$r;XDj$9$k@0?t!"(B
@var{string}$B$O$=$3$XDI2C$9$kCm5-$G$"$k!#(B

@c Each list returned by one of these functions must be already sorted in
@c increasing order by @var{position}.  If there is more than one function,
@c @code{write-region} merges the lists destructively into one sorted list.
$B$3$l$i$N4X?t$,JV$93F%j%9%H$O!"(B@var{position}$B$N>:=g$K$J$C$F$$$kI,MW$,$"$k!#(B
$BJ#?t$N4X?t$,$"$k$H!"(B@code{write-region}$B$O(B
$B%j%9%H$rGK2uE*$KJ;9g$7$F(B1$B$D$N%=!<%H$7$?%j%9%H$K$9$k!#(B

@c When @code{write-region} actually writes the text from the buffer to the
@c file, it intermixes the specified annotations at the corresponding
@c positions.  All this takes place without modifying the buffer.
@code{write-region}$B$,%P%C%U%!$+$i%U%!%$%k$K%F%-%9%H$r<B:]$K=q$/$H$-$K!"(B
$B;XDj$5$l$?Cm5-$rBP1~$9$k0LCV$K:.:_$5$;$k!#(B
$B%P%C%U%!$rJQ99$;$:$K$3$l$i$9$Y$F$r9T$&!#(B
@end defvar

@defvar after-insert-file-functions
@c This variable holds a list of functions for @code{insert-file-contents}
@c to call after inserting a file's contents.  These functions should scan
@c the inserted text for annotations, and convert them to the text
@c properties they stand for.
$B$3$NJQ?t$O!"(B@code{insert-file-contents}$B$,%U%!%$%k$NFbMF$rA^F~$7$F$+$i(B
$B8F$S=P$94X?t$N%j%9%H$rJ];}$9$k!#(B
$B$3$l$i$N4X?t$OA^F~$5$l$?%F%-%9%H$GCm5-$rAv::$7!"(B
$B$=$l$i$,I=$9%F%-%9%HB0@-$K$=$l$i$rJQ49$9$k!#(B

@c Each function receives one argument, the length of the inserted text;
@c point indicates the start of that text.  The function should scan that
@c text for annotations, delete them, and create the text properties that
@c the annotations specify.  The function should return the updated length
@c of the inserted text, as it stands after those changes.  The value
@c returned by one function becomes the argument to the next function.
$B3F4X?t$O(B1$B$D$N0z?t!"$D$^$j!"A^F~$5$l$?%F%-%9%H$ND9$5$G8F$P$l!"(B
$B%]%$%s%H$OA^F~$5$l$?%F%-%9%H$N@hF,$rI=$9!#(B
$B4X?t$OEv3:%F%-%9%H$GCm5-$rAv::$7$FCm5-$r:o=|$7!"(B
$BCm5-$,;XDj$9$k%F%-%9%HB0@-$r:n@.$9$k!#(B
$B4X?t$O!"JQ99$rH?1G$7$?A^F~$5$l$?%F%-%9%H$N99?7$5$l$?D9$5$rJV$9$3$H!#(B
$B4X?t$,JV$7$?CM$,$D$.$N4X?t$N0z?t$K$J$k!#(B

@c These functions should always return with point at the beginning of
@c the inserted text.
$B$3$l$i$N4X?t$O!"A^F~$5$l$?%F%-%9%H$N@hF,$K%]%$%s%H$r$D$M$KLa$9$3$H!#(B

@c The intended use of @code{after-insert-file-functions} is for converting
@c some sort of textual annotations into actual text properties.  But other
@c uses may be possible.
@code{after-insert-file-functions}$B$N0U?^$5$l$?MQES$O!"(B
$B%F%-%9%HI=8=$NCm5-$r<B:]$N%F%-%9%HB0@-$KJQ49$9$k$3$H$G$"$k!#(B
$B$7$+$7!"JL$N;H$$J}$b2DG=$G$"$k!#(B
@end defvar

@c We invite users to write Lisp programs to store and retrieve text
@c properties in files, using these hooks, and thus to experiment with
@c various data formats and find good ones.  Eventually we hope users 
@c will produce good, general extensions we can install in Emacs.
$B$3$l$i$N%U%C%/$r;H$C$F%U%!%$%k$K%F%-%9%HB0@-$rJ]B8$7$?$jI|85$9$k(B
Lisp$B%W%m%0%i%`$r=q$$$F!"$5$^$6$^$J%G!<%?=q<0$r;n$7$F(B
$B$h$$$b$N$r$_$D$1$k$h$&$K$*4j$$$7$^$9!#(B
$B:G=*E*$K$O!"(BEmacs$B$K<h$j9~$a$kNI<A$GHFMQ$N3HD%$r(B
$B%f!<%6!<$,:n$j=P$9$3$H$r4j$C$F$$$^$9!#(B

@c We suggest not trying to handle arbitrary Lisp objects as text property
@c names or values---because a program that general is probably difficult
@c to write, and slow.  Instead, choose a set of possible data types that
@c are reasonably flexible, and not too hard to encode.
$B%F%-%9%HB0@-$NL>A0$dCM$H$7$FG$0U$N(BLisp$B%*%V%8%'%/%H$r(B
$B=hM}$7$J$$$h$&$KCi9p$7$F$*$-$^$9!#(B
$B$=$N$h$&$JHFMQ$N%W%m%0%i%`$O=q$/$N$,Fq$7$/F0:n$,CY$/$J$j$,$A$G$9!#(B
$B$=$N$+$o$j$K!"E,Ev$K=@Fp@-$,$"$jId9f2=$,Fq$7$/$J$$%G!<%?7?$N=89g$rA*$S$^$9!#(B

@c @xref{Format Conversion}, for a related feature.
$B4XO"$9$k5!G=$K$D$$$F$O!"(B@xref{Format Conversion}$B!#(B

@c ??? In next edition, merge this info Format Conversion.

@node Lazy Properties
@c @subsection Lazy Computation of Text Properties
@subsection $B%F%-%9%HB0@-$NCY1d7W;;(B

@c   Instead of computing text properties for all the text in the buffer,
@c you can arrange to compute the text properties for parts of the text
@c when and if something depends on them.
$B%P%C%U%!Fb$N$9$Y$F$N%F%-%9%H$N%F%-%9%HB0@-$r7W;;$9$k$+$o$j$K!"(B
$BI,MW$K$J$C$?;~E@$G%F%-%9%H$N0lItJ,$N%F%-%9%HB0@-$r7W;;$9$k$h$&$K$G$-$^$9!#(B

@c   The primitive that extracts text from the buffer along with its
@c properties is @code{buffer-substring}.  Before examining the properties,
@c this function runs the abnormal hook @code{buffer-access-fontify-functions}.
$B%P%C%U%!$+$i%F%-%9%HB0@-$H$H$b$K%F%-%9%H$r<h$j=P$94pK\4X?t$O!"(B
@code{buffer-substring}$B$G$9!#(B
$BB0@-$rD4$Y$k$^$($K!"$3$N4X?t$O%"%V%N!<%^%k%U%C%/(B
@code{buffer-access-fontify-functions}$B$r<B9T$7$^$9!#(B

@defvar buffer-access-fontify-functions
@c This variable holds a list of functions for computing text properties.
@c Before @code{buffer-substring} copies the text and text properties for a
@c portion of the buffer, it calls all the functions in this list.  Each of
@c the functions receives two arguments that specify the range of the
@c buffer being accessed.  (The buffer itself is always the current
@c buffer.)
$B$3$NJQ?t$O!"%F%-%9%HB0@-$r7W;;$9$k4X?t$N%j%9%H$rJ];}$9$k!#(B
@code{buffer-substring}$B$,%P%C%U%!$N0lItJ,$+$i%F%-%9%H$H%F%-%9%HB0@-$r(B
$B%3%T!<$9$k$^$($K!"$3$N4X?t$O$3$N%j%9%HFb$N4X?t$9$Y$F$r8F$S=P$9!#(B
$B3F4X?t$O!"%P%C%U%!$N;2>H$5$l$kHO0O$r;XDj$9$k(B2$B$D$N0z?t$r<u$1<h$k!#(B
$B!J%P%C%U%!$O$D$M$K%+%l%s%H%P%C%U%!$G$"$k!#!K(B
@end defvar

@c   The function @code{buffer-substring-no-properties} does not call these
@c functions, since it ignores text properties anyway.
$B4X?t(B@code{buffer-substring-no-properties}$B$O(B
$B%F%-%9%HB0@-$rL5;k$9$k$N$G!"$3$l$i$N4X?t$r8F$S=P$7$^$;$s!#(B

@c   In order to prevent the hook functions from being called more than
@c once for the same part of the buffer, you can use the variable
@c @code{buffer-access-fontified-property}.
$B%P%C%U%!$NF1$8ItJ,$KBP$7$F%U%C%/4X?t$,J#?t2s8F$S=P$5$l$k$N$rKI$0$K$O!"(B
$BJQ?t(B@code{buffer-access-fontified-property}$B$r;H$$$^$9!#(B

@defvar buffer-access-fontified-property
@c If this value's variable is non-@code{nil}, it is a symbol which is used
@c as a text property name.  A non-@code{nil} value for that text property
@c means, ``the other text properties for this character have already been
@c computed.''
$B$3$NJQ?t$NCM$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$=$l$O%F%-%9%HB0@-$NL>A0$H$7$F;H$o$l$k%7%s%\%k$G$"$k!#(B
$B$=$N%F%-%9%HB0@-$KBP$9$k(B@code{nil}$B0J30$NCM$O!"(B
$B!X$3$NJ8;z$NB>$N%F%-%9%HB0@-$O$9$G$K7W;;:Q$_$G$"$k!Y$3$H$r0UL#$9$k!#(B

@c If all the characters in the range specified for @code{buffer-substring}
@c have a non-@code{nil} value for this property, @code{buffer-substring}
@c does not call the @code{buffer-access-fontify-functions} functions.  It
@c assumes these characters already have the right text properties, and
@c just copies the properties they already have.
@code{buffer-substring}$B$K;XDj$5$l$?HO0O$N$9$Y$F$NJ8;z$K$*$$$F!"(B
$B$3$NB0@-$KBP$7$F(B@code{nil}$B0J30$NCM$,$"$k$H!"(B
@code{buffer-substring}$B$O(B
@code{buffer-access-fontify-functions}$B$N4X?t$r8F$S=P$5$J$$!#(B
$B$=$l$i$NJ8;z$K$O$9$G$K@5$7$$%F%-%9%HB0@-$,$"$k$H$_$J$7!"(B
$B$=$l$i$K$9$G$K$"$kB0@-$r%3%T!<$9$k!#(B

@c The normal way to use this feature is that the
@c @code{buffer-access-fontify-functions} functions add this property, as
@c well as others, to the characters they operate on.  That way, they avoid
@c being called over and over for the same text.
$B$3$N5!G=$r;H$&IaDL$NJ}K!$O!"(B
@code{buffer-access-fontify-functions}$B$N4X?t$,(B
$BB>$NB0@-$H$H$H$b$K$3$NB0@-$r$=$l$i$,A`:n$7$?J8;z$KDI2C$9$k!#(B
$B$=$&$9$l$P!"F1$8%F%-%9%H$KBP$7$F2?2s$b8F$S=P$5$l$k$N$rKI$0$3$H$,$G$-$k!#(B
@end defvar

@node Clickable Text
@c @subsection Defining Clickable Text
@subsection $B%/%j%C%/2DG=$J%F%-%9%H$rDj5A$9$k(B
@c @cindex clickable text
@cindex $B%/%j%C%/2DG=$J%F%-%9%H(B

@c   There are two ways to set up @dfn{clickable text} in a buffer.
@c There are typically two parts of this: to make the text highlight
@c when the mouse is over it, and to make a mouse button do something
@c when you click it on that part of the text.
$B%P%C%U%!Fb$K(B@dfn{$B%/%j%C%/2DG=$J%F%-%9%H(B}$B!J(Bclickable text$B!K$r@_Dj$9$k$K$O(B
2$B$D$NJ}K!$,$"$j$^$9!#(B
$B$3$l$OE57?E*$K$O(B2$B$D$NItJ,$+$i@.$j$^$9!#(B
$B$D$^$j!"%^%&%9$,=E$J$k$H%F%-%9%H$r6/D4I=<($7!"(B
$B%F%-%9%H$N$=$NItJ,$r%/%j%C%/$9$k$H(B
$B%^%&%9%\%?%s$,$J$s$i$+$N=hM}$r9T$&$h$&$K$7$^$9!#(B

@c   Highlighting is done with the @code{mouse-face} text property.
@c Here is an example of how Dired does it:
$B6/D4I=<($O%F%-%9%HB0@-(B@code{mouse-face}$B$G9T$$$^$9!#(B
dired$B$G$NJ}K!$rNc$H$7$F<($7$^$9!#(B

@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))
  (error nil))
@end smallexample

@noindent
@c The first two arguments to @code{put-text-property} specify the
@c beginning and end of the text.
@code{put-text-property}$B$N:G=i$N(B2$B$D$N0z?t$O!"(B
$B%F%-%9%H$N@hF,$HKvHx$r;XDj$7$^$9!#(B

@c   The usual way to make the mouse do something when you click it
@c on this text is to define @code{mouse-2} in the major mode's
@c keymap.  The job of checking whether the click was on clickable text
@c is done by the command definition.  Here is how Dired does it:
$B$3$N%F%-%9%H$r%/%j%C%/$7$?$H$-$K%^%&%9$K$J$K$+$r$5$;$k$h$&$K$9$k(B
$BIaDL$NJ}K!$O!"%a%8%c!<%b!<%I$N%-!<%^%C%W$G(B@code{mouse-2}$B$rDj5A$9$k$3$H$G$9!#(B
$B%/%j%C%/2DG=$J%F%-%9%H$r%/%j%C%/$7$?$+$I$&$+$N8!::$O!"(B
$B%3%^%s%IDj5A$G9T$o$l$^$9!#(B
dired$B$G$O$D$.$N$h$&$K$7$F$$$^$9!#(B

@smallexample
(defun dired-mouse-find-file-other-window (event)
  "In dired, visit the file or directory name you click on."
  (interactive "e")
  (let (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))))
@end smallexample

@noindent
@c The reason for the outer @code{save-excursion} construct is to avoid
@c changing the current buffer; the reason for the inner one is to avoid
@c permanently altering point in the buffer you click on.  In this case,
@c Dired uses the function @code{dired-get-filename} to determine which
@c file to visit, based on the position found in the event.
$B30B&$N(B@code{save-excursion}$B$O!"%+%l%s%H%P%C%U%!$,JQ$o$k$3$H$rKI$.$^$9!#(B
$BFbB&$N$O!"%/%j%C%/$7$?%P%C%U%!$N%]%$%s%H$r915WE*$KJQ99$9$k$3$H$rKI$.$^$9!#(B
$B$3$NNc$G$O!"(Bdired$B$O4X?t(B@code{dired-get-filename}$B$rMQ$$$F!"(B
$B%$%Y%s%H$N0LCV$K4p$E$$$FK,Ld$9$Y$-%U%!%$%k$r7hDj$7$^$9!#(B

@c   Instead of defining a mouse command for the major mode, you can define
@c a key binding for the clickable text itself, using the @code{local-map}
@c text property:
$B%a%8%c!<%b!<%I$N%^%&%9%3%^%s%I$rDj5A$9$k$+$o$j$K!"(B
$B%F%-%9%HB0@-(B@code{local-map}$B$r;H$C$F!"(B
$B%/%j%C%/2DG=$J%F%-%9%H$=$N$b$N$K%-!<%P%$%s%G%#%s%0$rDj5A$9$k$3$H$b$G$-$^$9!#(B

@example
(let ((map (make-sparse-keymap)))
  (define-key-binding map [mouse-2] 'operate-this-button)
  (put-text-property (point)
                     (save-excursion
                       (dired-move-to-end-of-filename)
                       (point))
                     'local-map map))
@end example

@noindent
@c This method makes it possible to define different commands for various
@c clickable pieces of text.  Also, the major mode definition (or the
@c global definition) remains available for the rest of the text in the
@c buffer.
$B$3$NJ}K!$G$O!"%F%-%9%H$N$5$^$6$^$J%/%j%C%/2DG=$JItJ,$K(B
$B0[$J$k%3%^%s%I$rDj5A$G$-$^$9!#(B
$B$5$i$K!"%P%C%U%!$N;D$j$NItJ,$KBP$7$F$O!"(B
$B%a%8%c!<%b!<%I$NDj5A!J$d%0%m!<%P%k$JDj5A!K$,$=$N$^$^M-8z$G$9!#(B

@node Not Intervals
@c @subsection Why Text Properties are not Intervals
@subsection $B%F%-%9%HB0@-$,HO0O$G$J$$M}M3(B
@c @cindex intervals
@cindex $BHO0O(B

@c   Some editors that support adding attributes to text in the buffer do
@c so by letting the user specify ``intervals'' within the text, and adding
@c the properties to the intervals.  Those editors permit the user or the
@c programmer to determine where individual intervals start and end.  We
@c deliberately provided a different sort of interface in Emacs Lisp to
@c avoid certain paradoxical behavior associated with text modification.
$B%P%C%U%!Fb$N%F%-%9%H$KB0@-$rIU2C$G$-$k%(%G%#%?$N$J$+$K$O!"(B
$B%f!<%6!<$K%F%-%9%HFb$N!XHO0O!Y$r;XDj$5$;!"(B
$B$=$NHO0O$KB0@-$rIU2C$9$k$b$N$,$"$j$^$9!#(B
$B$3$N$h$&$J%(%G%#%?$G$O!"%f!<%6!<$d%W%m%0%i%^$,(B
$B8D!9$NHO0O$N@hF,$HKvHx$r7hDj$G$-$^$9!#(B
$B%F%-%9%HJQ99$KH<$&$"$k<o$NL7=b$9$k$h$&$J$U$k$^$$$rHr$1$k$?$a$K!"(B
$B=O9M$N7k2L(BEmacs Lisp$B$G$OJL$N<oN`$N%$%s%?!<%U%'%$%9$rDs6!$9$k$3$H$K$7$^$7$?!#(B

@c   If the actual subdivision into intervals is meaningful, that means you
@c can distinguish between a buffer that is just one interval with a
@c certain property, and a buffer containing the same text subdivided into
@c two intervals, both of which have that property.
$BJ#?t$NHO0O$K:YJ,$9$k$3$H$,0UL#$r;}$D$J$i$P!"(B
$B$"$kB0@-$N(B1$B$D$NHO0O$,$"$k$@$1$N%P%C%U%!$H!"(B
$B$=$NF1$8%F%-%9%H$r$=$NF1$8B0@-$N(B2$B$D$NHO0O$K$7$F$"$k%P%C%U%!$H$r(B
$B6hJL$G$-$k$O$:$G$9!#(B

@c   Suppose you take the buffer with just one interval and kill part of
@c the text.  The text remaining in the buffer is one interval, and the
@c copy in the kill ring (and the undo list) becomes a separate interval.
@c Then if you yank back the killed text, you get two intervals with the
@c same properties.  Thus, editing does not preserve the distinction
@c between one interval and two.
1$B$D$NHO0O$@$1$r;}$D%P%C%U%!$K$*$$$F!"$=$N%F%-%9%H$N0lIt$r%-%k$7$?$H$7$^$9!#(B
$B%P%C%U%!$K;D$C$F$$$k%F%-%9%H$O(B1$B$D$NHO0O$G$"$j!"(B
$B%-%k%j%s%0!J$H%"%s%I%%%j%9%H!KFb$N%3%T!<$O(B1$B$D$NJL$NHO0O$K$J$j$^$9!#(B
$B$=$7$F%-%k$5$l$?%F%-%9%H$r%d%s%/$7$FLa$9$H!"(B
$BF1$8B0@-$r;}$D(B2$B$D$NHO0O$,$G$-$^$9!#(B
$B$D$^$j!"JT=8$9$k$H!"(B1$B$D$NHO0O$H(B2$B$D$NHO0O$N6hJL$rJ]B8$G$-$J$/$J$j$^$9!#(B

@c   Suppose we ``fix'' this problem by coalescing the two intervals when
@c the text is inserted.  That works fine if the buffer originally was a
@c single interval.  But suppose instead that we have two adjacent
@c intervals with the same properties, and we kill the text of one interval
@c and yank it back.  The same interval-coalescence feature that rescues
@c the other case causes trouble in this one: after yanking, we have just
@c one interval.  One again, editing does not preserve the distinction
@c between one interval and two.
$B%F%-%9%H$rA^F~$9$k$H(B2$B$D$NHO0O$rM;9g$9$k$3$H$G(B
$B$3$NLdBj$r!X=$@5!Y$7$?$H$7$^$9!#(B
$B%P%C%U%!$K$b$H$b$H(B1$B$D$NHO0O$7$+$J$1$l$P!"$&$^$/$$$-$^$9!#(B
$B$7$+$7!"F1$8B0@-$NHO0O$,O"B3$7$F(B2$B$D$"$k>l9g$K!"(B
$B0lJ}$NHO0O$r%-%k$7$F$+$i%d%s%/$7$FLa$7$?$H$7$^$9!#(B
$BJL$N>lLL$G$O5_$$$K$J$kF1$8B0@-$NHO0O$rM;9g$9$k5!G=$,!"(B
$B$3$3$G$O%H%i%V%k$r0z$-5/$3$7$^$9!#(B
$B$D$^$j!"%d%s%/$9$k$H(B1$B$D$NHO0O$K$J$C$F$7$^$$$^$9!#(B
$B$3$3$G$b!"JT=8$9$k$H!"(B1$B$D$NHO0O$H(B2$B$D$NHO0O$N6hJL$rJ]B8$G$-$J$/$J$j$^$9!#(B

@c   Insertion of text at the border between intervals also raises
@c questions that have no satisfactory answer.
2$B$D$NHO0O$N6-3&$K%F%-%9%H$rA^F~$9$k>l9g$G$b!"(B
$BK~B-$G$-$k2r7hJ}K!$,$J$$LdBj$rDs5/$7$^$9!#(B

@c   However, it is easy to arrange for editing to behave consistently for
@c questions of the form, ``What are the properties of this character?''
@c So we have decided these are the only questions that make sense; we have
@c not implemented asking questions about where intervals start or end.
$B$7$+$7!"!X$3$NJ8;z$NB0@-$O$J$K$+!Y$H$$$C$?7A$NLd$$$KBP$7$F(B
$B0l4S$7$?$U$k$^$$$r$9$k$h$&$JJT=8$K$9$k$N$O4JC1$G$9!#(B
$B$=$N$?$a$K!"$3$l$i$,M#0l$N0UL#$"$kLd$$$+$1$G$"$k$HH=CG$7$?$N$G$9!#(B
$BHO0O$N@hF,$HKvHx$rLd$&$h$&$J$b$N$O<BAu$7$F$"$j$^$;$s!#(B

@c   In practice, you can usually use the text property search functions in
@c place of explicit interval boundaries.  You can think of them as finding
@c the boundaries of intervals, assuming that intervals are always
@c coalesced whenever possible.  @xref{Property Search}.
$B<BMQ>e$O!"L@<(E*$JHO0O$N6-3&$N$+$o$j$K!"(B
$B%F%-%9%HB0@-$rC5:w$9$k4X?t$rIaDL$O;H$($^$9!#(B
$B$=$l$i$N4X?t$O!"2DG=$J>l9g$K$O$D$M$KHO0O$OM;9g$5$l$k$H2>Dj$7$F(B
$BHO0O$N6-3&$rC5$9$H9M$($k$3$H$,$G$-$^$9!#(B
@xref{Property Search}$B!#(B

@c   Emacs also provides explicit intervals as a presentation feature; see
@c @ref{Overlays}.
Emacs$B$K$OI=<(5!G=$H$7$FL@<(E*$JHO0O$b$"$j$^$9!#(B
@ref{Overlays}$B$r;2>H$7$F$/$@$5$$!#(B

@node Substitution
@c @section Substituting for a Character Code
@section $BJ8;z%3!<%I$NCV49(B

@c   The following functions replace characters within a specified region
@c based on their character codes.
$B$D$.$N4X?t$O!";XDj$7$?NN0hFb$NJ8;z$r$=$l$i$NJ8;z%3!<%I$K4p$E$$$FCV$-49$($^$9!#(B

@defun subst-char-in-region start end old-char new-char &optional noundo
@c @cindex replace characters
@cindex $BJ8;z$NCV49(B
@cindex $BCV49!"J8;z(B
@c This function replaces all occurrences of the character @var{old-char}
@c with the character @var{new-char} in the region of the current buffer
@c defined by @var{start} and @var{end}.
$B$3$N4X?t$O!"%+%l%s%H%P%C%U%!$N(B@var{start}$B$H(B@var{end}$B$GDj5A$5$l$kNN0h$N(B
$B$9$Y$F$NJ8;z(B@var{old-char}$B$rJ8;z(B@var{new-char}$B$KCV$-49$($k!#(B

@c @cindex Outline mode
@c @cindex undo avoidance
@cindex $B%"%&%H%i%$%s!J(Boutline$B!K%b!<%I(B
@cindex $B%"%s%I%%$NM^@)(B
@c If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
@c not record the change for undo and does not mark the buffer as modified.
@c This feature is used for controlling selective display (@pxref{Selective
@c Display}).
@var{noundo}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{subst-char-in-region}$B$O%"%s%I%%MQ$NJQ99$r5-O?$;$:!"(B
$B%P%C%U%!$KJQ99:Q$_$N0u$bIU$1$J$$!#(B
$B$3$N5!G=$O!"A*BrI=<(!J(B@pxref{Selective Display}$B!K$N@)8f$K;H$o$l$F$$$k!#(B

@c @code{subst-char-in-region} does not move point and returns
@c @code{nil}.
@code{subst-char-in-region}$B$O%]%$%s%H$r0\F0$;$:!"(B
@code{nil}$B$rJV$9!#(B

@example
@group
---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------
@end group

@group
(subst-char-in-region 1 20 ?i ?X)
     @result{} nil

---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------
@end group
@end example
@end defun

@defun translate-region start end table
@c This function applies a translation table to the characters in the
@c buffer between positions @var{start} and @var{end}.
$B$3$N4X?t$O!"%P%C%U%!$N(B@var{start}$B$H(B@var{end}$B$N$"$$$@$NJ8;z$KJQ49I=$rE,MQ$9$k!#(B

@c The translation table @var{table} is a string; @code{(aref @var{table}
@c @var{ochar})} gives the translated character corresponding to
@c @var{ochar}.  If the length of @var{table} is less than 256, any
@c characters with codes larger than the length of @var{table} are not
@c altered by the translation.
$BJQ49I=(B@var{table}$B$OJ8;zNs$G$"$j!"(B
@code{(aref @var{table} @var{ochar})}$B$O!"(B
@var{ochar}$B$KBP1~$9$kJQ49$7$?J8;z$rM?$($k!#(B
@var{table}$B$ND9$5$,(B256$BL$K~$G$"$k$H!"(B
@var{table}$B$ND9$5$h$jBg$-$J%3!<%I$NJ8;z$OJQ49$K$h$C$F$OJQ99$5$l$J$$!#(B

@c The return value of @code{translate-region} is the number of
@c characters that were actually changed by the translation.  This does
@c not count characters that were mapped into themselves in the
@c translation table.
@code{translate-region}$B$NLa$jCM$O!"(B
$BJQ49$K$h$C$F<B:]$KJQ99$7$?J8;z$N8D?t$rJV$9!#(B
$B$3$l$K$O!"JQ49I=$G<+J,<+?H$KJQ49$5$l$?J8;z$O?t$($J$$!#(B
@end defun

@node Registers
@c @section Registers
@section $B%l%8%9%?(B
@c @cindex registers
@cindex $B%l%8%9%?(B

@c   A register is a sort of variable used in Emacs editing that can hold a
@c variety of different kinds of values.  Each register is named by a
@c single character.  All ASCII characters and their meta variants (but
@c with the exception of @kbd{C-g}) can be used to name registers.  Thus,
@c there are 255 possible registers.  A register is designated in Emacs
@c Lisp by the character that is its name.
$B%l%8%9%?$O!"(BEmacs$B$NJT=8$K$*$$$F$5$^$6$^$J<oN`$NCM$rJ];}$G$-$kJQ?t$N0l<o$G$9!#(B
$B3F%l%8%9%?$K$O(B1$BJ8;z$NL>A0$,IU$$$F$$$^$9!#(B
$B$9$Y$F$N(BASCII$BJ8;z$H$=$l$i$N%a%?JQ<o!J$?$@$7(B@kbd{C-g}$B$r=|$/!K$r(B
$B%l%8%9%?$NL>A0$K;H$($^$9!#(B
$B$7$?$,$C$F!"(B255$B8D$N%l%8%9%?$r;H$($^$9!#(B
Emacs Lisp$B$G$O!"%l%8%9%?L>$G%l%8%9%?$r6hJL$7$^$9!#(B

@defvar register-alist
@c This variable is an alist of elements of the form @code{(@var{name} .
@c @var{contents})}.  Normally, there is one element for each Emacs
@c register that has been used.
$B$3$NJQ?t$O!"(B@code{(@var{name} . @var{contents})}$B$N7A$NMWAG$NO"A[%j%9%H$G$"$k!#(B
$BDL>o!";HMQCf$N(BEmacs$B$N3F%l%8%9%?$KBP$7$F(B1$B$D$NMWAG$,$"$k!#(B

@c The object @var{name} is a character (an integer) identifying the
@c register.
$B%*%V%8%'%/%H(B@var{name}$B$O!"%l%8%9%?$r<1JL$9$kJ8;z!J@0?t!K$G$"$k!#(B
@end defvar

@c   The @var{contents} of a register can have several possible types:
$B%l%8%9%?$NFbMF!J(B@var{contents}$B!K$K2DG=$J7?$O$$$/$D$+$"$j$^$9!#(B

@table @asis
@c @item a number
@item $B?t(B
@c A number stands for itself.  If @code{insert-register} finds a number
@c in the register, it converts the number to decimal.
$B?t$=$N$b$N$rI=$9!#(B
@code{insert-register}$B$,%l%8%9%?Fb$G?t$r$_$D$1$k$H(B10$B?J?t$KJQ49$9$k!#(B

@c @item a marker
@item $B%^!<%+(B
@c A marker represents a buffer position to jump to.
$B%^!<%+$O%8%c%s%W@h$N%P%C%U%!Fb0LCV$rI=$9!#(B

@c @item a string
@item $BJ8;zNs(B
@c A string is text saved in the register.
$BJ8;zNs$O%l%8%9%?$KJ]B8$5$l$?%F%-%9%H$G$"$k!#(B

@c @item a rectangle
@item $B6k7ANN0h(B
@c A rectangle is represented by a list of strings.
$B6k7ANN0h$OJ8;zNs$N%j%9%H$GI=8=$5$l$k!#(B

@item @code{(@var{window-configuration} @var{position})}
@c This represents a window configuration to restore in one frame, and a
@c position to jump to in the current buffer.
$B$3$l$O!"(B1$B$D$N%U%l!<%`$KI|85$9$k%&%#%s%I%&9=@.$H(B
$B%+%l%s%H%P%C%U%!$G$N%]%$%s%H$N0\F0@h$rI=$9!#(B

@item @code{(@var{frame-configuration} @var{position})}
@c This represents a frame configuration to restore, and a position
@c to jump to in the current buffer.
$B$3$l$O!"I|85$9$k%U%l!<%`9=@.$H%+%l%s%H%P%C%U%!$G$N%]%$%s%H$N0\F0@h$rI=$9!#(B

@item (file @var{filename})
@c This represents a file to visit; jumping to this value visits file
@c @var{filename}.
$BK,Ld$9$Y$-%U%!%$%k$rI=$9!#(B
$B$3$NCM$K%8%c%s%W$9$k$H%U%!%$%k(B@var{filename}$B$rK,Ld$9$k!#(B

@item (file-query @var{filename} @var{position})
@c This represents a file to visit and a position in it; jumping to this
@c value visits file @var{filename} and goes to buffer position
@c @var{position}.  Restoring this type of position asks the user for
@c confirmation first.
$B$3$l$O!"K,Ld$9$Y$-%U%!%$%k$H$=$NCf$G$N0LCV$rI=$9!#(B
$B$3$NCM$K%8%c%s%W$9$k$H%U%!%$%k(B@var{filename}$B$rK,Ld$7(B
$B%P%C%U%!Fb0LCV(B@var{position}$B$X0\F0$9$k!#(B
$B$3$N<o$N0LCV$rI|85$9$k$H!"$^$:%f!<%6!<$K3NG'$r<h$k!#(B
@end table

@c   The functions in this section return unpredictable values unless
@c otherwise stated.
$BK\@a$N4X?t$O!"L@5-$7$F$J$$>l9g$K$OM=B,$G$-$J$$CM$rJV$7$^$9!#(B

@defun get-register reg
@c This function returns the contents of the register
@c @var{reg}, or @code{nil} if it has no contents.
$B$3$N4X?t$O!"%l%8%9%?(B@var{reg}$B$NFbMF!"(B
$B$"$k$$$O!"FbMF$,$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@defun set-register reg value
@c This function sets the contents of register @var{reg} to @var{value}.
@c A register can be set to any value, but the other register functions
@c expect only certain data types.  The return value is @var{value}.
$B$3$N4X?t$O!"%l%8%9%?(B@var{reg}$B$NFbMF$r(B@var{value}$B$H$9$k!#(B
$B%l%8%9%?$K$OG$0U$NCM$r@_Dj$G$-$k$,!"B>$N%l%8%9%?4X?t$O(B
$BFCDj$N%G!<%?7?$r4|BT$9$k!#(B
$BLa$jCM$O(B@var{value}$B$G$"$k!#(B
@end defun

@c @deffn Command view-register reg
@deffn $B%3%^%s%I(B view-register reg
@c This command displays what is contained in register @var{reg}.
$B$3$N%3%^%s%I$O!"%l%8%9%?(B@var{reg}$B$K$J$K$,F~$C$F$$$k$+$rI=<($9$k!#(B
@end deffn

@ignore
@deffn Command point-to-register reg
This command stores both the current location of point and the current
buffer in register @var{reg} as a marker.
@end deffn

@deffn Command jump-to-register reg
@deffnx Command register-to-point reg
@comment !!SourceFile register.el
This command restores the status recorded in register @var{reg}.

If @var{reg} contains a marker, it moves point to the position stored in
the marker.  Since both the buffer and the location within the buffer
are stored by the @code{point-to-register} function, this command can
switch you to another buffer.

If @var{reg} contains a window configuration or a frame configuration.
@code{jump-to-register} restores that configuration.
@end deffn
@end ignore

@c @deffn Command insert-register reg &optional beforep
@deffn $B%3%^%s%I(B insert-register reg &optional beforep
@c This command inserts contents of register @var{reg} into the current
@c buffer.
$B$3$N%3%^%s%I$O%l%8%9%?(B@var{reg}$B$NFbMF$r%+%l%s%H%P%C%U%!$KA^F~$9$k!#(B

@c Normally, this command puts point before the inserted text, and the
@c mark after it.  However, if the optional second argument @var{beforep}
@c is non-@code{nil}, it puts the mark before and point after.
@c You can pass a non-@code{nil} second argument @var{beforep} to this
@c function interactively by supplying any prefix argument.
$BDL>o!"$3$N%3%^%s%I$OA^F~$7$?%F%-%9%H$N$^$($K%]%$%s%H$rCV$-!"(B
$B$=$N$"$H$K%^!<%/$rCV$/!#(B
$B$7$+$7!">JN,2DG=$J(B2$BHVL\$N0z?t(B@var{beforep}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
$B$^$($K%^!<%/$rCV$-$"$H$K%]%$%s%H$rCV$/!#(B
$B$3$N4X?t$rBPOCE*$K8F$S=P$9$H$-$KA0CV0z?t$r;XDj$9$l$P!"(B
2$BHVL\$N0z?t(B@var{beforep}$B$K(B@code{nil}$B0J30$rEO$;$k!#(B

@c If the register contains a rectangle, then the rectangle is inserted
@c with its upper left corner at point.  This means that text is inserted
@c in the current line and underneath it on successive lines.
$B%l%8%9%?$K6k7ANN0h$,4^$^$l$k>l9g!"(B
$B%]%$%s%H0LCV$K6k7ANN0h$N:8>e6y$,$/$k$h$&$KA^F~$5$l$k!#(B
$B$D$^$j!"%F%-%9%H$O8=:_9T$H$=$N$7$?$NO"B3$9$k9T$KA^F~$5$l$k!#(B

@c If the register contains something other than saved text (a string) or
@c a rectangle (a list), currently useless things happen.  This may be
@c changed in the future.
$BJ]B8$7$?%F%-%9%H!JJ8;zNs!K$d6k7ANN0h!J%j%9%H!K0J30$,%l%8%9%?$KF~$C$F$$$k$H!"(B
$B8=>u$G$OM-MQ$J$3$H$O5/$3$i$J$$!#(B
$B>-Mh$3$l$OJQ99$5$l$k$G$"$m$&!#(B
@end deffn

@ignore
@deffn Command copy-to-register reg start end &optional delete-flag
This command copies the region from @var{start} to @var{end} into
register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
the region from the buffer after copying it into the register.
@end deffn

@deffn Command prepend-to-register reg start end &optional delete-flag
This command prepends the region from @var{start} to @var{end} into
register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
the region from the buffer after copying it to the register.
@end deffn

@deffn Command append-to-register reg start end &optional delete-flag
This command appends the region from @var{start} to @var{end} to the
text already in register @var{reg}.  If @var{delete-flag} is
non-@code{nil}, it deletes the region from the buffer after copying it
to the register.
@end deffn

@deffn Command copy-rectangle-to-register reg start end &optional delete-flag
This command copies a rectangular region from @var{start} to @var{end}
into register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it
deletes the region from the buffer after copying it to the register.
@end deffn

@deffn Command window-configuration-to-register reg
This function stores the window configuration of the selected frame in
register @var{reg}.
@end deffn

@deffn Command frame-configuration-to-register reg
This function stores the current frame configuration in register
@var{reg}.
@end deffn
@end ignore

@node Transposition
@c @section Transposition of Text
@section $B%F%-%9%H$NE>CV(B

@c   This subroutine is used by the transposition commands.
$B$D$.$N%5%V%k!<%F%#%s$OE>CV%3%^%s%I$G;H$o$l$^$9!#(B

@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
@c This function exchanges two nonoverlapping portions of the buffer.
@c Arguments @var{start1} and @var{end1} specify the bounds of one portion
@c and arguments @var{start2} and @var{end2} specify the bounds of the
@c other portion.
$B$3$N4X?t$O!"%P%C%U%!$N=E$J$j9g$o$J$$(B2$B$D$NItJ,$rF~$l49$($k!#(B
$B0z?t(B@var{start1}$B$H(B@var{end1}$B$G0lJ}$NItJ,$N6-3&$r;XDj$7!"(B
$B0z?t(B@var{start2}$B$H(B@var{end2}$B$GB>J}$NItJ,$N6-3&$r;XDj$9$k!#(B

@c Normally, @code{transpose-regions} relocates markers with the transposed
@c text; a marker previously positioned within one of the two transposed
@c portions moves along with that portion, thus remaining between the same
@c two characters in their new position.  However, if @var{leave-markers}
@c is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
@c all markers unrelocated.
$BDL>o!"(B@code{transpose-regions}$B$OE>CV$7$?%F%-%9%HFb$N%^!<%+$r:FG[CV$9$k!#(B
$B$D$^$j!"(B2$B$D$NE>CVItJ,$N0lJ}$NFbB&$r;X$7$F$$$?%^!<%+$O(B
$B$=$NItJ,$H$H$b$K0\F0$7$F!"?7$7$$0LCV$GF1$8(B2$B$D$NJ8;z$N$"$$$@$KN1$^$k!#(B
$B$7$+$7!"(B@var{leave-markers}$B$,(B@code{nil}$B0J30$G$"$k$H!"(B
@code{transpose-regions}$B$O$3$l$r9T$o$:!"(B
$B$9$Y$F$N%^!<%+$O:FG[CV$5$l$J$$!#(B
@end defun

@node Change Hooks
@c @section Change Hooks
@section $BJQ99%U%C%/(B
@c @cindex change hooks
@c @cindex hooks for text changes
@cindex $BJQ99%U%C%/(B
@cindex $B%F%-%9%HJQ998~$1$N%U%C%/(B

@c   These hook variables let you arrange to take notice of all changes in
@c all buffers (or in a particular buffer, if you make them buffer-local).
@c See also @ref{Special Properties}, for how to detect changes to specific
@c parts of the text.
$B$3$l$i$N%U%C%/$K$h$j!"$9$Y$F$N%P%C%U%!(B
$B!J$=$l$i$r%P%C%U%!%m!<%+%k$K$7$F$*$1$PFCDj$N%P%C%U%!!K$K$*$1$k(B
$B$9$Y$F$NJQ99$rCN$k$h$&$K$G$-$^$9!#(B
$B%F%-%9%H$NFCDjItJ,$NJQ99$r8!=P$9$kJ}K!$K$D$$$F$O!"(B
@ref{Special Properties}$B$b;2>H$7$F$/$@$5$$!#(B

@c   The functions you use in these hooks should save and restore the match
@c data if they do anything that uses regular expressions; otherwise, they
@c will interfere in bizarre ways with the editing operations that call
@c them.
$B$3$l$i$N%U%C%/$K;H$&4X?t$K$*$$$F@55,I=8=$r;H$&>l9g$K$O!"(B
$B%^%C%A%G!<%?$rJ]B8$7I|85$9$kI,MW$,$"$j$^$9!#(B
$B$5$b$J$$$H!"$=$l$i$r8F$S=P$9JT=8A`:n$H4qL/$J43>D$r0z$-5/$3$7$^$9!#(B

@defvar before-change-functions
@c This variable holds a list of functions to call before any buffer
@c modification.  Each function gets two arguments, the beginning and end
@c of the region that is about to change, represented as integers.  The
@c buffer that is about to change is always the current buffer.
$B$3$NJQ?t$O!"%P%C%U%!$rJQ99$9$k$^$($K8F$S=P$9$Y$-4X?t$N%j%9%H$rJ];}$9$k!#(B
$B3F4X?t$O(B2$B$D$N0z?t!"$D$^$j!"@0?t$GI=$7$?JQ99BP>]$NNN0h$N@hF,$HKvHx$r<u$1<h$k!#(B
$BJQ99BP>]$N%P%C%U%!$O$D$M$K%+%l%s%H%P%C%U%!$G$"$k!#(B
@end defvar

@defvar after-change-functions
@c This variable holds a list of functions to call after any buffer
@c modification.  Each function receives three arguments: the beginning and
@c end of the region just changed, and the length of the text that existed
@c before the change.  All three arguments are integers.  The buffer that's
@c about to change is always the current buffer.
$B$3$NJQ?t$O!"%P%C%U%!$rJQ99$7$?$"$H$K8F$S=P$9$Y$-4X?t$N%j%9%H$rJ];}$9$k!#(B
$B3F4X?t$O(B3$B$D$N0z?t!"$D$^$j!"JQ99$5$l$?$P$+$j$NNN0h$N@hF,$HKvHx!"(B
$BJQ99A0$KB8:_$7$F$$$?%F%-%9%H$ND9$5$r<u$1<h$k!#(B
3$B$D$N0z?t$O$9$Y$F@0?t$G$"$k!#(B
$BJQ99BP>]$N%P%C%U%!$O$D$M$K%+%l%s%H%P%C%U%!$G$"$k!#(B

@c The length of the old text is the difference between the buffer positions
@c before and after that text as it was before the change.  As for the
@c changed text, its length is simply the difference between the first two
@c arguments.
$B8E$$%F%-%9%H$ND9$5$O!"JQ99A0$N$=$N%F%-%9%H$N@hF,$HKvHx$N(B
$B%P%C%U%!Fb0LCV$N:9$G$"$k!#(B
$BJQ99:Q$_$N%F%-%9%H$ND9$5$O!"C1=c$K;O$a$N(B2$B$D$N0z?t$N:9$G$"$k!#(B
@end defvar

@defmac combine-after-change-calls body...
@tindex combine-after-change-calls
@c The macro executes @var{body} normally, but arranges to call the
@c after-change functions just once for a series of several changes---if
@c that seems safe.
$B$3$N%^%/%m$ODL>o$I$*$j(B@var{body}$B$r<B9T$9$k$,!"(B
$B0lO"$NJQ99$KBP$7$F0BA4$H;W$($k$H$-$K$O!"(B
@code{after-change-functions}$B$N4X?t$r0lEY$@$18F$S=P$9!#(B

@c If a program makes several text changes in the same area of the buffer,
@c using the macro @code{combine-after-change-calls} around that part of
@c the program can make it run considerably faster when after-change hooks
@c are in use.  When the after-change hooks are ultimately called, the
@c arguments specify a portion of the buffer including all of the changes
@c made within the @code{combine-after-change-calls} body.
$B%W%m%0%i%`$+$i%P%C%U%!$NF1$8ItJ,$G%F%-%9%HJQ99$rJ#?t2s9T$&>l9g!"(B
$B%W%m%0%i%`$NEv3:ItJ,$N<~$j$G%^%/%m(B@code{combine-after-change-calls}$B$r;H$&$H!"(B
$B%U%C%/(B@code{after-change-functions}$B$r;HMQ$7$F$k$H$-$K$O(B
$BF0:n$,$+$J$jB.$/$J$j$&$k!#(B
$B:G=*E*$K%U%C%/(B@code{after-change-functions}$B$,8F$P$l$k$H!"(B
@code{combine-after-change-calls}$B$NK\BN$G9T$C$?JQ99$9$Y$F$r4^$`$h$&$J(B
$B%P%C%U%!ItJ,$,0z?t$K;XDj$5$l$k!#(B

@c @strong{Warning:} You must not alter the values of
@c @code{after-change-functions} and @code{after-change-function} within
@c the body of a @code{combine-after-change-calls} form.
@strong{$B7Y9p!'(B}@code{ }
$B%U%)!<%`(B@code{combine-after-change-calls}$B$NK\BN$NFbB&$G$O(B
@code{after-change-functions}$B$H(B@code{after-change-function}$B$NCM$r(B
$BJQ99$7$J$$$3$H!#(B

@c @strong{Note:} If the changes you combine occur in widely scattered
@c parts of the buffer, this will still work, but it is not advisable,
@c because it may lead to inefficient behavior for some change hook
@c functions.
@strong{$BCm0U!'(B}@code{ }
$BJQ99$,%P%C%U%!$N9-$/J,;6$7$?ItJ,$K9T$o$l$k$H$-$K$b$3$l$OF0:n$9$k$,!"(B
$B?d>)$G$-$J$$!#(B
$BHs8zN($J$U$k$^$$$r$9$k$h$&$J%U%C%/4X?t$,$"$k$+$i$G$"$k!#(B
@end defmac

@defvar before-change-function
@c This obsolete variable holds one function to call before any buffer
@c modification (or @code{nil} for no function).  It is called just like
@c the functions in @code{before-change-functions}.
$B$3$NGQ$l$?JQ?t$O!"G$0U$N%P%C%U%!$NJQ99$r9T$&$^$($K(B
$B8F$P$l$k(B1$B$D$N4X?t$rJ];}$9$k(B
$B!J(B@code{nil}$B$J$i$P$=$N$h$&$J4X?t$O$J$7!K!#(B
@code{before-change-functions}$B$N4X?t$HF1MM$K8F$P$l$k!#(B
@end defvar

@defvar after-change-function
@c This obsolete variable holds one function to call after any buffer modification
@c (or @code{nil} for no function).  It is called just like the functions in
@c @code{after-change-functions}.
$B$3$NGQ$l$?JQ?t$O!"G$0U$N%P%C%U%!$NJQ99$r9T$C$?$"$H$K(B
$B8F$P$l$k(B1$B$D$N4X?t$rJ];}$9$k(B
$B!J(B@code{nil}$B$J$i$P$=$N$h$&$J4X?t$O$J$7!K!#(B
@code{after-change-functions}$B$N4X?t$HF1MM$K8F$P$l$k!#(B
@end defvar

@c The four variables above are temporarily bound to @code{nil} during the
@c time that any of these functions is running.  This means that if one of
@c these functions changes the buffer, that change won't run these
@c functions.  If you do want a hook function to make changes that run
@c these functions, make it bind these variables back to their usual
@c values.
$B>e$N(B4$B$D$NJQ?t$O!"$3$l$i$N4X?t$,<B9TCf$K$O0l;~E*$K(B@code{nil}$B$KB+G{$5$l$^$9!#(B
$B$D$^$j!"$3$l$i$N4X?t$N(B1$B$D$,%P%C%U%!$rJQ99$7$F$b!"(B
$B$=$NJQ99$G$O$3$l$i$N4X?t$r8F$S=P$7$^$;$s!#(B
$B%U%C%/4X?t$K$*$$$F$3$l$i$N4X?t$r<B9T$9$k$h$&$JJQ99$r9T$$$?$$>l9g$K$O!"(B
$B%U%C%/4X?t$G$3$l$i$NJQ?t$r$=$l$i$NDL>o$NCM$KB+G{$7D>$7$^$9!#(B

@c One inconvenient result of this protective feature is that you cannot
@c have a function in @code{after-change-functions} or
@c @code{before-change-functions} which changes the value of that variable.
@c But that's not a real limitation.  If you want those functions to change
@c the list of functions to run, simply add one fixed function to the hook,
@c and code that function to look in another variable for other functions
@c to call.  Here is an example:
$B$3$NJ]8nE*$J5!9=$N(B1$B$D$NITJX$J5"7k$O!"(B
@code{after-change-functions}$B$d(B@code{before-change-functions}$B$K$O!"(B
$B$=$NJQ?t$NCM$rJQ99$9$k4X?t$r;}$F$J$$$3$H$G$9!#(B
$B$7$+$7!"$3$l$OK\Ev$N@)8B$G$O$"$j$^$;$s!#(B
$B$=$l$i$N4X?t$G<B9T$9$Y$-4X?t$N%j%9%H$rJQ99$7$?$1$l$P!"(B
$BC1=c$K(B1$B$D$NDj$^$C$?4X?t$r%U%C%/$KDI2C$7!"(B
$B$=$N4X?t$G$O8F$S=P$9$Y$-JL$N4X?t$r;XDj$9$kJL$NJQ?t$rD4$Y$^$9!#(B
$B$D$.$N$h$&$K$7$^$9!#(B

@example
(setq my-own-after-change-functions nil)
(defun indirect-after-change-function (beg end len)
  (let ((list my-own-after-change-functions))
    (while list
      (funcall (car list) beg end len)
      (setq list (cdr list)))))

@group
(add-hooks 'after-change-functions
           'indirect-after-change-function)
@end group
@end example

@defvar first-change-hook
@c This variable is a normal hook that is run whenever a buffer is changed
@c that was previously in the unmodified state.
$B$3$NJQ?t$O!"L$JQ99>uBV$N%P%C%U%!$rJQ99$9$k$?$S$K<B9T$5$l$k(B
$B%N!<%^%k%U%C%/$G$"$k!#(B
@end defvar