color: prefer set_color --reset over set_color normal

`set_color normal` is too ambiguous and easily misinterpreted since
it actually reset all colors and modes instead of resetting just
the foreground color as one without prior knowledge might expect.

Closes fish-shell#12548

Author: Nahor

doc_src/cmds/fish_breakpoint_prompt.rst

@@ -34,6 +34,6 @@ A simple prompt that is a simplified version of the default debugging prompt::
         set -l function (status current-function)
         set -l line (status current-line-number)
         set -l prompt "$function:$line >"
-        echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' '
+        echo -ns (set_color $fish_color_status) "BP $prompt" (set_color --reset) ' '
     end
 

doc_src/cmds/fish_config.rst

@@ -85,10 +85,10 @@ The format looks like this:
     fish_color_command 5c5cff
 
     [unknown]
-    fish_color_normal normal
+    fish_color_normal --reset
     fish_color_autosuggestion brblack
     fish_color_cancel -r
-    fish_color_command normal
+    fish_color_command --reset
 
 The comments provide name and background color to the web config tool.
 

doc_src/cmds/fish_greeting.rst

@@ -39,5 +39,5 @@ A simple greeting:
 
   function fish_greeting
       echo Hello friend!
-      echo The time is (set_color yellow)(date +%T)(set_color normal) and this machine is called $hostname
+      echo The time is (set_color yellow)(date +%T)(set_color --reset) and this machine is called $hostname
   end

doc_src/cmds/fish_mode_prompt.rst

@@ -62,7 +62,7 @@ Example
           set_color --bold red
           echo '?'
       end
-      set_color normal
+      set_color --reset
     end
 
 

doc_src/cmds/fish_prompt.rst

@@ -41,7 +41,7 @@ A simple prompt:
         # $USER and $hostname are set by fish, so you can just use them
         # instead of using `whoami` and `hostname`
         printf '%s@%s %s%s%s > ' $USER $hostname \
-            (set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
+            (set_color $fish_color_cwd) (prompt_pwd) (set_color --reset)
     end
 
 

doc_src/cmds/read.rst

@@ -62,7 +62,7 @@ The following options control the interactive mode:
     Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
 
 **-p** or **--prompt** *PROMPT_CMD*
-    Uses the output of the shell command *PROMPT_CMD* as the prompt for the interactive mode. The default prompt command is ``set_color green; echo -n read; set_color normal; echo -n "> "``
+    Uses the output of the shell command *PROMPT_CMD* as the prompt for the interactive mode. The default prompt command is ``set_color green; echo -n read; set_color --reset; echo -n "> "``
 
 **-P** or **--prompt-str** *PROMPT_STR*
     Uses the literal *PROMPT_STR* as the prompt for the interactive mode.

doc_src/cmds/set_color.rst

@@ -11,7 +11,10 @@ Synopsis
 Description
 -----------
 
-``set_color`` is used to control the color and styling of text in the terminal. *VALUE* describes that styling. *VALUE* can be a reserved color name like **red** or an RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword **normal** resets text formatting to terminal defaults.
+``set_color`` is used to control the color and styling of text in the terminal.
+*VALUE* describes that styling.
+*VALUE* can be a reserved color name like **red** or an RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277").
+A special keyword **normal** resets text formatting to terminal defaults, however it is not recommended and the **--reset** option is preferred as it is less confusing and more future-proof.
 
 Valid colors include:
 
@@ -87,9 +90,10 @@ Notes
 
 1. Using ``set_color normal`` will reset all colors and modes to the terminal's default.
 2. In contrast, ``set_color --foreground normal`` will only reset the foreground color and leave all the other colors and modes unchanged.
-3. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option.
-4. Some terminals use the ``--bold`` escape sequence to switch to a brighter color set rather than increasing the weight of text.
-5. ``set_color`` works by printing sequences of characters to standard output. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
+3. Because of the risk of confusion, ``set_color --reset`` is recommended over ``set_color normal``.
+4. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option.
+5. Some terminals use the ``--bold`` escape sequence to switch to a brighter color set rather than increasing the weight of text.
+6. ``set_color`` works by printing sequences of characters to standard output. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
 
 Examples
 --------

doc_src/faq.rst

@@ -91,7 +91,7 @@ The prompt is the output of the ``fish_prompt`` function. Put it in ``~/.config/
     function fish_prompt
         set_color $fish_color_cwd
         echo -n (prompt_pwd)
-        set_color normal
+        set_color --reset
         echo -n ' > '
     end
 

doc_src/fish_for_bash_users.rst

@@ -318,7 +318,7 @@ and a rough fish equivalent::
 
       echo -s (prompt_hostname) \
       (set_color blue) (prompt_pwd) \
-      (set_color yellow) $prompt_symbol (set_color normal)
+      (set_color yellow) $prompt_symbol (set_color --reset)
   end
 
 This shows a few differences:

doc_src/interactive.rst

@@ -105,6 +105,7 @@ Syntax highlighting variables
 
 The colors used by fish for syntax highlighting can be configured by changing the values of various variables. The value of these variables can be one of the colors accepted by the :doc:`set_color <cmds/set_color>` command.
 Options accepted by ``set_color`` like
+``--foreground=``,
 ``--background=``,
 ``--bold``,
 ``--dim``,