doc strings for read-*-completion-ignore-case [was: add `read-buffer-completion-ignore-case' ?]

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

> It adds a customizable variable, `read-buffer-completion-ignore-case',
> that specifies the case-sensitivity of completion for `read-buffer'.
> Its default value is nil, meaning that `read-buffer' is case-sensitive
> when completing buffer names.

Actually, the doc strings for both variables (file and buffer) seem incomplete
(and even not quite correct) to me: "Non-nil means when reading a buffer name
completion ignores case."

I would like to see a little more, saying explicitly that this means only when
using `read-buffer' or an `interactive' spec with spec "B..." or "b...".
Similarly for file names and `read-file-name'.

The reason:

1. It's not obvious that if you read a file name using, say, `completing-read'
with file-name candidates as the TABLE arg, this variable has no effect. You
must use `read-file-name'. Similarly for reading a buffer name using
`completing-read' with a list of buffer names as TABLE arg - the variable has no
effect.

2. It's not obvious that (interactive "B...") uses `read-buffer', and so on.

At least the latter was not obvious to me. I had to study the C code just now to
see how it is that a change to `read-buffer' also affects (interactive "B...").

Both #1 and #2 are important to know for those programming in Emacs Lisp. #1 is
presumably the reason for the name `read-buffer-...' instead of
`read-buffer-name-...'.

And #1 is presumably the reason for both names instead of, say, just
`file-name-completion-ignore-case' and `buffer-name-completion-ignore-case'.
These variables do not, _in general_, affect completion when reading a buffer
name or a file name - they are limited to `read-buffer' and `read-file-name'
(and `interactive'). 

The doc strings should help dispel the idea that this is about completion of
buffer/file names - it is about `read-buffer' and `read-file-name',
specifically.

---

Also, the doc strings are not great grammatically. It would be clearer to say:
"Non-nil means that file-name completion ignores case." 

Or, if you really want to keep the current order (which is less clear, IMO),
then: "Non-nil means that, when reading a file name, completion ignores case."
The "that" here helps understanding, especially for those whose mother tongue is
not English.