RE: buffer variable values

[Drew Adams]

> Was insert-buffer ever meant to be called non-interactively, 
> though? The newer insert-buffer has this in its documentation:
> 
> "This function is meant for the user to run interactively.
> Don't call it from programs: use `insert-buffer-substring' instead!"

Barry M. gave the short answer:

 "Just because it's not *meant* to be used from programs
  doesn't mean it shouldn't work reasonably when it is."

"Shouldn't" could be "couldn't" here.  It was a design choice to make it "work
reasonably" for a buffer-name argument, for convenience.

That short answer is repeated as #2 here:

1. "Meant to be" is pretty loose in Lisp.  What you see in a doc string does not
necessarily convey all possibilities and situations.  It is intended as general
guidance, to help you.  This is not the Napoleon code.

You will sometimes see imperative directives such as "Don't...", like here.
Take them as if they were polite guidance/advice, in the spirit of "You probably
don't want to..."  They are generally just trying to remind you that this is
something that you probably do not want to do here.

2. All that first `setq' sexp does is make sure that the rest of the function
body really does have a buffer object to work with, in case the function was
passed a buffer name (string) - for whatever reason.  That is an alternative
design to raising an error.

It was deemed useful to mention in the doc string that the command is generally
meant to be invoked interactively.  That's a sign that at least some people have
confusedly invoked it non-interactively.  That `setq' sexp takes care of this.

3. Lisp is multi-leveled and dynamic.  And every command is also a function,
which _could_ be invoked non-interactively.  Sometimes code invokes other code
indirectly, including sometimes interactively (e.g. so that a user can pass it a
prefix arg).  And a function to be called indirectly could be passed as a
variable (so that the caller does not know what function it will call).