   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Indentation Controlled by Major Mode
------------------------------------

   An important function of each major mode is to customize the TAB key
to indent properly for the language being edited.  This section
describes the mechanism of the TAB key and how to control it.  The
functions in this section return unpredictable values.

 - Variable: indent-line-function
     This variable's value is the function to be used by TAB (and
     various commands) to indent the current line.  The command
     `indent-according-to-mode' does no more than call this function.

     In Lisp mode, the value is the symbol `lisp-indent-line'; in C
     mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'.  In
     Fundamental mode, Text mode, and many other modes with no standard
     for indentation, the value is `indent-to-left-margin' (which is the
     default value).

 - Command: indent-according-to-mode
     This command calls the function in `indent-line-function' to
     indent the current line in a way appropriate for the current major
     mode.

 - Command: indent-for-tab-command
     This command calls the function in `indent-line-function' to
     indent the current line, except that if that function is
     `indent-to-left-margin', `insert-tab' is called instead.  (That is
     a trivial command which inserts a tab character.)

 - Variable: left-margin
     This variable is the column to which the default
     `indent-line-function' will indent.  (That function is
     `indent-to-left-margin'.)  In Fundamental mode, LFD indents to
     this column.  This variable automatically becomes buffer-local when
     set in any fashion.

 - Function: indent-to-left-margin
     This is the default `indent-line-function', used in Fundamental
     mode, Text mode, etc.  Its effect is to adjust the indentation at
     the beginning of the current line to the value specified by the
     variable `left-margin'.  This may involve either inserting or
     deleting whitespace.

 - Command: newline-and-indent
     This function inserts a newline, then indents the new line (the one
     following the newline just inserted) according to the major mode.

     Indentation is done using the current `indent-line-function'.  In
     programming language modes, this is the same thing TAB does, but
     in some text modes, where TAB inserts a tab, `newline-and-indent'
     indents to the column specified by `left-margin'.

 - Command: reindent-then-newline-and-indent
     This command reindents the current line, inserts a newline at
     point, and then reindents the new line (the one following the
     newline just inserted).

     Indentation of both lines is done according to the current major
     mode; this means that the current value of `indent-line-function'
     is called.  In programming language modes, this is the same thing
     TAB does, but in some text modes, where TAB inserts a tab,
     `reindent-then-newline-and-indent' indents to the column specified
     by `left-margin'.

Indenting an Entire Region
--------------------------

   This section describes commands which indent all the lines in the
