git: 154bef0234 - main - handbooks: Add Accessibility Handbook
Alfonso S. Siciliano <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
The branch main has been updated by asiciliano: URL: https://cgit.FreeBSD.org/doc/commit/?id=154bef02348cf2ab52a8d7ae0eb1b51e2c768d58 commit 154bef02348cf2ab52a8d7ae0eb1b51e2c768d58 Author: Alfonso S. Siciliano <[email protected]> AuthorDate: 2025-11-24 20:03:59 +0000 Commit: Alfonso S. Siciliano <[email protected]> CommitDate: 2025-11-24 20:07:42 +0000 handbooks: Add Accessibility Handbook The Accessibility Handbook describes the assistive technologies available in the base system and in the Ports Collection. Currently, it covers features useful for visual impairments. Reviewed by: pauamma_gundo.com Approved by: carlavilla Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D50894 --- .../content/en/books/accessibility/_index.adoc | 63 +++ .../en/books/accessibility/blindness/_index.adoc | 320 ++++++++++++++ .../content/en/books/accessibility/book.adoc | 88 ++++ .../en/books/accessibility/colors/_index.adoc | 490 +++++++++++++++++++++ .../en/books/accessibility/development/_index.adoc | 193 ++++++++ .../en/books/accessibility/help/_index.adoc | 89 ++++ .../en/books/accessibility/lowvision/_index.adoc | 393 +++++++++++++++++ .../content/en/books/accessibility/parti.adoc | 14 + .../content/en/books/accessibility/partii.adoc | 25 ++ .../en/books/accessibility/preface/_index.adoc | 92 ++++ .../accessibility/virtual-terminal/_index.adoc | 344 +++++++++++++++ 11 files changed, 2111 insertions(+) diff --git a/documentation/content/en/books/accessibility/_index.adoc b/documentation/content/en/books/accessibility/_index.adoc new file mode 100644 index 0000000000..2c8cada910 --- /dev/null +++ b/documentation/content/en/books/accessibility/_index.adoc @@ -0,0 +1,63 @@ +--- +title: FreeBSD Accessibility Handbook +authors: + - author: Alfonso S. Siciliano +copyright: 2025 The FreeBSD Foundation +trademarks: ["freebsd"] +description: Assistive technologies available in FreeBSD +tags: ["Accessibility", "Documentation", "FreeBSD", "Index"] +next: books/accessibility/preface +add_single_page_link: true +showBookMenu: true +weight: 10 +params: + path: "/books/accessibility/" +bookOrder: 50 +--- + += FreeBSD Accessibility Handbook +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +// Split HTML view, sync with book.adoc +[.abstract-title] +Abstract + +Welcome to the Accessibility Handbook. +This book covers the assistive technologies available in FreeBSD. + +Accessibility is an ongoing effort, not a fixed destination. +As such, this handbook is a living document and continually evolving. +Contributions, suggestions, and feedback are highly encouraged. +If you are interested in contributing, please reach out to us via the https://lists.freebsd.org/subscription/freebsd-accessibility[FreeBSD accessibility mailing list]. + +You can download this book in various formats and compression options from the FreeBSD download server or one of its many mirror sites. + +''' diff --git a/documentation/content/en/books/accessibility/blindness/_index.adoc b/documentation/content/en/books/accessibility/blindness/_index.adoc new file mode 100644 index 0000000000..020adbef74 --- /dev/null +++ b/documentation/content/en/books/accessibility/blindness/_index.adoc @@ -0,0 +1,320 @@ +--- +title: Chapter 5. Blindness +part: Part II. Vision +prev: books/accessibility/lowvision +next: books/accessibility/development +description: Assistive technologies for blindness +tags: ["Accessibility", "Blindness", "Screen Reader"] +showBookMenu: true +weight: 8 +params: + path: "/books/accessibility/blindness/" +--- + +[[blindness]] += Blindness +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 5 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/blindness/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[blindness-intro]] +== Introduction + +This chapter describes assistive technologies for users who are blind, focusing primarily on screen readers and tools designed to work in conjunction with them. +The chapter deliberately contains no images and aims to minimize the use of elements other than plain text. + +[[screen-reader]] +== Screen Reader + +Currently, screen readers function only within the extref:{handbook}x11[X Window System] and are not supported in the crossref:virtual-terminal[virtual-terminal,Virtual Terminal]. +FreeBSD does not currently support Braille displays, so they rely exclusively on speech synthesizers. + +[[orca]] +=== Orca + +Orca is a widely used and well-known open source screen reader. +It offers a comprehensive set of features and is available on FreeBSD through the package:accessibility/orca[] package. + +[[orca-install]] +==== Installation + +To install it, execute: + +[source,shell] +.... +# pkg install orca +.... + +[[orca-launch]] +==== Launch + +Orca can be launched in several ways. +From a terminal, type: + +[source,shell] +.... +% orca +.... + +Some desktop environments provide a keyboard shortcut to launch Orca: + +- XFCE: `Super` + `Alt` + `s` +- GNOME `Super` + `Alt` + `S` + +[TIP] +==== +The Super key is usually labeled as Windows icon, Command icon, or "Super". +Refer to https://en.wikipedia.org/wiki/Super_key_(keyboard_button) for more information. +==== + +[[orca-usage]] +==== Usage + +Orca provides a manual page: man:orca[1]. +However, most of the documentation is available online. +The main reference is the starting point in the https://gnome.pages.gitlab.gnome.org/orca/help/[Orca Users Guide], which includes: + + - Getting Started + - Reading Documents and Web Pages + - Reviewing and Interacting with Screen Contents + +The screen reader includes many keyboard commands for navigation and interaction. +Refer to the https://gnome.pages.gitlab.gnome.org/orca/help/commands.html[Orca's Commands] page for a full list. + +[[orca-config]] +==== Configuration + +Orca can be configured through a graphical settings interface. To open it, run: + +[source,shell] +.... +% orca -s +.... + +Configuration options are documented on the https://gnome.pages.gitlab.gnome.org/orca/help/preferences.html[Orca's Preferences Dialogs] page. + +[[yasr]] +=== yasr + +The package:accessibility/yasr[] utility is a lightweight screen reader that operates exclusively in a terminal environment. +Yasr requires a speech synthesizer to work. +Its default configuration file is set up to use package:accessibility/eflite[]. + +To install both yasr and eflite, run: + +[source,shell] +.... +# pkg install yasr eflite +.... + +To start the screen reader, execute: + +[source,shell] +.... +% yasr +.... + +The global configuration file for yasr is located at [.filename]#/usr/local/share/yasr/yasr.conf#. +To create a user-specific configuration file, copy the global one to your home directory: + +[source,shell] +.... +% cp /usr/local/share/yasr/yasr.conf ~/.yasr.conf +.... + +For details on configuration options and keyboard shortcuts, refer to man:yasr[1]. + +[[blindness-ports]] +== Ports Collection + +FreeBSD provides the extref:{handbook}ports[Ports Collection], which offers a simple way to install applications. +Some ports allow you to configure options before building and installation. +By default, configuration is handled through a TUI menu not accessible by a screen reader. + +The package:ports-mgmt/portoptscli[] utility is a text-only tool specifically designed to configure ports using a screen reader. +To install it, run: + +[source,shell] +.... +# pkg install portoptscli +.... + +Then add to [.filename]#/etc/make.conf#: + +[.programlisting] +.... +DIALOG4PORTS=/usr/local/bin/portoptscli +.... + +From now on, the Ports framework will automatically invoke portoptscli whenever a port offers configurable options. + +For detailed information about its features and usage, refer to the manual page man:portoptscli[1] and consult the online https://gitlab.com/alfix/portoptscli/-/raw/main/README.txt[README]. + +[[blindness-editor]] +== Editor + +[[ed]] +=== ed + +The man:ed[1] utility is a line-oriented text editor used to create, view, and modify text files. +It is included by default in a standard FreeBSD installation. +To start the editor, run: + +[source,shell] +.... +% ed +.... + +ed is a powerful editor. +Refer to its manual page man:ed[1] for a complete overview of its features and command syntax. + +[WARNING] +==== +ed does not support multibyte characters and may not handle non-ASCII text correctly. +Alternatively, consider using crossref:blindness[edbrowse,edbrowse], which offers robust text editing features in addition to its browsing capabilities. +==== + +[[blindness-internet-web]] +== Internet and WEB + +[[edbrowse]] +=== Edbrowse + +Edbrowse is a text-based browser, editor, IRC chat client, and mail client, specifically designed for screen reader users. +Its interface is similar to man:ed[1], but with extended functionality. + +[[edbrowse-install]] +==== Installation + +To install package:www/edbrowse[], execute: + +[source,shell] +.... +# pkg install edbrowse +.... + +[[edbrowse-usage]] +==== Usage + +To launch Edbrowse, run: + +[source,shell] +.... +% edbrowse +.... + +The first time you run edbrowse, it will not find the configuration file [.filename]#~/.ebrc#. +It will automatically create a default configuration file, display a message, and exit: + +[source,shell] +.... +% edbrowse +Your edbrowse config file is missing; a default file has been created for you. +Before running edbrowse again, take the time to personalize your config file: +/home/yournickname/.ebrc +edbrowse -c to edit +% +.... + +You can now relaunch Edbrowse; it will use the default configuration file. +To customize it, either run: + +[source,shell] +.... +% edbrowse -c +.... + +Or use your preferred text editor, for example: + +[source,shell] +.... +% ed ~/.ebrc +.... + +[TIP] +==== +Example configuration files are provided in [.filename]#/usr/local/share/doc/edbrowse/#. +These include: + + - sample.ebrc: with comments in English + - sample_fr.ebrc: with comments in French + - sample_it.ebrc: with comments in Italian +==== + +[[edbrowse-doc]] +==== Documentation + +The utility provides a manual page: man:edbrowse[1]. +However, the main documentation is available online in the https://edbrowse.org/usersguide.html[User's Guide]. + +The package also installs a local copy of the documentation at [.filename]#/usr/local/share/doc/edbrowse/usersguide.html#. +To view it using edbrowse, run: + +[source,shell] +.... +% edbrowse /usr/local/share/doc/edbrowse/usersguide.html +.... + +Translated versions of the user guide are available in the same directory: + + - usersguide_es.html: Spanish + - usersguide_fr.html: French + - usersguide_pt_br.html: Brazilian Portuguese + +[[blindness-liblouis]] +== Liblouis + +package:devel/liblouis[] is a translator for many languages to and from Braille. +It provides a large number of conversion tables. +To install, execute: + +[source,shell] +.... +# pkg install liblouis +.... + +The package installs both libraries and utilities. +The translation utility is man:lou_translate[1]. + +The following example demonstrates how to transcribe the text `FreeBSD Accessibility Handbook` into Braille with English Grade 2 translation table and the unicode.dis display table. +The final output is Braille encoded as Unicode dot patterns. + +[source,shell] +.... +% echo "FreeBSD Accessibility Handbook" | lou_translate -f unicode.dis,en-us-g2.ctb +⠠⠋⠗⠑⠑⠠⠠⠃⠎⠙⠀⠠⠁⠒⠑⠎⠎⠊⠃⠊⠇⠰⠽⠀⠠⠓⠯⠃⠕⠕⠅ +.... + +Documentation and additional examples for this utility are available on the project website, specifically in the https://liblouis.io/documentation/liblouis.html#Testing-Translation-Tables-interactively[Testing Translation Tables interactively] section of the official documentation. diff --git a/documentation/content/en/books/accessibility/book.adoc b/documentation/content/en/books/accessibility/book.adoc new file mode 100644 index 0000000000..715a9b3ff6 --- /dev/null +++ b/documentation/content/en/books/accessibility/book.adoc @@ -0,0 +1,88 @@ +--- +title: FreeBSD Accessibility Handbook +authors: + - author: Alfonso S. Siciliano +copyright: 2025 The FreeBSD Foundation +description: Assistive technologies available in FreeBSD +trademarks: ["freebsd"] +tags: ["Accessibility", "Documentation", "FreeBSD", "Index"] +add_split_page_link: true +--- + += FreeBSD Accessibility Handbook +:doctype: book +:toc: macro +:toclevels: 2 +:icons: font +:sectnums: +:sectnumlevels: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:book: true +:pdf: false +:images-path: books/accessibility/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +:chapters-path: content/{{% lang %}}/books/accessibility/ +endif::[] +ifdef::backend-pdf,backend-epub3[] +:chapters-path: +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +:chapters-path: +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +// Single HTML view, sync with _index.adoc +[.abstract-title] +Abstract + +Welcome to the Accessibility Handbook. +This book covers the assistive technologies available in FreeBSD. + +Accessibility is an ongoing effort, not a fixed destination. +As such, this handbook is a living document and continually evolving. +Contributions, suggestions, and feedback are highly encouraged. +If you are interested in contributing, please reach out to us via the https://lists.freebsd.org/subscription/freebsd-accessibility[FreeBSD accessibility mailing list]. + +You can download this book in various formats and compression options from the FreeBSD download server or one of its many mirror sites. + +''' + +toc::[] + +:sectnums!: + +include::{chapters-path}preface/_index.adoc[leveloffset=+1] + +:sectnums: + +// Section one +include::{chapters-path}parti.adoc[] + +include::{chapters-path}help/_index.adoc[leveloffset=+1] + +// Section two +include::{chapters-path}partii.adoc[] + +include::{chapters-path}virtual-terminal/_index.adoc[leveloffset=+1] + +include::{chapters-path}colors/_index.adoc[leveloffset=+1] + +include::{chapters-path}lowvision/_index.adoc[leveloffset=+1] + +include::{chapters-path}blindness/_index.adoc[leveloffset=+1] + +include::{chapters-path}development/_index.adoc[leveloffset=+1] diff --git a/documentation/content/en/books/accessibility/colors/_index.adoc b/documentation/content/en/books/accessibility/colors/_index.adoc new file mode 100644 index 0000000000..6de26c0398 --- /dev/null +++ b/documentation/content/en/books/accessibility/colors/_index.adoc @@ -0,0 +1,490 @@ +--- +title: Chapter 3. Colors +part: Part II. Vision +prev: books/accessibility/virtual-terminal +next: books/accessibility/lowvision +description: Features to set up colors +tags: ["Accessibility", "High contrast", "Color blindness", "Theming"] +showBookMenu: true +weight: 6 +params: + path: "/books/accessibility/colors/" +--- + +[[colors]] += High Contrast +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 3 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/colors/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[colors-intro]] +== Introduction + +This chapter explains how to configure colors for on-screen elements, including: + +- Setting high-contrast color schemes in graphical environments. +- Adapting screen color temperature for optimal viewing in daylight and nighttime conditions. +- Selecting colors for configuration ports menus. + +[[high-contrast-theme]] +== High Contrast Theme + +Graphical Environments allow you to easily install and set up graphical themes. +This paragraph describes how to configure high contrast themes for windows. + +[[xfce-high-contrast]] +=== XFCE + +Download from https://www.xfce-look.org/p/2289345[High Contrast Windows 11 Themes]: + +- _Adwaita-Dusk.tar.bz2_ +- _Adwaita-Desert.tar.bz2_ +- _Adwaita-Aquatic.tar.bz2_ +- _Adwaita-NightSky.tar.bz2_ + +The example is for _NightSky_, but of course you can choose whichever theme you prefer. + +[source,shell] +.... +% tar xzvf Adwaita-NightSky.tar.bz2 <1> +% mkdir ~/.themes <2> +% cp -a Adwaita-NightSky ~/.themes/ <3> +% rm Adwaita-NightSky.tar.bz2 <4> +% xfconf-query -c xfwm4 -p /general/theme -s 'Adwaita-NightSky' <5> +% xfconf-query -c xsettings -p /Net/ThemeName -s 'Adwaita-NightSky' <6> +.... + +<.> Extract the downloaded theme archive. +<.> Create the [.filename]#~/.themes# directory if it does not already exist. +<.> Copy the extracted themes into [.filename]#~/.themes#. +<.> Optionally, delete the original compressed file to save space. +<.> Apply the Adwaita-NightSky theme for the XFCE desktop environment. +<.> Apply the Adwaita-NightSky theme for GTK applications. + +The theme selection steps (5 and 6) can also be performed using the graphical configuration dialogs in XFCE: + +[source,shell] +.... +% xfwm4-settings +% xfce4-appearance-settings +.... + +[[high-contrast-icon]] +== High Contrast Icons + +Graphical Environments allow you to easily install and set up icon themes. +This paragraph describes how to configure high contrast icons. + +[[xfce-icon-high-contrast]] +=== XFCE + +Run the following commands to use the _Treepata - High Contrast_ icons theme with XFCE. + +Download _Treepata.zip_ from https://www.xfce-look.org/p/1015854[Treepata - High contrast]. +Then execute: + +[source,shell] +.... +# pkg search zip <1> +% unzip Treepata.zip <2> +% mkdir ~/.icons <3> +% cp -a Treepata ~/.icons/ <4> +% rm Treepata.zip <5> +% xfconf-query -c xsettings -p /Net/IconThemeName -s Treepata <6> +.... + +<.> Install the package package:archivers/zip[]: +<.> Extract the downloaded archive file. +<.> Create the [.filename]#~/.icons# directory if it does not already exist. +<.> Copy the extracted theme into [.filename]#~/.icons#. +<.> Optionally, delete the downloaded archive file to free up space. +<.> Set the _Treepata_ icon theme. + +The icon theme (step 6 above) can also be set graphically via the `_Appearance_` dialog under the `_Icons_` tab. +To do so, open the dialog and select your preferred icon theme: + +[source,shell] +.... +% xfce4-appearance-settings +.... + +[NOTE] +==== +If you have icon theme problems, install package:misc/hicolor-icon-theme[] and package:graphics/gtk-update-icon-cache[]: + +[source,shell] +.... +# pkg install hicolor-icon-theme gtk-update-icon-cache +.... + +Run man:gtk-update-icon-cache[1] to create or update the icon cache: + +[source,shell] +.... +% gtk-update-icon-cache -f -t ~/.icons/treepata +.... + +==== + +[[colors-temperature]] +== Color temperature + +This paragraph explains various utilities that adjust screen colors based on temperature, day/night cycles, and gamma settings. +These utilities enable both interactive color adjustments and automatic changes based on the local time and geographical location. +Some utilities are compatible with the extref:{handbook}x11[X Window System], others support extref:{handbook}wayland[Wayland], and some work on both display servers. + +.Color Temperature Utilities +[options="header", cols="1,1,1,1"] +|=== +| Name | Auto Update | Environment | Package + +| darkman +| Yes +| X11 +| package:accessibility/darkman[] + +| gammastep +| Yes +| X11 +| package:accessibility/gammastep[] + +| redshift +| Yes +| X11, Wayland +| package:accessibility/redshift[] + +| sct +| No +| X11 +| package:accessibility/sct[] + +| sctd +| Yes +| X11 +| package:accessibility/sctd[] + +| wlsunset +| Yes +| Wayland +| package:accessibility/wlsunset[] + +|=== + +The rest of this section details the steps to install, configure, and launch the utilities. + +[[colors-darkman]] +=== darkman + +man:darkman[1] is a daemon that automatically manages transitions between dark mode and light mode. +It operates primarily in the background, switching the screen's color scheme based on the local time of the current location. +To install, run: + +[source,shell] +.... +# pkg install darkman +.... + +Create the file [.filename]#~/.config/darkman/config.yaml# and write your latitude and longitude. +Example: + +[.programlisting] +.... +lat: 37.52 +lng: 122.16 +.... + +The utility does not directly change the screen colors; instead, it calls external utilities to perform the color transitions. +Add scripts to be executed at sundown by placing them in [.filename]#$XDG_DATA_DIRS/dark-mode.d/# +and scripts to be executed at sunrise by placing them in [.filename]#XDG_DATA_DIRS/light-mode.d/#. +Several https://gitlab.com/WhyNotHugo/darkman/-/tree/main/examples[example scripts] are available in the project repository. + +To start darkman manually, run: + +[source,shell] +.... +% darkman run & +.... + +The utility also offers some interactive options; for more details refer to the man:darkman[1] manual page. + +[[gammastep]] +=== gammastep + +The man:gammastep[1] utility adjusts your screen’s color temperature automatically based on your location. +To install, run: + +[source,shell] +.... +# pkg install gammastep +.... + +The utility works out of the box without any configuration. +Simply start it by running: + +[source,shell] +.... +% gammastep & +.... + +[NOTE] +==== +If you encounter any issues, customize the configuration by adapting the link:https://gitlab.com/chinstrap/gammastep/-/blob/master/gammastep.conf.sample[gammastep.conf.sample] file and save it as [.filename]#~/.config/gammastep/conf.ini#. +Refer to the link:https://gitlab.com/chinstrap/gammastep/-/blob/master/README.md[README] for troubleshooting. +==== + +[[redshift]] +=== redshift + +The man:redshift[1] utility find your position and sets the color temperature accordingly. +To install, execute: + +[source,shell] +.... +# pkg install redshift +.... + +The redshift utility runs without any configuration. +To start it, simply execute: + +[source,shell] +.... +% redshift & +.... + +The utility might hang while trying to determine the location or the correct method to set the color. +In this case, specify them explicitly using `-l _latitude:longitude_` and `-m _method_`. +The available methods can be listed by running: `% redshift -m list`. + +Example of running redshift with an explicit location and method: + +[source,shell] +.... +% redshift -l 37.86:-122.27 -m randr & +.... + +To make this setting permanent, add the following lines to [.filename]#~/.config/redshift/redshift.conf# file: + +[.programlisting] +.... +[redshift] +adjustment-method=randr +location-provider=manual + +[manual] +lat=37.86 +lon=-122.27 +.... + +[NOTE] +==== +The project provides a default https://github.com/jonls/redshift/blob/master/redshift.conf.sample[redshift.conf.sample] configuration file. +For troubleshooting and additional information, please refer to the https://github.com/jonls/redshift/blob/master/README.md[README]. +==== + +[[sct]] +=== sct + +The man:sct[1] utility is a simple command-line tool for controlling screen color temperature. +It does not update automatically and must be run repeatedly to adjust the temperature over time. +To install, execute: + +[source,shell] +.... +# pkg install sct +.... + +The utility takes temperature values between 1000 and 10000, 6500 is the default. +To run sct, type: `sct _value_`: + +[source,shell] +.... +% sct 8000 +.... + +[TIP] +==== +The utility suggests 3 styles: + +1) Campfire style + +[source,shell] +.... +% sct 4500 +.... + +2) Dust storm on Mars style + +[source,shell] +.... +% sct 2000 +.... + +3) Coffee free all nighter style + +[source,shell] +.... +% sct 8000 +.... +==== + +[[sctd]] +=== sctd + +The sctd utility calculates sunrise and sunset times based on latitude and longitude, and adjusts the screen's color temperature accordingly. +To install, run: + +[source,shell] +.... +# pkg install sctd +.... + +To run sctd, specify your location using the `--latitude` and `--longitude` options: + +[source,shell] +.... +% sctd --latitude 40.55 --longitude 14.34 & +.... + +To reset the screen color to default, run: + +[source,shell] +.... +% sctd --reset +.... + +[[wlsunset]] +=== wlsunset + +The man:wlsunset[1] utility is a Day/Night gamma adjustments for Wayland compositors. + +To install, execute: + +[source,shell] +.... +# pkg install wlsunset +.... + +To start the utility type `wlsunset -l _latitude_ -L _longitude_`. +Example: + +[source,shell] +.... +% wlsunset -l 14.34 -L 40.55 & +.... + +[[colors-ports]] +== Ports Collection + +FreeBSD provides the extref:{handbook}ports[Ports Collection], which offers a simple way to install applications. +Some ports allow you to configure options before building and installation. +By default, configuration is handled through a TUI menu built by the package:ports-mgmt/portconfig[]. +The colors can be customized in several ways: + +. Terminal color capabilities. +. The $NO_COLOR environment variable. +. The $PORTCONFIG_THEMEFILE environment variable. +. The global [.filename]#/usr/local/etc/portconfig/theme.conf# file. + +[NOTE] +==== +These methods are listed in order of decreasing priority and are mutually exclusive, meaning only one can be active at a time. +==== + +*1. Terminal Colors* + +man:portconfig[1] automatically detects whether the terminal supports colors. +If not, it defaults to a black-and-white theme. + +*2. NO_COLOR* + +If the `$NO_COLOR` environment variable is set and not empty, portconfig forces the black-and-white theme + +.Example persistent setting `$NO_COLOR` +[example] +==== +[.filename]#/etc/make.conf# + +[.programlisting] +.... +export NO_COLOR=YES +.... +==== + +*3. PORTCONFIG_THEMEFILE* + +If the `$PORTCONFIG_THEMEFILE` environment variable is set and points to a valid theme file, it will be used. +Otherwise, the default theme is applied. + +..Example persistent setting `$PORTCONFIG_THEMEFILE` +[example] +==== +[.filename]#/etc/make.conf# + +[.programlisting] +.... +export PORTCONFIG_THEMEFILE=/home/foo/mytheme.conf +.... *** 1224 LINES SKIPPED ***