Subject: Re: bug#52782: Man Page: Incorrect Summary of --color Option

From: Paul Eggert <[email-masked]>
Date: Fri, 24 Dec 2021 09:52:40 -0800

On 12/24/21 07:11, Pranab Lawrence Ekka Dasgupta wrote:
> The summary of the `--color` option incorrectly states that the default
> option is 'always', whereas it functions otherwise

It sounds like you misunderstood the man page. It says that 
--color[=WHEN] means "colorize the output; WHEN can be 'always' (default 
if omitted), 'auto', or 'never'". The phrase "if omitted" refers to when 
you use plain "--colorize", not to when you don't use "--colorize" at 
all. The same wording is used to document  --classify[=WHEN], 
--hyperlink[=WHEN].

I suppose we could reword the man page to avoid this potential confusion 
in --color, --classify and --hyperlink. However, I don't see how to do 
that without adding so much wording that the cost would likely exceed 
the benefit. Perhaps some other wordsmith could chip in.

In the meantime I noticed that the documentation uses the word 
"colorize" when it should say "color", so I installed the attached.

From 2b30312f77f99efc8c56804424c4a317e25953f1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 24 Dec 2021 09:47:18 -0800
Subject: [PATCH] doc: colorize -> color

Living so close to Hollywood I know that "colorize"
means adding color to something that was already monochrome,
whereas "color" means to give color to something.
Coreutils apps color text instead of colorizing it.
---
 NEWS                           | 2 +-
 cfg.mk                         | 2 +-
 doc/coreutils.texi             | 2 +-
 src/dircolors.hin              | 6 +++---
 src/ls.c                       | 4 ++--
 tests/ls/capability.sh         | 2 +-
 tests/ls/color-ext.sh          | 2 +-
 tests/ls/color-norm.sh         | 2 +-
 tests/ls/multihardlink.sh      | 2 +-
 tests/ls/stat-free-symlinks.sh | 2 +-
 10 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/NEWS b/NEWS
index c8e8bdc16..811e27e3a 100644
--- a/NEWS
+++ b/NEWS
@@ -3063,7 +3063,7 @@ GNU coreutils NEWS                                    -*- outline -*-
   install accepts a new option --strip-program to specify the program used to
   strip binaries.
 
-  ls now colorizes files with capabilities if libcap is available
+  ls now colors names of files with capabilities if libcap is available.
 
   ls -v now uses filevercmp function as sort predicate (instead of strverscmp)
 
diff --git a/cfg.mk b/cfg.mk
index 6d6c37dc2..046f14167 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -49,7 +49,7 @@ export VERBOSE = yes
 # 4914152 9e
 export XZ_OPT = -8e
 
-old_NEWS_hash = 4d17651e2318a01687a1f0fdca9177e5
+old_NEWS_hash = 612bad626bf28b1847ad0114cb2cd6fe
 
 # Add an exemption for sc_makefile_at_at_check.
 _makefile_at_at_check_exceptions = ' && !/^cu_install_prog/ && !/dynamic-dep/'
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 6068d8b08..f7ce1654b 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8109,7 +8109,7 @@ may be omitted, or one of:
 @end itemize
 Specifying @option{--color} and no @var{when} is equivalent to
 @option{--color=always}.
-If piping a colorized listing through a pager like @command{less},
+If piping a colored listing through a pager like @command{less},
 use the pager's @option{-R} option to pass the color codes to the terminal.
 
 @vindex LS_COLORS
diff --git a/src/dircolors.hin b/src/dircolors.hin
index b5d6452d7..d86e0088f 100644
--- a/src/dircolors.hin
+++ b/src/dircolors.hin
@@ -9,7 +9,7 @@
 # slackware version of dircolors) are recognized but ignored.
 
 # Below are TERM entries, which can be a glob patterns, to match
-# against the TERM environment variable to determine if it is colorizable.
+# against the TERM environment variable to determine if it is colorable.
 TERM Eterm
 TERM ansi
 TERM *color*
@@ -71,7 +71,7 @@ STICKY 37;44	# dir with the sticky bit set (+t) and not other-writable
 EXEC 01;32
 
 # List any file extensions like '.gz' or '.tar' that you would like ls
