system-quote: Add more comments.

* lib/system-quote.h: Add more comments about wilcards and limitations.
Suggested by Eli Zaretskii <eliz@gnu.org>.

diff --git a/ChangeLog b/ChangeLog
index c92156c..03125f9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2012-05-12  Bruno Haible  <bruno@clisp.org>
 
+       system-quote: Add more comments.
+       * lib/system-quote.h: Add more comments about wilcards and limitations.
+       Suggested by Eli Zaretskii <eliz@gnu.org>.
+
        sh-quote, system-quote: Add comments about wildcards.
        * lib/sh-quote.h: Clarify what happens with wildcard characters.
        * lib/system-quote.h: Likewise.

diff --git a/lib/system-quote.h b/lib/system-quote.h
index 48d59ef..a136a31 100644 (file)
--- a/lib/system-quote.h
+++ b/lib/system-quote.h
@@ -29,7 +29,22 @@
        contain newlines or carriage return characters to programs through
        cmd.exe.
      - Windows programs usually perform wildcard expansion when they receive
-       arguments that contain unquoted '*', '?' characters.  */
+       arguments that contain unquoted '*', '?' characters.
+
+  With this module, you can build a command that will invoke a program with
+  specific strings as arguments.
+
+  Note: If you want wildcard expansion to happen, you have to first do wildcard
+  expansion through the 'glob' module, then quote the resulting strings through
+  this module, and then invoke the system's command interpreter.
+
+  Limitations:
+    - When invoking native Windows programs on Windows Vista or newer,
+      wildcard expansion will occur in the invoked program nevertheless.
+    - On native Windows, for SCI_SYSTEM and SCI_WINDOWS_CMD, newlines and
+      carriage return characters are not supported.  Their undesired effect
+      is to truncate the entire command line.
+ */
 
 #include <stddef.h>