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

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

[Drew Adams]

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.

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.

Please consider adding a little explanation of the example, including,
for instance, what table `uniprop-table' is being used for.  Adding a
docstring for the `defvar' would also help.

2. The example also not indented properly - see the second `let' binding
(which also needs to be on two lines, as it is too long if indented
properly).

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=A1=AFs category table - as opposed to having this
statement only in the sentence preceding the individual function
descriptions.  Each description acts somewhat like a doc string - it
would help if it were pretty much self-contained.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-08-16 on LEG570
Bzr revision: f7ee23e587b01f179284b5554c67d579a2def676
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=3Di686-pc-mingw32 --enable-checking=3Dyes,glyphs'

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.

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

[Drew Adams]

> > 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:

Yes, I read, and referred to, the doc string.

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

The bug is about the example in the manual, not about the doc string.

As the bug report says, the doc string of `unicode-property-table-internal'
is not enough to understand the example.  Please explain the _example_,
in the manual.

> > 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".

It's fine to have that cross reference.  As the bug report says, it does
not do much to help you understand the _example_.

> > 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.

Clearly, it is passed as argument to `map-char-table'.  That does not
explain the example.

> > 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.

What can be said about the example is to explain it.  If you don't
think a doc string would help with that, then fine.  I agree that
the defvar docstring would not explain how the example does what it
does.

> > 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.

Just a suggestion.  It would be clearer, but it is not the point of
this report.  For that, see #1.

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

[Eli Zaretskii]

> Date: Wed, 9 Sep 2015 13:07:24 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21448@debbugs.gnu.org
> 
> > > 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:
> 
> Yes, I read, and referred to, the doc string.
> 
> > What exactly is unclear about that?  That's an honest question: this
> > sounds crystal clear to me.
> 
> The bug is about the example in the manual, not about the doc string.

OK, then please provide more details about what information should be
added to explain the example.  I think the code is straightforward, it
just loops over a char-table, which is clear from the code.  What is
missing?

I really need that help, if you want any changes.  Just repeating that
the example is not clear enough doesn't cut it.

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

[Drew Adams]

> OK, then please provide more details about what information should be
> added to explain the example.  I think the code is straightforward, it
> just loops over a char-table, which is clear from the code.  What is
> missing?
> 
> I really need that help, if you want any changes.  Just repeating that
> the example is not clear enough doesn't cut it.

Thank you for looking into this.  Let me start by saying that the
first part of the node, which explains categories, is very clear
and well put.

I think that all that is missing wrt explaining the example is to
say (in this node) what `uniprop-table' is here, and why and how
it is used.

A minor help might be to rename variable `uniprop-table' to, say,
`bidi-class-table' or `bidi-table'.  I don't know enough about bidi
or `unicode-property-table-internal' to really know what this
char-table is: what its char entries are mapped to.  Something to
do with character property `bidi-class' (a property I am  not
familiar with).  Maybe it means that a char entry is mapped by the
table to all of the chars in its bidi class?

These bidi things are clear to you, but not necessarily to a
reader of this node.  A few words about this might help.

If the use of `bidi-class-table' is clarified (explained a bit)
then I think the example becomes clear.  You iterate over
`bidi-class-table', and for any char that the table maps to R, AL,
or RLO, you modify that same char's entry in the new `category-table',
so that the char gets mapped in `category-table' to the character
?R (which represents its category) .

It might also help if function `modify-category-entry' were
presented before this example, but that's not critical.

HTH.  Feel free to close the bug if you disagree about adding
some explanation here.  (Well, it's already closed, I guess.)

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

[Drew Adams]

> HTH.  Feel free to close the bug if you disagree about adding
> some explanation here.  (Well, it's already closed, I guess.)

I was mistaken - this bug is not yet closed.  I confused it with
bug #21441.

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

[Eli Zaretskii]

> Date: Thu, 10 Sep 2015 08:27:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21448@debbugs.gnu.org
> 
> I think that all that is missing wrt explaining the example is to
> say (in this node) what `uniprop-table' is here, and why and how
> it is used.

Is the text below OK?

     Here's an example of defining a new category for characters that
     have strong right-to-left directionality (*note Bidirectional
     Display::) and using it in a special category table.  To obtain
     the information about the directionality of characters, the
     example code uses the `bidi-class' Unicode property (*note
     bidi-class: Character Properties.).

          (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))
                       (modify-category-entry key ?R category-table)))
               uniprop-table)
              category-table))

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

[Drew Adams]

> > I think that all that is missing wrt explaining the example is to
> > say (in this node) what `uniprop-table' is here, and why and how
> > it is used.
> 
> Is the text below OK?

Super.  Thank you.

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

[Eli Zaretskii]

> Date: Thu, 10 Sep 2015 10:23:09 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21448@debbugs.gnu.org
> 
> > > I think that all that is missing wrt explaining the example is to
> > > say (in this node) what `uniprop-table' is here, and why and how
> > > it is used.
> > 
> > Is the text below OK?
> 
> Super.  Thank you.

Pushed.