[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual
From: |
Drew Adams |
Subject: |
bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual |
Date: |
Wed, 9 Sep 2015 13:07:24 -0700 (PDT) |
> > 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, Drew Adams, 2015/09/09
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Eli Zaretskii, 2015/09/09
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual,
Drew Adams <=
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Eli Zaretskii, 2015/09/09
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Drew Adams, 2015/09/10
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Drew Adams, 2015/09/10
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Eli Zaretskii, 2015/09/10
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Drew Adams, 2015/09/10
- bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual, Eli Zaretskii, 2015/09/10