GNU bug report logs - #52782
Man Page: Incorrect Summary of --color Option

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 52782 in the body.
You can then email your comments to 52782 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Pranab Lawrence Ekka Dasgupta <pranabekka <at> gmail.com>
To: bug-coreutils <at> gnu.org
Subject: Man Page: Incorrect Summary of --color Option
Date: Fri, 24 Dec 2021 20:41:45 +0530

Version Information
ls/coreutils: 8.32
Distribution: Pop_OS! 20.10

The summary of the `--color` option incorrectly states that the default
option is 'always', whereas it functions otherwise and the information
at the bottom of the man page suggests that the default is 'never'.

This error persists in online manual pages and in other distributions

From the manual page:

---
       --color[=WHEN]
              colorize  the output; WHEN can be 'always' (default if omitted),
              'auto', or 'never'; more info below

...

       Using  color  to distinguish file types is disabled both by default and
       with --color=never.  With --color=auto, ls emits color codes only  when
---

Thanks and Regards,
Pranab Dasgupta

Message #8 received at 52782 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Pranab Lawrence Ekka Dasgupta <pranabekka <at> gmail.com>, 52782 <at> debbugs.gnu.org
Subject: Re: bug#52782: Man Page: Incorrect Summary of --color Option
Date: Fri, 24 Dec 2021 09:52:40 -0800

[Message part 1 (text/plain, inline)]

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.

[0001-doc-colorize-color.patch (text/x-patch, attachment)]

Message #11 received at 52782 <at> debbugs.gnu.org (full text, mbox):

From: Pranab Lawrence Ekka Dasgupta <pranabekka <at> gmail.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 52782 <at> debbugs.gnu.org
Subject: Re: bug#52782: Man Page: Incorrect Summary of --color Option
Date: Sat, 25 Dec 2021 00:10:23 +0530

Ah, my mistake. It does make sense that the contents of the parentheses
apply to the specification of WHEN.

Perhaps it could be reworded to "default if WHEN is omitted", although
that does cause some repetition. Alternatively, the entire description
could be modified, as on die.net[1]: "color the output. WHEN defaults to
'always' (if omitted) or can be 'never' or 'auto'. More info below." The
issue here is that it might suggest that the user may not explicitly
specify 'always'.

Regarding the usage of 'colorize', I think the correction future proofs
the documentation, given that I've never heard or seen it used.

[1]https://linux.die.net/man/1/ls

Message #16 received at 52782-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Pranab Lawrence Ekka Dasgupta <pranabekka <at> gmail.com>
Cc: 52782-done <at> debbugs.gnu.org
Subject: Re: bug#52782: Man Page: Incorrect Summary of --color Option
Date: Fri, 24 Dec 2021 15:28:01 -0800

[Message part 1 (text/plain, inline)]

On 12/24/21 10:40, Pranab Lawrence Ekka Dasgupta wrote:
> Perhaps it could be reworded to "default if WHEN is omitted", although
> that does cause some repetition

Thanks, I gave that sort of thing a shot by installing the attached, and 
am closing the bug report.

[0001-ls-improve-doc-for-WHEN.patch (text/x-patch, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.