diff --git a/docs/book.py b/docs/book.py index 2c5a77d..fe3d117 100644 --- a/docs/book.py +++ b/docs/book.py @@ -9,7 +9,7 @@ def test0() -> None: - print('Testing file "docs/src/overview/2020s.md", line 141, chapter "2020s High-Resolution Colors"', + print('Testing file "docs/src/colors/2020s.md", line 141, chapter "2020s High-Resolution Colors"', file=sys.stderr) from prettypretty.color import Color, ColorSpace @@ -25,7 +25,7 @@ def test0() -> None: def test1() -> None: - print('Testing file "docs/src/overview/1970s.md", line 384, chapter "1970s Terminal Colors"', + print('Testing file "docs/src/colors/1970s.md", line 384, chapter "1970s Terminal Colors"', file=sys.stderr) from prettypretty.color import Color @@ -64,7 +64,7 @@ def test1() -> None: def test2() -> None: - print('Testing file "docs/src/overview/integration.md", line 215, chapter "Accommodating All Colors"', + print('Testing file "docs/src/colors/integration.md", line 215, chapter "Accommodating All Colors"', file=sys.stderr) from prettypretty.color import Color, OkVersion diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index ee6d3aa..dae7d35 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -4,13 +4,14 @@ # Getting Started - - [Installing and Building Prettypretty](installation.md) + - [Installing and Building Prettypretty](starting/installation.md) + - [Prettypretty's One-Two-Three](starting/one-two-three.md) # All the Colors - - [2020s High-Resolution Colors](overview/2020s.md) - - [1970s Terminal Colors](overview/1970s.md) - - [Accommodating All Colors](overview/integration.md) + - [2020s High-Resolution Colors](colors/2020s.md) + - [1970s Terminal Colors](colors/1970s.md) + - [Accommodating All Colors](colors/integration.md) # Deep Dives diff --git a/docs/src/overview/1970s.md b/docs/src/colors/1970s.md similarity index 100% rename from docs/src/overview/1970s.md rename to docs/src/colors/1970s.md diff --git a/docs/src/overview/2020s.md b/docs/src/colors/2020s.md similarity index 100% rename from docs/src/overview/2020s.md rename to docs/src/colors/2020s.md diff --git a/docs/src/overview/integration.md b/docs/src/colors/integration.md similarity index 100% rename from docs/src/overview/integration.md rename to docs/src/colors/integration.md diff --git a/docs/src/links.md b/docs/src/links.md index 1a151b4..18ccf3c 100644 --- a/docs/src/links.md +++ b/docs/src/links.md @@ -11,6 +11,7 @@ [`ColorSpace`]: https://apparebit.github.io/prettypretty/prettypretty/enum.ColorSpace.html [`EmbeddedRgb`]: https://apparebit.github.io/prettypretty/prettypretty/style/struct.EmbeddedRgb.html [`Fidelity`]: https://apparebit.github.io/prettypretty/prettypretty/style/enum.Fidelity.html +[`Fidelity::from_environment`]: https://apparebit.github.io/prettypretty/prettypretty/style/enum.Fidelity.html#method.from_environment [`Float`]: https://apparebit.github.io/prettypretty/prettypretty/type.Float.html [`Format`]: https://apparebit.github.io/prettypretty/prettypretty/style/format/struct.Format.html [`GrayGradient`]: https://apparebit.github.io/prettypretty/prettypretty/style/struct.GrayGradient.html @@ -24,5 +25,6 @@ [`ThemeEntry`]: https://apparebit.github.io/prettypretty/prettypretty/trans/enum.ThemeEntry.html [`ThemeEntryIterator`]: https://apparebit.github.io/prettypretty/prettypretty/trans/struct.ThemeEntryIterator.html [`Translator`]: https://apparebit.github.io/prettypretty/prettypretty/trans/struct.Translator.html +[`Translator::is_dark_theme`]: https://apparebit.github.io/prettypretty/prettypretty/trans/struct.Translator.html#method.is_dark_theme [`TrueColor`]: https://apparebit.github.io/prettypretty/prettypretty/style/struct.TrueColor.html [`VGA_COLORS`]: https://apparebit.github.io/prettypretty/prettypretty/trans/constant.VGA_COLORS.html diff --git a/docs/src/overview/summary.md b/docs/src/overview/summary.md deleted file mode 100644 index 7739a8f..0000000 --- a/docs/src/overview/summary.md +++ /dev/null @@ -1,30 +0,0 @@ -# Summary - -Prettypretty's abstractions fall into four major categories: - - * High-resolution colors - * Terminal colors - * Direct conversion between color representations - * Translation between colors - -In more detail: - - * [`Color`] is prettypretty's high-resolution color object. It combines a - [`ColorSpace`] with three [`Float`] coordinates. Its methods expose much - of prettypretty's functionality, including conversion between color - spaces, interpolation between colors, calculation of perceptual - contrast, as well as gamut testing, clipping, and mapping. - * [`TerminalColor`] combines [`DefaultColor`], [`AnsiColor`], - [`EmbeddedRgb`], [`GrayGradient`], and [`TrueColor`] to represent the - different kinds of terminal colors. - * A fair number of `From` and `TryFrom` implementations cover - lossless and partial conversions between color representations - including, for example, conversion from EmbeddedRgb to `u8` index values - as well true, terminal, and high-resolution colors. - * [`Translator`] performs the more difficult translation from ANSI to - high-resolution colors, from high-resolution to 8-bit or ANSI colors, and - the downgrading of terminal colors based on terminal capabilities and user - preferences. - - -{{#include ../links.md}} diff --git a/docs/src/installation.md b/docs/src/starting/installation.md similarity index 99% rename from docs/src/installation.md rename to docs/src/starting/installation.md index 7321200..fec3cd3 100644 --- a/docs/src/installation.md +++ b/docs/src/starting/installation.md @@ -128,4 +128,4 @@ $ ./rr.sh help ``` -{{#include links.md}} +{{#include ../links.md}} diff --git a/docs/src/starting/one-two-three.md b/docs/src/starting/one-two-three.md new file mode 100644 index 0000000..4893cc4 --- /dev/null +++ b/docs/src/starting/one-two-three.md @@ -0,0 +1,128 @@ +# Prettypretty's One-Two-Three + +Prettypretty's integration of 2020s color science with 1970s terminal output +enables a fresh take on styling the output of command line applications. Similar +to CSS on the web, that approach treats styles as dynamic, with rendered results +looking differently on different terminals. However, while CSS favors +progressive enhancement, i.e., starting with a more basic design and adding +features and flourishes as screen sizes and computing power increase, +prettypretty builds on graceful degradation, i.e., starting with expressive +styles and automatically adjusting them to user preferences and less capable +terminals. Very much like CSS, prettypretty delivers better results, when you +author for variability. Prettypretty's workflow is based on three major steps. +Here's an overview of them. + + +## 1. Fluently Assembling Styles + +The first step is the fluent assembly of [`Style`] objects with [`stylist`]s, +i.e., style builders. Each such style can optionally reset terminal appearance, +may include a text [`Format`], a foreground color using any supported color +format, and a background color using any supported color format. + +The following example fluently assembles a style for bold black text on yellow +background: + +```rust +# extern crate prettypretty; +# use prettypretty::{Color, ColorSpace}; +# use prettypretty::style::{stylist, Colorant, format::Format, TrueColor}; +let style = stylist() + .bold() + .foreground(Color::default()) + .background(TrueColor::new(0xff, 0xe0, 0x6c)) + .et_voila(); + +assert_eq!(style.format(), Some(Format::new().bold())); +assert_eq!(style.foreground(), + Some(Colorant::HiRes(Color::new( + ColorSpace::Xyz, [0.0, 0.0, 0.0]))).as_ref()); +assert_eq!(style.background(), + Some(Colorant::Rgb(TrueColor::new(255, 224, 108))).as_ref()); +``` +
+
+
+
+
+ +Best practice is to define a complimentary style for dark mode as well. Since +colors tend to appear more saturated in dark mode, simply switching foreground +and background colors doesn't work. Instead pick a less saturated yellow and +also a less dark black. Once you picked those colors, how about assembling the +corresponding style in Rust? + + +## 2. Adjusting the Fidelity of Styles + +The second step is adjusting those pretty assembled styles to the capabilities +of the current terminal and to user preferences, e.g., `NO_COLOR`, as captured +by [`Fidelity`] levels. [`Fidelity::from_environment`] determines likely +terminal capabilities based on environment variables. Meanwhile, [`Translator`] +performs the actual conversion. You instantiate a translator with the colors for +the current color theme. + +Once you have the right fidelity level and a translator, you pick between +styles for light or dark mode with the [`Translator::is_dark_theme`]. And you +adjust the selected styles with [`Style::cap`]. + +The example code shows how to adjust the style from the previous example for a +terminal that renders 8-bit colorts only. + +```rust +# extern crate prettypretty; +# use prettypretty::{Color, OkVersion}; +# use prettypretty::style::{stylist, AnsiColor, Colorant, Fidelity, TrueColor}; +# use prettypretty::trans::{Translator, VGA_COLORS}; +# let style = stylist() +# .bold() +# .foreground(Color::default()) +# .background(TrueColor::new(0xff, 0xe0, 0x6c)) +# .et_voila(); +let translator = Translator::new( + OkVersion::Revised, VGA_COLORS.clone()); +let style = style.cap(Fidelity::Ansi, &translator); + +assert_eq!(style.foreground(), + Some(Colorant::Ansi(AnsiColor::Black)).as_ref()); +assert_eq!(style.background(), + Some(Colorant::Ansi(AnsiColor::BrightYellow)).as_ref()); +``` +
+
+
+
+ + +## 3. Applying and Reverting Styles + +The third step is actually using the assembled and adjusted styles. Applying a +style to text, say, `prettypretty`, is as simple as writing its display to the +terminal. Reverting the style again takes nothing more than writing the display +of the negation to the terminal. + +The example illustrates how to apply the style from the example above to this +package's name, `prettypretty`. + +```rust +# extern crate prettypretty; +# use prettypretty::{Color, OkVersion}; +# use prettypretty::style::{stylist, AnsiColor, Colorant, Fidelity, TrueColor}; +# use prettypretty::trans::{Translator, VGA_COLORS}; +# let style = stylist() +# .bold() +# .foreground(Color::default()) +# .background(TrueColor::new(0xff, 0xe0, 0x6c)) +# .et_voila(); +# let translator = Translator::new( +# OkVersion::Revised, VGA_COLORS.clone()); +# let style = style.cap(Fidelity::Ansi, &translator); +let s = format!("{}prettypretty{}", style, !&style); + +assert_eq!(s, "\x1b[1;30;103mprettypretty\x1b[22;39;49m") +``` + +That's all! + + +{{#include ../links.md}}