From 6f566b9c4d55c42e707e1d2518eb05677dd3a040 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Marcos=20P=2E=20Bezerra?= Date: Fri, 15 Mar 2024 15:23:44 -0300 Subject: [PATCH] add module docs for accessible mode --- src/accessible.rs | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/src/accessible.rs b/src/accessible.rs index 1e4e220..5f68550 100644 --- a/src/accessible.rs +++ b/src/accessible.rs @@ -1,13 +1,51 @@ +//! Accessibility mode functions. +//! +//! # Problem +//! +//! `Ouch`'s default output contains symbols which make it visually easier to +//! read, but harder for people who are visually impaired and rely on +//! text-to-voice readers. +//! +//! On top of that, people who use text-to-voice tools can't easily skim +//! through verbose lines of text, so they strongly benefit from fewer lines +//! of output. +//! +//! # Solution +//! +//! To tackle that, `Ouch` has an accessibility mode that filters out most of +//! the verbose logging, displaying only the most important pieces of +//! information. +//! +//! Accessible mode also changes how logs are displayed, to remove symbols +//! which are "noise" to text-to-voice tools and change formatting of error +//! messages. +//! +//! # Are impaired people actually benefiting from this? +//! +//! So far we don't know. Most CLI tools aren't accessible, so we can't expect +//! many impaired people to be using the terminal and CLI tools, including +//! `Ouch`. +//! +//! I consider this to be an experiment, and a tiny step towards the right +//! direction, `Ouch` shows that this is possible and easy to do, hopefully +//! we can use our experience to later create guides or libraries for other +//! developers. + use once_cell::sync::OnceCell; -/// Whether to enable accessible output (removes info output and reduces other -/// output, removes visual markers like '[' and ']'). +/// Global flag for accessible mode. pub static ACCESSIBLE: OnceCell = OnceCell::new(); +/// Check if `Ouch` is running in accessible mode. +/// +/// Check the module-level documentation for more details. pub fn is_running_in_accessible_mode() -> bool { ACCESSIBLE.get().copied().unwrap_or(false) } +/// Set the value of the global [`ACCESSIBLE`] flag. +/// +/// Check the module-level documentation for more details. pub fn set_accessible(value: bool) { if ACCESSIBLE.get().is_none() { ACCESSIBLE.set(value).unwrap();