From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#21448: 25.0.50; `unicode-property-table-internal' in Elisp manual Date: Wed, 9 Sep 2015 13:07:24 -0700 (PDT) Message-ID: <029d2a95-ca25-48be-bf19-2159ed753d81@default> References: <> <<83io7j5rye.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1441830627 11757 80.91.229.3 (9 Sep 2015 20:30:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 9 Sep 2015 20:30:27 +0000 (UTC) Cc: 21448@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Sep 09 22:30:13 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZZm0P-0000FV-3T for geb-bug-gnu-emacs@m.gmane.org; Wed, 09 Sep 2015 22:30:09 +0200 Original-Received: from localhost ([::1]:45333 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZlgu-0001IL-Ug for geb-bug-gnu-emacs@m.gmane.org; Wed, 09 Sep 2015 16:10:00 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41443) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZlf4-0007Yb-Ac for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 16:08:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZZlf1-0006rg-0Z for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 16:08:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33768) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZlf0-0006rZ-TF for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 16:08:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1ZZlf0-00082L-E8 for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 16:08:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 09 Sep 2015 20:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21448 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 21448-submit@debbugs.gnu.org id=B21448.144182925130823 (code B ref 21448); Wed, 09 Sep 2015 20:08:02 +0000 Original-Received: (at 21448) by debbugs.gnu.org; 9 Sep 2015 20:07:31 +0000 Original-Received: from localhost ([127.0.0.1]:54211 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZZleU-000813-F0 for submit@debbugs.gnu.org; Wed, 09 Sep 2015 16:07:30 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:33566) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZZleR-00080o-2q for 21448@debbugs.gnu.org; Wed, 09 Sep 2015 16:07:27 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t89K7PmG032141 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 9 Sep 2015 20:07:26 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0021.oracle.com (8.13.8/8.13.8) with ESMTP id t89K7PB8012093 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Wed, 9 Sep 2015 20:07:25 GMT Original-Received: from abhmp0005.oracle.com (abhmp0005.oracle.com [141.146.116.11]) by aserv0122.oracle.com (8.13.8/8.13.8) with ESMTP id t89K7POX023125; Wed, 9 Sep 2015 20:07:25 GMT In-Reply-To: <<83io7j5rye.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:106327 Archived-At: > > 1. In node `Categories' you give an example that is incomprehensible, a= s > > 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 th= e > > example. >=20 > 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. >=20 > 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. >=20 > 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. >=20 > This text before the example: >=20 > Here's an example of defining a new category for characters that > have strong right-to-left directionality >=20 > 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' bindin= g >=20 > Fixed (someone left TABs in the Texinfo source, which is a no-no). >=20 > > 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. >=20 > 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.