bug#12694: 24.2.50; `file-cache-add-file(-list)' commands

[Drew Adams]

1. These two commands are not documented along with the others, in the
Emacs manual.  Fair enough, if they are not deemed useful enough.  Just
mentioning this here in case it was overlooked.
 
2. Doc string of `file-cache-add-file-list':
 
a. Typo: "files names" -> "file names".
 
b. The doc string should say that the input you provide is read as a
Lisp sexp and evaluated to produce a list of (absolute?) file names.
Otherwise users of the command will have no idea what to type!  IOW,
users do not see the `X' `interactive' spec, and the implementation
of that spec provides no runtime help to users (AFAIK).
 
3. A cursory scan of the code suggests that the behavior might not be
correct if you input a relative file name to `file-cache-add-file-list'.

If you do that,  directory of nil is recorded for the file, and I'm
guessing that is incorrect (?).  If so, then `file-cache-add-file-list'
should, for example, expand the name relative to the default directory.
 
If it is not incorrect, then #2 above should mention that your input can
be an absolute or a relative file name, and it should explain what the
interpretation of a relative file name is.

IOW, how does the code use an element of `file-cache-alist' that looks
like this: ("foo.el" nil)?  Does it interpret the nil at runtime (i.e.,
during completion) as the default directory?  Just what does it do?
 
If a user doesn't know what form the input must take then s?he cannot
use the command.  To know that means to know something about the
_treatment_ of an entry like ("foo.el" nil) (even if it does not
imply that that form need be known to users), which form is allowed
today (but whose behavior doesn't seem to be described anywhere).
 
4. `file-cache-add-file': Why does the file need to exist for
interactive use?  Why not let users add names of files that do not yet
exist?  In any case we provide a message for such a case.  That
message is used currently only when NOT interactive, which seems wrong
in itself.  Code executed non-interactively has little use for messages.
(Of course, if the function is called from a command that is itself
invoked interactively then showing the message might make sense.)

In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600)
 of 2012-10-15 on DANI-PC
Bzr revision: 110553 monnier@iro.umontreal.ca-20121015164957-6zms5w2js1xkldtg
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'