Skip to content

Commit e97aef3

Browse files
bashbash
committed
📝 Make library docs less overwhelming
1 parent 5cadac6 commit e97aef3

File tree

4 files changed

+66
-64
lines changed

4 files changed

+66
-64
lines changed

‎Justfile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,6 @@ test-package name *args:
1212
# Updates the lockfile using the MSRV-aware resolver
1313
update-cargo-lock:
1414
CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback cargo +nightly -Zmsrv-policy generate-lockfile
15+
16+
doc:
17+
cargo +nightly docs-rs -p terminal-colorsaurus

‎crates/terminal-colorsaurus/doc/comparison.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Comparison with other crates in the ecosystem.
2+
3+
### [termbg]
4+
* Is hardcoded to use stdin/stderr for communicating with the terminal. \
5+
This means that it does not work if some or all of these streams are redirected.
6+
* Pulls in an async runtime for the timeout.
7+
* Does not calculate the perceived lightness, but another metric.
8+
9+
### [terminal-light]
10+
* Is hardcoded to use stdin/stdout for communicating with the terminal.
11+
* Does not report the colors, only the color's luma.
12+
* Does not calculate the perceived lightness, but another metric.
13+
14+
[termbg]: https://docs.rs/termbg
15+
[terminal-light]: https://docs.rs/terminal-light

‎crates/terminal-colorsaurus/src/lib.rs

Lines changed: 13 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,17 @@
77
//!
88
//! ## Features
99
//! * Background and foreground color detection.
10-
//! * Uses a timeout (for situations with high latency such as an SSH connection).
10+
//! * Uses a fast and reliable heuristic to detect if the terminal supports color querying.
1111
//! * *Correct* perceived lightness calculation.
12-
//! * Works even if all of stderr, stdout and stdin are redirected.
12+
//! * Works on Windows (*soon*).
1313
//! * Safely restores the terminal from raw mode even if the library errors or panicks.
1414
//! * Does not send any escape sequences if `TERM=dumb`.
15-
//! * Works on Windows (*soon*).
15+
//! * Works even if all of stderr, stdout and stdin are redirected.
16+
//! * Supports a timeout (for situations with high latency such as an SSH connection).
17+
//!
18+
//! ## Terminal Support
19+
//! `terminal-colorsaurus` works with most modern terminals and has been [tested extensively](`terminal_survey`).
20+
//! It's also really good at [detecting](`feature_detection`) when querying for the terminal's colors is not supported.
1621
//!
1722
//! ## Example 1: Test If the Terminal Uses a Dark Background
1823
//! ```no_run
@@ -22,77 +27,17 @@
2227
//! dbg!(color_scheme == ColorScheme::Dark);
2328
//! ```
2429
//!
25-
//! ## Example 2: Query for the Terminal's Foreground Color
30+
//! ## Example 2: Get the Terminal's Foreground Color
2631
//! ```no_run
2732
//! use terminal_colorsaurus::foreground_color;
2833
//!
2934
//! let fg = foreground_color().unwrap();
3035
//! println!("rgb({}, {}, {})", fg.r, fg.g, fg.b);
3136
//! ```
3237
//!
33-
//! ## Terminals
34-
//! The following terminals have known support or non-support for
35-
//! querying for the background/foreground colors.
36-
//!
37-
//! Note that terminals that support the relevant terminal
38-
//! sequences automatically work with this library even if they
39-
//! are not explicitly listed below.
40-
//!
41-
//! <details>
42-
//! <summary><strong>Supported</strong></summary>
43-
//!
44-
//! * Alacritty
45-
//! * Contour
46-
//! * foot
47-
//! * GNOME Terminal, (GNOME) Console, MATE Terminal, XFCE Terminal, (elementary) Terminal, LXTerminal
48-
//! * Hyper
49-
//! * The builtin terminal of JetBrains IDEs (i.e. IntelliJ IDEA, …)
50-
//! * iTerm2
51-
//! * kitty
52-
//! * Konsole
53-
//! * macOS Terminal
54-
//! * Rio
55-
//! * st
56-
//! * Terminology
57-
//! * Termux
58-
//! * tmux (next-3.4)
59-
//! * urxvt (rxvt-unicode)
60-
//! * VSCode (xterm.js)
61-
//! * WezTerm
62-
//! * Windows Terminal (in an upcoming version)
63-
//! * xterm
64-
//! * [Zed](https://zed.dev)
65-
//!
66-
//! </details>
67-
//!
68-
//! <details>
69-
//! <summary><strong>Unsupported</strong></summary>
70-
//!
71-
//! * linux
72-
//! * Jetbrains Fleet
73-
//! * iSH
74-
//! * GNU Screen
75-
//!
76-
//! </details>
77-
//!
7838
//! ## Optional Dependencies
7939
//! * [`rgb`] — Enable this feature to convert between [`Color`] and [`rgb::RGB16`] / [`rgb::RGB8`].
8040
//! * [`anstyle`] — Enable this feature to convert [`Color`] to [`anstyle::RgbColor`].
81-
//!
82-
//! ## Comparison with Other Crates
83-
//! ### [termbg]
84-
//! * Is hardcoded to use stdin/stderr for communicating with the terminal. \
85-
//! This means that it does not work if some or all of these streams are redirected.
86-
//! * Pulls in an async runtime for the timeout.
87-
//! * Does not calculate the perceived lightness, but another metric.
88-
//!
89-
//! ### [terminal-light]
90-
//! * Is hardcoded to use stdin/stdout for communicating with the terminal.
91-
//! * Does not report the colors, only the color's luma.
92-
//! * Does not calculate the perceived lightness, but another metric.
93-
//!
94-
//! [termbg]: https://docs.rs/termbg
95-
//! [terminal-light]: https://docs.rs/terminal-light
9641
9742
use cfg_if::cfg_if;
9843
use std::time::Duration;
@@ -128,6 +73,10 @@ cfg_if! {
12873
#[doc(cfg(docsrs))]
12974
#[doc = include_str!("../doc/feature-detection.md")]
13075
pub mod feature_detection {}
76+
77+
#[doc(cfg(docsrs))]
78+
#[doc = include_str!("../doc/comparison.md")]
79+
pub mod comparison {}
13180
}
13281
}
13382

‎doc/terminal-survey.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,38 @@
1+
The following terminals have known support or non-support for
2+
querying for the background/foreground colors and have been tested
3+
with `terminal-colorsaurus`:
4+
5+
## Supported
6+
* Alacritty
7+
* Contour
8+
* foot
9+
* GNOME Terminal, (GNOME) Console, MATE Terminal, XFCE Terminal, (elementary) Terminal, LXTerminal
10+
* Hyper
11+
* The builtin terminal of JetBrains IDEs (i.e. IntelliJ IDEA, …)
12+
* iTerm2
13+
* kitty
14+
* Konsole
15+
* macOS Terminal
16+
* Rio
17+
* st
18+
* Terminology
19+
* Termux
20+
* tmux (next-3.4)
21+
* urxvt (rxvt-unicode)
22+
* VSCode (xterm.js)
23+
* WezTerm
24+
* Windows Terminal (in an upcoming version)
25+
* xterm
26+
* [Zed](https://zed.dev)
27+
28+
## Unsupported
29+
* linux
30+
* Jetbrains Fleet
31+
* iSH
32+
* GNU Screen
33+
34+
## Details
35+
136
A list of terminals that were tested for support of `OSC 10` / `OSC 11` and `DA1` (= `CSI c`).
237

338
| Terminal | `OSC 10` and `OSC 11` | `DA1` | Version Tested |

0 commit comments

Comments
 (0)