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

["Drew Adams" <drew.adams@oracle.com>]

> > 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').
> 
> As its docstring says, it also accepts a hexadecimal number
> of Unicode code whose input can't use completion.

Yes, I know.  But the doc string also says that the hex numbers accepted are
those corresponding to Unicode code points.  And it mentions hash notation for
numbers, but in that case it does not say that those numbers too must correspond
to Unicode code points.

The question I posed is whether the intention was to always return a recognized
Unicode char.  If that is the case then the function should never return nil or
anything else (e.g. a non code-point number) other than a Unicode char.  It's an
open question.

If you are answering for the design intention, stating that the intention is not
to do what the doc currently says (always return a Unicode char), then fine.  In
that case, all that's needed is a doc-string patch, to point out that exception
to its general statement.

However (see below), that exception needs to be clarified in the case of hash
notation input that does not correspond to a Unicode char.

> +When input is neither a known Unicode name nor a hex number string,
> +return nil."

It is not enough, according to the existing doc string, for input to be  any old
hex number - it must be a "hexadecimal number of Unicode code point" - or
presumably we return nil (?).  The additional info should say this (or
equivalent):

"Return nil if the input does not correspond to a Unicode character."

The doc string should also be corrected to not give the impression that hash
notation input somehow escapes this need for the number to represent a
character, i.e., to be numerically equivalent to "a hexadecimal number of
Unicode code point".

So we should replace the last paragraph of the doc string with something like
this:

"Besides a Unicode character name, input can represent a Unicode character
numerically.  It can be a hexadecimal number or a number in hash notation, e.g.
#o21430 for octal, #x2318 for hex, or #10r8984 for decimal."

Follow that with the statement above that _any other_ input, i.e., any input
that does not correspond to a recognized Unicode char, means return nil.  Then
things will be clear.

Otherwise, we are not saying anything about what is returned if the input hash
notation does not correspond to a Unicode char - a doc bug.

If, on the other hand, it is not the case that the function returns nil for hash
notation input that does not correspond to a known character, then the doc
should say that clearly.

In that case, the function has two exceptions to returning a Unicode character:

1. Return nil if a name is entered that is not a recognized name.

2. Return a number if hash notation is entered that does not match a Unicode
code point.

I cannot speak for what the function is supposed to do (design), so I cannot say
whether there is a code bug or a doc bug here.  I can only outline the
possibilities.