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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 05 Dec 2010 16:28:16 -0500
> From: Dave Abrahams <dave@boostpro.com>
> Cc: 
> 
>        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.

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