bug#13177: 24.3.50; doc of `read-char-by-name'

[Drew Adams]

Emacs-Lisp `read*' functions generally return what they say
they read.  This function does not necessarily return a character,
which is what its doc says it does.  It can return nil.  The doc
needs to mention this behavior, especially as it is pretty
exceptional.
 
There's nothing wrong with such behavior, but I wonder a bit whether
this function shouldn't perhaps use `completing-read' with a non-nil
REQUIRE-MATCH argument.  IOW, perhaps it should ignore names that
are unknown.  In that case it would always do what the doc currently
says it does: return a character (by name).  At least it's another
possibility.

Dunno just what the intention was for this function.  If it really
was to return a recognized Unicode character then this is a product
bug and reading should not end until the user enters matching input
(or hits `C-g').  If the intention was really to do what the
function does now, then this is a doc bug: mention a possible nil
return value and what it means.
 
Alternatively, we might add another function, say
`read-char-by-name-exclusive', that always returns a named char.
That would be somewhat analogous to how `read-char-exclusive'
ignores non-chars, while `read-char' signals an error for them.
(Note though that neither of those functions simply accepts and
returns a non-char event.)
 
Anyway, for this bug report and for my part, it would be enough
to correct the doc to say that if the user enters a name that
is unknown then nil is returned.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-13 on ODIEONE
Bzr revision: 111211 eggert@cs.ucla.edu-20121213021749-eyqqen0ewhn2hogq
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include -Wall -Wextra -Wno-sign-compare
 -Wno-type-limits -Wno-missing-field-initializers -Wno-pointer-sign
 -Wdeclaration-after-statement --ldflags -LC:/Devel/emacs/build/lib'