From: Bruno Haible Date: Sun, 31 Mar 2024 20:56:14 +0000 (+0200) Subject: quotearg: Improve documentation. X-Git-Tag: v1.0~197 X-Git-Url: https://gitweb.git.savannah.gnu.org/gitweb/?a=commitdiff_plain;h=4d694d878f8792d510f5d30eaaf9d51c7b48ca10;p=gnulib.git quotearg: Improve documentation. * lib/quotearg.h: Refer to specification of $'...' syntax. Document a limitation of QA_ELIDE_OUTER_QUOTES. --- diff --git a/ChangeLog b/ChangeLog index ffae5513ae..182a894039 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2024-03-31 Bruno Haible + + quotearg: Improve documentation. + * lib/quotearg.h: Refer to specification of $'...' syntax. Document a + limitation of QA_ELIDE_OUTER_QUOTES. + 2024-03-31 Bruno Haible canonicalize[-lgpl] tests: Fix test failure on musl libc. diff --git a/lib/quotearg.h b/lib/quotearg.h index 4e9099fff4..202b79f33e 100644 --- a/lib/quotearg.h +++ b/lib/quotearg.h @@ -80,7 +80,8 @@ enum quoting_style /* Quote names for the shell if they contain shell metacharacters or other problematic characters (ls --quoting-style=shell-escape). - Non printable characters are quoted using the $'...' syntax, + Non printable characters are quoted using the $'...' syntax + , which originated in ksh93 and is widely supported by most shells, and proposed for inclusion in POSIX. @@ -95,7 +96,8 @@ enum quoting_style /* Quote names for the shell even if they would normally not require quoting (ls --quoting-style=shell-escape). - Non printable characters are quoted using the $'...' syntax, + Non printable characters are quoted using the $'...' syntax + , which originated in ksh93 and is widely supported by most shells, and proposed for inclusion in POSIX. Behaves like shell_escape_quoting_style if QA_ELIDE_OUTER_QUOTES is in effect. @@ -253,7 +255,11 @@ enum quoting_flags /* Omit the surrounding quote characters if no escaped characters are encountered. Note that if no other character needs - escaping, then neither does the escape character. */ + escaping, then neither does the escape character. + *Attention!* This flag is unsupported in combination with the styles + shell_escape_quoting_style and shell_escape_always_quoting_style + (because in this situation it cannot handle strings that start + with a non-printable character). */ QA_ELIDE_OUTER_QUOTES = 0x02, /* In the c_quoting_style and c_maybe_quoting_style, split ANSI