bug#21441: 25.0.50; doc of `make-char-table'

bug#21441: 25.0.50; doc of `make-char-table'

[Drew Adams]

The doc is inconsistent and unclear wrt the first argument.

In (elisp) `Char-Tables' the arg is named SUBTYPE.  In the doc string it
is named PURPOSE.  Why SUBTYPE and not TYPE?  There is no parent type
described anywhere, for which this arg would be the SUBtype.

Please make the doc clearer, reconciling the treatment of the arg as a
"purpose" and as a "subtype".


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=i686-pc-mingw32 --enable-checking=yes,glyphs'

bug#21441: 25.0.50; doc of `make-char-table'

[Eli Zaretskii]

> Date: Wed, 9 Sep 2015 08:10:45 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The doc is inconsistent and unclear wrt the first argument.
> 
> In (elisp) `Char-Tables' the arg is named SUBTYPE.  In the doc string it
> is named PURPOSE.  Why SUBTYPE and not TYPE?

Because "type" is char-table.

> Please make the doc clearer, reconciling the treatment of the arg as a
> "purpose" and as a "subtype".

The text before the description of make-char-table explains at length
what is the subtype.  I see nothing unclear there.  I also see no
reason to insists that the doc string and the manual use exactly the
same nomenclature for the arguments.

In sum, I see nothing that needs to be fixed here.

I'm closing the bug.

bug#21441: 25.0.50; doc of `make-char-table'

[Drew Adams]

> > The doc is inconsistent and unclear wrt the first argument.
> >
> > In (elisp) `Char-Tables' the arg is named SUBTYPE.  In the doc string it
> > is named PURPOSE.  Why SUBTYPE and not TYPE?
> 
> 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".
> 
> The text before the description of make-char-table explains at length
> what is the subtype.  I see nothing unclear there. 

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.