RE: doc string of with-temp-file

[Drew Adams]

    > My point is that the doc string of `with-temp-file' says that
    > a new buffer is _created_, used to evaluate stuff, and then
    > written to its file. It says nothing about the buffer being
    > _temporary_ (i.e., being deleted after being saved).

    Indeed it doesn't say so.  I don't find it indispensable to
    mention it since it seems that the behavior is the expected
    one:

Well, it wasn't expected by me. I just went by what the doc string said.
Experimenting a bit (not enough) suggested to me that the buffer name was
the same as the supplied file-name, so that was what I "expected": buffer
creation and saving, but not deletion.

    after all, it doesn't even tell you which name this
    buffer is going to have, so if you have to kill it
    yourself afterwards you're going to always have to do something like

      (let (buf)
        (unwind-protect
            (with-temp-file "foo"
              (setq buf (current-buffer))
              ...)
          (kill-buffer buf)))

    which is really cumbersome.

Yes.

But the more important point is that the doc string _suggests_ that you
_need_ to do something like that, if you want to remove the buffer - and you
don't in fact need to. It's easy to state that explicitly, especially given
the misleading function name. So why not do so?

    > My second point is that the name of the function
    > `with-temp-file' suggests that the _file_ is temporary,
    > not the buffer.

    100% agreement here.  Actually, when I created make-temp-file I
    thought it would be quite natural to define a macro

      (defmacro with-temp-file (x &rest body)
        (let ((file-name (make-symbol "file-name")))
          `(let ((,file-name (make-temp-file ,@(or (cdr x) '("etemp")))))
             (unwind-protect
                 (let ((,(car x) ,file-name))
                   ,@body)
               (if (file-exists-p ,file-name)
                   (delete-file ,file-name))))))

    and only later on noticed that the name was already taken by
    something which I found wasn't doing what its name implied.

IIUC, this has no connection with the existing with-temp-file. It could be
useful - for actually creating, using, and deleting a temporary _file_.

    > A better name would be something like `with-temp-buffer-write' or
    > `with-temp-buffer-saved'. I don't suggest that those are great names
    > either, but they make it clear that 1) the buffer is temporary, 2) the
    > file is not temporary, and 3) the buffer is written (to its
    > file). With such a name, even the current, bad doc string would
    > be less of a problem.

    Agreed.  It should be made clear that the point of this form is
    to be able to build a file's content bit-by-bit in elisp (by
    working in a temp buffer which is then written to the file when
    the work is finished).

    I can't think of a good name either:

      with-temp-buffer-for-file
      build-file-in-temp-buffer

Is it even possible to rename this function/macro (with-temp-file) now? If
it's not too late, then let's ask emacs-devel for input on a good name.  The
name should say these things: create a temp buffer, do something with that
buffer current, save it to a file, then delete the buffer. It should
concentrate on "file" or "save", so it's clear that the temporary-buffer is
written.

Here are some more possibilities:

 with-temp-buffer-save or -saved
 with-temp-buffer-write
 with-temp-saved-buffer
 save-with-temp-buffer
 write-temp-buffer
 save-temp-buffer

The problem with the last two, and with build-file-in-temp-buffer, is that
they don't suggest that a new buffer is _created_ by the operation; they
suggest that you supply a temporary buffer and it gets used (as the current
buffer), written, then discarded. To deal with that problem, I think we need
"with" in the name - "with" conventionally means "create something, do
something with it, then destroy it".

A (more minor) problem with a name that mentions "buffer" (creation,
current, destruction) but not "file" is that the argument is actually a file
name, not a buffer name, as Stefan pointed out. The name provided is
nevertheless the basis of the temporary-buffer name, in the same sense that
`generate-new-buffer' takes as argument a name that is only the root name of
the buffer, not its actual name.

Since more is done in this operation to/with the buffer (creation, use as
current, saving, destruction) than to/with the file (creation or
overwriting), I'd suggest that "buffer" be used in the name instead of
"file". The word "save" or "write", in connection with "buffer", is enough
to suggest that a file is written. Hence, my "buffer" suggestions above.

The doc string, however, should in any case make clear what happens if the
file name already corresponds to an existing file. (BTW - shouldn't we allow
for either overwriting or appending to such an existing file?)

 - Drew