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 #12548

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``,

doc_src/prompt.rst

@@ -67,10 +67,10 @@ Fortunately, fish offers the :doc:`set_color <cmds/set_color>` command, so you c
 So, taking our previous prompt and adding some color::
 
   function fish_prompt
-      string join '' -- (set_color green) $PWD (set_color normal) '>'
+      string join '' -- (set_color green) $PWD (set_color --reset) '>'
   end
 
-A "normal" color tells the terminal to go back to its normal formatting options.
+"--reset" tells the terminal to go back to its default formatting options.
 
 ``set_color`` works by producing an escape sequence, which is a special piece of text that terminals
 interpret as instructions - for example, to change color. So ``set_color red`` produces the same
@@ -86,13 +86,13 @@ Shortening the working directory
 This is fine, but our :envvar:`PWD` can be a bit long, and we are typically only interested in the last few directories. We can shorten this with the :doc:`prompt_pwd <cmds/prompt_pwd>` helper that will give us a shortened working directory::
 
   function fish_prompt
-      string join '' -- (set_color green) (prompt_pwd) (set_color normal) '>'
+      string join '' -- (set_color green) (prompt_pwd) (set_color --reset) '>'
   end
 
 ``prompt_pwd`` takes options to control how much to shorten. For instance, if we want to display the last two directories, we'd use ``prompt_pwd --full-length-dirs 2``::
 
   function fish_prompt
-      string join '' -- (set_color green) (prompt_pwd --full-length-dirs 2) (set_color normal) '>'
+      string join '' -- (set_color green) (prompt_pwd --full-length-dirs 2) (set_color --reset) '>'
   end
 
 With a current directory of "/home/tutorial/Music/Lena Raine/Oneknowing", this would print
@@ -119,12 +119,12 @@ And after that, you can set a string if it is not zero::
   # Prompt status only if it's not 0
   set -l stat
   if test $last_status -ne 0
-      set stat (set_color red)"[$last_status]"(set_color normal)
+      set stat (set_color red)"[$last_status]"(set_color --reset)
   end
 
 And to print it, we add it to our ``string join``::
 
-  string join '' -- (set_color green) (prompt_pwd) (set_color normal) $stat '>'
+  string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $stat '>'
 
 If ``$last_status`` was 0, ``$stat`` is empty, and so it will simply disappear.
 
@@ -135,10 +135,10 @@ So our entire prompt is now::
       # Prompt status only if it's not 0
       set -l stat
       if test $last_status -ne 0
-          set stat (set_color red)"[$last_status]"(set_color normal)
+          set stat (set_color red)"[$last_status]"(set_color --reset)
       end
 
-      string join '' -- (set_color green) (prompt_pwd) (set_color normal) $stat '>'
+      string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $stat '>'
   end
 
 And it looks like:
@@ -176,11 +176,11 @@ So you can use it to declutter your old prompts. For example if you want to see
           set pwd (prompt_pwd)
           # Prompt status only if it's not 0
           if test $last_status -ne 0
-              set stat (set_color red)"[$last_status]"(set_color normal)
+              set stat (set_color red)"[$last_status]"(set_color --reset)
           end
       end
 
-      string join '' -- (set_color green) $pwd (set_color normal) $stat '>'
+      string join '' -- (set_color green) $pwd (set_color --reset) $stat '>'
   end
 
 Now running two commands in the same directory could result in this screen:

doc_src/tutorial.rst

@@ -633,7 +633,7 @@ Multiple lines are OK. Colors can be set via :doc:`set_color <cmds/set_color>` b
         set_color purple
         date "+%m/%d/%y"
         set_color FF0000
-        echo (pwd) '>' (set_color normal)
+        echo (pwd) '>' (set_color --reset)
     end