From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 10 Sep 2015 17:39:02 +0000 (+0300)
Subject: Improve documentation of categories
X-Git-Tag: emacs-25.0.90~1224^2~162
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0fafb582957135a16a9603c420e992dc46a50544;p=emacs.git

Improve documentation of categories

* doc/lispref/syntax.texi (Categories): Clarify the example of
using define-category and modify-category-entry.  (Bug#21448)
---

diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 3ab1e9d81d8..5d9935dc556 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -1084,14 +1084,23 @@ 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:
+and using it in a special category table.  To obtain the information
+about the directionality of characters, the example code uses the
+@samp{bidi-class} Unicode property (@pxref{Character Properties,
+bidi-class}).
 
 @example
 (defvar special-category-table-for-bidi
+  ;;     Make an empty category-table.
   (let ((category-table (make-category-table))
+        ;; Create a char-table which gives the 'bidi-class' Unicode
+        ;; property for each character.
         (uniprop-table (unicode-property-table-internal 'bidi-class)))
     (define-category ?R "Characters of bidi-class R, AL, or RLO"
                      category-table)
+    ;; Modify the category entry of each character whose 'bidi-class'
+    ;; Unicode property is R, AL, or RLO -- these have a
+    ;; right-to-left directionality.
     (map-char-table
      #'(lambda (key val)
          (if (memq val '(R AL RLO))