bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual

[Eli Zaretskii]

> Date: Wed, 9 Sep 2015 07:57:13 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. In node `Categories' you give an example that is incomprehensible, as
> it uses function `unicode-property-table-internal', which is not
> explained anywhere in the manual.  With just the doc string of that
> function to go on, it is difficult, if not impossible, to understand the
> example.

The doc string of unicode-property-table-internal says:

  (unicode-property-table-internal PROP)

  Return a char-table for Unicode character property PROP.

What exactly is unclear about that?  That's an honest question: this
sounds crystal clear to me.

> There is a cross-reference to node `Bidirectional Display', but that
> node, although quite long (and with large, verbose paragraphs) does not
> seem to help with understanding the example.  It didn't help me, at
> least.

That cross-reference is for those who don't know what is "strong
right-to-left directionality".

> Please consider adding a little explanation of the example, including,
> for instance, what table `uniprop-table' is being used for.

It is used as an argument to map-char-table, as should be clear from
the example.  Once again, I don't see what should be explained about
that.

> Adding a docstring for the `defvar' would also help.

This text before the example:

     Here's an example of defining a new category for characters that
     have strong right-to-left directionality

is all that can be said about that defvar.

> 2. The example also not indented properly - see the second `let' binding

Fixed (someone left TABs in the Texinfo source, which is a no-no).

> 3. Please consider also adding to the description of each of the
> functions described in this node the statement that TABLE defaults to
> the current buffer's category table - as opposed to having this
> statement only in the sentence preceding the individual function
> descriptions.

I don't see why this should be an issue -- that sentence immediately
precedes the description of the functions.