--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/abbrevs
+@node Abbrevs, Processes, Syntax Tables, Top
+@chapter Abbrevs And Abbrev Expansion
+@cindex abbrev
+@cindex abbrev table
+
+ An abbreviation or @dfn{abbrev} is a string of characters that may be
+expanded to a longer string. The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev. This
+saves typing.
+
+ The set of abbrevs currently in effect is recorded in an @dfn{abbrev
+table}. Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table. There is also a global
+abbrev table. Normally both are used.
+
+ An abbrev table is represented as an obarray containing a symbol for
+each abbreviation. The symbol's name is the abbreviation. Its value is
+the expansion; its function definition is the hook function to do the
+expansion (if any); its property list cell contains the use count, the
+number of times the abbreviation has been expanded. Because these
+symbols are not interned in the usual obarray, they will never appear as
+the result of reading a Lisp expression; in fact, normally they are
+never used except by the code that handles abbrevs. Therefore, it is
+safe to use them in an extremely nonstandard way. @xref{Creating
+Symbols}.
+
+ For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
+Mode, emacs, The GNU Emacs Manual}.
+
+@menu
+* Abbrev Mode:: Setting up Emacs for abbreviation.
+* Tables: Abbrev Tables. Creating and working with abbrev tables.
+* Defining Abbrevs:: Specifying abbreviations and their expansions.
+* Files: Abbrev Files. Saving abbrevs in files.
+* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+@end menu
+
+@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
+@comment node-name, next, previous, up
+@section Setting Up Abbrev Mode
+
+ Abbrev mode is a minor mode controlled by the value of the variable
+@code{abbrev-mode}.
+
+@defvar abbrev-mode
+A non-@code{nil} value of this variable turns on the automatic expansion
+of abbrevs when their abbreviations are inserted into a buffer.
+If the value is @code{nil}, abbrevs may be defined, but they are not
+expanded automatically.
+
+This variable automatically becomes local when set in any fashion.
+@end defvar
+
+@defvar default-abbrev-mode
+This is the value @code{abbrev-mode} for buffers that do not override it.
+This is the same as @code{(default-value 'abbrev-mode)}.
+@end defvar
+
+@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
+@section Abbrev Tables
+
+ This section describes how to create and manipulate abbrev tables.
+
+@defun make-abbrev-table
+This function creates and returns a new, empty abbrev table---an obarray
+containing no symbols. It is a vector filled with zeros.
+@end defun
+
+@defun clear-abbrev-table table
+This function undefines all the abbrevs in abbrev table @var{table},
+leaving it empty. The function returns @code{nil}.
+@end defun
+
+@defun define-abbrev-table tabname definitions
+This function defines @var{tabname} (a symbol) as an abbrev table name,
+i.e., as a variable whose value is an abbrev table. It defines abbrevs
+in the table according to @var{definitions}, a list of elements of the
+form @code{(@var{abbrevname} @var{expansion} @var{hook}
+@var{usecount})}. The value is always @code{nil}.
+@end defun
+
+@defvar abbrev-table-name-list
+This is a list of symbols whose values are abbrev tables.
+@code{define-abbrev-table} adds the new abbrev table name to this list.
+@end defvar
+
+@defun insert-abbrev-table-description name &optional human
+This function inserts before point a description of the abbrev table
+named @var{name}. The argument @var{name} is a symbol whose value is an
+abbrev table. The value is always @code{nil}.
+
+If @var{human} is non-@code{nil}, the description is human-oriented.
+Otherwise the description is a Lisp expression---a call to
+@code{define-abbrev-table} which would define @var{name} exactly as it
+is currently defined.
+@end defun
+
+@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
+@comment node-name, next, previous, up
+@section Defining Abbrevs
+
+ These functions define an abbrev in a specified abbrev table.
+@code{define-abbrev} is the low-level basic function, while
+@code{add-abbrev} is used by commands that ask for information from the
+user.
+
+@defun add-abbrev table type arg
+This function adds an abbreviation to abbrev table @var{table}. The
+argument @var{type} is a string describing in English the kind of abbrev
+this will be (typically, @code{"global"} or @code{"mode-specific"});
+this is used in prompting the user. The argument @var{arg} is the
+number of words in the expansion.
+
+The return value is the symbol which internally represents the new
+abbrev, or @code{nil} if the user declines to confirm redefining an
+existing abbrev.
+@end defun
+
+@defun define-abbrev table name expansion hook
+This function defines an abbrev in @var{table} named @var{name}, to
+expand to @var{expansion}, and call @var{hook}. The return value is an
+uninterned symbol which represents the abbrev inside Emacs; its name is
+@var{name}.
+
+The argument @var{name} should be a string. The argument
+@var{expansion} should be a string, or @code{nil}, to undefine the
+abbrev.
+
+The argument @var{hook} is a function or @code{nil}. If @var{hook} is
+non-@code{nil}, then it is called with no arguments after the abbrev is
+replaced with @var{expansion}; point is located at the end of
+@var{expansion}.
+
+The use count of the abbrev is initialized to zero.
+@end defun
+
+@defopt only-global-abbrevs
+If this variable is non-@code{nil}, it means that the user plans to use
+global abbrevs only. This tells the commands that define mode-specific
+abbrevs to define global ones instead. This variable does not alter the
+functioning of the functions in this section; it is examined by their
+callers.
+@end defopt
+
+@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
+@section Saving Abbrevs in Files
+
+ A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents. Therefore, you can load the file
+with @code{load} (@pxref{How Programs Do Loading}). However, the
+function @code{quietly-read-abbrev-file} is provided as a more
+convenient interface.
+
+ User-level facilities such as @code{save-some-buffers} can save
+abbrevs in a file automatically, under the control of variables
+described here.
+
+@defopt abbrev-file-name
+This is the default file name for reading and saving abbrevs.
+@end defopt
+
+@defun quietly-read-abbrev-file filename
+This function reads abbrev definitions from a file named @var{filename},
+previously written with @code{write-abbrev-file}. If @var{filename} is
+@code{nil}, the file specified in @code{abbrev-file-name} is used.
+@code{save-abbrevs} is set to @code{t} so that changes will be saved.
+
+This function does not display any messages. It returns @code{nil}.
+@end defun
+
+@defopt save-abbrevs
+A non-@code{nil} value for @code{save-abbrev} means that Emacs should
+save abbrevs when files are saved. @code{abbrev-file-name} specifies
+the file to save the abbrevs in.
+@end defopt
+
+@defvar abbrevs-changed
+This variable is set non-@code{nil} by defining or altering any
+abbrevs. This serves as a flag for various Emacs commands to offer to
+save your abbrevs.
+@end defvar
+
+@deffn Command write-abbrev-file filename
+Save all abbrev definitions, in all abbrev tables, in the file
+@var{filename}, in the form of a Lisp program which when loaded will
+define the same abbrevs. This function returns @code{nil}.
+@end deffn
+
+@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
+@comment node-name, next, previous, up
+@section Looking Up and Expanding Abbreviations
+
+ Abbrevs are usually expanded by commands for interactive use,
+including @code{self-insert-command}. This section describes the
+subroutines used in writing such functions, as well as the variables
+they use for communication.
+
+@defun abbrev-symbol abbrev &optional table
+This function returns the symbol representing the abbrev named
+@var{abbrev}. The value returned is @code{nil} if that abbrev is not
+defined. The optional second argument @var{table} is the abbrev table
+to look it up in. If @var{table} is @code{nil}, this function tries
+first the current buffer's local abbrev table, and second the global
+abbrev table.
+@end defun
+
+@defopt abbrev-all-caps
+When this is set non-@code{nil}, an abbrev entered entirely in upper
+case is expanded using all upper case. Otherwise, an abbrev entered
+entirely in upper case is expanded by capitalizing each word of the
+expansion.
+@end defopt
+
+@defun abbrev-expansion abbrev &optional table
+This function returns the string that @var{abbrev} would expand into (as
+defined by the abbrev tables used for the current buffer). The optional
+argument @var{table} specifies the abbrev table to use; if it is
+specified, the abbrev is looked up in that table only.
+@end defun
+
+@defvar abbrev-start-location
+This is the buffer position for @code{expand-abbrev} to use as the start
+of the next abbrev to be expanded. (@code{nil} means use the word
+before point instead.) @code{abbrev-start-location} is set to
+@code{nil} each time @code{expand-abbrev} is called. This variable is
+also set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar abbrev-start-location-buffer
+The value of this variable is the buffer for which
+@code{abbrev-start-location} has been set. Trying to expand an abbrev
+in any other buffer clears @code{abbrev-start-location}. This variable
+is set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar last-abbrev
+This is the @code{abbrev-symbol} of the last abbrev expanded. This
+information is left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@defvar last-abbrev-location
+This is the location of the last abbrev expanded. This contains
+information left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@defvar last-abbrev-text
+This is the exact expansion text of the last abbrev expanded, as
+results from case conversion. Its value is
+@code{nil} if the abbrev has already been unexpanded. This
+contains information left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@c Emacs 19 feature
+@defvar pre-abbrev-expand-hook
+This is a normal hook whose functions are executed, in sequence, just
+before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
+hook, the hook functions receive no arguments. However, they can find
+the abbrev to be expanded by looking in the buffer before point.
+@end defvar
+
+ The following sample code shows a simple use of
+@code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation. Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+@smallexample
+(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+
+;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.}
+
+;; @r{If the user terminated the abbrev with a space, the function does}
+;; @r{nothing (that is, it returns so that the abbrev can expand). If the}
+;; @r{user entered some other character, this function asks whether}
+;; @r{expansion should continue.}
+
+;; @r{If the user enters the prompt with @kbd{y}, the function returns}
+;; @r{@code{nil} (because of the @code{not} function), but that is}
+;; @r{acceptable; the return value has no effect on expansion.}
+
+(defun query-if-not-space ()
+ (if (/= ?\ (preceding-char))
+ (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+ (error "Not expanding this abbrev"))))
+@end smallexample
+
+@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs
+@comment node-name, next, previous, up
+@section Standard Abbrev Tables
+
+ Here we list the variables that hold the abbrev tables for the
+preloaded major modes of Emacs.
+
+@defvar global-abbrev-table
+This is the abbrev table for mode-independent abbrevs. The abbrevs
+defined in it apply to all buffers. Each buffer may also have a local
+abbrev table, whose abbrev definitions take precedence over those in the
+global table.
+@end defvar
+
+@defvar local-abbrev-table
+The value of this buffer-local variable is the (mode-specific)
+abbreviation table of the current buffer.
+@end defvar
+
+@defvar fundamental-mode-abbrev-table
+This is the local abbrev table used in Fundamental mode. It is the
+local abbrev table in all buffers in Fundamental mode.
+@end defvar
+
+@defvar text-mode-abbrev-table
+This is the local abbrev table used in Text mode.
+@end defvar
+
+@defvar c-mode-abbrev-table
+This is the local abbrev table used in C mode.
+@end defvar
+
+@defvar lisp-mode-abbrev-table
+This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
+@end defvar
--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/positions
+@node Positions, Markers, Frames, Top
+@chapter Positions
+@cindex position (in buffer)
+
+ A @dfn{position} is the index of a character in the text of buffer.
+More precisely, a position identifies the place between two characters
+(or before the first character, or after the last character), so we can
+speak of the character before or after a given position. However, the
+we often speak of the character ``at'' a position, meaning the character
+after that position.
+
+ Positions are usually represented as integers starting from 1, but can
+also be represented as @dfn{markers}---special objects which relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters. @xref{Markers}.
+
+@menu
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+@end menu
+
+@node Point
+@section Point
+@cindex point
+
+ @dfn{Point} is a special buffer position used by many editing
+commands, including the self-inserting typed characters and text
+insertion functions. Other commands move point through the text
+to allow editing and insertion at different places.
+
+ Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character. Many terminals display the cursor over the
+character that immediately follows point; on such terminals, point is
+actually before the character on which the cursor sits.
+
+@cindex point with narrowing
+ The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (@pxref{Narrowing}), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
+
+ Each buffer has its own value of point, which is independent of the
+value of point in other buffers. Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer. This is why point can have different values in various windows
+that display the same buffer. When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important. @xref{Window Point}, for more
+details.
+
+@defun point
+@cindex current buffer position
+ This function returns the position of point in the current buffer,
+as an integer.
+
+@need 700
+@example
+@group
+(point)
+ @result{} 175
+@end group
+@end example
+@end defun
+
+@defun point-min
+ This function returns the minimum accessible value of point in the
+current buffer. This is 1, unless narrowing is in effect, in
+which case it is the position of the start of the region that you
+narrowed to. (@xref{Narrowing}.)
+@end defun
+
+@defun point-max
+ This function returns the maximum accessible value of point in the
+current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
+in effect, in which case it is the position of the end of the region
+that you narrowed to. (@xref{Narrowing}).
+@end defun
+
+@defun buffer-end flag
+ This function returns @code{(point-min)} if @var{flag} is less than 1,
+@code{(point-max)} otherwise. The argument @var{flag} must be a number.
+@end defun
+
+@defun buffer-size
+ This function returns the total number of characters in the current
+buffer. In the absence of any narrowing (@pxref{Narrowing}),
+@code{point-max} returns a value one larger than this.
+
+@example
+@group
+(buffer-size)
+ @result{} 35
+@end group
+@group
+(point-max)
+ @result{} 36
+@end group
+@end example
+@end defun
+
+@defvar buffer-saved-size
+ The value of this buffer-local variable is the former length of the
+current buffer, as of the last time it was read in, saved or auto-saved.
+@end defvar
+
+@node Motion
+@section Motion
+
+ Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window. @xref{Point}.
+
+@menu
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* Vertical Motion:: Implementation of @code{next-line} and
+ @code{previous-line}.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
+@end menu
+
+@node Character Motion
+@subsection Motion by Characters
+
+ These functions move point based on a count of characters.
+@code{goto-char} is the fundamental primitive; the functions others use
+that.
+
+@deffn Command goto-char position
+This function sets point in the current buffer to the value
+@var{position}. If @var{position} is less than 1, it moves point to the
+beginning of the buffer. If @var{position} is greater than the length
+of the buffer, it moves point to the end.
+
+If narrowing is in effect, @var{position} still counts from the
+beginning of the buffer, but point cannot go outside the accessible
+portion. If @var{position} is out of range, @code{goto-char} moves
+point to the beginning or the end of the accessible portion.
+
+When this function is called interactively, @var{position} is the
+numeric prefix argument, if provided; otherwise it is read from the
+minibuffer.
+
+@code{goto-char} returns @var{position}.
+@end deffn
+
+@deffn Command forward-char &optional count
+@c @kindex beginning-of-buffer
+@c @kindex end-of-buffer
+This function moves point @var{count} characters forward, towards the
+end of the buffer (or backward, towards the beginning of the buffer, if
+@var{count} is negative). If the function attempts to move point past
+the beginning or end of the buffer (or the limits of the accessible
+portion, when narrowing is in effect), an error is signaled with error
+code @code{beginning-of-buffer} or @code{end-of-buffer}.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@deffn Command backward-char &optional count
+This function moves point @var{count} characters backward, towards the
+beginning of the buffer (or forward, towards the end of the buffer, if
+@var{count} is negative). If the function attempts to move point past
+the beginning or end of the buffer (or the limits of the accessible
+portion, when narrowing is in effect), an error is signaled with error
+code @code{beginning-of-buffer} or @code{end-of-buffer}.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@node Word Motion
+@subsection Motion by Words
+
+ These functions for parsing words use the syntax table to decide
+whether a given character is part of a word. @xref{Syntax Tables}.
+
+@deffn Command forward-word count
+This function moves point forward @var{count} words (or backward if
+@var{count} is negative). Normally it returns @code{t}. If this motion
+encounters the beginning or end of the buffer, or the limits of the
+accessible portion when narrowing is in effect, point stops there
+and the value is @code{nil}.
+
+In an interactive call, @var{count} is set to the numeric prefix
+argument.
+@end deffn
+
+@deffn Command backward-word count
+This function just like @code{forward-word}, except that it moves
+backward until encountering the front of a word, rather than forward.
+
+In an interactive call, @var{count} is set to the numeric prefix
+argument.
+
+This function is rarely used in programs, as it is more efficient to
+call @code{forward-word} with negative argument.
+@end deffn
+
+@defvar words-include-escapes
+@c Emacs 19 feature
+This variable affects the behavior of @code{forward-word} and everything
+that uses it. If it is non-@code{nil}, then characters in the
+``escape'' and ``character quote'' syntax classes count as part of
+words. Otherwise, they do not.
+@end defvar
+
+@node Buffer End Motion
+@subsection Motion to an End of the Buffer
+
+ To move point to the beginning of the buffer, write:
+
+@example
+@group
+(goto-char (point-min))
+@end group
+@end example
+
+@noindent
+Likewise, to move to the end of the buffer, use:
+
+@example
+@group
+(goto-char (point-max))
+@end group
+@end example
+
+ Here are two commands which users use to do these things. They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+@deffn Command beginning-of-buffer &optional n
+This function moves point to the beginning of the buffer (or the limits
+of the accessible portion, when narrowing is in effect), setting the
+mark at the previous position. If @var{n} is non-@code{nil}, then it
+puts point @var{n} tenths of the way from the beginning of the buffer.
+
+In an interactive call, @var{n} is the numeric prefix argument,
+if provided; otherwise @var{n} defaults to @code{nil}.
+
+Don't use this function in Lisp programs!
+@end deffn
+
+@deffn Command end-of-buffer &optional n
+This function moves point to the end of the buffer (or the limits of
+the accessible portion, when narrowing is in effect), setting the mark
+at the previous position. If @var{n} is non-@code{nil}, then it puts
+point @var{n} tenths of the way from the end.
+
+In an interactive call, @var{n} is the numeric prefix argument,
+if provided; otherwise @var{n} defaults to @code{nil}.
+
+Don't use this function in Lisp programs!
+@end deffn
+
+@node Text Lines
+@subsection Motion by Text Lines
+@cindex lines
+
+ Text lines are portions of the buffer delimited by newline characters,
+which are regarded as part of the previous line. The first text line
+begins at the beginning of the buffer, and the last text line ends at
+the end of the buffer whether or not the last character is a newline.
+The division of the buffer into text lines is not affected by the width
+of the window, by line continuation in display, or by how tabs and
+control characters are displayed.
+
+@deffn Command goto-line line
+This function moves point to the front of the @var{line}th line,
+counting from line 1 at beginning of buffer. If @var{line} is less than
+1, it moves point to the beginning of the buffer. If @var{line} is
+greater than the number of lines in the buffer, it moves point to the
+@emph{end of the last line} of the buffer.
+
+If narrowing is in effect, then @var{line} still counts from the
+beginning of the buffer, but point cannot go outside the accessible
+portion. So @code{goto-line} moves point to the beginning or end of the
+accessible portion, if the line number specifies an inaccessible
+position.
+
+The return value of @code{goto-line} is the difference between
+@var{line} and the line number of the line to which point actually was
+able move (in the full buffer, disregarding any narrowing). Thus, the
+value is positive if the scan encounters the real end of the buffer.
+
+In an interactive call, @var{line} is the numeric prefix argument if
+one has been provided. Otherwise @var{line} is read in the minibuffer.
+@end deffn
+
+@deffn Command beginning-of-line &optional count
+This function moves point to the beginning of the current line. With an
+argument @var{count} not @code{nil} or 1, it moves forward
+@var{count}@minus{}1 lines and then to the beginning of the line.
+
+If this function reaches the end of the buffer (or of the accessible
+portion, if narrowing is in effect), it positions point at the end of
+the buffer. No error is signaled.
+@end deffn
+
+@deffn Command end-of-line &optional count
+This function moves point to the end of the current line. With an
+argument @var{count} not @code{nil} or 1, it moves forward
+@var{count}@minus{}1 lines and then to the end of the line.
+
+If this function reaches the end of the buffer (or of the accessible
+portion, if narrowing is in effect), it positions point at the end of
+the buffer. No error is signaled.
+@end deffn
+
+@deffn Command forward-line &optional count
+@cindex beginning of line
+This function moves point forward @var{count} lines, to the beginning of
+the line. If @var{count} is negative, it moves point
+@minus{}@var{count} lines backward, to the beginning of the line.
+
+If @code{forward-line} encounters the beginning or end of the buffer (or
+of the accessible portion) before finding that many lines, it sets point
+there. No error is signaled.
+
+@code{forward-line} returns the difference between @var{count} and the
+number of lines actually moved. If you attempt to move down five lines
+from the beginning of a buffer that has only three lines, point stops at
+the end of the last line, and the value will be 2.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+@end deffn
+
+@defun count-lines start end
+@cindex lines in region
+This function returns the number of lines between the positions
+@var{start} and @var{end} in the current buffer. If @var{start} and
+@var{end} are equal, then it returns 0. Otherwise it returns at least
+1, even if @var{start} and @var{end} are on the same line. This is
+because the text between them, considered in isolation, must contain at
+least one line unless it is empty.
+
+Here is an example of using @code{count-lines}:
+
+@example
+@group
+(defun current-line ()
+ "Return the vertical position of point@dots{}"
+ (+ (count-lines (window-start) (point))
+ (if (= (current-column) 0) 1 0)
+ -1))
+@end group
+@end example
+@end defun
+
+@ignore
+@c ================
+The @code{previous-line} and @code{next-line} commands are functions
+that should not be used in programs. They are for users and are
+mentioned here only for completeness.
+
+@deffn Command previous-line count
+@cindex goal column
+This function moves point up @var{count} lines (down if @var{count}
+is negative). In moving, it attempts to keep point in the ``goal column''
+(normally the same column that it was at the beginning of the move).
+
+If there is no character in the target line exactly under the current
+column, point is positioned after the character in that line which
+spans this column, or at the end of the line if it is not long enough.
+
+If it attempts to move beyond the top or bottom of the buffer (or clipped
+region), then point is positioned in the goal column in the top or
+bottom line. No error is signaled.
+
+In an interactive call, @var{count} will be the numeric
+prefix argument.
+
+The command @code{set-goal-column} can be used to create a semipermanent
+goal column to which this command always moves. Then it does not try to
+move vertically.
+
+If you are thinking of using this in a Lisp program, consider using
+@code{forward-line} with a negative argument instead. It is usually easier
+to use and more reliable (no dependence on goal column, etc.).
+@end deffn
+
+@deffn Command next-line count
+This function moves point down @var{count} lines (up if @var{count}
+is negative). In moving, it attempts to keep point in the ``goal column''
+(normally the same column that it was at the beginning of the move).
+
+If there is no character in the target line exactly under the current
+column, point is positioned after the character in that line which
+spans this column, or at the end of the line if it is not long enough.
+
+If it attempts to move beyond the top or bottom of the buffer (or clipped
+region), then point is positioned in the goal column in the top or
+bottom line. No error is signaled.
+
+In the case where the @var{count} is 1, and point is on the last
+line of the buffer (or clipped region), a new empty line is inserted at the
+end of the buffer (or clipped region) and point moved there.
+
+In an interactive call, @var{count} will be the numeric
+prefix argument.
+
+The command @code{set-goal-column} can be used to create a semipermanent
+goal column to which this command always moves. Then it does not try to
+move vertically.
+
+If you are thinking of using this in a Lisp program, consider using
+@code{forward-line} instead. It is usually easier
+to use and more reliable (no dependence on goal column, etc.).
+@end deffn
+
+@c ================
+@end ignore
+
+ Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+@node Screen Lines
+@subsection Motion by Screen Lines
+
+ The line functions in the previous section count text lines, delimited
+only by newline characters. By contrast, these functions count screen
+lines, which are defined by the way the text appears on the screen. A
+text line is a single screen line if it is short enough to fit the width
+of the selected window, but otherwise it may occupy several screen
+lines.
+
+ In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines. In these cases,
+@code{vertical-motion} moves point much like @code{forward-line}.
+@xref{Truncation}.
+
+ Because the width of a given string depends on the flags which control
+the appearance of certain characters, @code{vertical-motion} behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows). @xref{Usual
+Display}.
+
+@defun vertical-motion count
+This function moves point to the start of the screen line @var{count}
+screen lines down from the screen line containing point. If @var{count}
+is negative, it moves up instead.
+
+This function returns the number of lines moved. The value may be less
+in absolute value than @var{count} if the beginning or end of the buffer
+was reached.
+@end defun
+
+@deffn Command move-to-window-line count
+This function moves point with respect to the text currently displayed
+in the selected window. It moves point to the beginning of the screen
+line @var{count} screen lines from the top of the window. If
+@var{count} is negative, that specifies a position
+@w{@minus{}@var{count}} lines from the bottom---or else the last line of
+the buffer, if the buffer ends above the specified screen position.
+
+If @var{count} is @code{nil}, then point moves to the beginning of the
+line in the middle of the window. If the absolute value of @var{count}
+is greater than the size of the window, then point moves to the place
+which would appear on that screen line if the window were tall enough.
+This will probably cause the next redisplay to scroll to bring that
+location onto the screen.
+
+In an interactive call, @var{count} is the numeric prefix argument.
+
+The value returned is the window line number, with the top line in the
+window numbered 0.
+@end deffn
+
+@defun compute-motion from frompos to topos width offsets
+This function scan through the current buffer, calculating screen
+position. It scans the current buffer forward from position @var{from},
+assuming that is at screen coordinates @var{frompos}, to position
+@var{to} or coordinates @var{topos}, whichever comes first. It returns
+the ending buffer position and screen coordinates.
+
+The coordinate arguments @var{frompos} and @var{topos} are cons cells of
+the form @code{(@var{hpos} . @var{vpos})}.
+
+The argument @var{width} is the number of columns available to display
+text; this affects handling of continuation lines. Use the value
+returned by @code{window-width} for the window of your choice.
+
+The argument @var{offsets} is either @code{nil} or a cons cell of the
+form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
+the number of columns not being displayed at the left margin; in most
+calls, this comes from @code{window-hscroll}. Meanwhile,
+@var{tab-offset} is the number of columns of an initial tab character
+(at @var{from}) that aren't included in the display, perhaps because the
+line was continued within that character.
+
+The return value is a list of five elements:
+
+@example
+(@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin})
+@end example
+
+@noindent
+Here @var{pos} is the buffer position where the scan stopped, @var{vpos}
+is the vertical position, and @var{hpos} is the horizontal position.
+
+The result @var{prevhpos} is the horizontal position one character back
+from @var{pos}. The result @var{contin} is @code{t} if a line was
+continued after (or within) the previous character.
+
+For example, to find the buffer position of column @var{col} of line
+@var{line} of a certain window, pass the window's display start location
+as @var{from} and the window's upper-left coordinates as @var{frompos}.
+Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
+the end of the visible section of the buffer, and pass @var{line} and
+@var{col} as @var{topos}. Here's a function that does this:
+
+@example
+(defun coordinates-of-position (col line)
+ (car (compute-motion (window-start)
+ '(0 . 0)
+ (point)
+ (cons col line)
+ (window-width)
+ (cons (window-hscroll) 0))))
+@end example
+@end defun
+
+@node Vertical Motion
+@comment node-name, next, previous, up
+@subsection The User-Level Vertical Motion Commands
+@cindex goal column
+@cindex vertical text line motion
+@findex next-line
+@findex previous-line
+
+ A goal column is useful if you want to edit text such as a table in
+which you want to move point to a certain column on each line. The goal
+column affects the vertical text line motion commands, @code{next-line}
+and @code{previous-line}. @xref{Basic,, Basic Editing Commands, emacs,
+The GNU Emacs Manual}.
+
+@defopt goal-column
+This variable holds an explicitly specified goal column for vertical
+line motion commands. If it is an integer, it specifies a column, and
+these commands try to move to that column on each line. If it is
+@code{nil}, then the commands set their own goal columns. Any other
+value is invalid.
+@end defopt
+
+@defvar temporary-goal-column
+This variable holds the temporary goal column during a sequence of
+consecutive vertical line motion commands. It is overridden by
+@code{goal-column} if that is non-@code{nil}. It is set each time a
+vertical motion command is invoked, unless the previous command was also
+a vertical motion command.
+@end defvar
+
+@defopt track-eol
+This variable controls how the vertical line motion commands operate
+when starting at the end of a line. If @code{track-eol} is
+non-@code{nil}, then vertical motion starting at the end of a line will
+keep to the ends of lines. This means moving to the end of each line
+moved onto. The value of @code{track-eol} has no effect if point is not
+at the end of a line when the first vertical motion command is given.
+
+@code{track-eol} has its effect by telling line motion commands to set
+@code{temporary-goal-column} to 9999 instead of to the current column.
+@end defopt
+
+@node List Motion
+@comment node-name, next, previous, up
+@subsection Moving over Balanced Expressions
+@cindex sexp motion
+@cindex Lisp expression motion
+@cindex list motion
+
+ Here are several functions concerned with balanced-parenthesis
+expressions (also called @dfn{sexps} in connection with moving across
+them in Emacs). The syntax table controls how these functions interpret
+various characters; see @ref{Syntax Tables}. @xref{Parsing
+Expressions}, for lower-level primitives for scanning sexps or parts of
+sexps. For user-level commands, see @ref{Lists and Sexps,,, emacs, GNU
+Emacs Manual}.
+
+@deffn Command forward-list arg
+Move forward across @var{arg} balanced groups of parentheses.
+(Other syntactic entities such as words or paired string quotes
+are ignored.)
+@end deffn
+
+@deffn Command backward-list arg
+Move backward across @var{arg} balanced groups of parentheses.
+(Other syntactic entities such as words or paired string quotes
+are ignored.)
+@end deffn
+
+@deffn Command up-list arg
+Move forward out of @var{arg} levels of parentheses.
+A negative argument means move backward but still to a less deep spot.
+@end deffn
+
+@deffn Command down-list arg
+Move forward down @var{arg} levels of parentheses. A negative argument
+means move backward but still go down @var{arg} levels.
+@end deffn
+
+@deffn Command forward-sexp arg
+Move forward across @var{arg} balanced expressions.
+Balanced expressions include both those delimited by parentheses
+and other kinds, such as words and string constants. For example,
+
+@example
+@group
+---------- Buffer: foo ----------
+(concat@point{} "foo " (car x) y z)
+---------- Buffer: foo ----------
+@end group
+
+@group
+(forward-sexp 3)
+ @result{} nil
+
+---------- Buffer: foo ----------
+(concat "foo " (car x) y@point{} z)
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command backward-sexp arg
+Move backward across @var{arg} balanced expressions.
+@end deffn
+
+@node Skipping Characters
+@comment node-name, next, previous, up
+@subsection Skipping Characters
+@cindex skipping characters
+
+ The following two functions move point over a specified set of
+characters. For example, they are often used to skip whitespace. For
+related functions, see @ref{Motion and Syntax}.
+
+@defun skip-chars-forward character-set &optional limit
+This function moves point in the current buffer forward, skipping over a
+given set of characters. It examines the character following point,
+then advances point if the character matches @var{character-set}. This
+continues until it reaches a character that does not match. The
+function returns @code{nil}.
+
+The argument @var{character-set} is like the inside of a
+@samp{[@dots{}]} in a regular expression except that @samp{]} is never
+special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus,
+@code{"a-zA-Z"} skips over all letters, stopping before the first
+nonletter, and @code{"^a-zA-Z}" skips nonletters stopping before the
+first letter. @xref{Regular Expressions}.
+
+If @var{limit} is supplied (it must be a number or a marker), it
+specifies the maximum position in the buffer that point can be skipped
+to. Point will stop at or before @var{limit}.
+
+In the following example, point is initially located directly before the
+@samp{T}. After the form is evaluated, point is located at the end of
+that line (between the @samp{t} of @samp{hat} and the newline). The
+function skips all letters and spaces, but not newlines.
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(skip-chars-forward "a-zA-Z ")
+ @result{} nil
+
+---------- Buffer: foo ----------
+I read "The cat in the hat@point{}
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defun
+
+@defun skip-chars-backward character-set &optional limit
+This function moves point backward, skipping characters that match
+@var{character-set}, until @var{limit}. It just like
+@code{skip-chars-forward} except for the direction of motion.
+@end defun
+
+@node Excursions
+@section Excursions
+@cindex excursion
+
+ It is often useful to move point ``temporarily'' within a localized
+portion of the program, or to switch buffers temporarily. This is
+called an @dfn{excursion}, and it is done with the @code{save-excursion}
+special form. This construct saves the current buffer and its values of
+point and the mark so they can be restored after the completion of the
+excursion.
+
+ The forms for saving and restoring the configuration of windows are
+described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
+Configurations}).
+
+@defspec save-excursion forms@dots{}
+@cindex mark excursion
+@cindex point excursion
+@cindex current buffer excursion
+The @code{save-excursion} special form saves the identity of the current
+buffer and the values of point and the mark in it, evaluates @var{forms},
+and finally restores the buffer and its saved values of point and the mark.
+All three saved values are restored even in case of an abnormal exit
+via throw or error (@pxref{Nonlocal Exits}).
+
+The @code{save-excursion} special form is the standard way to switch
+buffers or move point within one part of a program and avoid affecting
+the rest of the program. It is used more than 500 times in the Lisp
+sources of Emacs.
+
+@code{save-excursion} does not save the values of point and the mark for
+other buffers, so changes in other buffers remain in effect after
+@code{save-excursion} exits.
+
+@cindex window excursions
+Likewise, @code{save-excursion} does not restore window-buffer
+correspondences altered by functions such as @code{switch-to-buffer}.
+One way to restore these correspondences, and the selected window, is to
+use @code{save-window-excursion} inside @code{save-excursion}
+(@pxref{Window Configurations}).
+
+The value returned by @code{save-excursion} is the result of the last of
+@var{forms}, or @code{nil} if no @var{forms} are given.
+
+@example
+@group
+(save-excursion
+ @var{forms})
+@equiv{}
+(let ((old-buf (current-buffer))
+ (old-pnt (point-marker))
+ (old-mark (copy-marker (mark-marker))))
+ (unwind-protect
+ (progn @var{forms})
+ (set-buffer old-buf)
+ (goto-char old-pnt)
+ (set-marker (mark-marker) old-mark)))
+@end group
+@end example
+@end defspec
+
+@node Narrowing
+@section Narrowing
+@cindex narrowing
+@cindex restriction (in a buffer)
+@cindex accessible portion (of a buffer)
+
+ @dfn{Narrowing} means limiting the text addressable by Emacs editing
+commands to a limited range of characters in a buffer. The text that
+remains addressable is called the @dfn{accessible portion} of the
+buffer.
+
+ Narrowing is specified with two buffer positions which become the
+beginning and end of the accessible portion. For most editing commands
+and most Emacs primitives, these positions replace the values of the
+beginning and end of the buffer. While narrowing is in effect, no text
+outside the accessible portion is displayed, and point cannot move
+outside the accessible portion.
+
+ Values such as positions or line numbers, that usually count from the
+beginning of the buffer, do so despite narrowing, but the functions
+which use them refuse to operate on text that is inaccessible.
+
+ The commands for saving buffers are unaffected by narrowing; they save
+the entire buffer regardless of the any narrowing.
+
+@deffn Command narrow-to-region start end
+This function sets the accessible portion of the current buffer to start
+at @var{start} and end at @var{end}. Both arguments should be character
+positions.
+
+In an interactive call, @var{start} and @var{end} are set to the bounds
+of the current region (point and the mark, with the smallest first).
+@end deffn
+
+@deffn Command narrow-to-page move-count
+This function sets the accessible portion of the current buffer to
+include just the current page. An optional first argument
+@var{move-count} non-@code{nil} means to move forward or backward by
+@var{move-count} pages and then narrow. The variable
+@code{page-delimiter} specifies where pages start and end
+(@pxref{Standard Regexps}).
+
+In an interactive call, @var{move-count} is set to the numeric prefix
+argument.
+@end deffn
+
+@deffn Command widen
+@cindex widening
+This function cancels any narrowing in the current buffer, so that the
+entire contents are accessible. This is called @dfn{widening}.
+It is equivalent to the following expression:
+
+@example
+(narrow-to-region 1 (1+ (buffer-size)))
+@end example
+@end deffn
+
+@defspec save-restriction body@dots{}
+This special form saves the current bounds of the accessible portion,
+evaluates the @var{body} forms, and finally restores the saved bounds,
+thus restoring the same state of narrowing (or absence thereof) formerly
+in effect. The state of narrowing is restored even in the event of an
+abnormal exit via throw or error (@pxref{Nonlocal Exits}). Therefore,
+this construct is a clean way to narrow a buffer temporarily.
+
+The value returned by @code{save-restriction} is that returned by the
+last form in @var{body}, or @code{nil} if no body forms were given.
+
+@c Wordy to avoid overfull hbox. --rjc 16mar92
+@strong{Caution:} it is easy to make a mistake when using the
+@code{save-restriction} construct. Read the entire description here
+before you try it.
+
+If @var{body} changes the current buffer, @code{save-restriction} still
+restores the restrictions on the original buffer (the buffer whose
+restructions it saved from), but it does not restore the identity of the
+current buffer.
+
+@code{save-restriction} does @emph{not} restore point and the mark; use
+@code{save-excursion} for that. If you use both @code{save-restriction}
+and @code{save-excursion} together, @code{save-excursion} should come
+first (on the outside). Otherwise, the old point value would be
+restored with temporary narrowing still in effect. If the old point
+value were outside the limits of the temporary narrowing, this would
+fail to restore it accurately.
+
+The @code{save-restriction} special form records the values of the
+beginning and end of the accessible portion as distances from the
+beginning and end of the buffer. In other words, it records the amount
+of inaccessible text before and after the accessible portion.
+
+This method yields correct results if @var{body} does further narrowing.
+However, @code{save-restriction} can become confused if the body widens
+and then make changes outside the range of the saved narrowing. When
+this is what you want to do, @code{save-restriction} is not the right
+tool for the job. Here is what you must use instead:
+
+@example
+@group
+(let ((beg (point-min-marker))
+ (end (point-max-marker)))
+ (unwind-protect
+ (progn @var{body})
+ (save-excursion
+ (set-buffer (marker-buffer beg))
+ (narrow-to-region beg end))))
+@end group
+@end example
+
+Here is a simple example of correct use of @code{save-restriction}:
+
+@example
+@group
+---------- Buffer: foo ----------
+This is the contents of foo
+This is the contents of foo
+This is the contents of foo@point{}
+---------- Buffer: foo ----------
+@end group
+
+@group
+(save-excursion
+ (save-restriction
+ (goto-char 1)
+ (forward-line 2)
+ (narrow-to-region 1 (point))
+ (goto-char (point-min))
+ (replace-string "foo" "bar")))
+
+---------- Buffer: foo ----------
+This is the contents of bar
+This is the contents of bar
+This is the contents of foo@point{}
+---------- Buffer: foo ----------
+@end group
+@end example
+@end defspec
--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/searching
+@node Searching and Matching, Syntax Tables, Text, Top
+@chapter Searching and Matching
+@cindex searching
+
+ 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 examine the @dfn{match data} to
+determine which text matched the whole regular expression or various
+portions of it.
+
+@menu
+* String Search:: Search for an exact match.
+* Regular Expressions:: Describing classes of strings.
+* Regexp Search:: Searching for a match for a regexp.
+* Search and Replace:: Internals of @code{query-replace}.
+* Match Data:: Finding out which part of the text matched
+ various parts of a regexp, after regexp search.
+* Searching and Case:: Case-independent or case-significant searching.
+* Standard Regexps:: Useful regexps for finding sentences, pages,...
+@end menu
+
+ The @samp{skip-chars@dots{}} functions also perform a kind of searching.
+@xref{Skipping Characters}.
+
+@node String Search
+@section Searching for Strings
+@cindex string search
+
+ 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;
+@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
+is set to 1.
+
+@deffn Command search-forward string &optional limit noerror repeat
+ This function searches forward from point for an exact match for
+@var{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 @var{noerror} (see below).
+@c Emacs 19 feature
+
+ In the following example, point is initially at the beginning of the
+line. Then @code{(search-forward "fox")} moves point after the last
+letter of @samp{fox}:
+
+@example
+@group
+---------- Buffer: foo ----------
+@point{}The quick brown fox jumped over the lazy dog.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(search-forward "fox")
+ @result{} 20
+
+---------- Buffer: foo ----------
+The quick brown fox@point{} jumped over the lazy dog.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+ The argument @var{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 @var{limit} is omitted or @code{nil}, it
+defaults to the end of the accessible portion of the buffer.
+
+@kindex search-failed
+ What happens when the search fails depends on the value of
+@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
+error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
+returns @code{nil} and does nothing. If @var{noerror} is neither
+@code{nil} nor @code{t}, then @code{search-forward} moves point to the
+upper bound and returns @code{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 @code{nil}.)
+
+ If @var{repeat} is non-@code{nil}, then the search is repeated that
+many times. Point is positioned at the end of the last match.
+@end deffn
+
+@deffn Command search-backward string &optional limit noerror repeat
+This function searches backward from point for @var{string}. It is
+just like @code{search-forward} except that it searches backwards and
+leaves point at the beginning of the match.
+@end deffn
+
+@deffn Command word-search-forward string &optional limit noerror repeat
+@cindex word search
+This function searches forward from point for a ``word'' match for
+@var{string}. If it finds a match, it sets point to the end of the
+match found, and returns the new value of point.
+@c Emacs 19 feature
+
+Word matching regards @var{string} as a sequence of words, disregarding
+punctuation that separates them. It searches the buffer for the same
+sequence of words. Each word must be distinct in the buffer (searching
+for the word @samp{ball} does not match the word @samp{balls}), but the
+details of punctuation and spacing are ignored (searching for @samp{ball
+boy} does match @samp{ball. Boy!}).
+
+In this example, point is initially at the beginning of the buffer; the
+search leaves it between the @samp{y} and the @samp{!}.
+
+@example
+@group
+---------- Buffer: foo ----------
+@point{}He said "Please! Find
+the ball boy!"
+---------- Buffer: foo ----------
+@end group
+
+@group
+(word-search-forward "Please find the ball, boy.")
+ @result{} 35
+
+---------- Buffer: foo ----------
+He said "Please! Find
+the ball boy@point{}!"
+---------- Buffer: foo ----------
+@end group
+@end example
+
+If @var{limit} is non-@code{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 @var{noerror} is @code{nil}, then @code{word-search-forward} signals
+an error if the search fails. If @var{noerror} is @code{t}, then it
+returns @code{nil} instead of signaling an error. If @var{noerror} is
+neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
+end of the buffer) and returns @code{nil}.
+
+If @var{repeat} is non-@code{nil}, then the search is repeated that many
+times. Point is positioned at the end of the last match.
+@end deffn
+
+@deffn Command word-search-backward string &optional limit noerror repeat
+This function searches backward from point for a word match to
+@var{string}. This function is just like @code{word-search-forward}
+except that it searches backward and normally leaves point at the
+beginning of the match.
+@end deffn
+
+@node Regular Expressions
+@section Regular Expressions
+@cindex regular expression
+@cindex regexp
+
+ A @dfn{regular expression} (@dfn{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.
+
+@menu
+* Syntax of Regexps:: Rules for writing regular expressions.
+* Regexp Example:: Illustrates regular expression syntax.
+@end menu
+
+@node Syntax of Regexps
+@subsection Syntax of Regular Expressions
+
+ Regular expressions have a syntax in which a few characters are special
+constructs and the rest are @dfn{ordinary}. An ordinary character is a
+simple regular expression which matches that character and nothing else.
+The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
+@samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
+characters will be defined in the future. Any other character appearing
+in a regular expression is ordinary, unless a @samp{\} precedes it.
+
+For example, @samp{f} is not a special character, so it is ordinary, and
+therefore @samp{f} is a regular expression that matches the string
+@samp{f} and no other string. (It does @emph{not} match the string
+@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
+only @samp{o}.@refill
+
+Any two regular expressions @var{a} and @var{b} can be concatenated. The
+result is a regular expression which matches a string if @var{a} matches
+some amount of the beginning of that string and @var{b} matches the rest of
+the string.@refill
+
+As a simple example, we can concatenate the regular expressions @samp{f}
+and @samp{o} to get the regular expression @samp{fo}, which matches only
+the string @samp{fo}. Still trivial. To do something more powerful, you
+need to use one of the special characters. Here is a list of them:
+
+@need 1200
+@table @kbd
+@item .@: @r{(Period)}
+@cindex @samp{.} in regexp
+is a special character that matches any single character except a newline.
+Using concatenation, we can make regular expressions like @samp{a.b}, which
+matches any three-character string that begins with @samp{a} and ends with
+@samp{b}.@refill
+
+@item *
+@cindex @samp{*} in regexp
+is not a construct by itself; it is a suffix operator that means to
+repeat the preceding regular expression as many times as possible. In
+@samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matches
+one @samp{f} followed by any number of @samp{o}s. The case of zero
+@samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill
+
+@samp{*} always applies to the @emph{smallest} possible preceding
+expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
+repeating @samp{fo}.@refill
+
+The matcher processes a @samp{*} construct by matching, immediately,
+as many repetitions as can be found. Then it continues with the rest
+of the pattern. If that fails, backtracking occurs, discarding some
+of the matches of the @samp{*}-modified construct in case that makes
+it possible to match the rest of the pattern. For example, in matching
+@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
+tries to match all three @samp{a}s; but the rest of the pattern is
+@samp{ar} and there is only @samp{r} left to match, so this try fails.
+The next alternative is for @samp{a*} to match only two @samp{a}s.
+With this choice, the rest of the regexp matches successfully.@refill
+
+@item +
+@cindex @samp{+} in regexp
+is a suffix operator similar to @samp{*} except that the preceding
+expression must match at least once. So, for example, @samp{ca+r}
+matches the strings @samp{car} and @samp{caaaar} but not the string
+@samp{cr}, whereas @samp{ca*r} matches all three strings.
+
+@item ?
+@cindex @samp{?} in regexp
+is a suffix operator similar to @samp{*} except that the preceding
+expression can match either once or not at all. For example,
+@samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anyhing
+else.
+
+@item [ @dots{} ]
+@cindex character set (in regexp)
+@cindex @samp{[} in regexp
+@cindex @samp{]} in regexp
+@samp{[} begins a @dfn{character set}, which is terminated by a
+@samp{]}. In the simplest case, the characters between the two brackets
+form the set. Thus, @samp{[ad]} matches either one @samp{a} or one
+@samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s
+and @samp{d}s (including the empty string), from which it follows that
+@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
+@samp{caddaar}, etc.@refill
+
+The usual regular expression special characters are not special inside a
+character set. A completely different set of special characters exists
+inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
+
+@samp{-} is used for ranges of characters. To write a range, write two
+characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
+lower case letter. Ranges may be intermixed freely with individual
+characters, as in @samp{[a-z$%.]}, which matches any lower case letter
+or @samp{$}, @samp{%} or a period.@refill
+
+To include a @samp{]} in a character set, make it the first character.
+For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a
+@samp{-}, write @samp{-} as the first character in the set, or put
+immediately after a range. (You can replace one individual character
+@var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the
+@samp{-}). There is no way to write a set containing just @samp{-} and
+@samp{]}.
+
+To include @samp{^} in a set, put it anywhere but at the beginning of
+the set.
+
+@item [^ @dots{} ]
+@cindex @samp{^} in regexp
+@samp{[^} begins a @dfn{complement character set}, which matches any
+character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
+matches all characters @emph{except} letters and digits.@refill
+
+@samp{^} is not special in a character set unless it is the first
+character. The character following the @samp{^} is treated as if it
+were first (thus, @samp{-} and @samp{]} are not special there).
+
+Note that a complement character set can match a newline, unless
+newline is mentioned as one of the characters not to match.
+
+@item ^
+@cindex @samp{^} in regexp
+@cindex beginning of line in regexp
+is a special character that matches the empty string, but only at
+the beginning of a line in the text being matched. Otherwise it fails
+to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
+at the beginning of a line.
+
+When matching a string, @samp{^} matches at the beginning of the string
+or after a newline character @samp{\n}.
+
+@item $
+@cindex @samp{$} in regexp
+is similar to @samp{^} but matches only at the end of a line. Thus,
+@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
+
+When matching a string, @samp{$} matches at the end of the string
+or before a newline character @samp{\n}.
+
+@item \
+@cindex @samp{\} in regexp
+has two functions: it quotes the special characters (including
+@samp{\}), and it introduces additional special constructs.
+
+Because @samp{\} quotes special characters, @samp{\$} is a regular
+expression which matches only @samp{$}, and @samp{\[} is a regular
+expression which matches only @samp{[}, and so on.
+
+Note that @samp{\} also has special meaning in the read syntax of Lisp
+strings (@pxref{String Type}), and must be quoted with @samp{\}. For
+example, the regular expression that matches the @samp{\} character is
+@samp{\\}. To write a Lisp string that contains the characters
+@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
+@samp{\}. Therefore, the read syntax for a regular expression matching
+@samp{\} is @code{"\\\\"}.@refill
+@end table
+
+@strong{Please note:} for historical compatibility, special characters
+are treated as ordinary ones if they are in contexts where their special
+meanings make no sense. For example, @samp{*foo} treats @samp{*} as
+ordinary since there is no preceding expression on which the @samp{*}
+can act. It is poor practice to depend on this behavior; better to
+quote the special character anyway, regardless of where it
+appears.@refill
+
+For the most part, @samp{\} followed by any character matches only
+that character. However, there are several exceptions: characters
+which, when preceded by @samp{\}, are special constructs. Such
+characters are always ordinary when encountered on their own. Here
+is a table of @samp{\} constructs:
+
+@table @kbd
+@item \|
+@cindex @samp{|} in regexp
+@cindex regexp alternative
+specifies an alternative.
+Two regular expressions @var{a} and @var{b} with @samp{\|} in
+between form an expression that matches anything that either @var{a} or
+@var{b} matches.@refill
+
+Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
+but no other string.@refill
+
+@samp{\|} applies to the largest possible surrounding expressions. Only a
+surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
+@samp{\|}.@refill
+
+Full backtracking capability exists to handle multiple uses of @samp{\|}.
+
+@item \( @dots{} \)
+@cindex @samp{(} in regexp
+@cindex @samp{)} in regexp
+@cindex regexp grouping
+is a grouping construct that serves three purposes:
+
+@enumerate
+@item
+To enclose a set of @samp{\|} alternatives for other operations.
+Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
+
+@item
+To enclose an expression for a suffix operator such as @samp{*} to act
+on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any
+(zero or more) number of @samp{na} strings.@refill
+
+@item
+To record a matched substring for future reference.
+@end enumerate
+
+This last application is not a consequence of the idea of a
+parenthetical grouping; it is a separate feature which happens to be
+assigned as a second meaning to the same @samp{\( @dots{} \)} construct
+because there is no conflict in practice between the two meanings.
+Here is an explanation of this feature:
+
+@item \@var{digit}
+matches the same text which matched the @var{digit}th occurrence of a
+@samp{\( @dots{} \)} construct.
+
+In other words, after the end of a @samp{\( @dots{} \)} construct. the
+matcher remembers the beginning and end of the text matched by that
+construct. Then, later on in the regular expression, you can use
+@samp{\} followed by @var{digit} to match that same text, whatever it
+may have been.
+
+The strings matching the first nine @samp{\( @dots{} \)} constructs
+appearing in a regular expression are assigned numbers 1 through 9 in
+the order that the open parentheses appear in the regular expression.
+So you can use @samp{\1} through @samp{\9} to refer to the text matched
+by the corresponding @samp{\( @dots{} \)} constructs.
+
+For example, @samp{\(.*\)\1} matches any newline-free string that is
+composed of two identical halves. The @samp{\(.*\)} matches the first
+half, which may be anything, but the @samp{\1} that follows must match
+the same exact text.
+
+@item \w
+@cindex @samp{\w} in regexp
+matches any word-constituent character. The editor syntax table
+determines which characters these are. @xref{Syntax Tables}.
+
+@item \W
+@cindex @samp{\W} in regexp
+matches any character that is not a word-constituent.
+
+@item \s@var{code}
+@cindex @samp{\s} in regexp
+matches any character whose syntax is @var{code}. Here @var{code} is a
+character which represents a syntax code: thus, @samp{w} for word
+constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
+etc. @xref{Syntax Tables}, for a list of syntax codes and the
+characters that stand for them.
+
+@item \S@var{code}
+@cindex @samp{\S} in regexp
+matches any character whose syntax is not @var{code}.
+@end table
+
+ These regular expression constructs match the empty string---that is,
+they don't use up any characters---but whether they match depends on the
+context.
+
+@table @kbd
+@item \`
+@cindex @samp{\`} in regexp
+matches the empty string, but only at the beginning
+of the buffer or string being matched against.
+
+@item \'
+@cindex @samp{\'} in regexp
+matches the empty string, but only at the end of
+the buffer or string being matched against.
+
+@item \=
+@cindex @samp{\=} in regexp
+matches the empty string, but only at point.
+(This construct is not defined when matching against a string.)
+
+@item \b
+@cindex @samp{\b} in regexp
+matches the empty string, but only at the beginning or
+end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
+@samp{foo} as a separate word. @samp{\bballs?\b} matches
+@samp{ball} or @samp{balls} as a separate word.@refill
+
+@item \B
+@cindex @samp{\B} in regexp
+matches the empty string, but @emph{not} at the beginning or
+end of a word.
+
+@item \<
+@cindex @samp{\<} in regexp
+matches the empty string, but only at the beginning of a word.
+
+@item \>
+@cindex @samp{\>} in regexp
+matches the empty string, but only at the end of a word.
+@end table
+
+@kindex invalid-regexp
+ Not every string is a valid regular expression. For example, a string
+with unbalanced square brackets is invalid (with a few exceptions, such
+as @samp{[]]}, and so is a string that ends with a single @samp{\}. If
+an invalid regular expression is passed to any of the search functions,
+an @code{invalid-regexp} error is signaled.
+
+@defun regexp-quote string
+This function returns a regular expression string that matches exactly
+@var{string} and nothing else. This allows you to request an exact
+string match when calling a function that wants a regular expression.
+
+@example
+@group
+(regexp-quote "^The cat$")
+ @result{} "\\^The cat\\$"
+@end group
+@end example
+
+One use of @code{regexp-quote} is to combine an exact string match with
+context described as a regular expression. For example, this searches
+for the string which is the value of @code{string}, surrounded by
+whitespace:
+
+@example
+@group
+(re-search-forward
+ (concat "\\s " (regexp-quote string) "\\s "))
+@end group
+@end example
+@end defun
+
+@node Regexp Example
+@comment node-name, next, previous, up
+@subsection Complex Regexp Example
+
+ Here is a complicated regexp, used by Emacs to recognize the end of a
+sentence together with any whitespace that follows. It is the value of
+the variable @code{sentence-end}.
+
+ First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters. The string constant begins and ends with a
+double-quote. @samp{\"} stands for a double-quote as part of the
+string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
+tab and @samp{\n} for a newline.
+
+@example
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+@end example
+
+ In contrast, if you evaluate the variable @code{sentence-end}, you
+will see the following:
+
+@example
+@group
+sentence-end
+@result{}
+"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
+]*"
+@end group
+@end example
+
+@noindent
+In this output, tab and newline appear as themselves.
+
+ This regular expression contains four parts in succession and can be
+deciphered as follows:
+
+@table @code
+@item [.?!]
+The first part of the pattern consists of three characters, a period, a
+question mark and an exclamation mark, within square brackets. The
+match must begin with one of these three characters.
+
+@item []\"')@}]*
+The second part of the pattern matches any closing braces and quotation
+marks, zero or more of them, that may follow the period, question mark
+or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
+a string. The @samp{*} at the end indicates that the immediately
+preceding regular expression (a character set, in this case) may be
+repeated zero or more times.
+
+@item \\($\\|@ \\|\t\\|@ @ \\)
+The third part of the pattern matches the whitespace that follows the
+end of a sentence: the end of a line, or a tab, or two spaces. The
+double backslashes mark the parentheses and vertical bars as regular
+expression syntax; the parentheses mark the group and the vertical bars
+separate alternatives. The dollar sign is used to match the end of a
+line.
+
+@item [ \t\n]*
+Finally, the last part of the pattern matches any additional whitespace
+beyond the minimum needed to end a sentence.
+@end table
+
+@node Regexp Search
+@section Regular Expression Searching
+@cindex regular expression searching
+@cindex regexp searching
+@cindex searching for regexp
+
+ In GNU Emacs, you can search for the next match for a regexp either
+incrementally or not. For incremental search commands, see @ref{Regexp
+Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
+we describe only the search functions useful in programs. The principal
+one is @code{re-search-forward}.
+
+@deffn Command re-search-forward regexp &optional limit noerror repeat
+This function searches forward in the current buffer for a string of
+text that is matched by the regular expression @var{regexp}. The
+function skips over any amount of text that is not matched by
+@var{regexp}, and leaves point at the end of the first match found.
+It returns the new value of point.
+
+If @var{limit} is non-@code{nil} (it must be a position in the current
+buffer), then it is the upper bound to the search. No match extending
+after that position is accepted.
+
+What happens when the search fails depends on the value of
+@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
+error is signaled. If @var{noerror} is @code{t},
+@code{re-search-forward} does nothing and returns @code{nil}. If
+@var{noerror} is neither @code{nil} nor @code{t}, then
+@code{re-search-forward} moves point to @var{limit} (or the end of the
+buffer) and returns @code{nil}.
+
+If @var{repeat} is supplied (it must be a positive number), then the
+search is repeated that many times (each time starting at the end of the
+previous time's match). If these successive searches succeed, the
+function succeeds, moving point and returning its new value. Otherwise
+the search fails.
+
+In the following example, point is initially before the @samp{T}.
+Evaluating the search call moves point to the end of that line (between
+the @samp{t} of @samp{hat} and the newline).
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(re-search-forward "[a-z]+" nil t 5)
+ @result{} 27
+
+---------- Buffer: foo ----------
+I read "The cat in the hat@point{}
+comes back" twice.
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command re-search-backward regexp &optional limit noerror repeat
+This function searches backward in the current buffer for a string of
+text that is matched by the regular expression @var{regexp}, leaving
+point at the beginning of the first text found.
+
+This function is analogous to @code{re-search-forward}, but they are
+not simple mirror images. @code{re-search-forward} finds the match
+whose beginning is as close as possible. If @code{re-search-backward}
+were a perfect mirror image, it would find the match whose end is as
+close as possible. However, in fact it finds the match whose beginning
+is as close as possible. The reason is that matching a regular
+expression at a given spot always works from beginning to end, and is
+done at a specified beginning position.
+
+A true mirror-image of @code{re-search-forward} would require a special
+feature for matching regexps from end to beginning. It's not worth the
+trouble of implementing that.
+@end deffn
+
+@defun string-match regexp string &optional start
+This function returns the index of the start of the first match for
+the regular expression @var{regexp} in @var{string}, or @code{nil} if
+there is no match. If @var{start} is non-@code{nil}, the search starts
+at that index in @var{string}.
+
+For example,
+
+@example
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly.")
+ @result{} 4
+@end group
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ @result{} 27
+@end group
+@end example
+
+@noindent
+The index of the first character of the
+string is 0, the index of the second character is 1, and so on.
+
+After this function returns, the index of the first character beyond
+the match is available as @code{(match-end 0)}. @xref{Match Data}.
+
+@example
+@group
+(string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ @result{} 27
+@end group
+
+@group
+(match-end 0)
+ @result{} 32
+@end group
+@end example
+@end defun
+
+@defun looking-at regexp
+This function determines whether the text in the current buffer directly
+following point matches the regular expression @var{regexp}. ``Directly
+following'' means precisely that: the search is ``anchored'' and it can
+succeed only starting with the first character following point. The
+result is @code{t} if so, @code{nil} otherwise.
+
+This function does not move point, but it updates the match data, which
+you can access using @code{match-beginning} and @code{match-end}.
+@xref{Match Data}.
+
+In this example, point is located directly before the @samp{T}. If it
+were anywhere else, the result would be @code{nil}.
+
+@example
+@group
+---------- Buffer: foo ----------
+I read "@point{}The cat in the hat
+comes back" twice.
+---------- Buffer: foo ----------
+
+(looking-at "The cat in the hat$")
+ @result{} t
+@end group
+@end example
+@end defun
+
+@ignore
+@deffn Command delete-matching-lines regexp
+This function is identical to @code{delete-non-matching-lines}, save
+that it deletes what @code{delete-non-matching-lines} keeps.
+
+In the example below, point is located on the first line of text.
+
+@example
+@group
+---------- Buffer: foo ----------
+We hold these truths
+to be self-evident,
+that all men are created
+equal, and that they are
+---------- Buffer: foo ----------
+@end group
+
+@group
+(delete-matching-lines "the")
+ @result{} nil
+
+---------- Buffer: foo ----------
+to be self-evident,
+that all men are created
+---------- Buffer: foo ----------
+@end group
+@end example
+@end deffn
+
+@deffn Command flush-lines regexp
+This function is the same as @code{delete-matching-lines}.
+@end deffn
+
+@defun delete-non-matching-lines regexp
+This function deletes all lines following point which don't
+contain a match for the regular expression @var{regexp}.
+@end defun
+
+@deffn Command keep-lines regexp
+This function is the same as @code{delete-non-matching-lines}.
+@end deffn
+
+@deffn Command how-many regexp
+This function counts the number of matches for @var{regexp} there are in
+the current buffer following point. It prints this number in
+the echo area, returning the string printed.
+@end deffn
+
+@deffn Command count-matches regexp
+This function is a synonym of @code{how-many}.
+@end deffn
+
+@deffn Command list-matching-lines regexp nlines
+This function is a synonym of @code{occur}.
+Show all lines following point containing a match for @var{regexp}.
+Display each line with @var{nlines} lines before and after,
+or @code{-}@var{nlines} before if @var{nlines} is negative.
+@var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
+Interactively it is the prefix arg.
+
+The lines are shown in a buffer named @samp{*Occur*}.
+It serves as a menu to find any of the occurrences in this buffer.
+@kbd{C-h m} (@code{describe-mode} in that buffer gives help.
+@end deffn
+
+@defopt list-matching-lines-default-context-lines
+Default value is 0.
+Default number of context lines to include around a @code{list-matching-lines}
+match. A negative number means to include that many lines before the match.
+A positive number means to include that many lines both before and after.
+@end defopt
+@end ignore
+
+@node Search and Replace
+@section Search and Replace
+@cindex replacement
+
+@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
+This function is the guts of @code{query-replace} and related commands.
+It searches for occurrences of @var{from-string} and replaces some or
+all of them. If @var{query-flag} is @code{nil}, it replaces all
+occurrences; otherwise, it asks the user what to do about each one.
+
+If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
+considered a regular expression; otherwise, it must match literally. If
+@var{delimited-flag} is non-@code{nil}, then only replacements
+surrounded by word boundaries are considered.
+
+The argument @var{replacements} specifies what to replace occurrences
+with. If it is a string, that string is used. It can also be a list of
+strings, to be used in cyclic order.
+
+If @var{repeat-count} is non-@code{nil}, it should be an integer, the
+number of occurrences to consider. In this case, @code{perform-replace}
+returns after considering that many occurrences.
+
+Normally, the keymap @code{query-replace-map} defines the possible user
+responses. The argument @var{map}, if non-@code{nil}, is a keymap to
+use instead of @code{query-replace-map}.
+@end defun
+
+@defvar query-replace-map
+This variable holds a special keymap that defines the valid user
+responses for @code{query-replace} and related functions, as well as
+@code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:
+
+@itemize @bullet
+@item
+The ``key bindings'' are not commands, just symbols that are meaningful
+to the functions that use this map.
+
+@item
+Prefix keys are not supported; each key binding must be for a single event
+key sequence. This is because the functions don't use read key sequence to
+get the input; instead, they read a single event and look it up ``by hand.''
+@end itemize
+@end defvar
+
+Here are the meaningful ``bindings'' for @code{query-replace-map}.
+Several of them are meaningful only for @code{query-replace} and
+friends.
+
+@table @code
+@item act
+Do take the action being considered---in other words, ``yes.''
+
+@item skip
+Do not take action for this question---in other words, ``no.''
+
+@item exit
+Answer this question ``no,'' and don't ask any more.
+
+@item act-and-exit
+Answer this question ``yes,'' and don't ask any more.
+
+@item act-and-show
+Answer this question ``yes,'' but show the results---don't advance yet
+to the next question.
+
+@item automatic
+Answer this question and all subsequent questions in the series with
+``yes,'' without further user interaction.
+
+@item backup
+Move back to the previous place that a question was asked about.
+
+@item edit
+Enter a recursive edit to deal with this question---instead of any
+other action that would normally be taken.
+
+@item delete-and-edit
+Delete the text being considered, then enter a recursive edit to replace
+it.
+
+@item recenter
+Redisplay and center the window, then ask the same question again.
+
+@item quit
+Perform a quit right away. Only @code{y-or-n-p} and related functions
+use this answer.
+
+@item help
+Display some help, then ask again.
+@end table
+
+@node Match Data
+@section The Match Data
+@cindex match data
+
+ Emacs keeps track of the positions of the start and end of segments of
+text found during a regular expression search. This means, for example,
+that you can search for a complex pattern, such as a date in an Rmail
+message, and then extract parts of the match under control of the
+pattern.
+
+ Because the match data normally describe the most recent search only,
+you must be careful not to do another search inadvertently between the
+search you wish to refer back to and the use of the match data. If you
+can't avoid another intervening search, you must save and restore the
+match data around it, to prevent it from being overwritten.
+
+@menu
+* Simple Match Data:: Accessing single items of match data,
+ such as where a particular subexpression started.
+* Replacing Match:: Replacing a substring that was matched.
+* Entire Match Data:: Accessing the entire match data at once, as a list.
+* Saving Match Data:: Saving and restoring the match data.
+@end menu
+
+@node Simple Match Data
+@subsection Simple Match Data Access
+
+ This section explains how to use the match data to find the starting
+point or ending point of the text that was matched by a particular
+search, or by a particular parenthetical subexpression of a regular
+expression.
+
+@defun match-beginning count
+This function returns the position of the start of text matched by the
+last regular expression searched for, or a subexpression of it.
+
+The argument @var{count}, a number, specifies a subexpression whose
+start position is the value. If @var{count} is zero, then the value is
+the position of the text matched by the whole regexp. If @var{count} is
+greater than zero, then the value is the position of the beginning of
+the text matched by the @var{count}th subexpression.
+
+Subexpressions of a regular expression are those expressions grouped
+inside of parentheses, @samp{\(@dots{}\)}. The @var{count}th
+subexpression is found by counting occurrences of @samp{\(} from the
+beginning of the whole regular expression. The first subexpression is
+numbered 1, the second 2, and so on.
+
+The value is @code{nil} for a parenthetical grouping inside of a
+@samp{\|} alternative that wasn't used in the match.
+@end defun
+
+@defun match-end count
+This function returns the position of the end of the text that matched
+the last regular expression searched for, or a subexpression of it.
+This function is otherwise similar to @code{match-beginning}.
+@end defun
+
+ Here is an example of using the match data, with a comment showing the
+positions within the text:
+
+@example
+@group
+(string-match "\\(qu\\)\\(ick\\)"
+ "The quick fox jumped quickly.")
+ ;0123456789
+ @result{} 4
+@end group
+
+@group
+(match-beginning 1) ; @r{The beginning of the match}
+ @result{} 4 ; @r{with @samp{qu} is at index 4.}
+@end group
+
+@group
+(match-beginning 2) ; @r{The beginning of the match}
+ @result{} 6 ; @r{with @samp{ick} is at index 6.}
+@end group
+
+@group
+(match-end 1) ; @r{The end of the match}
+ @result{} 6 ; @r{with @samp{qu} is at index 6.}
+
+(match-end 2) ; @r{The end of the match}
+ @result{} 9 ; @r{with @samp{ick} is at index 9.}
+@end group
+@end example
+
+ Here is another example. Point is initially located at the beginning
+of the line. Searching moves point to between the space and the word
+@samp{in}. The beginning of the entire match is at the 9th character of
+the buffer (@samp{T}), and the beginning of the match for the first
+subexpression is at the 13th character (@samp{c}).
+
+@example
+@group
+(list
+ (re-search-forward "The \\(cat \\)")
+ (match-beginning 0)
+ (match-beginning 1))
+ @result{} (t 9 13)
+@end group
+
+@group
+---------- Buffer: foo ----------
+I read "The cat @point{}in the hat comes back" twice.
+ ^ ^
+ 9 13
+---------- Buffer: foo ----------
+@end group
+@end example
+
+@noindent
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)
+
+@node Replacing Match
+@subsection Replacing the Text That Matched
+
+ This function replaces the text matched by the last search with
+@var{replacement}.
+
+@cindex case in replacements
+@defun replace-match replacement &optional fixedcase literal
+This function replaces the buffer text matched by the last search, with
+@var{replacement}. It applies only to buffers; you can't use
+@code{replace-match} to replace a substring found with
+@code{string-match}.
+
+If @var{fixedcase} is non-@code{nil}, then the case of the replacement
+text is not changed; otherwise, the replacement text is converted to a
+different case depending upon the capitalization of the text to be
+replaced. If the original text is all upper case, the replacement text
+is converted to upper case, except when all of the words in the original
+text are only one character long. In that event, the replacement text
+is capitalized. If @emph{any} of the words in the original text is
+capitalized, then all of the words in the replacement text are
+capitalized.
+
+If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
+exactly as it is, the only alterations being case changes as needed.
+If it is @code{nil} (the default), then the character @samp{\} is treated
+specially. If a @samp{\} appears in @var{replacement}, then it must be
+part of one of the following sequences:
+
+@table @asis
+@item @samp{\&}
+@cindex @samp{&} in replacement
+@samp{\&} stands for the entire text being replaced.
+
+@item @samp{\@var{n}}
+@cindex @samp{\@var{n}} in replacement
+@samp{\@var{n}} stands for the text that matched the @var{n}th
+subexpression in the original regexp. Subexpressions are those
+expressions grouped inside of @samp{\(@dots{}\)}. @var{n} is a digit.
+
+@item @samp{\\}
+@cindex @samp{\} in replacement
+@samp{\\} stands for a single @samp{\} in the replacement text.
+@end table
+
+@code{replace-match} leaves point at the end of the replacement text,
+and returns @code{t}.
+@end defun
+
+@node Entire Match Data
+@subsection Accessing the Entire Match Data
+
+ The functions @code{match-data} and @code{set-match-data} read or
+write the entire match data, all at once.
+
+@defun match-data
+This function returns a newly constructed list containing all the
+information on what text the last search matched. Element zero is the
+position of the beginning of the match for the whole expression; element
+one is the position of the end of the match for the expression. The
+next two elements are the positions of the beginning and end of the
+match for the first subexpression, and so on. In general, element
+@ifinfo
+number 2@var{n}
+@end ifinfo
+@tex
+number {\mathsurround=0pt $2n$}
+@end tex
+corresponds to @code{(match-beginning @var{n})}; and
+element
+@ifinfo
+number 2@var{n} + 1
+@end ifinfo
+@tex
+number {\mathsurround=0pt $2n+1$}
+@end tex
+corresponds to @code{(match-end @var{n})}.
+
+All the elements are markers or @code{nil} if matching was done on a
+buffer, and all are integers or @code{nil} if matching was done on a
+string with @code{string-match}. (In Emacs 18 and earlier versions,
+markers were used even for matching on a string, except in the case
+of the integer 0.)
+
+As always, there must be no possibility of intervening searches between
+the call to a search function and the call to @code{match-data} that is
+intended to access the match data for that search.
+
+@example
+@group
+(match-data)
+ @result{} (#<marker at 9 in foo>
+ #<marker at 17 in foo>
+ #<marker at 13 in foo>
+ #<marker at 17 in foo>)
+@end group
+@end example
+@end defun
+
+@defun set-match-data match-list
+This function sets the match data from the elements of @var{match-list},
+which should be a list that was the value of a previous call to
+@code{match-data}.
+
+If @var{match-list} refers to a buffer that doesn't exist, you don't get
+an error; that sets the match data in a meaningless but harmless way.
+
+@findex store-match-data
+@code{store-match-data} is an alias for @code{set-match-data}.
+@end defun
+
+@node Saving Match Data
+@subsection Saving and Restoring the Match Data
+
+ All asynchronous process functions (filters and sentinels) and
+functions that use @code{recursive-edit} should save and restore the
+match data if they do a search or if they let the user type arbitrary
+commands. Saving the match data is useful in other cases as
+well---whenever you want to access the match data resulting from an
+earlier search, notwithstanding another intervening search.
+
+ This example shows the problem that can arise if you fail to
+attend to this requirement:
+
+@example
+@group
+(re-search-forward "The \\(cat \\)")
+ @result{} 48
+(foo) ; @r{Perhaps @code{foo} does}
+ ; @r{more searching.}
+(match-end 0)
+ @result{} 61 ; @r{Unexpected result---not 48!}
+@end group
+@end example
+
+ In Emacs versions 19 and later, you can save and restore the match
+data with @code{save-match-data}:
+
+@defspec save-match-data body@dots{}
+This special form executes @var{body}, saving and restoring the match
+data around it. This is useful if you wish to do a search without
+altering the match data that resulted from an earlier search.
+@end defspec
+
+ You can use @code{set-match-data} together with @code{match-data} to
+imitate the effect of the special form @code{save-match-data}. This is
+useful for writing code that can run in Emacs 18. Here is how:
+
+@example
+@group
+(let ((data (match-data)))
+ (unwind-protect
+ @dots{} ; @r{May change the original match data.}
+ (set-match-data data)))
+@end group
+@end example
+
+@ignore
+ Here is a function which restores the match data provided the buffer
+associated with it still exists.
+
+@smallexample
+@group
+(defun restore-match-data (data)
+@c It is incorrect to split the first line of a doc string.
+@c If there's a problem here, it should be solved in some other way.
+ "Restore the match data DATA unless the buffer is missing."
+ (catch 'foo
+ (let ((d data))
+@end group
+ (while d
+ (and (car d)
+ (null (marker-buffer (car d)))
+@group
+ ;; @file{match-data} @r{buffer is deleted.}
+ (throw 'foo nil))
+ (setq d (cdr d)))
+ (set-match-data data))))
+@end group
+@end smallexample
+@end ignore
+
+@node Searching and Case
+@section Searching and Case
+@cindex searching and case
+
+ By default, searches in Emacs ignore the case of the text they are
+searching through; if you specify searching for @samp{FOO}, then
+@samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
+particular character sets, are included: thus, @samp{[aB]} would match
+@samp{a} or @samp{A} or @samp{b} or @samp{B}.
+
+ If you do not want this feature, set the variable
+@code{case-fold-search} to @code{nil}. Then all letters must match
+exactly, including case. This is a per-buffer-local variable; altering
+the variable affects only the current buffer. (@xref{Intro to
+Buffer-Local}.) Alternatively, you may change the value of
+@code{default-case-fold-search}, which is the default value of
+@code{case-fold-search} for buffers that do not override it.
+
+ Note that the user-level incremental search feature handles case
+distinctions differently. When given a lower case letter, it looks for
+a match of either case, but when given an upper case letter, it looks
+for an upper case letter only. But this has nothing to do with the
+searching functions Lisp functions use.
+
+@defopt case-replace
+This variable determines whether @code{query-replace} should preserve
+case in replacements. If the variable is @code{nil}, then
+@code{replace-match} should not try to convert case.
+@end defopt
+
+@defopt case-fold-search
+This buffer-local variable determines whether searches should ignore
+case. If the variable is @code{nil} they do not ignore case; otherwise
+they do ignore case.
+@end defopt
+
+@defvar default-case-fold-search
+The value of this variable is the default value for
+@code{case-fold-search} in buffers that do not override it. This is the
+same as @code{(default-value 'case-fold-search)}.
+@end defvar
+
+@node Standard Regexps
+@section Standard Regular Expressions Used in Editing
+@cindex regexps used standardly in editing
+@cindex standard regexps used in editing
+
+ This section describes some variables that hold regular expressions
+used for certain purposes in editing:
+
+@defvar page-delimiter
+This is the regexp describing line-beginnings that separate pages. The
+default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"}).
+@end defvar
+
+@defvar paragraph-separate
+This is the regular expression for recognizing the beginning of a line
+that separates paragraphs. (If you change this, you may have to
+change @code{paragraph-start} also.) The default value is @code{"^[
+\t\f]*$"}, which is a line that consists entirely of spaces, tabs, and
+form feeds.
+@end defvar
+
+@defvar paragraph-start
+This is the regular expression for recognizing the beginning of a line
+that starts @emph{or} separates paragraphs. The default value is
+@code{"^[ \t\n\f]"}, which matches a line starting with a space, tab,
+newline, or form feed.
+@end defvar
+
+@defvar sentence-end
+This is the regular expression describing the end of a sentence. (All
+paragraph boundaries also end sentences, regardless.) The default value
+is:
+
+@example
+"[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*"
+@end example
+
+This means a period, question mark or exclamation mark, followed by a
+closing brace, followed by tabs, spaces or new lines.
+
+For a detailed explanation of this regular expression, see @ref{Regexp
+Example}.
+@end defvar
--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/syntax
+@node Syntax Tables, Abbrevs, Searching and Matching, Top
+@chapter Syntax Tables
+@cindex parsing
+@cindex syntax table
+@cindex text parsing
+
+ A @dfn{syntax table} specifies the syntactic textual function of each
+character. This information is used by the parsing commands, the
+complex movement commands, and others to determine where words, symbols,
+and other syntactic constructs begin and end. The current syntax table
+controls the meaning of the word motion functions (@pxref{Word Motion})
+and the list motion functions (@pxref{List Motion}) as well as the
+functions in this chapter.
+
+@menu
+* Basics: Syntax Basics. Basic concepts of syntax tables.
+* Desc: Syntax Descriptors. How characters are classified.
+* Syntax Table Functions:: How to create, examine and alter syntax tables.
+* Motion and Syntax:: Moving over characters with certain syntaxes.
+* Parsing Expressions:: Parsing balanced expressions
+ using the syntax table.
+* Standard Syntax Tables:: Syntax tables used by various major modes.
+* Syntax Table Internals:: How syntax table information is stored.
+@end menu
+
+@node Syntax Basics
+@section Syntax Table Concepts
+
+@ifinfo
+ A @dfn{syntax table} provides Emacs with the information that
+determines the syntactic use of each character in a buffer. This
+information is used by the parsing commands, the complex movement
+commands, and others to determine where words, symbols, and other
+syntactic constructs begin and end. The current syntax table controls
+the meaning of the word motion functions (@pxref{Word Motion}) and the
+list motion functions (@pxref{List Motion}) as well as the functions in
+this chapter.
+@end ifinfo
+
+ A syntax table is a vector of 256 elements; it contains one entry for
+each of the 256 @sc{ASCII} characters of an 8-bit byte. Each element is
+an integer that encodes the syntax of the character in question.
+
+ Syntax tables are used only for moving across text, not for the Emacs
+Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
+expressions, and these rules cannot be changed.
+
+ Each buffer has its own major mode, and each major mode has its own
+idea of the syntactic class of various characters. For example, in Lisp
+mode, the character @samp{;} begins a comment, but in C mode, it
+terminates a statement. To support these variations, Emacs makes the
+choice of syntax table local to each buffer. Typically, each major
+mode has its own syntax table and installs that table in each buffer
+which uses that mode. Changing this table alters the syntax in all
+those buffers as well as in any buffers subsequently put in that mode.
+Occasionally several similar modes share one syntax table.
+@xref{Example Major Modes}, for an example of how to set up a syntax
+table.
+
+A syntax table can inherit the data for some characters from the
+standard syntax table, while specifying other characters itself. The
+``inherit'' syntax class means ``inherit this character's syntax from
+the standard syntax table.'' Most major modes' syntax tables inherit
+the syntax of character codes 0 through 31 and 128 through 255. This is
+useful with character sets such as ISO Latin-1 that have additional
+alphabetic characters in the range 128 to 255. Just changing the
+standard syntax for these characters affects all major modes.
+
+@defun syntax-table-p object
+This function returns @code{t} if @var{object} is a vector of length 256
+elements. This means that the vector may be a syntax table. However,
+according to this test, any vector of length 256 is considered to be a
+syntax table, no matter what its contents.
+@end defun
+
+@node Syntax Descriptors
+@section Syntax Descriptors
+@cindex syntax classes
+
+ This section describes the syntax classes and flags that denote the
+syntax of a character, and how they are represented as a @dfn{syntax
+descriptor}, which is a Lisp string that you pass to
+@code{modify-syntax-entry} to specify the desired syntax.
+
+ Emacs defines a number of @dfn{syntax classes}. Each syntax table
+puts each character into one class. There is no necessary relationship
+between the class of a character in one syntax table and its class in
+any other table.
+
+ Each class is designated by a mnemonic character which serves as the
+name of the class when you need to specify a class. Usually the
+designator character is one which is frequently put in that class;
+however, its meaning as a designator is unvarying and independent of
+what syntax that character currently has.
+
+@cindex syntax descriptor
+ A syntax descriptor is a Lisp string which specifies a syntax class, a
+matching character (used only for the parenthesis classes) and flags.
+The first character is the designator for a syntax class. The second
+character is the character to match; if it is unused, put a space there.
+Then come the characters for any desired flags. If no matching
+character or flags are needed, one character is sufficient.
+
+ For example, the descriptor for the character @samp{*} in C mode is
+@samp{@w{. 23}} (i.e., punctuation, matching character slot unused,
+second character of a comment-starter, first character of an
+comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
+punctuation, matching character slot unused, first character of a
+comment-starter, second character of a comment-ender).
+
+@menu
+* Syntax Class Table:: Table of syntax classes.
+* Syntax Flags:: Additional flags each character can have.
+@end menu
+
+@node Syntax Class Table
+@subsection Table of Syntax Classes
+
+ Here is a table syntax classes, the characters that stand for them,
+their meanings, and examples of their use.
+
+@deffn {Syntax class} @w{whitespace character}
+@dfn{Whitespace characters} (designated with @w{@samp{@ }} or @samp{-})
+separate symbols and words from each other. Typically, whitespace
+characters have no other syntactic significance, and multiple whitespace
+characters are syntactically equivalent to a single one. Space, tab,
+newline and formfeed are almost always classified as whitespace.
+@end deffn
+
+@deffn {Syntax class} @w{word constituent}
+@dfn{Word constituents} (designated with @samp{w}) are parts of normal
+English words and are typically used in variable and command names in
+programs. All upper and lower case letters and the digits are typically
+word constituents.
+@end deffn
+
+@deffn {Syntax class} @w{symbol constituent}
+@dfn{Symbol constituents} (designated with @samp{_}) are the extra
+characters that are used in variable and command names along with word
+constituents. For example, the symbol constituents class is used in
+Lisp mode to indicate that certain characters may be part of symbol
+names even though they are not part of English words. These characters
+are @samp{$&*+-_<>}. In standard C, the only non-word-constituent
+character that is valid in symbols is underscore (@samp{_}).
+@end deffn
+
+@deffn {Syntax class} @w{punctuation character}
+@dfn{Punctuation characters} (@samp{.}) are those characters that are
+used as punctuation in English, or are used in some way in a programming
+language to separate symbols from one another. Most programming
+language modes, including Emacs Lisp mode, have no characters in this
+class since the few characters that are not symbol or word constituents
+all have other uses.
+@end deffn
+
+@deffn {Syntax class} @w{open parenthesis character}
+@deffnx {Syntax class} @w{close parenthesis character}
+@cindex parenthesis syntax
+Open and close @dfn{parenthesis characters} are characters used in
+dissimilar pairs to surround sentences or expressions. Such a grouping
+is begun with an open parenthesis character and terminated with a close.
+Each open parenthesis character matches a particular close parenthesis
+character, and vice versa. Normally, Emacs indicates momentarily the
+matching open parenthesis when you insert a close parenthesis.
+@xref{Blinking}.
+
+The class of open parentheses is designated with @samp{(}, and that of
+close parentheses with @samp{)}.
+
+In English text, and in C code, the parenthesis pairs are @samp{()},
+@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and
+vectors (@samp{()} and @samp{[]}) are classified as parenthesis
+characters.
+@end deffn
+
+@deffn {Syntax class} @w{string quote}
+@dfn{String quote characters} (designated with @samp{"}) are used in
+many languages, including Lisp and C, to delimit string constants. The
+same string quote character appears at the beginning and the end of a
+string. Such quoted strings do not nest.
+
+The parsing facilities of Emacs consider a string as a single token.
+The usual syntactic meanings of the characters in the string are
+suppressed.
+
+The Lisp modes have two string quote characters: double-quote (@samp{"})
+and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it
+is used in Common Lisp. C also has two string quote characters:
+double-quote for strings, and single-quote (@samp{'}) for character
+constants.
+
+English text has no string quote characters because English is not a
+programming language. Although quotation marks are used in English,
+we do not want them to turn off the usual syntactic properties of
+other characters in the quotation.
+@end deffn
+
+@deffn {Syntax class} @w{escape}
+An @dfn{escape character} (designated with @samp{\}) starts an escape
+sequence such as is used in C string and character constants. The
+character @samp{\} belongs to this class in both C and Lisp. (In C, it
+is used thus only inside strings, but it turns out to cause no trouble
+to treat it this way throughout C code.)
+
+Characters in this class count as part of words if
+@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
+@end deffn
+
+@deffn {Syntax class} @w{character quote}
+A @dfn{character quote character} (designated with @samp{/}) quotes the
+following character so that it loses its normal syntactic meaning. This
+differs from an escape character in that only the character immediately
+following is ever affected.
+
+Characters in this class count as part of words if
+@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}.
+
+This class is not currently used in any standard Emacs modes.
+@end deffn
+
+@deffn {Syntax class} @w{paired delimiter}
+@dfn{Paired delimiter characters} (designated with @samp{$}) are like
+string quote characters except that the syntactic properties of the
+characters between the delimiters are not suppressed. Only @TeX{} mode
+uses a paired identical delimiter presently---the @samp{$} that both
+enters and leaves math mode.
+@end deffn
+
+@deffn {Syntax class} @w{expression prefix}
+An @dfn{expression prefix operator} (designated with @samp{'}) is used
+for syntactic operators that are part of an expression if they appear
+next to one. These characters in Lisp include the apostrophe, @samp{'}
+(used for quoting), the comma, @samp{,} (used in macros), and @samp{#}
+(used in the read syntax for certain data types).
+@end deffn
+
+@deffn {Syntax class} @w{comment starter}
+@deffnx {Syntax class} @w{comment ender}
+@cindex comment syntax
+The @dfn{comment starter} and @dfn{comment ender} characters are used in
+various languages to delimit comments. These classes are designated
+with @samp{<} and @samp{>}, respectively.
+
+English text has no comment characters. In Lisp, the semicolon
+(@samp{;}) starts a comment and a newline or formfeed ends one.
+@end deffn
+
+@deffn {Syntax class} @w{inherit}
+This syntax class does not specify a syntax. It says to look in the
+standard syntax table to find the syntax of this character. The
+designator for this syntax code is @samp{@@}.
+@end deffn
+
+@node Syntax Flags
+@subsection Syntax Flags
+@cindex syntax flags
+
+ In addition to the classes, entries for characters in a syntax table
+can include flags. There are six possible flags, represented by the
+characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b} and
+@samp{p}.
+
+ All the flags except @samp{p} are used to describe multi-character
+comment delimiters. The digit flags indicate that a character can
+@emph{also} be part of a comment sequence, in addition to the syntactic
+properties associated with its character class. The flags are
+independent of the class and each other for the sake of characters such
+as @samp{*} in C mode, which is a punctuation character, @emph{and} the
+second character of a start-of-comment sequence (@samp{/*}), @emph{and}
+the first character of an end-of-comment sequence (@samp{*/}).
+
+The flags for a character @var{c} are:
+
+@itemize @bullet
+@item
+@samp{1} means @var{c} is the start of a two-character comment start
+sequence.
+
+@item
+@samp{2} means @var{c} is the second character of such a sequence.
+
+@item
+@samp{3} means @var{c} is the start of a two-character comment end
+sequence.
+
+@item
+@samp{4} means @var{c} is the second character of such a sequence.
+
+@item
+@c Emacs 19 feature
+@samp{b} means that @var{c} as a comment delimiter belongs to the
+alternative ``b'' comment style.
+
+Emacs supports two comment styles simultaneously in any one syntax
+table. This is for the sake of C++. Each style of comment syntax has
+its own comment-start sequence and its own comment-end sequence. Each
+comment must stick to one style or the other; thus, if it starts with
+the comment-start sequence of style ``b'', it must also end with the
+comment-end sequence of style ``b''.
+
+The two comment-start sequences must begin with the same character; only
+the second character may differ. Mark the second character of the
+``b''-style comment start sequence with the @samp{b} flag.
+
+A comment-end sequence (one or two characters) applies to the ``b''
+style if its first character has the @samp{b} flag set; otherwise, it
+applies to the ``a'' style.
+
+The appropriate comment syntax settings for C++ are as follows:
+
+@table @asis
+@item @samp{/}
+@samp{124b}
+@item @samp{*}
+@samp{23}
+@item newline
+@samp{>b}
+@end table
+
+Thus @samp{/*} is a comment-start sequence for ``a'' style, @samp{//}
+is a comment-start sequence for ``b'' style, @samp{*/} is a
+comment-end sequence for ``a'' style, and newline is a comment-end
+sequence for ``b'' style.
+
+@item
+@c Emacs 19 feature
+@samp{p} identifies an additional ``prefix character'' for Lisp syntax.
+These characters are treated as whitespace when they appear between
+expressions. When they appear within an expression, they are handled
+according to their usual syntax codes.
+
+The function @code{backward-prefix-chars} moves back over these
+characters, as well as over characters whose primary syntax class is
+prefix (@samp{'}). @xref{Motion and Syntax}.
+@end itemize
+
+@node Syntax Table Functions
+@section Syntax Table Functions
+
+ In this section we describe functions for creating, accessing and
+altering syntax tables.
+
+@defun make-syntax-table
+This function creates a new syntax table. Character codes 0 through
+31, and 128 through 255, are set up to inherit from the standard syntax
+table. The other character codes are set up by copying what the
+standard syntax table says about them.
+
+Most major mode syntax tables are created in this way.
+@end defun
+
+@defun copy-syntax-table &optional table
+This function constructs a copy of @var{table} and returns it. If
+@var{table} is not supplied (or is @code{nil}), it returns a copy of the
+current syntax table. Otherwise, an error is signaled if @var{table} is
+not a syntax table.
+@end defun
+
+@deffn Command modify-syntax-entry char syntax-descriptor &optional table
+This function sets the syntax entry for @var{char} according to
+@var{syntax-descriptor}. The syntax is changed only for @var{table},
+which defaults to the current buffer's syntax table, and not in any
+other syntax table. The argument @var{syntax-descriptor} specifies the
+desired syntax; this is a string beginning with a class designator
+character, and optionally containing a matching character and flags as
+well. @xref{Syntax Descriptors}.
+
+This function always returns @code{nil}. The old syntax information in
+the table for this character is discarded.
+
+An error is signaled if the first character of the syntax descriptor is not
+one of the twelve syntax class designator characters. An error is also
+signaled if @var{char} is not a character.
+
+@example
+@group
+@exdent @r{Examples:}
+
+;; @r{Put the space character in class whitespace.}
+(modify-syntax-entry ?\ " ")
+ @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{$} an open parenthesis character,}
+;; @r{with @samp{^} as its matching close.}
+(modify-syntax-entry ?$ "(^")
+ @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{^} a close parenthesis character,}
+;; @r{with @samp{$} as its matching open.}
+(modify-syntax-entry ?^ ")$")
+ @result{} nil
+@end group
+
+@group
+;; @r{Make @samp{/} a punctuation character,}
+;; @r{the first character of a start-comment sequence,}
+;; @r{and the second character of an end-comment sequence.}
+;; @r{This is used in C mode.}
+(modify-syntax-entry ?/ ".13")
+ @result{} nil
+@end group
+@end example
+@end deffn
+
+@defun char-syntax character
+This function returns the syntax class of @var{character}, represented
+by its mnemonic designator character. This @emph{only} returns the
+class, not any matching parenthesis or flags.
+
+An error is signaled if @var{char} is not a character.
+
+The following examples apply to C mode. The first example shows that
+the syntax class of space is whitespace (represented by a space). The
+second example shows that the syntax of @samp{/} is punctuation. This
+does not show the fact that it is also part of comment start and end
+sequence. The third example shows that open parenthesis is in the class
+of open parentheses. This does not show the fact that it has a matching
+character, @samp{)}.
+
+@example
+@group
+(char-to-string (char-syntax ?\ ))
+ @result{} " "
+@end group
+
+@group
+(char-to-string (char-syntax ?/))
+ @result{} "."
+@end group
+
+@group
+(char-to-string (char-syntax ?\())
+ @result{} "("
+@end group
+@end example
+@end defun
+
+@defun set-syntax-table table
+This function makes @var{table} the syntax table for the current buffer.
+It returns @var{table}.
+@end defun
+
+@defun syntax-table
+This function returns the current syntax table, which is the table for
+the current buffer.
+@end defun
+
+@node Motion and Syntax
+@section Motion and Syntax
+
+ This section describes functions for moving across characters in
+certain syntax classes. None of these functions exists in Emacs
+version 18 or earlier.
+
+@defun skip-syntax-forward syntaxes &optional limit
+This function moves point forward across characters having syntax classes
+mentioned in @var{syntaxes}. It stops when it encounters the end of
+the buffer, or position @var{lim} (if specified), or a character it is
+not supposed to skip.
+@ignore @c may want to change this.
+The return value is the distance traveled, which is a nonnegative
+integer.
+@end ignore
+@end defun
+
+@defun skip-syntax-backward syntaxes &optional limit
+This function moves point backward across characters whose syntax
+classes are mentioned in @var{syntaxes}. It stops when it encounters
+the beginning of the buffer, or position @var{lim} (if specified), or a
+character it is not supposed to skip.
+@ignore @c may want to change this.
+The return value indicates the distance traveled. It is an integer that
+is zero or less.
+@end ignore
+@end defun
+
+@defun backward-prefix-chars
+This function moves point backward over any number of characters with
+expression prefix syntax. This includes both characters in the
+expression prefix syntax class, and characters with the @samp{p} flag.
+@end defun
+
+@node Parsing Expressions
+@section Parsing Balanced Expressions
+
+ Here are several functions for parsing and scanning balanced
+expressions, also known as @dfn{sexps}, in which parentheses match in
+pairs. The syntax table controls the interpretation of characters, so
+these functions can be used for Lisp expressions when in Lisp mode and
+for C expressions when in C mode. @xref{List Motion}, for convenient
+higher-level functions for moving over balanced expressions.
+
+@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
+This function parses a sexp in the current buffer starting at
+@var{start}, not scanning past @var{limit}. It stops at @var{limit} or
+when certain criteria described below are met, and sets to the location
+where parsing stops. It returns a value describing the status of the
+parse at the point where it stops.
+
+If @var{state} is @code{nil}, @var{start} is assumed to be at the top
+level of parenthesis structure, such as the beginning of a function
+definition. Alternatively, you might wish to resume parsing in the
+middle of the structure. To do this, you must provide a @var{state}
+argument that describes the initial status of parsing.
+
+@cindex parenthesis depth
+If the third argument @var{target-depth} is non-@code{nil}, parsing
+stops if the depth in parentheses becomes equal to @var{target-depth}.
+The depth starts at 0, or at whatever is given in @var{state}.
+
+If the fourth argument @var{stop-before} is non-@code{nil}, parsing
+stops when it comes to any character that starts a sexp. If
+@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
+start of a comment.
+
+@cindex parse state
+The fifth argument @var{state} is an eight-element list of the same
+form as the value of this function, described below. The return value
+of one call may be used to initialize the state of the parse on another
+call to @code{parse-partial-sexp}.
+
+The result is a list of eight elements describing the final state of
+the parse:
+
+@enumerate 0
+@item
+The depth in parentheses, counting from 0.
+
+@item
+@cindex innermost containing parentheses
+The character position of the start of the innermost containing
+parenthetical grouping; @code{nil} if none.
+
+@item
+@cindex previous complete subexpression
+The character position of the start of the last complete subexpression
+terminated; @code{nil} if none.
+
+@item
+@cindex inside string
+Non-@code{nil} if inside a string. More precisely, this is the
+character that will terminate the string.
+
+@item
+@cindex inside comment
+@code{t} if inside a comment.
+
+@item
+@cindex quote character
+@code{t} if point is just after a quote character.
+
+@item
+The minimum parenthesis depth encountered during this scan.
+
+@item
+@code{t} if inside a comment of style ``b''.
+@end enumerate
+
+Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
+
+@cindex indenting with parentheses
+This function is most often used to compute indentation for languages
+that have nested parentheses.
+@end defun
+
+@defun scan-lists from count depth
+This function scans forward @var{count} balanced parenthetical groupings
+from character number @var{from}. It returns the character position
+where the scan stops.
+
+If @var{depth} is nonzero, parenthesis depth counting begins from that
+value. The only candidates for stopping are places where the depth in
+parentheses becomes zero; @code{scan-lists} counts @var{count} such
+places and then stops. Thus, a positive value for @var{depth} means go
+out levels of parenthesis.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{nil}.
+
+If scan reaches the beginning or end of the buffer (or its accessible
+portion), and the depth is not zero, an error is signaled. If the depth
+is zero but the count is not used up, @code{nil} is returned.
+@end defun
+
+@defun scan-sexps from count
+This function scans forward @var{count} sexps from character position
+@var{from}. It returns the character position where the scan stops.
+
+Scanning ignores comments if @code{parse-sexp-ignore-comments} is
+non-@code{nil}.
+
+If scan reaches the beginning or end of (the accessible part of) the
+buffer in the middle of a parenthetical grouping, an error is signaled.
+If it reaches the beginning or end between groupings but before count is
+used up, @code{nil} is returned.
+@end defun
+
+@defvar parse-sexp-ignore-comments
+@cindex skipping comments
+If the value is non-@code{nil}, then comments are treated as
+whitespace by the functions in this section and by @code{forward-sexp}.
+
+In older Emacs versions, this feature worked only when the comment
+terminator is something like @samp{*/}, and appears only to end a
+comment. In languages where newlines terminate comments, it was
+necessary make this variable @code{nil}, since not every newline is the
+end of a comment. This limitation no longer exists.
+@end defvar
+
+You can use @code{forward-comment} to move forward or backward over
+one comment or several comments.
+
+@defun forward-comment count
+This function moves point forward across @var{count} comments (backward,
+if @var{count} is negative). If it finds anything other than a comment
+or whitespace, it stops, leaving point at the place where it stopped.
+It also stops after satisfying @var{count}.
+@end defun
+
+To move forward over all comments and whitespace following point, use
+@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good
+argument to use, because the number of comments to in the buffer cannot
+exceed that many.
+
+@node Standard Syntax Tables
+@section Some Standard Syntax Tables
+
+ Each of the major modes in Emacs has its own syntax table. Here are
+several of them:
+
+@defun standard-syntax-table
+This function returns the standard syntax table, which is the syntax
+table used in Fundamental mode.
+@end defun
+
+@defvar text-mode-syntax-table
+The value of this variable is the syntax table used in Text mode.
+@end defvar
+
+@defvar c-mode-syntax-table
+The value of this variable is the syntax table for C-mode buffers.
+@end defvar
+
+@defvar emacs-lisp-mode-syntax-table
+The value of this variable is the syntax table used in Emacs Lisp mode
+by editing commands. (It has no effect on the Lisp @code{read}
+function.)
+@end defvar
+
+@node Syntax Table Internals
+@section Syntax Table Internals
+@cindex syntax table internals
+
+ Each element of a syntax table is an integer that encodes the syntax
+of one character: the syntax class, possible matching character, and
+flags. Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(@pxref{Syntax Descriptors}).
+
+ The low 8 bits of each element of a syntax table indicate the
+syntax class.
+
+@table @asis
+@item @i{Integer}
+@i{Class}
+@item 0
+whitespace
+@item 1
+punctuation
+@item 2
+word
+@item 3
+symbol
+@item 4
+open parenthesis
+@item 5
+close parenthesis
+@item 6
+expression prefix
+@item 7
+string quote
+@item 8
+paired delimiter
+@item 9
+escape
+@item 10
+character quote
+@item 11
+comment-start
+@item 12
+comment-end
+@item 13
+inherit
+@end table
+
+ The next 8 bits are the matching opposite parenthesis (if the
+character has parenthesis syntax); otherwise, they are not meaningful.
+The next 6 bits are the flags.
--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/tips
+@node Tips, GNU Emacs Internals, Calendar, Top
+@appendix Tips and Standards
+@cindex tips
+@cindex standards of coding style
+@cindex coding standards
+
+ This chapter describes no additional features of Emacs Lisp.
+Instead it gives advice on making effective use of the features described
+in the previous chapters.
+
+@menu
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
+@end menu
+
+@node Style Tips
+@section Writing Clean Lisp Programs
+
+ Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+@itemize @bullet
+@item
+Since all global variables share the same name space, and all functions
+share another name space, you should choose a short word to distinguish
+your program from other Lisp programs. Then take care to begin the
+names of all global variables, constants, and functions with the chosen
+prefix. This helps avoid name conflicts.
+
+This recommendation applies even to names for traditional Lisp
+primitives that are not primitives in Emacs Lisp---even to @code{cadr}.
+Believe it or not, there is more than one plausible way to define
+@code{cadr}. Play it safe; append your name prefix to produce a name
+like @code{foo-cadr} or @code{mylib-cadr} instead.
+
+If you write a function that you think ought to be added to Emacs under
+a certain name, such as @code{twiddle-files}, don't call it by that name
+in your program. Call it @code{mylib-twiddle-files} in your program,
+and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
+it to Emacs. If and when we do, we can change the name easily enough.
+
+If one prefix is insufficient, your package may use two or three
+alternative common prefixes, so long as they make sense.
+
+Separate the prefix from the rest of the symbol name with a hyphen,
+@samp{-}. This will be consistent with Emacs itself and with most Emacs
+Lisp programs.
+
+@item
+It is often useful to put a call to @code{provide} in each separate
+library program, at least if there is more than one entry point to the
+program.
+
+@item
+If one file @var{foo} uses a macro defined in another file @var{bar},
+@var{foo} should contain @code{(require '@var{bar})} before the first
+use of the macro. (And @var{bar} should contain @code{(provide
+'@var{bar})}, to make the @code{require} work.) This will cause
+@var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you
+risk compiling @var{foo} without the necessary macro loaded, and that
+would produce compiled code that won't work right. @xref{Compiling
+Macros}.
+
+@item
+If you define a major mode, make sure to run a hook variable using
+@code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
+
+@item
+Please do not define @kbd{C-c @var{letter}} as a key in your major
+modes. These sequences are reserved for users; they are the
+@strong{only} sequences reserved for users, so we cannot do without
+them.
+
+Instead, define sequences consisting of @kbd{C-c} followed by a
+non-letter. These sequences are reserved for major modes.
+
+Changing all the major modes in Emacs 18 so they would follow this
+convention was a lot of work. Abandoning this convention would waste
+that work and inconvenience the users.
+
+@item
+You should not bind @kbd{C-h} following any prefix character (including
+@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
+as a help character for listing the subcommands of the prefix character.
+
+@item
+You should not bind a key sequence ending in @key{ESC} except following
+another @key{ESC}. (That is, it is ok to bind a sequence ending in
+@kbd{@key{ESC} @key{ESC}}.)
+
+The reason for this rule is that a non-prefix binding for @key{ESC} in
+any context prevents recognition of escape sequences as function keys in
+that context.
+
+@item
+It is a bad idea to define aliases for the Emacs primitives.
+Use the standard names instead.
+
+@item
+Redefining an Emacs primitive is an even worse idea.
+It may do the right thing for a particular program, but
+there is no telling what other programs might break as a result.
+
+@item
+If a file does replace any of the functions or library programs of
+standard Emacs, prominent comments at the beginning of the file should
+say which functions are replaced, and how the behavior of the
+replacements differs from that of the originals.
+
+@item
+If a file requires certain standard library programs to be loaded
+beforehand, then the comments at the beginning of the file should say
+so.
+
+@item
+Please keep the names of your Emacs Lisp source files to 13 characters
+or less. This way, if the files are compiled, the compiled files' names
+will be 14 characters or less, which is short enough to fit on all kinds
+of Unix systems.
+
+@item
+Don't use @code{next-line} or @code{previous-line} in programs; nearly
+always, @code{forward-line} is more convenient as well as more
+predictable and robust. @xref{Text Lines}.
+
+@item
+Don't use functions that set the mark in your Lisp code (unless you are
+writing a command to set the mark). The mark is a user-level feature,
+so it is incorrect to change the mark except to supply a value for the
+user's benefit. @xref{The Mark}.
+
+In particular, don't use these functions:
+
+@itemize @bullet
+@item
+@code{beginning-of-buffer}, @code{end-of-buffer}
+@item
+@code{replace-string}, @code{replace-regexp}
+@end itemize
+
+If you just want to move point, or replace a certain string, without any
+of the other features intended for interactive users, you can replace
+these functions with one or two lines of simple Lisp code.
+
+@item
+The recommended way to print a message in the echo area is with
+the @code{message} function, not @code{princ}. @xref{The Echo Area}.
+
+@item
+When you encounter an error condition, call the function @code{error}
+(or @code{signal}). The function @code{error} does not return.
+@xref{Signaling Errors}.
+
+Do not use @code{message}, @code{throw}, @code{sleep-for},
+or @code{beep} to report errors.
+
+@item
+Avoid using recursive edits. Instead, do what the Rmail @kbd{w} command
+does: use a new local keymap that contains one command defined to
+switch back to the old local keymap. Or do what the @code{edit-options}
+command does: switch to another buffer and let the user switch back at
+will. @xref{Recursive Editing}.
+
+@item
+In some other systems there is a convention of choosing variable names
+that begin and end with @samp{*}. We don't use that convention in Emacs
+Lisp, so please don't use it in your library. (In fact, in Emacs names
+of this form are conventionally used for program-generated buffers.) The
+users will find Emacs more coherent if all libraries use the same
+conventions.
+
+@item
+Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
+default indentation parameters.
+
+@item
+Don't make a habit of putting close-parentheses on lines by themselves;
+Lisp programmers find this disconcerting. Once in a while, when there
+is a sequence of many consecutive close-parentheses, it may make sense
+to split them in one or two significant places.
+
+@item
+Please put a copyright notice on the file if you give copies to anyone.
+Use the same lines that appear at the top of the Lisp files in Emacs
+itself. If you have not signed papers to assign the copyright to the
+Foundation, then place your name in the copyright notice in place of the
+Foundation's name.
+@end itemize
+
+@node Compilation Tips
+@section Tips for Making Compiled Code Fast
+@cindex execution speed
+@cindex speedups
+
+ Here are ways of improving the execution speed of byte-compiled
+lisp programs.
+
+@itemize @bullet
+@item
+@cindex profiling
+@cindex timing programs
+@cindex @file{profile.el}
+Use the @file{profile} library to profile your program. See the file
+@file{profile.el} for instructions.
+
+@item
+Use iteration rather than recursion whenever possible.
+Function calls are slow in Emacs Lisp even when a compiled function
+is calling another compiled function.
+
+@item
+Using the primitive list-searching functions @code{memq}, @code{assq} or
+@code{assoc} is even faster than explicit iteration. It may be worth
+rearranging a data structure so that one of these primitive search
+functions can be used.
+
+@item
+Certain built-in functions are handled specially by the byte compiler
+avoiding the need for an ordinary function call. It is a good idea to
+use these functions rather than alternatives. To see whether a function
+is handled specially by the compiler, examine its @code{byte-compile}
+property. If the property is non-@code{nil}, then the function is
+handled specially.
+
+For example, the following input will show you that @code{aref} is
+compiled specially (@pxref{Array Functions}) while @code{elt} is not
+(@pxref{Sequence Functions}):
+
+@smallexample
+@group
+(get 'aref 'byte-compile)
+ @result{} byte-compile-two-args
+@end group
+
+@group
+(get 'elt 'byte-compile)
+ @result{} nil
+@end group
+@end smallexample
+
+@item
+If calling a small function accounts for a substantial part of your
+program's running time, make the function inline. This eliminates
+the function call overhead. Since making a function inline reduces
+the flexibility of changing the program, don't do it unless it gives
+a noticeable speedup in something slow enough for users to care about
+the speed. @xref{Inline Functions}.
+@end itemize
+
+@node Documentation Tips
+@section Tips for Documentation Strings
+
+ Here are some tips for the writing of documentation strings.
+
+@itemize @bullet
+@item
+Every command, function or variable intended for users to know about
+should have a documentation string.
+
+@item
+An internal subroutine of a Lisp program need not have a documentation
+string, and you can save space by using a comment instead.
+
+@item
+The first line of the documentation string should consist of one or two
+complete sentences which stand on their own as a summary. In particular,
+start the line with a capital letter and end with a period.
+For instance, use ``Return the cons of A and B.'' in preference to
+``Returns the cons of A and B@.''
+
+The documentation string can have additional lines which expand on the
+details of how to use the function or variable. The additional lines
+should be made up of complete sentences also, but they may be filled if
+that looks good.
+
+@item
+Write documentation strings in the active voice, not the passive, and in
+the present tense, not the future. For instance, use ``Return a list
+containing A and B.'' instead of ``A list containing A and B will be
+returned.''
+
+@item
+Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+Instead of, ``Cause Emacs to display text in boldface,'' write just
+``Display text in boldface.''
+
+@item
+Do not start or end a documentation string with whitespace.
+
+@item
+Format the documentation string so that it fits in an Emacs window on an
+80 column screen. It is a good idea for most lines to be no wider than
+60 characters. The first line can be wider if necessary to fit the
+information that ought to be there.
+
+However, rather than simply filling the entire documentation string, you
+can make it much more readable by choosing line breaks with care.
+Use blank lines between topics if the documentation string is long.
+
+@item
+@strong{Do not} indent subsequent lines of a documentation string so
+that the text is lined up in the source code with the text of the first
+line. This looks nice in the source code, but looks bizarre when users
+view the documentation. Remember that the indentation before the
+starting double-quote is not part of the string!
+
+@item
+A variable's documentation string should start with @samp{*} if the
+variable is one that users would want to set interactively often. If
+the value is a long list, or a function, or if the variable would only
+be set in init files, then don't start the documentation string with
+@samp{*}. @xref{Defining Variables}.
+
+@item
+The documentation string for a variable that is a yes-or-no flag should
+start with words such as ``Non-nil means@dots{}'', to make it clear both
+that the variable only has two meaningfully distinct values and which value
+means ``yes''.
+
+@item
+When a function's documentation string mentions the value of an argument
+of the function, use the argument name in capital letters as if it were
+a name for that value. Thus, the documentation string of the function
+@code{/} refers to its second argument as @samp{DIVISOR}.
+
+Also use all caps for meta-syntactic variables, such as when you show
+the decomposition of a list or vector into subunits, some of which may
+vary.
+
+@item
+@iftex
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it. For example: @samp{`lambda'}. There are two exceptions:
+write @code{t} and @code{nil} without single-quotes.
+@end iftex
+@ifinfo
+When a documentation string refers to a Lisp symbol, write it as it
+would be printed (which usually means in lower case), with single-quotes
+around it. For example: @samp{lambda}. There are two exceptions: write
+t and nil without single-quotes. (In this manual, we normally do use
+single-quotes for those symbols.)
+@end ifinfo
+
+@item
+Don't write key sequences directly in documentation strings. Instead,
+use the @samp{\\[@dots{}]} construct to stand for them. For example,
+instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When the
+documentation string is printed, Emacs will substitute whatever key is
+currently bound to @code{forward-char}. This will usually be
+@samp{C-f}, but if the user has moved key bindings, it will be the
+correct key for that user. @xref{Keys in Documentation}.
+
+@item
+In documentation strings for a major mode, you will want to refer to the
+key bindings of that mode's local map, rather than global ones.
+Therefore, use the construct @samp{\\<@dots{}>} once in the
+documentation string to specify which key map to use. Do this before
+the first use of @samp{\\[@dots{}]}. The text inside the
+@samp{\\<@dots{}>} should be the name of the variable containing the
+local keymap for the major mode.
+
+It is not practical to use @samp{\\[@dots{}]} very many times, because
+display of the documentation string will become slow. So use this to
+describe the most important commands in your major mode, and then use
+@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
+
+@item
+Don't use the term ``Elisp'', since that is or was a trademark.
+Use the term ``Emacs Lisp''.
+@end itemize
+
+@node Comment Tips
+@section Tips on Writing Comments
+
+ We recommend these conventions for where to put comments and how to
+indent them:
+
+@table @samp
+@item ;
+Comments that start with a single semicolon, @samp{;}, should all be
+aligned to the same column on the right of the source code. Such
+comments usually explain how the code on the same line does its job. In
+Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
+command automatically inserts such a @samp{;} in the right place, or
+aligns such a comment if it is already inserted.
+
+(The following examples are taken from the Emacs sources.)
+
+@smallexample
+@group
+(setq base-version-list ; there was a base
+ (assoc (substring fn 0 start-vn) ; version to which
+ file-version-assoc-list)) ; this looks like
+ ; a subversion
+@end group
+@end smallexample
+
+@item ;;
+Comments that start with two semicolons, @samp{;;}, should be aligned to
+the same level of indentation as the code. Such comments are used to
+describe the purpose of the following lines or the state of the program
+at that point. For example:
+
+@smallexample
+@group
+(prog1 (setq auto-fill-function
+ @dots{}
+ @dots{}
+ ;; update mode-line
+ (force-mode-line-update)))
+@end group
+@end smallexample
+
+These comments are also written before a function definition to explain
+what the function does and how to call it properly.
+
+@item ;;;
+Comments that start with three semicolons, @samp{;;;}, should start at
+the left margin. Such comments are not used within function
+definitions, but are used to make more general comments. For example:
+
+@smallexample
+@group
+;;; This Lisp code is run in Emacs
+;;; when it is to operate as a server
+;;; for other processes.
+@end group
+@end smallexample
+
+@item ;;;;
+Comments that start with four semicolons, @samp{;;;;}, should be aligned
+to the left margin and are used for headings of major sections of a
+program. For example:
+
+@smallexample
+;;;; The kill ring
+@end smallexample
+@end table
+
+@noindent
+The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+automatically indent comments according to these conventions,
+depending on the the number of semicolons. @xref{Comments,,
+Manipulating Comments, emacs, The GNU Emacs Manual}.
+
+ If you wish to ``comment out'' a number of lines of code, use triple
+semicolons at the beginnings of the lines.
+
+ Any character may be included in a comment, but it is advisable to
+precede a character with syntactic significance in Lisp (such as
+@samp{\} or unpaired @samp{(} or @samp{)}) with a @samp{\}, to prevent
+it from confusing the Emacs commands for editing Lisp.
+
+@node Library Headers
+@section Conventional Headers for Emacs Libraries
+@cindex header comments
+@cindex library header comments
+
+ Emacs 19 has conventions for using special comments in Lisp libraries
+to divide them into sections and give information such as who wrote
+them. This section explains these conventions. First, an example:
+
+@smallexample
+@group
+;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+
+;; Copyright (C) 1992 Free Software Foundation, Inc.
+@end group
+
+;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
+;; Created: 14 Jul 1992
+;; Version: 1.2
+@group
+;; Keywords: docs
+
+;; This file is part of GNU Emacs.
+@var{copying conditions}@dots{}
+@end group
+@end smallexample
+
+ The very first line should have this format:
+
+@example
+;;; @var{filename} --- @var{description}
+@end example
+
+@noindent
+The description should be complete in one line.
+
+ After the copyright notice come several @dfn{header comment} lines,
+each beginning with @samp{;;; @var{header-name}:}. Here is a table of
+the conventional possibilities for @var{header-name}:
+
+@table @samp
+@item Author
+This line states the name and net address of at least the principal
+author of the library.
+
+If there are multiple authors, you can list them on continuation lines
+led by @code{;;<TAB>}, like this:
+
+@smallexample
+@group
+;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
+;; Dave Sill <de5@@ornl.gov>
+;; Dave Brennan <brennan@@hal.com>
+;; Eric Raymond <esr@@snark.thyrsus.com>
+@end group
+@end smallexample
+
+@item Maintainer
+This line should contain a single name/address as in the Author line, or
+an address only, or the string ``FSF''. If there is no maintainer line,
+the person(s) in the Author field are presumed to be the maintainers.
+The example above is mildly bogus because the maintainer line is
+redundant.
+
+The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
+possible a Lisp function to ``send mail to the maintainer'' without
+having to mine the name out by hand.
+
+Be sure to surround the network address with @samp{<@dots{}>} if
+you include the person's full name as well as the network address.
+
+@item Created
+This optional line gives the original creation date of the
+file. For historical interest only.
+
+@item Version
+If you wish to record version numbers for the individual Lisp program, put
+them in this line.
+
+@item Adapted-By
+In this header line, place the name of the person who adapted the
+library for installation (to make it fit the style conventions, for
+example).
+
+@item Keywords
+This line lists keywords for the @code{finder-by-keyword} help command.
+This field is important; it's how people will find your package when
+they're looking for things by topic area.
+@end table
+
+ Just about every Lisp library ought to have the @samp{Author} and
+@samp{Keywords} header comment lines. Use the others if they are
+appropriate. You can also put in header lines with other header
+names---they have no standard meanings, so they can't do any harm.
+
+ We use additional stylized comments to subdivide the contents of the
+library file. Here is a table of them:
+
+@table @samp
+@item ;;; Commentary:
+This begins introductory comments that explain how the library works.
+It should come right after the copying permissions.
+
+@item ;;; Change log:
+This begins change log information stored in the library file (if you
+store the change history there). For most of the Lisp
+files distributed with Emacs, the change history is kept in the file
+@file{ChangeLog} and not in the source file at all; these files do
+not have a @samp{;;; Change log:} line.
+
+@item ;;; Code:
+This begins the actual code of the program.
+
+@item ;;; @var{filename} ends here
+This is the @dfn{footer line}; it appears at the very end of the file.
+Its purpose is to enable people to detect truncated versions of the file
+from the lack of a footer line.
+@end table
HCoop / bpt / emacs.git / commitdiff