Subject: 24.1; doc about characters and `characterp'

From: "Drew Adams" <[email-masked]>
Date: Sat, 28 Jul 2012 10:14:56 -0700

The Elisp manual has always said that in Emacs characters are integers.
And so they are, still; and so the manual says, still.  Good.
 
But not all integers are characters.  And we now have predicate
`characterp' to distinguish those that are from those that are not.
Good.
 
But the doc for `characterp' says nothing about characters being
integers.  That's not good, even if the intention is for the predicate
to serve at a higher level of abstraction.  In Emacs Lisp things should
be clear to users.
 
Please update (elisp) `Character Codes' to make it clear, as a reminder,
that (all) characters are integers.  Yes, that should be clear from the
use of #x... syntax etc.  But a reminder helps.  And please add a cross
reference to node `String Basics', where characters are introduced.
 
More importantly, the doc string of `characterp' should also mention
that a character is an integer.  All that's needed, to help users more,
is to add a couple of words:
 
"Return non-nil if OBJECT is an integer that is a valid character."
                          ^^^^^^^^^^^^^^^^^^

The general doc introducing characters is in node `String Basics'.  It
is pretty good as it is, because it implicitly says that not all
integers are characters (it explicitly says that whether an integer is a
character is determined by its use), and because it cross-references
node `Character Codes', which presents predicate `characterp'.
 
Although `String Basics' is pretty good, it would be helpful to mention
`characterp' there, as the predicate that determines "whether an integer
is a character or not" (supposedly by examining "how it is used" (?)).
IOW, mention predicate `characterp' here, and cross-reference the node
where it is described in detail.

In GNU Emacs 24.1.1 (i386-mingw-nt5.1.2600)
 of 2012-06-10 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'