[elpa] externals/auto-overlays bd7d56d 67/93: Refactor auto-overlays manual into a single source file.

[Stefan Monnier]

branch: externals/auto-overlays
commit bd7d56d35512d264ab2acd57ecff4b818b1d5f83
Author: Toby S. Cubitt <toby-predictive@dr-qubit.org>
Commit: Toby S. Cubitt <toby-predictive@dr-qubit.org>

    Refactor auto-overlays manual into a single source file.
---
 .../auto-overlay-manual.texinfo                    | 1665 +++++++++++++++++++-
 1 file changed, 1661 insertions(+), 4 deletions(-)

diff --git a/docs/auto-overlay-manual/auto-overlay-manual.texinfo 
b/docs/auto-overlay-manual/auto-overlay-manual.texinfo
index 4c580b8..1c910a0 100644
--- a/docs/auto-overlay-manual/auto-overlay-manual.texinfo
+++ b/docs/auto-overlay-manual/auto-overlay-manual.texinfo
@@ -16,10 +16,10 @@
 
 
 @copying
-This manual describes the Emacs Auto-Overlays package, version 0.10
+This manual describes the Emacs Auto-Overlays package, version 0.10.8
 @c --version--
 
-Copyright @copyright{} 2007, 2008 Toby Cubitt
+Copyright @copyright{} 2007-2015 Toby Cubitt
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -34,7 +34,7 @@ Documentation License".
 
 @titlepage
 @title Emacs Auto-Overlays Manual
-@subtitle Version 0.10
+@subtitle Version 0.10.8
 @c --version--
 @author Toby Cubitt
 
@@ -115,7 +115,1664 @@ Copying this Manual
 @contents
 
 