region.  They return unpredictable values.

 - Command: indent-region START END TO-COLUMN
     This command indents each nonblank line starting between START
     (inclusive) and END (exclusive).  If TO-COLUMN is `nil',
     `indent-region' indents each nonblank line by calling the current
     mode's indentation function, the value of `indent-line-function'.

     If TO-COLUMN is non-`nil', it should be an integer specifying the
     number of columns of indentation; then this function gives each
     line exactly that much indentation, by either adding or deleting
     whitespace.

     If there is a fill prefix, `indent-region' indents each line by
     making it start with the fill prefix.

 - Variable: indent-region-function
     The value of this variable is a function that can be used by
     `indent-region' as a short cut.  You should design the function so
     that it will produce the same results as indenting the lines of the
     region one by one (but presumably faster).

     If the value is `nil', there is no short cut, and `indent-region'
     actually works line by line.

     A short cut function is useful in modes such as C mode and Lisp
     mode, where the `indent-line-function' must scan from the
     beginning of the function: applying it to each line would be
     quadratic in time.  The short cut can update the scan information
     as it moves through the lines indenting them; this takes linear
     time.  If indenting a line individually is fast, there is no need
     for a short cut.

     `indent-region' with a non-`nil' argument has a different
     definition and does not use this variable.

 - Command: indent-rigidly START END COUNT
     This command indents all lines starting between START (inclusive)
     and END (exclusive) sideways by `count' columns.  This "preserves
     the shape" of the affected region, moving it as a rigid unit.
     Consequently, this command is useful not only for indenting
     regions of unindented text, but also for indenting regions of
     formatted code.

     For example, if COUNT is 3, this command adds 3 columns of
     indentation to each of the lines beginning in the region specified.

     In Mail mode, `C-c C-y' (`mail-yank-original') uses
     `indent-rigidly' to indent the text copied from the message being
     replied to.

 - Function: indent-code-rigidly START END COLUMNS &optional
          NOCHANGE-REGEXP
     This is like `indent-rigidly', except that it doesn't alter lines
     that start within strings or comments.

     In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
     the beginning of the line (if NOCHANGE-REGEXP is non-`nil').

Indentation Relative to Previous Lines
--------------------------------------

   This section describes two commands which indent the current line
based on the contents of previous lines.

 - Command: indent-relative &optional UNINDENTED-OK
     This function inserts whitespace at point, extending to the same
     column as the next "indent point" of the previous nonblank line.
     An indent point is a non-whitespace character following
     whitespace.  The next indent point is the first one at a column
     greater than the current column of point.  For example, if point
     is underneath and to the left of the first non-blank character of
     a line of text, it moves to that column by inserting whitespace.

     If the previous nonblank line has no next indent point (i.e., none
     at a great enough column position), this function either does
     nothing (if UNINDENTED-OK is non-`nil') or calls `tab-to-tab-stop'.
     Thus, if point is underneath and to the right of the last column
     of a short line of text, this function moves point to the next tab
     stop by inserting whitespace.

     This command returns an unpredictable value.

     In the following example, point is at the beginning of the second
     line:

                      This line is indented twelve spaces.
          -!-The quick brown fox jumped.

     Evaluation of the expression `(indent-relative nil)' produces the
     following:

                      This line is indented twelve spaces.
                      -!-The quick brown fox jumped.

     In this example, point is between the `m' and `p' of `jumped':

                      This line is indented twelve spaces.
          The quick brown fox jum-!-ped.

     Evaluation of the expression `(indent-relative nil)' produces the
     following:

                      This line is indented twelve spaces.
          The quick brown fox jum  -!-ped.

 - Command: indent-relative-maybe
     This command indents the current line like the previous nonblank
     line.  The function consists of a call to `indent-relative' with a
     non-`nil' value passed to the UNINDENTED-OK optional argument.
     The value is unpredictable.

     If the previous line has no indentation, the current line is given
     no indentation (any existing indentation is deleted); if the
     previous nonblank line has no indent points beyond the column at
     which point starts, nothing is changed.

Adjustable "Tab Stops"
----------------------

   This section explains the mechanism for user-specified "tab stops"
and the mechanisms which use and set them.  The name "tab stops" is
used because the feature is similar to that of the tab stops on a
typewriter.  The feature works by inserting an appropriate number of
spaces and tab characters to reach the designated position, like the
other indentation functions; it does not affect the display of tab
characters in the buffer (see Usual Display.).  Note that the TAB
character as input uses this tab stop feature only in a few major
modes, such as Text mode.

 - Function: tab-to-tab-stop
     This function inserts spaces or tabs up to the next tab stop column
     defined by `tab-stop-list'.  It searches the list for an element
     greater than the current column number, and uses that element as
     the column to indent to.  If no such element is found, then
     nothing is done.

 - User Option: tab-stop-list
     This variable is the list of tab stop columns used by
     `tab-to-tab-stops'.  The elements should be integers in increasing
     order.  The tab stop columns need not be evenly spaced.

     Use `M-x edit-tab-stops' to edit the location of tab stops
     interactively.

Indentation-Based Motion Commands
---------------------------------

   These commands, primarily for interactive use, act based on the
indentation in the text.

 - Command: back-to-indentation
     This command moves point to the first non-whitespace character in
     the current line (which is the line in which point is located).
     It returns `nil'.

 - Command: backward-to-indentation ARG
     This command moves point backward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.

 - Command: forward-to-indentation ARG
     This command moves point forward ARG lines and then to the first
     nonblank character on that line.  It returns `nil'.

Counting Columns
================

   The column functions convert between a character position (counting
characters from the beginning of the buffer) and a column position
(counting screen characters from the beginning of a line).

   Column number computations ignore the width of the window and the
amount of horizontal scrolling.  Consequently, a column value can be
arbitrarily high.  The first (or leftmost) column is numbered 0.

   A character counts according to the number of columns it occupies on
the screen.  This means control characters count as occupying 2 or 4
columns, depending upon the value of `ctl-arrow', and tabs count as
occupying a number of columns that depends on the value of `tab-width'
and on the column where the tab begins.  See Usual Display.

 - Function: current-column
     This function returns the horizontal position of point, measured in
     columns, counting from 0 at the left margin.  The column count is
     calculated by adding together the widths of all the displayed
     representations of the characters between the start of the current
     line and point.

     For a more complicated example of the use of `current-column', see
     the description of `count-lines' in Text Lines.

 - Function: move-to-column COLUMN &optional FORCE
     This function moves point to COLUMN in the current line.  The
     calculation of COLUMN takes into account the widths of all the
     displayed representations of the characters between the start of
     the line and point.

     If the argument COLUMN is greater than the column position of the
     end of the line, point moves to the end of the line.  If COLUMN is
     negative, point moves to the beginning of the line.

     If it is impossible to move to column COLUMN because that is in
     the middle of a multicolumn character such as a tab, point moves
     to the end of that character.  However, if FORCE is non-`nil', and
     COLUMN is in the middle of a tab, then `move-to-column' converts
     the tab into spaces so that it can move precisely to column COLUMN.

     The argument FORCE also has an effect if the line isn't long
     enough to reach column COLUMN; in that case, it says to indent at
     the end of the line to reach that column.

     If COLUMN is not an integer, an error is signaled.

     The return value is the column number actually moved to.

Case Changes
============

   The case change commands described here work on text in the current
buffer.  See Character Case, for case conversion commands that work
on strings and characters.  See Case Table, for how to customize
which characters are upper or lower case and how to convert them.

 - Command: capitalize-region START END
     This function capitalizes all words in the region defined by START
     and END.  To capitalize means to convert each word's first
     character to upper case and convert the rest of each word to lower
     case.  The function returns `nil'.

     If one end of the region is in the middle of a word, the part of
     the word within the region is treated as an entire word.

     When `capitalize-region' is called interactively, START and END
     are point and the mark, with the smallest first.

          ---------- Buffer: foo ----------
          This is the contents of the 5th foo.
          ---------- Buffer: foo ----------

          (capitalize-region 1 44)
          => nil

          ---------- Buffer: foo ----------
          This Is The Contents Of The 5th Foo.
          ---------- Buffer: foo ----------

 - Command: downcase-region START END
     This function converts all of the letters in the region defined by
     START and END to lower case.  The function returns `nil'.

     When `downcase-region' is called interactively, START and END are
     point and the mark, with the smallest first.

 - Command: upcase-region START END
     This function converts all of the letters in the region defined by
     START and END to upper case.  The function returns `nil'.

     When `upcase-region' is called interactively, START and END are
     point and the mark, with the smallest first.

 - Command: capitalize-word COUNT
     This function capitalizes COUNT words after point, moving point
     over as it does.  To capitalize means to convert each word's first
     character to upper case and convert the rest of each word to lower
     case.  If COUNT is negative, the function capitalizes the -COUNT
     previous words but does not move point.  The value is `nil'.

     If point is in the middle of a word, the part of word the before
     point (if moving forward) or after point (if operating backward)
     is ignored.  The rest is treated as an entire word.

     When `capitalize-word' is called interactively, COUNT is set to
     the numeric prefix argument.

 - Command: downcase-word COUNT
     This function converts the COUNT words after point to all lower
     case, moving point over as it does.  If COUNT is negative, it
     converts the -COUNT previous words but does not move point.  The
     value is `nil'.

     When `downcase-word' is called interactively, COUNT is set to the
     numeric prefix argument.

 - Command: upcase-word COUNT
     This function converts the COUNT words after point to all upper
     case, moving point over as it does.  If COUNT is negative, it
     converts the -COUNT previous words but does not move point.  The
     value is `nil'.

     When `upcase-word' is called interactively, COUNT is set to the
     numeric prefix argument.

Text Properties
===============

   Text properties in Lucid Emacs are provided for compatibility with
FSF Emacs 19.  Text properties are implemented using extents, which
provide a more powerful functionality.  See Extents.

   Each character position in a buffer or a string can have a "text
property list", much like the property list of a symbol.  The properties
belong to a particular character at a particular place, such as, the
letter `T' at the beginning of this sentence or the first `o' in
`foo'--if the same character occurs in two different places, the two
occurrences generally have different properties.

   Each property has a name, which is usually a symbol, and an
associated value, which can be any Lisp object--just as for properties
of symbols (see Property Lists.).

   If a character has a `category' property, we call it the "category"
of the character.  It should be a symbol.  The properties of the symbol
serve as defaults for the properties of the character.

   Copying text between strings and buffers preserves the properties
along with the characters; this includes such diverse functions as
`substring', `insert', and `buffer-substring'.

Examining Text Properties
-------------------------

   The simplest way to examine text properties is to ask for the value
of a particular property of a particular character.  For that, use
`get-text-property'.  Use `text-properties-at' to get the entire
property list of a character.  See Property Search, for functions
to examine the properties of a number of characters at once.

   Under FSF Emacs, these functions handle both strings and buffers.
(Keep in mind that positions in a string start from 0, whereas positions
in a buffer start from 1.) Under Lucid Emacs, these functions currently
only handle buffers.  This may change in the future.

 - Function: get-text-property POS PROP &optional OBJECT
     This function returns the value of the PROP property of the
     character after position POS in OBJECT (a buffer).  The argument
     OBJECT is optional and defaults to the current buffer.

     If there is no PROP property strictly speaking, but the character
     has a category which is a symbol, then `get-text-property' returns
     the PROP property of that symbol.

 - Function: text-properties-at POSITION &optional OBJECT
     This function returns the list of properties held by the character
     at POSITION in the buffer OBJECT.  If OBJECT is `nil', it defaults
     to the current buffer.

 - Function: text-property-any START END PROP VALUE &optional OBJECT
     This function returns non-`nil' if at least one character between
     START and END has a property PROP whose value is VALUE.  More
     precisely, it returns the position of the first such character.
     Otherwise, it returns `nil'.

     The optional fifth argument, OBJECT, specifies the buffer to scan.
     Positions are relative to OBJECT.

 - Function: text-property-not-all START END PROP VALUE &optional OBJECT
     This function returns non-`nil' if at least one character between
     START and END has a property PROP whose value differs from VALUE.
     More precisely, it returns the position of the first such
     character.  Otherwise, it returns `nil'.

     The optional fifth argument, OBJECT, specifies the buffer to scan.
     Positions are relative to OBJECT.

Changing Text Properties
------------------------

   The primitives for changing properties apply to a specified range of
text.  The function `set-text-properties' (see end of section) sets the
entire property list of the text in that range; more often, it is
useful to add, change, or delete just certain properties specified by
name.

   Since text properties are considered part of the buffer's contents,
and can affect how the buffer looks on the screen, any change in the
text properties is considered a buffer modification.  Buffer text
property changes are undoable.

 - Function: add-text-properties START END PROPS &optional OBJECT
     This function modifies the text properties for the text between
     START and END in the string or buffer OBJECT.  If OBJECT is `nil',
     it defaults to the current buffer.

     The argument PROPS specifies which properties to change.  It
     should have the form of a property list (see Property Lists.):
     a list whose elements include the property names followed
     alternately by the corresponding values.

     The return value is `t' if the function actually changed some
     property's value; `nil' otherwise (if PROPS is `nil' or its values
     agree with those in the text).

     For example, here is how to set the `comment' property to `t' for
     a range of text:

          (add-text-properties (region-beginning)
                               (region-end)
                               (list 'comment t))

 - Function: put-text-property START END PROP VALUE &optional OBJECT
     This function sets the PROP property to VALUE for the text between
     START and END in the buffer OBJECT.  If OBJECT is `nil', it
     defaults to the current buffer.

 - Function: remove-text-properties START END PROPS &optional OBJECT
     This function deletes specified text properties from the text
     between START and END in the buffer OBJECT.  If OBJECT is `nil',
     it defaults to the current buffer.

     The argument PROPS specifies which properties to delete.  It
     should have the form of a property list (see Property Lists.):
     a list whose elements include the property names followed by the
     corresponding values.  The property names mentioned in PROPS are
     the ones deleted from the text.  The values associated in PROPS
     with these names do not matter.

     The return value is `t' if the function actually changed some
     property's value; `nil' otherwise (if PROPS is `nil' or if none of
     the text had any of those properties).

 - Function: set-text-properties START END PROPS &optional OBJECT
     This function completely replaces the text property list for the
     text between START and END in the buffer OBJECT.  If OBJECT is
     `nil', it defaults to the current buffer.

     The argument PROPS is the new property list.  It should have the
     form of a list whose elements include the property names followed
     by the corresponding values.

     After `set-text-properties' returns, all the characters in the
     specified range have identical properties.

     If PROPS is `nil', the effect is to get rid of all properties from
     the specified range of text.  Here's an example:

          (set-text-properties (region-beginning)
                               (region-end)
                               nil)

Property Search Functions
-------------------------

   In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property.  Rather than
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.

   Here are functions you can use to do this.  In all cases, OBJECT
defaults to the current buffer.

 - Function: next-property-change POS &optional OBJECT
     The function scans the text forward from position POS in the
     string or buffer OBJECT till it finds a change in some text
     property, then returns the position of the change.  In other
     words, it returns the position of the first character beyond POS
     whose properties are not identical to those of the character just
     after POS.

     The value is `nil' if the properties remain unchanged all the way
     to the end of OBJECT.  If the value is non-`nil', it is a position
     greater than POS, never equal.

     Here is an example of how to scan the buffer by chunks of text
     within which all properties are constant:

          (while (not (eobp))
            (let ((plist (text-properties-at (point)))
                  (next-change
                   (or (next-property-change (point) (current-buffer))
                       (point-max))))
              PROCESS TEXT FROM POINT TO NEXT-CHANGE...
              (goto-char next-change)))

 - Function: next-single-property-change POS PROP &optional OBJECT
     The function scans the text forward from position POS in the
     buffer OBJECT till it finds a change in the PROP property, then
     returns the position of the change.  In other words, it returns the
     position of the first character beyond POS whose PROP property
     differs from that of the character just after POS.

     The value is `nil' if the properties remain unchanged all the way
     to the end of OBJECT.  If the value is non-`nil', it is a position
     greater than POS, never equal.

 - Function: previous-property-change POS &optional OBJECT
     This is like `next-property-change', but scans back from POS
     instead of forward.  If the value is non-`nil', it is a position
     always strictly less than POS.  Remember that a position is always
     between two characters; the position returned by this function is
     between two characters with different properties.

 - Function: previous-single-property-change POS PROP &optional OBJECT
     This is like `next-property-change', but scans back from POS
     instead of forward.  If the value is non-`nil', it is a position
     always strictly less than POS.

Special Properties
------------------

   The predefined properties are the same as those for extents.  See
Extent Properties.

Substituting for a Character Code
=================================

   The following functions replace characters within a specified region
based on their character codes.

 - Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional
          NOUNDO
     This function replaces all occurrences of the character OLD-CHAR
     with the character NEW-CHAR in the region of the current buffer
     defined by START and END.

     If NOUNDO is non-`nil', then `subst-char-in-region' does not
     record the change for undo and does not mark the buffer as
     modified.  This feature is useful for changes which are not
     considered significant, such as when Outline mode changes visible
     lines to invisible lines and vice versa.

     `subst-char-in-region' does not move point and returns `nil'.

          ---------- Buffer: foo ----------
          This is the contents of the buffer before.
          ---------- Buffer: foo ----------

          (subst-char-in-region 1 20 ?i ?X)
               => nil

          ---------- Buffer: foo ----------
          ThXs Xs the contents of the buffer before.
          ---------- Buffer: foo ----------

 - Function: translate-region START END TABLE
     This function applies a translation table to the characters in the
     buffer between positions START and END.

     The translation table TABLE is a string; `(aref TABLE OCHAR)'
     gives the translated character corresponding to OCHAR.  If the
     length of TABLE is less than 256, any characters with codes larger
     than the length of TABLE are not altered by the translation.

     The return value of `translate-region' is the number of characters
     which were actually changed by the translation.  This does not
     count characters which were mapped into themselves in the
     translation table.

     This function is available in Emacs versions 19 and later.

Underlining
===========

   The underlining commands are somewhat obsolete.  The
`underline-region' function actually inserts `_^H' before each
appropriate character in the region.  This command provides a minimal
text formatting feature that might work on your printer; however, we
recommend instead that you use more powerful text formatting facilities,
such as Texinfo.

 - Command: underline-region START END
     This function underlines all nonblank characters in the region
     defined by START and END.  That is, an underscore character and a
     backspace character are inserted just before each non-whitespace
     character in the region.  The backspace characters are intended to
     cause overstriking, but in Emacs they display as either `\010' or
     `^H', depending on the setting of `ctl-arrow'.  There is no way to
     see the effect of the overstriking within Emacs.  The value is
     `nil'.

 - Command: ununderline-region START END
     This function removes all underlining (overstruck underscores) in
     the region defined by START and END.  The value is `nil'.

Registers
=========

   A register is a sort of variable used in Emacs editing that can hold
a marker, a string, a rectangle, a window configuration (of one
screen), or a screen configuration (of all screens).  Each register is
named by a single character.  All characters, including control and
meta characters (but with the exception of `C-g'), can be used to name
registers.  Thus, there are 255 possible registers.  A register is
designated in Emacs Lisp by a character which is its name.

   The functions in this section return unpredictable values unless
otherwise stated.

 - Variable: register-alist
     This variable is an alist of elements of the form `(NAME .
     cONTENTS)'.  Normally, there is one element for each Emacs
     register that has been used.

     The object NAME is a character (an integer) identifying the
     register.  The object CONTENTS is a string, marker, or list
     representing the register contents.  A string represents text
     stored in the register.  A marker represents a position.  A list
     represents a rectangle; its elements are strings, one per line of
     the rectangle.

 - Command: view-register REG
     This command displays what is contained in register REG.

 - Function: get-register REG
     This function returns the contents of the register REG, or `nil'
     if it has no contents.

 - Function: set-register REG VALUE
     This function sets the contents of register REG to VALUE.  A
     register can be set to any value, but the other register functions
     expect only certain data types.  The return value is VALUE.

 - Command: point-to-register REG
     This command stores both the current location of point and the
     current buffer in register REG as a marker.

 - Command: jump-to-register REG
 - Command: register-to-point REG
     This command restores the status recorded in register REG.

     If 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 `point-to-register' function, this
     command can switch you to another buffer.

     If REG contains a window configuration or a screen configuration.
     `jump-to-register' restores that configuration.

 - Command: insert-register REG &optional BEFOREP
     This command inserts contents of register REG into the current
     buffer.

     Normally, this command puts point before the inserted text, and the
     mark after it.  However, if the optional second argument BEFOREP
     is non-`nil', it puts the mark before and point after.  You can
     pass a non-`nil' second argument BEFOREP to this function
     interactively by supplying any prefix argument.

     If the register contains a rectangle, then the rectangle is
     inserted with its upper left corner at point.  This means that
     text is inserted in the current line and underneath it on
     successive lines.

     If the register contains something other than saved text (a
     string) or a rectangle (a list), currently useless things happen.
     This may be changed in the future.

 - Command: copy-to-register REG START END &optional DELETE-FLAG
     This command copies the region from START to END into register
     REG.  If DELETE-FLAG is non-`nil', it deletes the region from the
     buffer after copying it into the register.

 - Command: prepend-to-register REG START END &optional DELETE-FLAG
     This command prepends the region from START to END into register
     REG.  If DELETE-FLAG is non-`nil', it deletes the region from the
     buffer after copying it to the register.

 - Command: append-to-register REG START END &optional DELETE-FLAG
     This command appends the region from START to END to the text
     already in register REG.  If DELETE-FLAG is non-`nil', it deletes
     the region from the buffer after copying it to the register.

 - Command: copy-rectangle-to-register REG START END &optional
          DELETE-FLAG
     This command copies a rectangular region from START to END into
     register REG.  If DELETE-FLAG is non-`nil', it deletes the region
     from the buffer after copying it to the register.

 - Command: window-configuration-to-register REG
     This function stores the window configuration of the selected
     screen in register REG.

Change Hooks
============

   These hook variables let you arrange to take notice of all changes in
all buffers (or in a particular buffer, if you make them buffer-local).

   The functions you use in these hooks should save and restore the
match data if they do anything that uses regular expressions;
otherwise, they will interfere in bizarre ways with the editing
operations that call them.

 - Variable: before-change-function
     If this variable is non-`nil', then it should be a function; the
     function is called before any buffer modification.  Its arguments
     are the beginning and end of the region that is going to change,
     represented as integers.  The buffer that's about to change is
     always the current buffer.

 - Variable: after-change-function
     If this variable is non-`nil', then it should be a function; the
     function is called after any buffer modification.  It receives
     three arguments: the beginning and end of the region just changed,
     and the length of the text that existed before the change.  (To
     get the current length, subtract the region beginning from the
     region end.) All three arguments are integers.  The buffer that's
     about to change is always the current buffer.

   Both of these variables are temporarily bound to `nil' during the
time that either of these hooks is running.  This means that if one of
these functions changes the buffer, that change won't run these
functions.  If you do want the hook function to be run recursively,
write your hook functions to bind these variables back to their usual
values.

 - Variable: first-change-hook
     This variable is a normal hook; its hook functions are run using
     `run-hooks' whenever a buffer is changed that was previously in
     the unmodified state.

   The variables described in this section are meaningful only starting
with Emacs version 19.

Searching and Matching
**********************

   GNU Emacs provides two ways to search through a buffer for specified
text: exact string searches and regular expression searches.  After a
regular expression search, you can identify the text matched by parts of
the regular expression by examining the "match data".

Searching for Strings
=====================

   These are the primitive functions for searching through the text in a
buffer.  They are meant for use in programs, but you may call them
interactively.  If you do so, they prompt for the search string; LIMIT
and NOERROR are set to `nil', and REPEAT is set to 1.

 - Command: search-forward STRING &optional LIMIT NOERROR REPEAT
     This function searches forward from point for an exact match for
     STRING.  If successful, it sets point to the end of the occurrence
     found, and returns the new value of point.  If no match is found,
     the value and side effects depend on NOERROR (see below).

     In the following example, point is positioned at the beginning of
     the line.  Then `(search-forward "fox")' is evaluated in the
     minibuffer and point is left after the last letter of `fox':

          ---------- Buffer: foo ----------
          -!-The quick brown fox jumped over the lazy dog.
          ---------- Buffer: foo ----------

          (search-forward "fox")
               => t

          ---------- Buffer: foo ----------
          The quick brown fox-!- jumped over the lazy dog.
          ---------- Buffer: foo ----------

     The argument LIMIT specifies the upper bound to the search.  (It
     must be a position in the current buffer.)  No match extending
     after that position is accepted.  If LIMIT is omitted or `nil', it
     defaults to the end of the accessible portion of the buffer.

     What happens when the search fails depends on the value of
     NOERROR.  If NOERROR is `nil', a `search-failed' error is
     signaled.  If NOERROR is `t', `search-forward' returns `nil' and
     does nothing.  If NOERROR is neither `nil' nor `t', then
     `search-forward' moves point to the upper bound and returns `nil'.
     (It would be more consistent now to return the new position of
     point in that case, but some programs may depend on a value of
     `nil'.)

     If REPEAT is non-`nil', then the search is repeated that many
     times.  Point is positioned at the end of the last match.

 - Command: search-backward STRING &optional LIMIT NOERROR REPEAT
     This function searches backward from point for STRING.  It is just
     like `search-forward' except that it searches backwards and leaves
     point at the beginning of the match.

 - Command: word-search-forward STRING &optional LIMIT NOERROR REPEAT
     This function searches forward from point for a "word" match for
     STRING.  If it finds a match, it sets point to the end of the
     match found, and returns the new value of point.

     A word search differs from a simple string search in that a word
     search *requires* that the words it searches for are present as
     entire words (searching for the word `ball' does not match the word
     `balls'), and punctuation and spacing are ignored (searching for
     `ball boy' does match `ball.  Boy!').

     In this example, point is first placed at the beginning of the
     buffer; the search leaves it between the `y' and the `!'.

          ---------- Buffer: foo ----------
          -!-He said "Please!  Find
          the ball boy!"
          ---------- Buffer: foo ----------

          (word-search-forward "Please find the ball, boy.")
               => t

          ---------- Buffer: foo ----------
          He said "Please!  Find
          the ball boy-!-!"
          ---------- Buffer: foo ----------

     If LIMIT is non-`nil' (it must be a position in the current
     buffer), then it is the upper bound to the search.  The match
     found must not extend after that position.

     If NOERROR is `t', then `word-search-forward' returns `nil' when a
     search fails, instead of signaling an error.  If NOERROR is
     neither `nil' nor `t', then `word-search-forward' moves point to
     LIMIT (or the end of the buffer) and returns `nil'.

     If REPEAT is non-`nil', then the search is repeated that many
     times.  Point is positioned at the end of the last match.

 - Command: word-search-backward STRING &optional LIMIT NOERROR REPEAT
     This function searches backward from point for a word match to
     STRING.  This function is just like `word-search-forward' except
     that it searches backward and normally leaves point at the
     beginning of the match.

Regular Expressions
===================

   A "regular expression" ("regexp", for short) is a pattern that
denotes a (possibly infinite) set of strings.  Searching for matches for
a regexp is a very powerful operation.  This section explains how to
write regexps; the following section says how to search for them.