-# to colorize below. Put the extension, a space, and the color init string.
+# to color below. Put the extension, a space, and the color init string.
 # (and any comments you want to add after a '#')
 
 # If you use DOS-style suffixes, you may want to uncomment the following:
@@ -80,7 +80,7 @@ EXEC 01;32
 #.com 01;32
 #.btm 01;32
 #.bat 01;32
-# Or if you want to colorize scripts even if they do not have the
+# Or if you want to color scripts even if they do not have the
 # executable bit actually set.
 #.sh  01;32
 #.csh 01;32
diff --git a/src/ls.c b/src/ls.c
index 6e87af651..c350787b6 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -361,7 +361,7 @@ static bool color_symlink_as_referent;
 
 static char const *hostname;
 
-/* mode of appropriate file for colorization */
+/* Mode of appropriate file for coloring.  */
 static mode_t
 file_or_link_mode (struct fileinfo const *file)
 {
@@ -5424,7 +5424,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
 "), stdout);
       fputs (_("\
   -C                         list entries by columns\n\
-      --color[=WHEN]         colorize the output; WHEN can be 'always' (default\
+      --color[=WHEN]         color the output; WHEN can be 'always' (default\
 \n\
                                if omitted), 'auto', or 'never'; more info below\
 \n\
diff --git a/tests/ls/capability.sh b/tests/ls/capability.sh
index 0886f50bf..5c5532dee 100755
--- a/tests/ls/capability.sh
+++ b/tests/ls/capability.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Ensure "ls --color" properly colorizes file with capability.
+# Ensure "ls --color" properly colors name of file with capability.
 
 # Copyright (C) 2008-2021 Free Software Foundation, Inc.
 
diff --git a/tests/ls/color-ext.sh b/tests/ls/color-ext.sh
index 5fa8c5ddf..b36b00345 100755
--- a/tests/ls/color-ext.sh
+++ b/tests/ls/color-ext.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Ensure "ls --color" properly colorizes file extensions
+# Ensure "ls --color" properly colors file name extensions.
 
 # Copyright (C) 2018-2021 Free Software Foundation, Inc.
 
diff --git a/tests/ls/color-norm.sh b/tests/ls/color-norm.sh
index 17a790e28..58d172ed7 100755
--- a/tests/ls/color-norm.sh
+++ b/tests/ls/color-norm.sh
@@ -36,7 +36,7 @@ touch nocolor || framework_failure_
 
 TCOLORS="no=7:ex=01;32"
 
-# Non coloured files inherit NORMAL attributes
+# Uncolored file names inherit NORMAL attributes.
 LS_COLORS=$TCOLORS      ls -gGU --color exe nocolor | qls >> out || fail=1
 LS_COLORS=$TCOLORS      ls -xU  --color exe nocolor       >> out || fail=1
 LS_COLORS=$TCOLORS      ls -gGU --color nocolor exe | qls >> out || fail=1
diff --git a/tests/ls/multihardlink.sh b/tests/ls/multihardlink.sh
index 2e8b1656d..fd1a3d441 100755
--- a/tests/ls/multihardlink.sh
+++ b/tests/ls/multihardlink.sh
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Ensure "ls --color" properly colorizes hard linked files.
+# Ensure "ls --color" properly colors names of hard linked files.
 
 # Copyright (C) 2008-2021 Free Software Foundation, Inc.
 
diff --git a/tests/ls/stat-free-symlinks.sh b/tests/ls/stat-free-symlinks.sh
index 6e97e8f65..3397c9e01 100755
--- a/tests/ls/stat-free-symlinks.sh
+++ b/tests/ls/stat-free-symlinks.sh
@@ -62,7 +62,7 @@ n_stat2=$(grep -vF '+++' log2 | wc -l) || framework_failure_
 test $n_stat1 = $(($n_stat2 - 1)) \
   || { fail=1; head -n30 log*; }
 
-# Check that output is colorized, as requested, too.
+# Check that output is colored, as requested, too.
 {
   printf '\033[0m\033[01;35mlink-to-x\033[0m@\n'
   printf '\033[01;32mx\033[0m*\n'
-- 
2.32.0