bug#1212: 23.0.60; split-string-and-unquote problems

[Eli Zaretskii <eliz@gnu.org>]

> From: Andreas Schwab <schwab@suse.de>
> Cc: 1212@emacsbugs.donarmstrong.com, emacs-pretest-bug@gnu.org
> Date: Mon, 20 Oct 2008 23:28:21 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Andreas Schwab <schwab@suse.de>
> >> Cc: 1212@emacsbugs.donarmstrong.com, emacs-pretest-bug@gnu.org
> >> Date: Mon, 20 Oct 2008 19:08:35 +0200
> >> 
> >> Why do you think that "Emacs Lisp quoting" has anything to do with
> >> "shell command quoting"?
> >
> > Because I grep'ped Emacs sources for its users.
> 
> That does not make it more suitable.

You know, since you evidently know better, how about if you explained
what that pair of functions is supposed to do, exactly, and what are
their intended uses?  The doc strings fall short by a large margin,
and NEWS had this to say about these functions:

    *** `split-string-and-unquote' does (what?)

    *** `combine-and-quote-strings' does (what?)

If I can understand the explanation, maybe I could produce from it a
suitable section of the ELisp manual, which is the reason why I
started to play with split-string-and-unquote.  Failing that, I will
stick to my interpretation.

Here's what I wrote in the ELisp manual about these two functions;
comments and corrections, if someone has them, are greatly
appreciated:

  @cindex quoting and unquoting shell command line
    The following two functions help creating shell commands from
  individual argument strings and taking shell command lines apart into
  individual arguments.

  @defun split-string-and-unquote string &optional separators
  This function splits @var{string} into substrings at matches for the
  regular expression @var{separators}, like @code{split-string} does
  (@pxref{Creating Strings}), but it additionally removes quoting from
  the substrings.  It then makes a list of the substrings and returns
  it.

  If @var{separators} is omitted or nil, it defaults to @code{"\\s-+"},
  which is a regular expression that matches one or more characters with
  whitespace syntax (@pxref{Syntax Class Table}).

  The quoting this function supports is of 2 styles: by enclosing a
  whole string in double quotes @code{"@dots{}"}, or by quoting
  individual characters with a backslash escape @samp{\}.  The latter is
  also used in Lisp strings, so this function can handle those as well.
  @end defun

  @defun combine-and-quote-strings list-of-strings &optional separator
  This function concatenates @var{list-of-strings} into a single string,
  quoting each string in the list that needs quoting as it goes.  It
  also sticks the @var{separator} string in between each pair of strings
  in the result, and returns that result.  If @var{separator} is omitted
  or @code{nil}, it defaults to a blank @code{" "}.

  The strings in @var{list-of-strings} that need quoting are those that
  include @var{separator} as their substring.  Quoting a string encloses
  it in double quotes @code{"@dots{}"}.  In the simplest case, if you
  are consing a shell command from the individual command-line
  arguments, every argument that includes embedded blanks will be
  quoted.
  @end defun