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

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'
 

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

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

Fixed in the branch, thanks.

> 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'.

Fixed in trunk.

> 4. `file-cache-add-file': Why does the file need to exist for
> interactive use?

I believe that's somewhat inherent in the design of filecache.el.  The
package assumes that the cached file names have unique non-directory
parts.  If `file-cache-add-file' lets you enter a non-existent file
name, and that inadvertently has the same non-directory part as an
existing cache entry, the result would be to wipe out the cache entry
for the existing file in favor of a non-existent entry, which would be
annoying.  That said, I don't personally use filecache.el; this is only
from my reading of the code.

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

[Drew Adams]

> > 4. `file-cache-add-file': Why does the file need to exist for
> > interactive use?
> 
> I believe that's somewhat inherent in the design of filecache.el.  The
> package assumes that the cached file names have unique non-directory
> parts.  If `file-cache-add-file' lets you enter a non-existent file
> name, and that inadvertently has the same non-directory part as an
> existing cache entry, the result would be to wipe out the cache entry
> for the existing file in favor of a non-existent entry, which would be
> annoying.  That said, I don't personally use filecache.el; 
> this is only from my reading of the code.

Thanks.  But what about the call to `message' for non-interactive use?  That's
pretty uncommon.  What's the rationale for that here?

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

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Thanks.  But what about the call to `message' for non-interactive use?
> That's pretty uncommon.  What's the rationale for that here?

I've converted it into an error.

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

[Drew Adams]

> > Thanks.  But what about the call to `message' for 
> > non-interactive use? That's pretty uncommon.  What's
> > the rationale for that here?
> 
> I've converted it into an error.

Thanks.