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

From: Dave Abrahams <[email-masked]>
Date: Sat, 11 Dec 2010 12:57:30 -0500

On Dec 11, 2010, at 10:52 AM, Eli Zaretskii <[email-masked]> wrote:

>> Date: Sat, 11 Dec 2010 08:43:42 -0500
>> From: Dave Abrahams <[email-masked]>
>> Cc: [email-masked],
>>    [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.
> 
> It's not "wrong", in the sense that previously the text made it sound
> as if split-string-and-unquote could actually _add_ quoting.  That is
> the only thing I intended to fix there.

Sorry, let me precise: your fix is correct inasmuch as it fulfills your intention, but the text you were working on is still wrong because it says quite clearly that backslash escaping is supported, but as I have shown, it is not. 

> 
>> 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\\")
> 
> That's by design; read the discussion I pointed to, where Stefan
> explained his rationale.  You could agree or disagree with him, but
> evidently these functions are useful in a certain class of situations;
> see how they are used in a few Lisp packages that come with Emacs.

Fine; I'm not arguing with their functionality. I'm arguing that they're mis-documented. 

> 
>>  * 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.
> 
> Now that the manual explicitly mentions call-process and
> start-process, which are the clients of this function, what else is
> missing or unclear?  Please be specific.

Specifically it specifically states they handle backslashes, and strongly implies that they have generally-useful semantics for interacting with arbitrary shells, when in fact they are essentially implementation details of call-/start-process whose semantics are only appropriate to an undocumented set of conditions set up in those two functions. 

>>  * 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 the manual says precisely that.  If the problem is with
> mentioning "shell", would removing that solve this difficulty?

It would certainly help

>> * Having now read the history of this issue, I am strongly convinced
>>  that the proper thing to do is deprecate these functions.
> 
> They were introduced fairly recently, and I'm sure they were added for
> good reasons.  I'll let Stefan respond in detail.

I'm sure they belong in the codebase, but fairly certain they don't belong in the docs until they can be documented accurately. 

BoostPro Computing * http://boostpro.com
[Sent from coveted but awkward mobile device]