diff --git a/doc/common.m4 b/doc/common.m4
index 916adbc81..77bdbbf07 100644
--- a/doc/common.m4
+++ b/doc/common.m4
@@ -161,11 +161,12 @@ m4_define({{_reportingoptions_}}, {{
 : generate future transactions from [periodic transaction](journal.html#periodic-transactions) rules, for the next 6 months or till report end date.
 In hledger-ui, also make ordinary future transactions visible.
 
-`--color=always|yes|never|no|auto (or --colour=...)`
-: 'auto' is the default, it tries to use ANSI color codes in terminal output when supported.
-: 'always' or 'yes' forces color on, useful when piping output, eg into 'less -R'.
-: 'never' or 'no' forces color off.
-: A NO_COLOR environment variable also disables color, overriding this option.
+`--color=WHEN (or --colour=WHEN)`
+: Should color-supporting commands use ANSI color codes in text output.
+: 'auto' (default): whenever stdout seems to be a color-supporting terminal.
+: 'always' or 'yes': always, useful eg when piping output into 'less -R'.
+: 'never' or 'no': never.
+: A NO_COLOR environment variable overrides this.
 
 When a reporting option appears more than once in the command line, the last one takes precedence.
 
diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs
index c1c7a1f25..f355c8c27 100644
--- a/hledger/Hledger/Cli/CliOptions.hs
+++ b/hledger/Hledger/Cli/CliOptions.hs
@@ -191,12 +191,13 @@ reportflags = [
 
   -- general output-related
 
- ,flagReq  ["color","colour"] (\s opts -> Right $ setopt "color" s opts) "always|yes|never|no|auto"
-   (unwords
-     ["'auto' is the default, it tries to use ANSI color codes in terminal output when supported."
-     ,"'always' or 'yes' forces color on, useful when piping output, eg into 'less -R'."
-     ,"'never' or 'no' forces color off."
-     ,"A NO_COLOR environment variable also disables color, overriding this option."
+ ,flagReq  ["color","colour"] (\s opts -> Right $ setopt "color" s opts) "WHEN"
+   (unlines
+     ["Should color-supporting commands use ANSI color codes in text output."
+     ,"'auto' (default): whenever stdout seems to be a color-supporting terminal."
+     ,"'always' or 'yes': always, useful eg when piping output into 'less -R'."
+     ,"'never' or 'no': never."
+     ,"A NO_COLOR environment variable overrides this."
      ])
  ]