Subject: Re: bug#7563: 23.2; `split-string-and-unquote' mis-documented / purpose unclear

From: Dave Abrahams <[email-masked]>
Date: Sat, 11 Dec 2010 08:43:42 -0500

At Sat, 11 Dec 2010 11:50:35 +0200,
Eli Zaretskii wrote:
> 
> > Date: Sun, 05 Dec 2010 16:28:16 -0500
> > From: Dave Abrahams <[email-masked]>
> > 
> >        This function performs two types of quoting: enclosing a whole
> >        string in double quotes `"..."', and quoting individual characters
> >        with a backslash escape `\'.  The latter is also used in Lisp
> >        strings, so this function can handle those as well.
> > 
> > 
> > First problem: the last paragraph above is simply wrong.
> > split-string-and-unquote doesn't perform any type of quoting; it
> > un-quotes.
> 
> I changed "performs" to "supports".  Thanks for catching this.

But it's still wrong, I'm afraid.  As I mentioned in my original
report,

    (split-string-and-unquote "foo\\ bar") 

yields a list of 2 elements (I wrote it wrong below: you get a
trailing backslash on "foo\\")

> > Second problem: the doc implies that a string that could be executed
> > by the shell could be split into its constituent arguments by
> > split-string-and-unquote, but in general, it cannot, e.g.:
> > 
> >   (split-string-and-unquote "'foo bar'") => ("'foo" "bar'")
> >   (split-string-and-unquote "foo\\ bar") => ("foo" "bar")
> > 
> > I'm not sure what this function is really supposed to be for, but any
> > implication that it properly handles conversion into shell arguments
> > is highly misleading.  Some motivation should be given for proper use
> > of split-string-and-unquote, or it should be deprecated.
> 
> This has come up before; see Bug #1212 and this thread:
> 
>   http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00431.html
> 
> The best explanation I can give you is that this function is for
> taking minibuffer input and converting it to a list of string
> arguments as required by call-process and start-process.  (I added
> this information to the manual.)  Note that the documentation does not
> mention "shell" anywhere.  You could also gain some insight by looking
> at the users of this function.
> 
> With those changes, I'm closing this bug report (and 1212 as well),
> because the issue has been already beaten to death in the above
> discussion.  The changes I made are on the emacs-23 branch, btw, in
> case you want to eyeball them.

Well, I'm sorry that the previous discussion was so unpleasant, but:

* I disagree strongly that it is a proper resolution:

  * I spent lots of time trying to suss out what was really going on
    here and writing a clear bug report.  I did that in the hopes that
    nobody else would waste time trying to figure this out again, and
    I don't believe that change will prevent it.

  * The functions' design still has nothing to do with shell quoting;
    they are hard-coded to work with double-quotes and only
    double-quotes, which is not guaranteed to work for an arbitrary
    definition of "shell."

* I believe my report is clearer than #1212 as it identifies the cause
  of the original reporter's confusion, and should be evaluated on its
  own merits without prejudice.

* Having now read the history of this issue, I am strongly convinced
  that the proper thing to do is deprecate these functions. I'm not
  sure what Emacs convention is here, but I would do it as follows:

  * Leave them in the source so nobody's code breaks

  * Change their documentation in source to note that they are 
    deprecated

  * Remove their documentation from the manual or move it to
    an appendix of deprecated functionality.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com