Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-12-26 12:53:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update set_color documentation

Browse source 
Update docs for "brblack", "brwhite"  existing.

We no longer mention colors like grey, brown and purple, which are aliases
for yellow, magenta, white/black. The color names still work but there
isn't a good argument for there being two ways to do that: especially in
the age of 24-bit terminals where one might expect yellow and brown or
magenta and purple to actually be different colors.

Copyedit rest of document for inaccuracies, strange advice, brevity (a lot
of "you" pronouns, for example.)

Document the color fallback feature (set_color 313554 blue) that's been
present quite a while.
This commit is contained in:
Aaron Gyes 2016-07-23 00:28:24 -07:00
parent 3669805627
commit 644ea82c2f
1 changed files with 22 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
doc_src/set_color.txt
View file

@ -2,36 +2,35 @@
\subsection set_color-synopsis Synopsis \subsection set_color-synopsis Synopsis
\fish{synopsis} \fish{synopsis}
set_color [OPTIONS] [COLOR] set_color [OPTIONS] VALUE
\endfish \endfish
\subsection set_color-description Description \subsection set_color-description Description
`set_color` changes the foreground and/or background color of the terminal. `COLOR` is one of `black`, `red`, `green`, `brown`, `yellow`, `blue`, `magenta`, `purple`, `cyan`, `brred`, `brgreen`, `brbrown`, `bryellow`, `brblue`, `brmagenta`, `brpurple`, `brcyan`, `white`. The `br`, bright, forms are most useful as background colors. The special color `normal` resets the background and foreground to whatever is normal for your terminal. `set_color` is used to control the color and styling of text in the terminal. `VALUE` corresponds to a reserved color name such as *red* or a RGB color value given as 3 or 6 hexadecimal digits. The *br*-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray. A special keyword *normal* resets text formatting to terminal defaults.
You can also specify an RGB value with three or six hex digits, such as A0FF33 or f2f. `fish` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., `#2BC` is the same as `#22BBCC`. Hex RGB values can be in lower or uppercase, optionally prefixed with the pound-sign character. Depending on the capabilities of your terminal the actual color may be approximated by the closest known matching color in the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) color palette. Valid colors include:
- *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*
- *brblack*, *brred*, *brgreen*, *bryellow*, *brblue*, *brmagenta*, *brcyan*, *brwhite*
An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. `fish` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., `set_color 2BC` is the same as `set_color 22BBCC`. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support `set_color` has for it) the actual color may be approximated by a nearby matching reserved color name or `set_color` may not have an effect on color. A second color may be given as a desired fallback color. e.g. `set_color 124212` *brblue* will instruct set_color to use *brblue* if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.
The following options are available: The following options are available:
- `-b`, `--background` `COLOR` sets the background color. - `-b`, `--background` *COLOR* sets the background color.
- `-c`, `--print-colors` prints a list of the 16 named colors.
- `-c`, `--print-colors` prints a list of all valid color names. - `-o`, `--bold` sets bold mode.
- `-o`, `--bold` sets bold or extra bright mode.
- `-u`, `--underline` sets underlined mode. - `-u`, `--underline` sets underlined mode.
Calling `set_color normal` will set the terminal background and foreground colors to the defaults for the terminal. Using the *normal* keyword will reset foreground, background, and all formatting back to default.
Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than bolding the characters. This only applies to the foreground color. You should probably use the `br` color name variants listed above for both the foreground and background "bright" colors rather than use this option. The only use for this option is on a black&white terminal (e.g., a DEC VT220) to select foreground black text that is bolder than the normal text. \subsection set_color-notes Notes
Not all terminal emulators support all these features. 1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal.
2. 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.
Note 1: Setting either color to "normal" will reset both background and foreground colors to whatever is the default for the terminal. 3. Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than increasing the weight of text.
4. `set_color` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of `isatty stdout` before using `set_color` can be useful to decide not to colorize output in a script.
Note 2: 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.
Note 3: `set_color` works by printing sequences of characters to its stdout. If you use it in a command substitution or pipe, these characters will also be captured (and can then later be printed to the terminal). To avoid printing these sequences (and hence not add color) if not connected to a terminal, use `isatty stdout`.
\subsection set_color-example Examples \subsection set_color-example Examples
@ -44,8 +43,10 @@ set_color normal; echo "Normal is nice" # This will reset background, too
\subsection set_color-detection Terminal Capability Detection \subsection set_color-detection Terminal Capability Detection
Fish uses a heuristic to decide if your terminal supports the 256 color palette (as opposed to the more limited 16 color palette of older terminals). If you've done the equivalent of `set fish_term256 1` that will be true. If the $TERM value contains "256color" (e.g., "xterm-256color") that will be true. If your $TERM value is "xterm" and $TERM_PROGRAM is not set to "Apple_Terminal" that will be true. If your terminal supports the full 256 color palette (which is pretty much every color terminal emulator written in the past decade) you should ensure one of the aforementioned conditions is true. Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting `fish_term256` to *1*. If `$TERM` contains "256color" (e.g., *xterm-256color*), 256-color support is enabled. If `$TERM` contains *xterm*, 256 color support is enabled (except for MacOS: `$TERM_PROGRAM` and `$TERM_PROGRAM_VERSION` are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports `xterm` and only supports 16 colors.
Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterms, Gnome Terminal, KDE Konsole, and iTerm2. Fish currently does some limited attempts to detect whether a given `$TERM` supports 24-bit colors. You can explicitly enable that support via `set fish_term24bit 1`. If you do so fish will not map your RGB color values to the closest known matching color in the ANSI X3.64 color palette. If terminfo reports 256 color support for a terminal, support will always be enabled. To debug color palette problems, `tput colors` may be useful to see the number of colors in terminfo for a terminal. Fish launched as `fish -d2` will include diagnostic messages that indicate the color support mode in use.
The `set_color` command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will use the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape sequences if the terminfo definition says less than 256 colors are supported; otherwise it will use the terminfo definition. Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterm, Gnome Terminal, Konsole, and iTerm2. Fish attempts to detect such terminals through various means in `config.fish` You can explicitly force that support via `set fish_term24bit 1`.
The `set_color` command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will assume that all terminals can use the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape sequences if the terminfo definition indicates a color below 16 is not supported.