From cdb966adb30e2744f7584fafad13f80341ac8f4a Mon Sep 17 00:00:00 2001 From: =?utf8?q?P=C3=A1draig=20Brady?= Date: Fri, 12 Dec 2025 16:41:36 +0000 Subject: [PATCH] doc: expand on shell-escape quoting style * doc/coreutils.texi (quotingStyles): Expand on the advantages of "shell-escape" quoting, and mention it's the default when outputting to a tty. Also mention how it's also useful with LC_ALL=C to further disambiguate output. Also reference the separate page detailing various considerations and options for file name quoting. Also move the mention of the default quoting style to the top of the page where it's more obvious. --- doc/coreutils.texi | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 5ff3865340..d37cf24714 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -8333,6 +8333,11 @@ longer than 1000 bytes may be treated as errors. These options change how file names themselves are printed. +You can specify the default value of the @option{--quoting-style} option +with the environment variable @env{QUOTING_STYLE}@. If that environment +variable is not set, the default value is @samp{shell-escape} when the +output is a terminal, and @samp{literal} otherwise. + @table @samp @optItem{ls,-b,} @@ -8385,8 +8390,17 @@ like @command{csh}. @item shell-always Quote strings for the shell, even if they would normally not require quoting. @item shell-escape -Like @samp{shell}, but also quoting non-printable characters using the POSIX -@samp{$''} syntax suitable for most shells. +Like @samp{shell}, but also quote non-printable characters using the POSIX +@samp{$''} syntax suitable for most shells. This is the most general format +as any file name is represented unambiguously and safely. I.e., the full +quoted string can be pasted back to the shell to refer to any file. +Consequently, this is the default format used when @command{ls} +is outputting to a tty. +Note also that specifying the C locale with @code{LC_ALL=C} can be useful +with this output format, to avoid character set conversion issues +with some terminals; e.g., xterm always converting to unicode composed form. +See also +@uref{https://www.gnu.org/software/coreutils/quotes.html, Quoting file names}. @item shell-escape-always Like @samp{shell-escape}, but quote strings even if they would normally not require quoting. @@ -8415,11 +8429,6 @@ this"} in the default C locale. This looks nicer on many displays. @end macro @quotingStyles -You can specify the default value of the @option{--quoting-style} option -with the environment variable @env{QUOTING_STYLE}@. If that environment -variable is not set, the default value is @samp{shell-escape} when the -output is a terminal, and @samp{literal} otherwise. - @optItem{ls,--show-control-chars,} Print nongraphic characters as-is in file names. This is the default unless the output is a terminal and the program is -- 2.47.3