Re: buffer variable values

[Barry Margolin <barmar@alum.mit.edu>]

In article <mailman.7566.1345906894.855.help-gnu-emacs@gnu.org>,
 "Drew Adams" <drew.adams@oracle.com> wrote:

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

Another issue is backward compatibility.  Perhaps at one time the 
function was commonly used from programs, but when the preferred 
alternative was added they put that warning into the documentation.  But 
the function still has to work properly for all the old code that was 
calling it before this.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***