 A cscope database directory is one in which EITHER a cscope database
 file (e.g., \"cscope.out\") OR a cscope file list (e.g., \"cscope.files\")
 exists.
+
+Here is an example of `cscope-database-regexps':
+
+        (setq cscope-database-regexps
+              '(
+                ( \"^/users/jdoe/sources/proj1\"
+                  ( t )
+                  ( \"/users/jdoe/sources/proj2\")
+                  ( \"/users/jdoe/sources/proj3\")
+                  t
+                  ( \"/some/master/directory\" (\"-d\" \"-I/usr/local/include\") )
+                  )
+                ( \"^/users/jdoe/sources/gnome/\"
+                  ( \"/master/gnome/database\" (\"-d\") )
+                  )
+                ))
+
+If the current buffer's directory matches the regexp,
+\"^/users/jdoe/sources/proj1\", then the following search will be
+done:
+
+    1. First, the normal hierarchical database search will be used to
+       locate a cscope database.
+
+    2. Next, searches will be done using the cscope database
+       directories, \"/users/jdoe/sources/proj2\" and
+       \"/users/jdoe/sources/proj3\".
+
+    3. If a match was found, searching will stop.
+
+    4. If a match was not found, searching will be done using
+       \"/some/master/directory\", and the command-line options \"-d\"
+       and \"-I/usr/local/include\" will be passed to cscope.
+
+If the current buffer's directory matches the regexp,
+\"^/users/jdoe/sources/gnome\", then the following search will be
+done:
+
+    The search will be done only using the directory,
+    \"/master/gnome/database\".  The \"-d\" option will be passed to
+    cscope.
+
+If the current buffer's directory does not match any of the above
+regexps, then only the normal hierarchical database search will be
+done.
+
 "
   :type '(repeat (list :format "%v"
 		       (choice :value ""


(defcustom cscope-database-regexps nil
  "*List to force directory-to-cscope-database mappings.
This is a list of `(REGEXP DIRECTORY OPTIONS)' triplets, where:

REGEXP is a regular expression matched against the current buffer's
current directory.  The current buffer is typically some source file,
and you're probably searching for some symbol in or related to this
file.  Basically, this regexp is used to relate the current directory
to a cscope database.

DIRECTORY is the name of the corresponding directory containing (or will
contain, if creating) the cscope database files.

OPTIONS is a string listing any additional options (e.g., \"-d\") to pass
to the cscope executable.  Normally, this string is empty.

All of the above are strings.

This variable is generally not used, as the normal hierarchical
database search is sufficient for placing and/or locating the cscope
databases.  However, there may be cases where it makes sense to place
the cscope databases away from where the source files are kept; in
this case, this variable is used to determine the mapping.

This module searches for the cscope databases by first using this
variable; if a database location cannot be found using this variable,

  (interactive "DIndex files in directory: ")
  (let ()
    (cscope-unix-index-files-internal
     top-directory
     (format "Creating cscope index `%s' in:\n\t%s\n\n%s"
	     cscope-database-file top-directory cscope-separator-line)
     nil)
