Improve documentation of regexp search for categories.

 doc/lispref/searching.texi (Regexp Backslash): Document how to display
 existing categories.  Mention the possibility of adding
 categories, and add an xref to where this is described.  Add an
 index entry.
 doc/lispref/syntax.texi (Categories): Add an example of defining a new
 category and category table.

3 files changed, 33 insertions, 1 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 5bdc17136e1..40ad3dc8c52 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2011-08-16  Eli Zaretskii  <eliz@gnu.org>
+
+        * syntax.texi (Categories): Add an example of defining a new
+        category and category table.
+
+        * searching.texi (Regexp Backslash): Document how to display
+        existing categories.  Mention the possibility of adding
+        categories, and add an xref to where this is described.  Add an
+        index entry.
+
 2011-08-09  Chong Yidong  <cyd@stupidchicken.com>
 
         * text.texi (Special Properties):
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 6272301dbb4..fe7c805c6f7 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -717,11 +717,15 @@ the characters that stand for them.
 @cindex @samp{\S} in regexp
 matches any character whose syntax is not @var{code}.
 
+@cindex category, regexp search for
 @item \c@var{c}
 matches any character whose category is @var{c}.  Here @var{c} is a
 character that represents a category: thus, @samp{c} for Chinese
 characters or @samp{g} for Greek characters in the standard category
-table.
+table.  You can see the list of all the currently defined categories
+with @kbd{M-x describe-categories @key{RET}}.  You can also define
+your own categories in addition to the standard ones using the
+@code{define-category} function (@pxref{Categories}).
 
 @item \C@var{c}
 matches any character whose category is not @var{c}.
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 31ee7eb4e7d..0d7a0c0bed4 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -1084,6 +1084,24 @@ defaults to the current buffer's category table.
 @defun define-category char docstring &optional table
 This function defines a new category, with name @var{char} and
 documentation @var{docstring}, for the category table @var{table}.
+
+Here's an example of defining a new category for characters that have
+strong right-to-left directionality (@pxref{Bidirectional Display})
+and using it in a special category table:
+
+@example
+(defvar special-category-table-for-bidi
+  (let ((category-table (make-category-table))
+        (uniprop-table (unicode-property-table-internal 'bidi-class)))
+    (define-category ?R "Characters of bidi-class R, AL, or RLO"
+                     category-table)
+    (map-char-table
+     #'(lambda (key val)
+         (if (memq val '(R AL RLO))
+             (modify-category-entry key ?R category-table)))
+     uniprop-table)
+    category-table))
+@end example
 @end defun
 
 @defun category-docstring category &optional table