From: simonmar <unknown>
Date: Fri, 27 Feb 2004 10:27:41 +0000 (+0000)
Subject: [project @ 2004-02-27 10:27:41 by simonmar]
X-Git-Tag: nhc98-1-18-release~361
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=c603825be5f43e1b451a4f753b56c28789286dc0;p=ghc-base.git

[project @ 2004-02-27 10:27:41 by simonmar]
Update the comments in here after changes in rev. 1.17.
---

diff --git a/System/Cmd.hs b/System/Cmd.hs
index 41fabb2..051380d 100644
--- a/System/Cmd.hs
+++ b/System/Cmd.hs
@@ -110,42 +110,23 @@ is well documented on http://msdn.microsoft/com.)
 
   - The invoked command can in turn access the entire lpCommandLine string,
 	and the C runtime does indeed do so, parsing it to generate the 
-	traditional argument vector argv[0], argv[1], etc.  Again, to
-	break it into argument items, any spaces must be quoted using
-	double quote thus
-		cmd "this is arg 1" "this is arg 2"
-
-What if an argument itself contains double-quotes? (File names can't
-can't, on Windows.)  Then the quote must be escaped with a backslash.
-If we call Create Process with this lpArgument:
-	cmd "Foo=\"baz\"" arg2
-then cmd will see argv[1] as
-	Foo="baz"
-However, experiments show that backslashes themselves must *not* be escaped.
-That is, to get a backslash in an argument, just put backslash, even inside
-quotes.  For eaxmple, this works fine to show the contents of the file
-foo\baz
-	cat "foo\baz"
-If you escape the backslash, thus
-	cat "foo\\baz"
-then @cat@ will see argument foo\\baz, and on WinME/98/95 you'll get
-"can't find file foo\\baz".  (As it happens, WinNT/XP commands don't
-mind double backslashes, but it's still a bug, given rawSystem's claim
-to pass exactly args to the command.)
-
-BOTTOM LINE: 
-	1 We wrap the command, and each argument, in quotes
-	2 Inside the quotes, we escape any double-quote characters
-		(but nothing else)
-	3 Then concatenate all these quoted things together, separated with 
-		spaces
-
-Steps 1,2 are done by the function 'translate' below.
-
-The exact rules used by the C runtime to unscramble quoted argumets
-are quite complex.  For example, how do you get the string \" into an
-argument?  You can find the rules in MSDN, here:
-    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccelng/htm/progs_12.asp
+	traditional argument vector argv[0], argv[1], etc.  It does this
+	using a complex and arcane set of rules which are described here:
+	
+	   http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccelng/htm/progs_12.asp
+
+	(if this URL stops working, you might be able to find it by
+	searching for "Parsing C Command-Line Arguments" on MSDN.  Also,
+	the code in the Microsoft C runtime that does this translation
+	is shipped with VC++).
+
+
+Our goal in rawSystem is to take a command filename and list of
+arguments, and construct a string which inverts the translatsions
+described above, such that the program at the other end sees exactly
+the same arguments in its argv[] that we passed to rawSystem.
+
+This inverse translation is implemented by 'translate' below.
 
 Here are some pages that give informations on Windows-related 
 limitations and deviations from Unix conventions:
@@ -163,7 +144,6 @@ limitations and deviations from Unix conventions:
     How CMD.EXE processes command lines.
 
 
-
 Note: CreateProcess does have a separate argument (lpApplicationName)
 with which you can specify the command, but we have to slap the
 command into lpCommandLine anyway, so that argv[0] is what a C program
@@ -212,11 +192,7 @@ translate str = '"' : snd (foldr escape (True,"\"") str)
         escape '\\' (True,  str) = (True,  '\\' : '\\' : str)
         escape '\\' (False, str) = (False, '\\' : str)
 	escape c    (b,     str) = (False, c : str)
-	-- This function attempts to invert the Microsoft C runtime's
-	-- quoting rules, which can be found here:
-	--     http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccelng/htm/progs_12.asp
-	-- (if this URL stops working, you might be able to find it by
-	-- searching for "Parsing C Command-Line Arguments" on MSDN).
+	-- See long comment above for what this function is trying to do.
 	--
 	-- The Bool passed back along the string is True iff the
 	-- rest of the string is a sequence of backslashes followed by