-@include auto-overlays.texinfo
+
+
+
+
+
+@node Overview
+@chapter Overview
+@cindex Overview
+The auto-overlays package automatically creates, updates and destroys
+overlays based on regular expression matches in the buffer text. The
+overlay is created when text is typed that matches an auto-overlay
+regexp, and is destroyed if and when the matching text is changed so
+that it no longer matches.
+
+@cindex regexp sets
+@cindex sets of regexps
+The regexps are grouped into sets, and any number of different sets of
+regexps can be active in the same buffer simultaneously. Regexps in
+different sets are completely independent, and each set can be activated
+and deactivated independently (@pxref{Defining Regexps}). This allows
+different Emacs modes to simultaneously make use of auto-overlays in the
+same buffer.
+
+@cindex overlay classes
+@cindex classes of overlay
+There are different ``classes'' of auto-overlay, used to define
+different kinds of overlay behaviour. Some classes only require a single
+regexp, others require separate regexps to define the start and end of
+the overlay (@pxref{Defining Regexps}). Any additional regexps, beyond
+the minimum requirements, act as alternatives; if more than one of the
+regexps matches overlapping regions of text, the one that appears
+earlier in the list will take precedence. The predefined regexp classes
+are: @code{word}, @code{line}, @code{self}, @code{nested} and
+@code{flat}, but the auto-overlays package can easily be extended with
+new classes.
+
+@table @code
+@item word
+@cindex word overlay class
+@cindex overlay class, word
+@cindex class, word
+These are used to define overlays that cover the text matched by the
+regexp itself, so require a single regexp. An example use would be to
+create overlays covering single words.
+
+@item line
+@cindex line overlay class
+@cindex overlay class, line
+@cindex class, line
+These are used to define overlays that stretch from the text matching
+the regexp to the end of the line, and require a single regexp to define
+the start of the overlay. An example use would be to create overlays
+covering single-line comments in programming languages such as c.
+
+@item self
+These are used to define overlays that stretch from one regexp match to
+the next match for the same regexp, so naturally require a single
+regexp. An example use would be to create overlays covering strings
+delimited by @samp{""}.
+
+@cindex self overlay class
+@cindex overlay class, self
+@cindex class, self
+Note that for efficiency reasons, @code{self} overlays are @emph{not}
+fully updated when a new match is found. Instead, when a modification is
+subsequently made at any position in the buffer after the new match, the
+overlays are updated @emph{up to} that position. The update occurs just
+@emph{before} the modification is made. Therefore, the overlays at a
+given buffer position will not necessarily be correct until a
+modification is made at or after that position (@pxref{To-Do}).
+
+@item nested
+@cindex nested overlay class
+@cindex overlay class, nested
+@cindex class, nested
+These are used to define overlays that start and end at different regexp
+matches, and that can be nested one inside another. This class requires
+separate start and end regexps. An example use would be to create
+overlays between matching braces @samp{@{@}}.
+
+@item flat
+@cindex flat overlay class
+@cindex overlay class, flat
+@cindex class, flat
+These are used to define overlays that start and end at different regexp
+matches, but that can not be nested. Extra start matches within one of
+these overlays are ignored. This class requires separate start and end
+regexps. An example use would be to create overlays covering multi-line
+comments in code, e.g. c++ block comments delimited by @samp{/*} and
+@samp{*/}.
+@end table
+
+@cindex delimeter
+@cindex regexp groups
+@cindex grouping in regexps
+By default, the entire text matching a regexp acts as the
+``delimeter''. For example, a @code{word} overlay will cover all the
+text matching its regexp, and a @code{nested} overlay will start at the
+end of the text matching its start regexp. Sometimes it is useful to be
+able to have only part of the regexp match act as the delimeter. This
+can be done by grouping that part of the regexp (@pxref{Defining
+Regexps}). Overlays will then start and end at the text matching the
+group, instead of the text matching the entire regexp.
+
+Of course, automatically creating overlays isn't much use without some
+way of setting their properties too. Overlay properties can be defined
+along with the regexp, and are applied to any overlays created by a
+match to that regexp. Certain properties have implications for
+auto-overlay behaviour.
+
+@table @code
+@item priority
+@cindex priority property
+@cindex overlay property, priority
+This is a standard Emacs overlay property (@pxref{Overlay
+Properties,,,elisp, GNU Emacs Lisp Reference Manual}), but it is also
+used to determine which regexp takes precedence when two or more regexps
+in the same auto-overlay definition match overlapping regions of
+text. It is also used to determine which regexp's properties take
+precedence for overlays that are defined by separate start and end
+matches.
+
+@item exclusive
+@cindex exclusive property
+@cindex overlay property, exclusive
+Normally, different auto-overlay regexps coexist, and act completely
+independently of one-another. However, if an auto-overlay has non-nil
+@code{exclusive} and @code{priority} properties, regexp matches within
+the overlay are ignored if they have lower priority. An example use is
+ignoring other regexp matches within comments in code.
+@end table
+@cindex overlay properties
+
+
+
+@node Auto-Overlay Functions
+@chapter Auto-Overlay Functions
+@cindex functions
+@cindex package, loading
+@cindex loading the package
+@cindex require
+@cindex using auto-overlays
+
+To use auto-overlays in an Elisp package, you must load the
+overlay classes that you require by including lines of the form
+@lisp
+(require 'auto-overlay-@var{class})
+@end lisp
+near the beginning of your package, where @var{class} is the class
+name. The standard classes are: @code{word}, @code{line}, @code{self},
+@code{nested} and @code{flat} (@pxref{Overview}), though new classes can
+easily be added (@pxref{Extending the Auto-Overlays Package}).
+
+Sometimes it is useful for a package to make use of auto-overlays if any
+are defined, without necessarily requiring them. To facilitate this, the
+relevant functions can be loaded separately from the rest of the
+auto-overlays package with the line
+@lisp
+(require 'auto-overlay-common)
+@end lisp
+This provides all the functions related to searching for overlays and
+retrieving overlay properties. @xref{Searching for Overlays}. Note that
+there is no need to include this line if any auto-overlay classes are
+@code{require}d, though it will do no harm.
+
+This section describes the functions that are needed in order to make
+use of auto-overlays in an Elisp package. It does @emph{not} describe
+functions related to extending the auto-overlays
+package. @xref{Extending the Auto-Overlays Package}.
+
+@menu
+* Defining Regexps::
+* Starting and Stopping Auto-Overlays::
+* Searching for Overlays::
+@end menu
+
+
+
+@node Defining Regexps
+@section Defining Regexps
+@cindex defining regexps
+@cindex regexps, defining
+@cindex regexps, loading and unloading
+@cindex functions, defining regexps
+@cindex functions, loading and unloading regexps
+
+An auto-overlay definition is a list of the form:
+@lisp
+(@var{class} &optional :id @var{entry-id} @var{regexp1} @var{regexp2} ...)
+@end lisp
+@var{class} is one of the regexp classes described in the previous
+section (@pxref{Overview}). The optional @code{:id} property should be a
+symbol that can be used to uniquely identify the auto-overlay
+definition.
+
+Each @var{regexp} defines one of the regexps that make up the
+auto-overlay definition. It should be a list of the form
+@lisp
+(@var{rgxp} &optional :edge @var{edge} :id @var{subentry-id} @@rest 
@var{property1} @var{property2} ...)
+@end lisp
+The @code{:edge} property should be one of the symbols @code{'start} or
+@code{'end}, and determines which edge of the auto-overlay this regexp
+corresponds to. If @code{:edge} is not specified, it is assumed to be
+@code{'start}. Auto-overlay classes that do not require separate
+@code{start} and @code{end} regexps ignore this property. The @code{:id}
+property should be a symbol that can be used to uniquely identify the
+regexp. Any further elements in the list are cons cells of the form
+@code{(property . value)}, where @var{property} is an overlay property
+name (a symbol) and @var{value} its value. In its simplest form,
+@var{rgxp} is a single regular expression.
+
+If only part of the regexp should act as the delimeter
+(@pxref{Overview}), @var{rgxp} should instead be a cons cell:
+@lisp
+(@var{rx} . @var{group})
+@end lisp
+@noindent where @var{rx} is a regexp that contains at least one group
+(@pxref{Regular Expressions,,,elisp, GNU Emacs Lisp Reference Manual}),
+and @var{group} is an integer identifying which group should act as the
+delimeter.
+
+If the overlay class requires additional groups to be specified,
+@var{rgxp} should instead be a list:
+@lisp
+(@var{rx} @var{group0} @var{group1} ...)
+@end lisp
+@noindent where @var{rx} is a regexp. The first @var{group0} still specifies 
the
+part that acts as the delimeter, as before. If the entire regexp should
+act as the delimeter, @var{group0} must still be supplied but should be
+set to 0 (meaning the entire regexp). None of the standard classes make
+use of any additional groups, but extensions to the auto-overlays
+package that define new classes may. @xref{Extending the Auto-Overlays
+Package}.
+
+
+The following functions are used to load and unload regexp definitions:
+@cindex defining regexps
+@cindex regexps, defining
+@cindex regexps, loading and unloading
+@cindex functions, defining regexps
+@cindex functions, loading and unloading regexps
+
+@table @code
+@item (auto-overlay-load-definition @var{set-id} @var{definition} &optional 
@var{pos})
+@findex auto-overlay-load-definition
+@cindex auto-overlay definitions
+@cindex auto-overlays, defining
+@cindex auto-overlays, loading
+@cindex loading auto-overlay definitions
+@cindex defining auto-overlays
+Load a new auto-overlay @var{definition}, which should be a list of the
+form described above, into the set identified by the symbol
+@var{set-id}. The optional parameter @var{pos} determines where in the
+set's regexp list the new regexp is inserted. If it is @code{nil}, the
+regexp is added at the end. If it is @code{t}, the regexp is added at
+the beginning. If it is an integer, the regexp is added at that position
+in the list. Whilst the position in the list has no effect on overlay
+behaviour, it does determine the order in which regexps are checked, so
+can affect efficiency.
+
+@item (auto-overlay-load-regexp @var{set-id} @var{entry-id} @var{regexp} 
&optional @var{pos})
+@findex auto-overlay-load-regexp
+@cindex defining regexps
+@cindex loading regexps
+@cindex regexps, defining
+@cindex regexps, loading
+Load a new @var{regexp}, which should be a list of the form described
+above, into the auto-overlay definition identified by the symbol
+@var{entry-id}, in the set identified by the symbol
+@var{set-id}. @var{regexp} should be a list of the form described above.
+The optional @var{pos} determines the position of the regexp in the list
+of regexps defining the auto-overlay, which can be significant for
+overlay behaviour since it determines which regexp takes precedence when
+two match the same text.
+
+
+@item (auto-overlay-unload-set @var{set-id})
+@findex auto-overlay-unload-set
+@cindex unloading regexp sets
+@cindex regexp sets, unloading
+@cindex auto-overlay definitions, unloading
+Unload the entire regexp set identified by the symbol @var{set-id}.
+
+
+@item (auto-overlay-unload-definition @var{set-id} @var{entry-id})
+@findex auto-overlay-unload-definition
+@cindex unloading regexp definitions
+@cindex regexp definitions, unloading
+Unload the auto-overlay definition identified by the symbol
+@var{entry-id} from the set identified by the symbol @var{set-id}.
+
+
+@item (auto-overlay-unload-regexp @var{set-id} @var{entry-id} 
@var{subentry-id})
+@findex auto-overlay-unload-regexp
+@cindex unloading regexps
+@cindex regexps, unloading
+Unload the auto-overlay regexp identified by the symbol
+@var{subentry-id} from the auto-overlay definition identified by the
+symbol @var{entry-id} in the set identified by the symbol @var{set-id}.
+
+
+@item (auto-overlay-share-regexp-set @var{set-id} @var{from-buffer} @@optional 
@var{to-buffer})
+@findex auto-overlay-share-regexp-set
+@cindex sharing regexp sets
+@cindex regexp sets, sharing between buffers
+@cindex buffers, sharing regexp sets between
+Share the set of regexp definitions identified by the symbol
+@var{set-id} in buffer @code{from-buffer} with the buffer
+@var{to-buffer}, or the current buffer if @var{to-buffer} is null. The
+regexp set becomes common to both buffers, and any changes made to it in
+one buffer, such as loading and unloading regexp definitions, are also
+reflected in the other buffer. However, the regexp set can still be
+enabled and disabled independently in both buffers. The same regexp set
+can be shared between any number of buffers. To remove a shared regexp
+set from one of the buffers, simply unload the entire set from that
+buffer using @command{auto-overlay-unload-regexp}. The regexp set will
+remain defined in all the other buffers it was shared with.
+@end table
+
+
+
+@node Starting and Stopping Auto-Overlays
+@section Starting and Stopping Auto-Overlays
+@cindex starting and stopping auto-overlays
+@cindex regexp sets, starting and stopping
+@cindex saving overlays
+@cindex loading overlays
+@cindex overlays, starting and stopping
+@cindex overlays, saving and loading
+@cindex functions, starting and stopping overlays
+@cindex functions, loading and saving overlays
+A set of regexps is not active until it has been ``started'', and can be
+deactivated by ``stopping'' it. When a regexp set is activated, the
+entire buffer is scanned for regexp matches, and the corresponding
+overlays created. Similarly, when a set is deactivated, all the overlays
+are deleted. Note that regexp definitions can be loaded and unloaded
+whether the regexp set is active or inactive, and that deactivating a
+regexp set does @emph{not} delete its regexp definitions.
+
+Since scanning the whole buffer for regexp matches can take some time,
+especially for large buffers, auto-overlay data can be saved to an
+auxiliary file so that the overlays can be restored more quickly if the
+same regexp set is subsequently re-activated. Of course, if either the
+text in the buffer or the overlay definitions are modified whilst the
+regexp set is disabled, then the saved data will be out of date.
+Auto-overlays automatically checks whether the text or overlay
+definitions have been modified since the data was saved. If so, it
+ignores the saved data and re-scans the buffer.
+
+The usual time to save and restore overlay data is when a regexp set is
+deactivated or activated. The auxilliary file name is then constructed
+automatically from the buffer name and the set-id. However,
+auto-overlays can also be saved and restored manually.
+
+
+@table @code
+@item (auto-overlay-start @var{set-id} @@optional @var{buffer} @var{save-file} 
@var{no-regexp-check})
+@findex auto-overlay-start
+Activate the auto-overlay regexp set identified by the symbol
+@var{set-id} in @var{buffer}, or the current buffer if the latter is
+@code{nil}. If there is a file called
+@file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} containing
+up-to-date overlay data, it will be used to restore the auto-overlays
+(@var{buffer-name} is the name of the file visited by the buffer, or the
+buffer name itself if there is none). Otherwise, the entire buffer will
+be scanned for regexp matches.
+
+The string @var{save-file} specifies the where to look for the file of
+saved overlay data. If it is nil, it defaults to the current
+directory. If it is a string specifying a relative path, then it is
+relative to the current directory, whereas an absolute path specifies
+exactly where to look. If it is a string specifying a file name (with or
+without a full path, relative or absolute), then it overrides the
+default file name and/or location. Any other value of @var{save-file}
+will cause the file of overlay data to be ignored, even if it exists.
+
+If the overlays are being loaded from a file, but optional argument
+no-regexp-check is non-nil, the file of saved overlays will be used, but
+no check will be made to ensure regexp refinitions are the same as when
+the overlays were saved.
+
+
+@item (auto-overlay-stop @var{set-id} @@optional @var{buffer} @var{save-file} 
@var{leave-overlays})
+@findex auto-overlay-stop
+Deactivate the auto-overlay regexp set identified by the symbol
+@var{set-id} in @var{buffer}, or the current buffer if the latter is
+@code{nil}. All corresponding overlays will be deleted (unless the
+@var{leave-overlays} option is non-nil, which should only be used if the
+buffer is about to be killed), but the regexp definitions are preserved
+and can be reactivated later.
+
+If @var{save-file} is non-nil, overlay data will be saved in an
+auxilliary file called
+@file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current
+directory, to speed up subsequent reactivation of the regexp set in the
+same buffer (@var{buffer-name} is the name of the file visited by the
+buffer, or the buffer name itself if there is none). If @var{save-file}
+is a string, it overrides the default save location, overriding either
+the directory if it only specifies a path (relative paths are relative
+to the current directory), or the file name if it only specifies a
+filename, or both if it specifies a full path.
+
+
+@item (auto-overlay-save-overlays @var{set-id} @@optional @var{buffer} 
@var{file})
+@findex auto-overlay-save-overlays
+Save auto-overlay data for the regexp set identified by the symbol
+@var{set-id} in @var{buffer}, or the current buffer if @code{nil}, to an
+auxilliary file called @var{file}. If @var{file} is nil, the overlay
+data are saved to a file called
+@file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current
+directory (@var{buffer-name} is the name of the file visited by the
+buffer, or the buffer name itself if it's not visiting a file). If
+@file{file} is a directory name (either an absolute path or relative to
+the current directory), the overlay data are saved to the default file
+name under that directory.
+
+
+@item (auto-overlay-load-overlays @var{set-id} @@optional @var{buffer} 
@var{file} @var{no-regexp-check})
+@findex auto-overlay-load-overlays
+Load auto-overlay data for the regexp set identified by the symbol
+@var{set-id} into @var{buffer}, or the current buffer if @code{nil},
+from an auxilliary file called @var{file}. If @var{file} is nil, it
+attempts to load the overlay data from a file called
+@file{auto-overlay-}@var{buffer-name}@file{-}@var{set-id} in the current
+directory (@var{buffer-name} is the name of the file visited by the
+buffer, or the buffer name itself if it's not visiting a file). If
+@file{file} is a directory name (either an absolute path or relative to
+the current directory), it attempts to load the overlay data from the
+default file name under that directory. If @var{no-regexp-check} is
+no-nil, the saved overlays will be loaded even if different regexp
+definitions were active when the overlays were saved. Returns @code{t}
+if the overlays were successfully loaded, @code{nil} otherwise.
+@end table
+
+
+
+@node Searching for Overlays
+@section Searching for Overlays
+@cindex searching for overlays
+@cindex finding overlays
+@cindex functions, searching for overlays
+@cindex overlays, finding
+@cindex overlay properties
+Auto-overlays are just normal Emacs overlays, so any of the standard
+Emacs functions can be used to search for overlays and retrieve overlay
+properties. The auto-overlays package provides some additional
+functions.
+
+@table @code
+@item (auto-overlays-at-point @@optional @var{point} @var{prop-test} 
@var{inactive})
+@findex auto-overlays-at-point
+Return a list of overlays overlapping @var{point}, or the point if
+@var{point} is null. The list includes @emph{all} overlays, not just
+auto-overlays (but see below). The list can be filtered to only return
+overlays with properties matching criteria specified by
+@var{prop-test}. This should be a list defining a property test, with
+one of the following forms (or a list of such lists, if more than one
+property test is required):
+@lisp
+(@var{function} @var{property})
+(@var{function} @var{property} @var{value})
+(@var{function} (@var{property1} @var{property2} ...) (@var{value1} 
@var{value2} ...))
+@end lisp
+where @var{function} is a function, @var{property} is an overlay
+property name (a symbol), and @var{value} can be any value or lisp
+expression. For each overlay, first the values corresponding to the
+@var{property} names are retrieved from the overlay and any @var{value}s
+that are lisp expressions are evaluated. Then @var{function} is called
+with the property values followed by the other values as its
+arguments. The test is satisfied if the result is non-nil, otherwise it
+fails. Tests are evaluated in order, but only up to the first
+failure. Only overlays that satisfy all property tests are returned.
+
+All auto-overlays are given a non-nil @code{auto-overlay} property, so
+to restrict the list to auto-overlays, @var{prop-test} should include
+the following property test:
+@lisp
+('identity 'auto-overlay)
+@end lisp
+For efficiency reasons, the auto-overlays package sometimes leaves
+overlays hanging around in the buffer even when they should have been
+deleted. These are marked with a non-nil @code{inactive} property. By
+default, @command{auto-overlays-at-point} ignores these. A non-nil
+@var{inactive} will override this, causing inactive overlays to be
+included in the returned list (assuming they pass all property tests).
+
+
+@item (auto-overlays-in @var{start} @var{end} @@optional @var{prop-test} 
@var{within} @var{inactive})
+@findex auto-overlays-in
+Return a list of overlays overlapping the region between @var{start} and
+@var{end}. The @var{prop-test} and @var{inactive} arguments have the
+same behaviour as in @command{auto-overlays-at-point}, above. If
+@var{within} is non-nil, only overlays that are entirely within the
+region from @var{start} to @var{end} will be returned, not overlays that
+extend outside that region.
+
+
+@item (auto-overlay-highest-priority-at-point @@optional @var{point} 
@var{prop-test})
+@findex auto-overlay-highest-priority-at-point
+@cindex overlays, priority
+@cindex highest priority overlay
+Return the highest priority overlay at @var{point} (or the point, if
+@var{point} is null). The @var{prop-test} argument has the same
+behaviour as in @command{auto-overlays-at-point}, above. An overlay's
+priority is determined by the value of its @code{priority} property
+(@pxref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference
+Manual}). If two overlays have the same priority, the innermost one
+takes precedence (i.e. the one that begins later in the buffer, or if
+they begin at the same point the one that ends earlier; if two overlays
+have the same priority and extend over the same region, there is no way
+to predict which will be returned).
+
+@item (auto-overlay-local-binding @var{symbol} @@optional @var{point})
+@findex auto-overlay-local-binding
+@cindex overlays, local-binding
+@cindex overlay-local binding
+@cindex local-binding
+Return the ``overlay-local'' binding of @var{symbol} at @var{point} (or
+the point if @var{point} is null), or the current local binding if there
+is no overlay binding. An ``overlay-local'' binding for @var{symbol} is
+the value of the overlay property called @var{symbol}. If more than one
+overlay at @var{point} has a non-nil @var{symbol} property, the value
+from the highest priority overlay is returned (see
+@command{auto-overlay-highest-priority-at-point}, above, for an
+explanation of ``highest priority'').
+@end table
+
+
+
+
+@node Worked Example
+@chapter Worked Example
+@cindex worked example
+@cindex example
+@cindex LaTeX
+The interaction of all the different regexp definitions, overlay
+properties and auto-overlay classes provided by the auto-overlays package
+can be a little daunting. This section will go through an example of how
+the auto-overlay regexps could be defined to create overlays for a
+subset of @LaTeX{}, which is complex enough to demonstrate most of the
+features.
+
+@LaTeX{} is a markup language, so a @LaTeX{} document combines markup
+commands with normal text. Commands start with @samp{\}, and end at the
+first non-word-constituent character. We want to highlight all @LaTeX{}
+commands in blue. Two commands that will particularly interest us are
+@samp{\begin} and @samp{\end}, which begin and end a @LaTeX{}
+environment. The environment name is enclosed in braces:
+@samp{\begin@{@var{environment-name}@}}, and we want it to be
+highlighted in pink. @LaTeX{} provides many environments, used to create
+lists, tables, titles, etc. We will take the example of an
+@samp{equation} environment, used to typeset mathematical
+equations. Thus equations are enclosed by @samp{\begin@{equation@}} and
+@samp{\end@{equation@}}, and we would like to highlight these equations
+in yellow. Another example we will use is the @samp{$} delimiter. Pairs
+of @samp{$}s delimit mathematical expressions that appear in the middle
+of a paragraph of normal text (whereas @samp{equation} environments
+appear on their own, slightly separated from surrounding text). Again,
+we want to highlight these mathematical expressions, this time in
+green. The final piece of @LaTeX{} markup we will need to consider is
+the @samp{%} character, which creates a comment that lasts till the end
+of the line (i.e. text after the @samp{%} is ignored by the @LaTeX{}
+processor up to the end of the line).
+
+
+@cindex word overlay class example
+@cindex example, word class
+@cindex overlay class, word example
+@cindex class, word example
+@LaTeX{} commands are a good example of when to use @code{word} regular
+expressions (@pxref{Overview}). The appropriate regexp definition is
+loaded by
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(word ("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)"
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+We have called the regexp set @code{latex}. The @code{face} property is
+a standard Emacs overlay property that sets font properties within the
+overlay. @xref{Overlay Properties,,,elisp, GNU Emacs Lisp Reference
+Manual}. @code{"\\\\"} is the string defining the regexp that matches a
+@emph{single} @samp{\}. (Note that the @samp{\} character has a special
+meaning in regular expressions, so to include a literal one it must be
+escaped: @samp{\\}. However, @samp{\} also has a special meaning in lisp
+strings, so both @samp{\} characters must be escaped there too, giving
+@code{\\\\}.) @code{[[:alpha:]]*?} matches a sequence of zero or more
+letter characters. The @code{?} ensures that it matches the
+@emph{shortest} sequence of letters consistent with matching the regexp,
+since we want the region to end at the first non-letter character,
+matched by @code{[^[:alpha:]]}. The @code{\|} defines an alternative, to
+allow the @LaTeX{} command to be terminated either by a non-letter
+character or by the end of the line (@code{$}). @xref{Regular
+Expressions,,,elisp, GNU Emacs Lisp Reference Manual}, for more details
+on Emacs regular expressions.
+
+However, there's a small problem. We only want the blue background to
+cover the characters making up a @LaTeX{} command. But as we've defined
+things so far, it will cover all the text matched by the regexp, which
+includes the leading @samp{\} and the trailing non-letter character. To
+rectify this, we need to group the part of the regexp that matches the
+command (i.e. by surround it with @samp{\(} and @samp{\)}), and put the
+regexp inside a cons cell containing the regexp in its @code{car} and a
+number indicating which subgroup to use in its @code{cdr}:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+
+@cindex self overlay class example
+@cindex overlay class, self example
+@cindex example, self class
+@cindex class, self example
+The @samp{$} delimiter is an obvious example of when to use a
+@code{self} regexp (@pxref{Overview}). We can update our example to
+include this (note that @samp{$} also has a special meaning in regular
+expressions, so it must be escaped with @samp{\} which itself must be
+escaped in lisp strings):
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (face . (background-color . "green")))))
+@end lisp
+
+@noindent
+This won't quite work though. @LaTeX{} maths commands also start with a
+@samp{\} character, which will match the @code{word} regexp. For the
+sake of example we want the entire equation highlighted in green,
+without highlighting any @LaTeX{} maths commands it contains in
+blue. Since the @code{word} overlay will be within the @code{self}
+overlay, the blue highlighting will take precedence. We can change this
+by giving the @code{self} overlay a higher priority (any priority is
+higher than a non-existent one; we use 3 here for later
+convenience). For efficiency reasons, it's a good idea to put higher
+priority regexp definitions before lower priority ones, so we get:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+
+@cindex nested overlay class example
+@cindex overlay class, nested example
+@cindex example, nested class
+@cindex class, nested example
+The @samp{\begin@{equation@}} and @samp{\end@{equation@}} commands also
+enclose maths regions, which we would like to highlight in yellow. Since
+the opening and closing delimiters are different in this case, we must
+use @code{nested} overlays (@pxref{Overview}). Our example now looks like:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+Notice how we've used separate @code{start} and @code{end} regexps to
+define the auto-overlay. Once again, we have had to escape the @samp{\}
+characters, and increase the priority of the new regexp definition to
+avoid any @LaTeX{} commands within the maths region being highlighted in
+blue.
+
+
+@cindex line overlay class example
+@cindex overlay class, line example
+@cindex example, line class
+@cindex class, line example
+@LaTeX{} comments start with @samp{%} and last till the end of the line:
+a perfect demonstration of a @code{line} regexp. Here's a first attempt:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+@end lisp
+
+@noindent
+We use the standard Emacs @command{face-attribute} function to retrieve
+the default background colour, which is evaluated before the regexp
+definition is loaded. (This will of course go wrong if the default
+background colour is subsequently changed, but it's sufficient for this
+example). Let's think about this a bit. We probably don't want anything
+within a comment to be highlighted at all, even if it matches one of the
+other regexps. In fact, creating overlays for @samp{\begin} and
+@samp{\end} commands which are within a comment could cause havoc! If
+they don't occur in pairs within the commented region, they will
+erroneously pair up with ones outside the comment. We need comments to
+take precedence over everything else, and we need them to block other
+regexp matches, so we boost the overlay's priority and set the exclusive
+property:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+
+@cindex nested overlay class example
+@cindex overlay class, nested example
+@cindex example, nested class
+@cindex class, nested example
+We're well on our way to creating a useful setup, at least for the
+@LaTeX{} commands we're considering in this example. There is one last
+type of overlay to create, but it is the most complicated. We want
+environment names to be highlighted in pink, i.e. the region between
+@samp{\begin@{} and @samp{@}}. A first attempt at this might result in:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("@}"
+    :edge end
+    (priority . 2)
+    (face . (background-color . "pink")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+However, we'll hit a problem with this. The @samp{@}} character also
+closes the @samp{\end@{} command. Since we haven't told auto-overlays
+about @samp{\end@{}, every @samp{@}} that should close an @samp{\end@{}
+command will instead be interpreted as the end of a @samp{\start@{}
+command, probably resulting in lots of unmatched @samp{@}} characters,
+creating pink splodges everywhere! Clearly, since we also want
+environment names between @samp{\end@{} and @samp{@}} to be pink, we
+need something more along the lines of:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\end@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("@}"
+    :edge end
+    (priority . 2)
+    (face . (background-color . "pink")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+We still haven't solved the problem though. The @samp{@}} character
+doesn't only close @samp{\begin@{} and @samp{\end@{} commands in
+@LaTeX{}. @emph{All} arguments to @LaTeX{} commands are surrounded by
+@samp{@{} and @samp{@}}. We could add all the commands that take
+arguments, but we don't really want to bother about any other commands
+(at least in this example). All we want to do is prevent predictive mode
+incorrectly pairing the @samp{@}} characters used for other
+commands. Instead, we can just add @samp{@{} to the list:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("@{"
+    :edge start
+    (priority . 2))
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\end@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("@}"
+    :edge end
+    (priority . 2))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+Notice how the @code{@{} and @code{@}} regexps do not define a
+background colour (or indeed any other properties), so that any overlays
+they create will have no effect other than making sure all @samp{@{} and
+@samp{@}} characters are correctly paired.
+
+We've made one mistake though: by putting the @code{@{} regexp at the
+beginning of the list, it will take priority over any other regexp in
+the list that could match the same text. And since @code{@{} will match
+whenever @code{\begin@{} or @code{\end@{} matches, environments will
+never be highlighted! The @code{@{} regexp must come @emph{after} the
+@code{\begin@{} and @code{\end@{} regexps, to ensure it is only used if
+neither of them match (it doesn't matter whether it appears before or
+after the @code{@{} regexp, since the latter will never match the same
+text):
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\end@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("@{"
+    :edge start
+    (priority . 2))
+   ("@}"
+    :edge end
+    (priority . 2))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+There is one last issue. A literal @samp{@{} or @samp{@}} character can
+be included in a @LaTeX{} document by escaping it with @samp{\}:
+@samp{\@{} and @samp{\@}}. In this situation, the characters do not
+match anything and should not be treated as delimiters. We can modify
+the @code{@{} and @code{@}} regexps to exclude these cases:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\end@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\([^\\]\\|^\\)@{"
+    :edge start
+    (priority . 2))
+   ("\\([^\\]\\|^\\)@}"
+    :edge end
+    (priority . 2))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+@noindent
+The new, complicated-looking regexps will only match @samp{@{} and
+@samp{@}} characters if they are @emph{not} preceded by a @samp{\}
+character (@pxref{Regular Expressions,,,elisp,GNU Emacs Lisp Reference
+Manual}). Note that the character alternative @code{[^\]\|^} can match
+any character that isn't a @samp{\} @emph{or} the start of a line. This
+is required because matches to auto-overlay regexps are not allowed to
+span more than one line. If @samp{@{} or @samp{@}} appear at the
+beginning of a line, there will be no character in front (the newline
+character doesn't count, since it isn't on the same line), so the
+@code{[^\]} will not match.
+
+However, when it does match, the @code{@}} regexp will now match an
+additional character before the @code{@}}, causing the overlay to end
+one character early. (The @code{@{} regexp will also match one
+additional character before the @code{@{}, but since the beginning of
+the overlay starts from the @emph{end} of the @code{start} delimiter,
+this poses less of a problem.) We need to group the part of the regexp
+that should define the delimiter, i.e. the @code{@}}, by surrounding it
+with @code{\(} and @code{\)}, and put the regexp in the @code{car} of a
+cons cell whose @code{cdr} specifies the new subgroup (i.e. the 2nd
+subgroup, since the regexp already included a group for other reasons;
+we could alternatively replace the original group by a shy-group, since
+we don't actually need to capture match data for that group). Our final
+version looks like this:
+
+@lisp
+(auto-overlay-load-definition
+ 'latex
+ `(line ("%" (priority . 4) (exclusive . t)
+             (face . (background-color
+                      . ,(face-attribute 'default :background))))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(self ("\\$" (priority . 3) (face . (background-color . "green")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\end@{"
+    :edge start
+    (priority . 2)
+    (face . (background-color . "pink")))
+   ("\\([^\\]\\|^\\)@{"
+    :edge start
+    (priority . 2))
+   (("\\([^\\]\\|^\\)\\(@}\\)" . 2)
+    :edge end
+    (priority . 2))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(nested
+   ("\\begin@{equation@}"
+    :edge start
+    (priority . 1)
+    (face . (background-color . "yellow")))
+   ("\\end@{equation@}"
+    :edge end
+    (priority . 1)
+    (face . (background-color . "yellow")))))
+
+(auto-overlay-load-definition
+ 'latex
+ '(word (("\\\\[[:alpha:]]*?\\([^[:alpha:]]\\|$\\)" . 1)
+         (face . (background-color . "blue")))))
+@end lisp
+
+With these regexp definitions, @LaTeX{} commands will automatically be
+highlighted in blue, equation environments in yellow, inline maths
+commands in green, and environment names in pink. @LaTeX{} markup within
+comments will be ignored. And @samp{@{} and @samp{@}} characters from
+other commands will be correctly taken into account. All this is done in
+``real-time''; it doesn't wait until Emacs is idle to update the
+overlays. Not bad for a bundle of regexps!
+
+Of course, this could all be done more easily using Emacs' built-in
+syntax highlighting features, but the highlighting was only an example
+to show the location of the overlays. The main point is that the
+overlays are automatically created and kept up to date, and can be given
+any properties you like and used for whatever purpose is required by
+your Elisp package.
+
+
+
+
+@node Extending the Auto-Overlays Package
+@chapter Extending the Auto-Overlays Package
+@cindex extending the auto-overlays package
+@cindex adding new overlay classes
+@cindex package, extending
+@cindex classes, adding new
+The auto-overlays package can easily be extended by adding new overlay
+classes@footnote{Or rather, it is easy to integrate new overlay classes
+into the package. Whether writing a new overlay class is easy or not
+depends on what you're trying to do, and how good your coding skills are
+;-)}. The next sections document the functions and interfaces provided
+by the auto-overlays package for this purpose.
+
+Often, a new class is a minor modification of one of the standard
+classes. For example, it may work exactly like one of the standard
+classes, but in addition call some function whenever an overlay is
+created or destroyed. In this case, it is far better to build the new
+class on top of the existing class, using functions from the
+class-specific Elisp files, rather than starting from
+scratch. @xref{Standard Parse and Suicide Functions}.
+
+
+@menu
+* Auto-Overlays in Depth::
+* Integrating New Overlay Classes::
+* Functions for Writing New Overlay Classes::
+* Auto-Overlay Hooks::
+* Auto-Overlay Modification Pseudo-Hooks::
+@end menu
+
+@node Auto-Overlays in Depth
+@section Auto-Overlays in Depth
+@cindex auto-overlays in depth
+@cindex package, in depth
+In order to write new classes, a deeper understanding is required of how
+the auto-overlays package works. In fact, two kinds of overlays are
+automatically created, updated and destroyed when auto-overlays are
+active: the auto-overlays themselves, and ``match'' overlays, used to
+mark text that matches an auto-overlay regexp.
+
+For overlay classes that only require one regexp to fully define an
+overlay (the @code{word} and @code{line} classes are the only standard
+classes like this@footnote{Although the @code{self} class only requires
+one regexp definition, the auto-overlays themselves require two matches
+to that same regexp to set the start and end of the overlay.}), the
+auto-overlays are always matched with the corresponding match
+overlay. For classes that require two regexp matches to define the start
+and end of an overlay (all other standard classes), each edge of an
+auto-overlay can be matched with a match overlay. The match overlays
+define where the edge of the auto-overlay is located. There will always
+be at least one matched edge, since an auto-overlay is only created when
+a regexp match is found, but it is possible for the second edge to not
+yet be matched (for many classes, the unmatched edge will be located at
+the beginning or end of the buffer).
+
+If a match overlay delimits the start of an auto-overlay, the match
+overlay is stored in the auto-overlay's @code{start} property. The match
+overlay is also stored in the @code{start} property for auto-overlays
+that only require a single match. If a match overlay delimits the end of
+an auto-overlay, the match overlay is stored in the auto-overlay's
+@code{end} property. Conversely, a ``link'' to the auto-overlay is
+always stored in the match overlay's @code{parent} property@footnote{The
+``parent'' terminology is admittedly very poor, and is a relic of a
+previous incarnation of the auto-overlays package, when it made more
+sense.}.
+
+Whenever a buffer is modified, the lines containing the modifications
+are scanned for new regexp matches. If one is found, a new match overlay
+is created covering the matching text, and then passed as an argument to
+the appropriate ``parse'' function@footnote{More bad terminology.} for
+its class. This deals with creating or updating the auto-overlays, as
+appropriate. If the text within a match overlay is modified, the match
+overlay checks whether the text it covers still matches the regexp. If
+it no longer matches, the match overlay is passed as an argument to the
+appropriate ``suicide'' function for its class, which deals with
+updating or deleting its parent auto-overlay (and possibly more
+besides).
+
+To summarise, the core of the auto-overlays package deals with searching
+for regexp matches, and creating or deleting the corresponding match
+overlays. It then hands over the task of creating, updating or deleting
+the auto-overlays themselves to class-specific functions, which
+implement the correct behaviour for that class.
+
+
+
+@node Integrating New Overlay Classes
+@section Integrating New Overlay Classes
+@cindex integrating new overlay classes
+@cindex overlay classes, integrating new
+@cindex classes, integrating new
+@cindex extending, integrating new overlay classes
+To add a new overlay class, all that is required is to write new
+``parse'' and ``suicide'' functions, and inform the auto-overlays
+package of their existence. A ``match'' function can also optionally be
+defined. It is called whenever a match overlay in the class becomes
+matched with the edge of an auto-overlay (@pxref{Functions for Modifying
+Overlays}). The parse, suicide and match functions are conventionally
+called @code{auto-o-parse-}@var{class}@code{-match},
+@code{auto-o-}@var{class}@code{-suicide} and
+@code{auto-o-match-}@var{class}, where @var{class} is the name of the
+class, though the convention is not enforced in any way.
+
+@table @asis
+@item parse function
+@cindex parse function
+@cindex overlay classes, parse function
+@cindex functions, parse function
+@cindex integrating new classes, parse function
+@findex auto-o-parse-@{class@}-match
+A parse function is passed a single argument containing a match
+overlay. It should return a list containing any new auto-overlays it
+creates, or @code{nil} if none were created.
+@lisp
+@var{o-list} = (auto-o-parse-@var{class}-match @var{o-match})
+@end lisp
+Note that the parse function itself is responsible for calling the
+@command{auto-o-update-exclusive} function if a new exclusive overlay is
+created. @xref{Functions for Modifying Overlays}.
+
+@item suicide function
+@cindex suicide function
+@cindex overlay classes, suicide function
+@cindex functions, suicide function
+@cindex integrating new classes, suicide function
+@findex auto-o-@{class@}-suicide
+A suicide function is passed a single argument containing a match
+overlay. Its return value is ignored.
+@lisp
+(auto-o-@var{class}-suicide @var{o-match})
+@end lisp
+The text covered by the match overlay should be considered to no longer
+match its regexp, although in certain cases matches are ignored for
+other reasons and this may not really be the case (for example if a new,
+higher-priority, exclusive overlay overlaps the match,
+@pxref{Overview}).
+
+@item match function
+@cindex match function
+@cindex overlay classes, match function
+@cindex functions, match function
+@cindex integrating new classes, match function
+@findex auto-o-match-@{class@}
+A match function is passed a single argument containing a match overlay
+that has just been matched with an edge of an auto-overlay
+(@pxref{Functions for Modifying Overlays}). Its return value is ignored.
+@lisp
+(auto-o-match-@var{class} @var{o-match})
+@end lisp
+The auto-overlay it is matched with is stored in the match overlay's
+@code{parent} property.
+@end table
+
+To integrate the new class into the auto-overlays package, the parse and
+suicide functions must be added to the property list of the symbol used
+to refer to the new class, denoted here by @var{class}:
+@lisp
+(put '@var{class} 'auto-overlay-parse-function
+     'auto-o-parse-@var{class}-match)
+(put '@var{class} 'auto-overlay-suicide-function
+     'auto-o-@var{class}-suicide)
+@end lisp
+If the optional match function is defined, it should similarly be added
+to the symbol's property list:
+@lisp
+(put '@var{class} 'auto-overlay-match-function
+     'auto-o-match-@var{class})
+@end lisp
+
+
+
+@node Functions for Writing New Overlay Classes
+@section Functions for Writing New Overlay Classes
+@cindex functions, writing new overlay classes
+@cindex overlay classes, functions for writing new
+@cindex extending, functions
+Some functions are provided by the auto-overlays package for use in new
+parse and suicide functions. The functions that modify overlays carry
+out tasks that require interaction with the core of the auto-overlays
+package, and provide the only reliable way of carrying out those
+tasks. The other functions are used to query various things about
+auto-overlays and match overlays. Again, they are the only reliable
+interface for this, since the internal implementation may change between
+releases of the auto-overlays package.
+
+@menu
+* Standard Parse and Suicide Functions::
+* Functions for Modifying Overlays::
+* Functions for Querying Overlays::
+@end menu
+
+
+@node Standard Parse and Suicide Functions
+@subsection Standard Parse and Suicide Functions
+@cindex standard parse and suicide functions
+@cindex overlay classes, standard parse functions
+@cindex overlay classes, standard suicide functions
+@cindex class, standard parse functions
+@cindex class, standard suicide functions
+@cindex extending, standard parse functions
+@cindex extending, standard suicide functions
+All the standard overlay classes define their own parse and suicide
+functions (none of them require a match function), which can be used to
+create new ``derived'' classes based on the standard ones. This is the
+easiest and most common way to create a new class. For example, the new
+class may behave exactly like one of the standard classes, but perform
+some additional processing whenever an overlay is created, destroyed, or
+matched. The parse and suicide functions for the new class should
+perform whatever additional processing is required, and call the
+standard class functions to deal with creating and destroying the
+overlay.
+
+All the standard parse and suicide functions follow the same naming
+convention (@pxref{Integrating New Overlay Classes}), where @var{class}
+is the name of the overlay class (one of @code{word}, @code{line},
+@code{self}, @code{nested} or @code{flat}, @pxref{Overview}):
+
+@table @code
+@item (auto-o-parse-@var{class}-match @var{o-match})
+@findex auto-o-parse-@{class@}-match
+Parse a new match overlay @var{o-match} whose class is @var{class}. This
+will create or update auto-overlays, as appropriate for the class.
+
+
+@item (auto-o-@var{class}-suicide @var{o-match})
+@findex auto-o-@{class@}-suicide
+Delete or update auto-overlays as appropriate for overlay class
+@var{class}, due to the match overlay @var{o-match} no longer matching.
+@end table
+
+
+
+@node Functions for Modifying Overlays
+@subsection Functions for Modifying Overlays
+@cindex functions, modifying overlays
+@cindex overlays, functions for modifying
+@cindex extending, functions for modifying overlays
+These functions modify auto-overlays and match overlays as necessary to
+perform a particular update. They should @emph{always} be used to carry
+out their corresponding tasks, rather than doing it separately, since
+these tasks require interaction with the core of the auto-overlays
+package.
+
+@table @code
+@item (auto-o-update-exclusive @var{set-id} @var{beg} @var{end} 
@var{old-priority} @var{new-priority})
+@findex auto-o-update-exclusive
+@cindex overlay property, exclusive
+@cindex exclusive property
+@cindex extending, updating exclusive
+@cindex updating exclusive regions
+Update the region between @var{beg} and @var{end} in the current buffer
+as necessary due to the priority of an exclusive overlay overlapping the
+region changing from @var{old-priority} to @var{new-priority}. If the
+exclusive overlay did not previously overlap the region,
+@var{old-priority} should be null. If it no longer overlaps the region,
+@var{new-priority} should be null. (If both are null, nothing will
+happen!) The return value is meaningless.
+
+
+@item (auto-o-match-overlay @var{overlay} @var{start} @@optional @var{end} 
@var{no-props} @var{no-parse} @var{protect-match})
+@findex auto-o-match-overlays
+@cindex overlays, matching
+@cindex matching overlays
+@cindex extending, matching overlays
+Match or unmatch the start and end of the auto-overlay @var{overlay},
+update all appropriate properties (such as @code{parent}, @code{start}
+and @code{end} properties, and any properties specified in regexp
+definitions), and update other auto-overlays in the region covered by
+@var{overlay} as necessary (usually because the @code{exclusive} or
+@code{priority} properties of @var{overlay} have changed).
+
+If @var{start} or @var{end} are match overlays, match the corresponding
+edge of @var{overlay}. The edge is moved to the location defined by the
+match overlay, and the @code{parent} property of the match overlay and
+the @code{start} and @code{end} properties of @var{overlay} are updated
+accordingly. The @var{start} argument should be a match overlay
+corresponding either to the unique regexp if only one is needed for that
+overlay class, or to a start regexp if the overlay class uses separate
+start and end regexps. The @var{end} argument should then be a match
+overlay corresponding to an end regexp in the same class
+(@pxref{Overview}). You're responsible for enforcing this; no check is
+made.
+
+If @var{start} or @var{end} are numbers or markers, move the
+corresponding edge of @var{overlay} to that location and set it as
+unmatched. The @code{start} or @code{end} property of @var{overlay} and
+the @code{parent} property of any corresponding match overlay are set to
+@code{nil}. If @var{start} or @var{end} are non-nil but neither of the
+above, leave the corresponding edge of @var{overlay} where it is, but
+set it unmatched (as described above). If @var{start} or @var{end} are
+null, don't change the corresponding edge. However, for convenience, if
+@var{end} is null but @var{start} is a match overlay corresponding to a
+match for an end-regexp, match the end of @var{overlay} rather than the
+start.
+
+The remaining arguments disable some of the tasks normally carried out
+by @command{auto-o-match-overlay}. If @var{no-props} is non-nil, overlay
+properties specified in regexp definitions are ignored and not
+updated. If @var{no-parse} is non-nil, auto-overlays in the region
+covered by @var{overlay} are not updated, even if the @code{exclusive}
+or @code{priority} properties of @var{overlay} have changed. If
+@var{protect-match} is non-nil, the @code{parent} properties of the
+@var{start} and @var{end} match overlays are left alone.
+
+
+@item (auto-o-delete-overlay @var{overlay} @@optional @var{no-parse} 
@var{protect-match})
+@findex auto-o-delete-overlay
+@cindex overlays, deleting
+@cindex deleting overlays
+@cindex extending, deleting overlays
+Delete auto-overlay @var{overlay} from the buffer, and update overlays
+and overlay properties as necessary. The optional arguments disable
+parts of the updating process, as for @command{auto-o-match-overlay},
+above.
+@end table
+
+
+
+@node Functions for Querying Overlays
+@subsection Functions for Querying Overlays
+@cindex functions, querying overlays
+@cindex overlays, functions for querying
+@cindex extending, functions for querying overlays
+These functions query certain things about auto-overlays or match
+overlays, or retrieve certain values associated with them. A few are
+merely convenience functions, but most depend on the internal
+implementation details of the auto-overlays package, and provide the
+only reliable interface for whatever they return.
+
+@table @code
+@item (auto-o-class @var{o-match})
+@findex auto-o-class
+Return the class of match overlay @var{o-match}.
+
+
+@item (auto-o-regexp @var{o-match})
+@findex auto-o-regexp
+Return the regular expression matched by the text covered by match
+overlay @var{o-match}.
+
+
+@item (auto-o-regexp-group @var{o-match})
+@findex auto-o-regexp-group
+Return the regexp group defined in the regexp definition corresponding
+to match overlay @var{o-match} (@pxref{Defining Regexps}).
+
+
+@c @item @c (auto-o-regexp-group-nth n @var{o-match})
+@c @findex auto-o-regexp-group-nth
+@c Return match overlay @var{o-match}'s Nth regexp group entry, or 0
+@c if there is no Nth entry.
+
+
+@item (auto-o-props @var{o-match})
+@findex auto-o-props
+Return the list of overlay properties defined in the regexp definition
+corresponding to match overlay @var{o-match} (@pxref{Defining Regexps}).
+
+
+@item (auto-o-edge @var{o-match})
+@findex auto-o-edge
+Return edge (the symbol @code{start} or @code{end}) of match overlay
+@var{o-match}.
+
+
+@item (auto-o-parse-function @var{o-match})
+@findex auto-o-parse-function
+Return appropriate parse function for match overlay @var{o-match}.
+
+
+@item (auto-o-suicide-function @var{o-match})
+@findex auto-o-suicide-function
+Return appropriate suicide function for match overlay @var{o-match}.
+
+
+@item (auto-o-match-function @var{o-match})
+@findex auto-o-match-function
+Return match function for match overlay @var{o-match}, if any.
+
+
+@item (auto-o-edge-matched-p @var{overlay} @var{edge})
+@findex auto-o-edge-matched-p
+Return non-nil if @var{edge} (the symbol @code{start} or @code{end}) of
+auto-overlay @code{overlay} is matched.
+
+
+@item (auto-o-start-matched-p @var{overlay})
+@findex auto-o-start-matched-p
+Return non-nil if auto-overlay @var{overlay} is start-matched.
+
+
+@item (auto-o-end-matched-p @var{overlay})
+@findex auto-o-end-matched-p
+Return non-nil if auto-overlay @var{overlay} is end-matched.
+@end table
+
+
+
+@node Auto-Overlay Hooks
+@section Auto-Overlay Hooks
+@cindex hooks
+@cindex package, hooks
+@cindex hooks, loading and unloading
+The auto-overlays package defines two hooks, that are called when
+auto-overlays are enabled and disabled in a buffer. These are intended
+to be used by overlay classes to set up any extra buffer-local variables
+and settings they require, and clean them up afterwards. (There is no
+point leaving auto-overlay variables and settings hanging around in a
+buffer when auto-overlays are not in use.)
+
+@vtable @env
+@item auto-overlay-load-hook
+This hook is run when the first auto-overlay regexp set in a buffer is
+started, using the @command{auto-overlay-start} function. @xref{Starting
+and Stopping Auto-Overlays}.
+
+
+@item auto-overlay-unload-hook
+This hook is run when the last auto-overlay regexp set in a buffer is
+stopped, using the @command{auto-overlay-stop} function. @xref{Starting
+and Stopping Auto-Overlays}.
+@end vtable
+
+
+
+
+@node Auto-Overlay Modification Pseudo-Hooks
+@section Auto-Overlay Modification Pseudo-Hooks
+@cindex modification pseudo-hooks
+@cindex hooks, modification
+@cindex scheduling functions after modification
+@cindex functions, scheduling
+The auto-overlays package adds functions to buffer and overlay
+modification hooks in order to update the overlays as the buffer text is
+modified (@pxref{Modification Hooks,,,elisp,GNU Emacs Lisp Reference
+Manual}). The order in which all these modification hooks are called is
+undefined in Emacs@footnote{Or at least undocumented, and therefore
+unreliable.}. Therefore, the auto-overlays package provides a mechanism
+to schedule functions to run at particular points during the overlay
+update process.
+
+There are two stages to the overlay update process: first, any match
+overlay suicide functions are called, then modified buffer lines are
+scanned for new regexp matches. Three pseudo-hooks are defined that are
+called before, after and in between these stages. Their values are lists
+containing elements of the form:
+@lisp
+(@var{function} @var{arg1} @var{arg2} ...)
+@end lisp
+where @var{function} is the function to be called by the hook, and the
+@var{arg}'s are the arguments to be passed to that function. The list
+elements are evaluated in order. The pseudo-hooks are cleared each time
+after they have been called.
+
+@vtable @env
+@item auto-o-pending-pre-suicide
+Pseudo-hook called before any suicide functions.
+
+
+@item auto-o-pending-post-suicide
+Pseudo-hook called after any suicide functions but before scanning for
+regexp matches.
+
+
+@item auto-o-pending-post-update
+Pseudo-hook called after scanning for regexp matches.
+@end vtable
+
+These pseudo-hooks can be used to ensure that a function that would
+normally be added to a modification hook will be called at a particular
+point in the auto-overlay update process. To achieve this, a helper
+function must be added to the modification hook instead. The helper
+function should add the function itself to the appropriate pseudo-hook
+by adding a list element with the form described above. The
+@command{push} and @command{add-to-list} Elisp functions are the most
+useful ways to add elements to the list.
+
+
+
+@node To-Do
+@chapter To-Do
+@cindex to-do
+Things that still need to be implemented (in no particular order):
+
+@enumerate
+@item
+There needs to be an @code{eager-self} overlay class, similar to the
+existing @code{self} class but updated immediately, rather than waiting
+for buffer modifications. This will be significantly less efficient, but
+is necessary for applications that require overlays to be up to date all
+the time, not just when the buffer is being modified.
+
+
+@item
+Currently, it's difficult to deal with @code{nested} class regexps for
+which the @code{end} regexps match some @code{start} regexps of interest
+but also others that are irrelevant. E.g. @samp{@{} and @samp{@}} in
+@LaTeX{} when you're only interested in @samp{\somecommand@{}
+@code{start} regexps. Or matching parens in LISP, when you're only
+interested in function bodies, say. The only solution is to include all
+@code{start} regexps, but not set any of their properties. This can end
+up creating a lot of overlays! A variant of the @code{nested} class that
+avoids this problem is needed.
+@end enumerate
+
+
+
 
 
 @node Function Index