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#21441: 25.0.50; doc of `make-char-table' Date: Wed, 9 Sep 2015 09:14:46 -0700 (PDT) Message-ID: <05c22ac6-7f67-4976-ab73-36c3177b8e6a@default> References: <<08a7ab3a-5a20-4157-9cf5-a1b95ddf40b7@default>> <<83oahb60nt.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 1441815339 8632 80.91.229.3 (9 Sep 2015 16:15:39 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 9 Sep 2015 16:15:39 +0000 (UTC) Cc: 21441-done@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 18:15:25 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 1ZZi1h-0002jq-Ke for geb-bug-gnu-emacs@m.gmane.org; Wed, 09 Sep 2015 18:15:13 +0200 Original-Received: from localhost ([::1]:43839 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZi1h-0000V5-5m for geb-bug-gnu-emacs@m.gmane.org; Wed, 09 Sep 2015 12:15:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37307) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZi1a-0000Uj-39 for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 12:15:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZZi1W-0003hG-Mv for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 12:15:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33608) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZZi1W-0003gq-J9 for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 12:15:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1ZZi1W-0007Qf-3L for bug-gnu-emacs@gnu.org; Wed, 09 Sep 2015 12:15: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 16:15:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21441 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 21441-done@debbugs.gnu.org id=D21441.144181529328531 (code D ref 21441); Wed, 09 Sep 2015 16:15:02 +0000 Original-Received: (at 21441-done) by debbugs.gnu.org; 9 Sep 2015 16:14:53 +0000 Original-Received: from localhost ([127.0.0.1]:54051 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZZi1M-0007Q7-NQ for submit@debbugs.gnu.org; Wed, 09 Sep 2015 12:14:53 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:49740) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1ZZi1K-0007Py-Cg for 21441-done@debbugs.gnu.org; Wed, 09 Sep 2015 12:14:50 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id t89GEma5032141 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 9 Sep 2015 16:14:49 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id t89GEm1I011556 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Wed, 9 Sep 2015 16:14:48 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 t89GElrY029848; Wed, 9 Sep 2015 16:14:47 GMT In-Reply-To: <<83oahb60nt.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: userv0022.oracle.com [156.151.31.74] 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:106307 Archived-At: > > The doc is inconsistent and unclear wrt the first argument. > > > > In (elisp) `Char-Tables' the arg is named SUBTYPE. In the doc string i= t > > is named PURPOSE. Why SUBTYPE and not TYPE? >=20 > Because "type" is char-table. The doc refers to "char-table" as _a_ char table, not as a type. And it says the each char table has a "subtype" (in quotes). That says that a table has a subtype, which is already unclear. A table is not considered a type,normally. If arg SUBTYPE is a subtype of "char-table", whatever is meant (and there is no explanation) by "subtype", then say so: say that SUBTYPE is a subtype of the char-table that is created by `make-char-table' (if that is what is meant - I'm really just guessing here, as the text is nearly totally unclear). > > Please make the doc clearer, reconciling the treatment of the arg as a > > "purpose" and as a "subtype". >=20 > The text before the description of make-char-table explains at length > what is the subtype. I see nothing unclear there.=20 See above. It is quite unclear as currently written. In addition, nothing about this is in the doc string. It seems to say something entirely different. > I also see no > reason to insists that the doc string and the manual use exactly the > same nomenclature for the arguments. I don't care about the nomenclature or the wording. What is not clear is the _message_. And in particular, whatever the message is, it does not seem to be the same, between the manual text and the doc string. > In sum, I see nothing that needs to be fixed here. > I'm closing the bug. Too bad. This doc is unclear. The problem is presumably that the message is clear to you, but you have not expressed it, and you cannot see that. When you read the text you think of your understanding of what you want to say, rather than only what the text says. Trust me, the text is not comprehensible - certainly not helpful enough. Not even enough for me to offer a suggestion - I do not understand what message it is really trying to convey.