quotearg: document limitations of quote_these_too

* lib/quotearg.c (quotearg_buffer_restyled): Add comments where
those limitations are created.
* lib/quotearg.h (set_char_quoting): Document that digits and
letters that are special after backslash are not permitted.
(quotearg_char): Cross-reference set_char_quoting documentation.

diff --git a/ChangeLog b/ChangeLog
index c71b417..6fc1016 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2009-08-22  Joel E. Denny  <jdenny@clemson.edu>
+
+       quotearg: document limitations of quote_these_too
+       * lib/quotearg.c (quotearg_buffer_restyled): Add comments where
+       those limitations are created.
+       * lib/quotearg.h (set_char_quoting): Document that digits and
+       letters that are special after backslash are not permitted.
+       (quotearg_char): Cross-reference set_char_quoting documentation.
+
 2009-08-23  Joel E. Denny  <jdenny@clemson.edu>
 
        quotearg: implement custom_quoting_style

diff --git a/lib/quotearg.c b/lib/quotearg.c
index 314c627..8380e9d 100644 (file)
--- a/lib/quotearg.c
+++ b/lib/quotearg.c
@@ -336,6 +336,10 @@ quotearg_buffer_restyled (char *buffer, size_t buffersize,
                  STORE ('0');
                }
              c = '0';
+             /* We don't have to worry that this last '0' will be
+                backslash-escaped because, again, quote_string should
+                not start with it and because quote_these_too is
+                documented as not accepting it.  */
            }
          else if (flags & QA_ELIDE_NULL_BYTES)
            continue;
@@ -461,7 +465,9 @@ quotearg_buffer_restyled (char *buffer, size_t buffersize,
             escape by prepending a backslash.  However, it's hard to
             imagine any locale that would use digits or letters as
             quotes, and set_custom_quoting is documented not to accept
-            them.  */
+            them.  Also, a digit or a special letter would cause
+            trouble if it appeared in quote_these_too, but that's also
+            documented as not accepting them.  */
          break;
 
        default:

diff --git a/lib/quotearg.h b/lib/quotearg.h
index e9f6f56..63c47f1 100644 (file)
--- a/lib/quotearg.h
+++ b/lib/quotearg.h
@@ -255,7 +255,9 @@ void set_quoting_style (struct quoting_options *o, enum quoting_style s);
    set the value of the quoting options for character C to I.
    Return the old value.  Currently, the only values defined for I are
    0 (the default) and 1 (which means to quote the character even if
-   it would not otherwise be quoted).  */
+   it would not otherwise be quoted).  C must never be a digit or a
+   letter that has special meaning after a backslash (for example, "\t"
+   for tab).  */
 int set_char_quoting (struct quoting_options *o, char c, int i);
 
 /* In O (or in the default if O is null),
@@ -345,7 +347,8 @@ char *quotearg_style (enum quoting_style s, char const *arg);
 char *quotearg_style_mem (enum quoting_style s,
                          char const *arg, size_t argsize);
 
-/* Like quotearg (ARG), except also quote any instances of CH.  */
+/* Like quotearg (ARG), except also quote any instances of CH.
+   See set_char_quoting for a description of acceptable CH values.  */
 char *quotearg_char (char const *arg, char ch);
 
 /* Like quotearg_char (ARG, CH), except it can quote null bytes.  */