[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
doc strings for read-*-completion-ignore-case [was: add `read-buffer-com
From: |
Drew Adams |
Subject: |
doc strings for read-*-completion-ignore-case [was: add `read-buffer-completion-ignore-case' ?] |
Date: |
Sun, 8 Jun 2008 15:51:47 -0700 |
> 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.
Re: add `read-buffer-completion-ignore-case' ?, John Paul Wallington, 2008/06/09