diff --git a/documentation/content/en/books/accessibility/_index.adoc b/documentation/content/en/books/accessibility/_index.adoc new file mode 100644 --- /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 --- /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 --- /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 --- /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 +.... +==== + +[TIP] +==== +To create a new theme file, run: + +[source,shell] +.... +% /usr/local/bin/bsddialog --save-theme mytheme.conf --infobox "Saving theme..." 0 0 +.... +==== + +*4. Global theme.conf* + +If the file [.filename]#/usr/local/etc/portconfig/theme.conf# exists and is valid, it will be used. +If not, the default theme is applied. + +[TIP] +==== +Sample themes are included in [.filename]#/usr/local/etc/portconfig/#: + +- blackwhite.conf +- default.conf +- red-green.conf +- yellow-blue.conf + +To use the yellow-blue.conf theme: +[source,shell] +.... +# ln -s /usr/local/etc/portconfig/yellow-blue.conf /usr/local/etc/portconfig/theme.conf +.... +==== diff --git a/documentation/content/en/books/accessibility/development/_index.adoc b/documentation/content/en/books/accessibility/development/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/development/_index.adoc @@ -0,0 +1,193 @@ +--- +title: Chapter 6. Development +part: Part II. Vision +prev: books/accessibility/desktop +description: Resources for developers +tags: ["Accessibility", "Development"] +showBookMenu: true +weight: 9 +params: + path: "/books/accessibility/development/" +--- + +[[development]] += Development +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/development/ + +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::[] + +[[devel-intro]] +== Introduction + +This chapter provides resources for developers seeking to make their programs accessible, test accessibility, and improve the accessibility of their software. + +[[devel-colors]] +== Colors + +Do not assume that users can distinguish all (or even any of) the colors used in your program. +While official statistics on the prevalence of color blindness are lacking, it is estimated that approximately 5% of the population is affected by some form of it, whether partial or total. + +[[devel-color-guidelines]] +=== Colors Guidelines + +Avoid using color as the sole means of conveying information. +If color must be used, provide a straightforward and well-documented method for configuring color settings. +Where possible, ensure support for the `$NO_COLOR` environment variable to accommodate user preferences. + +[[devel-color-checkers]] +=== Colors Checker + +The package:graphics/kontrast[] package provides the Kontrast GUI utility to check if the color combinations are distinct enough to be readable and accessible. +To install: + +[source,shell] +.... +# pkg install kontrast +.... + +[[devel-cli]] +== Command Line Interface + +The CLI is generally considered accessible by a screen reader. +However, it is important to understand some concepts, follow best practices, and avoid certain mistakes to ensure an accessible UI. + +Dahlke, Karl. _Command Line Programs for the Blind_. +Available at: http://www.eklhad.net/philosophy.html. +This article discusses the concept of presenting information in one dimension and addresses the accessibility challenges inherent in programs designed exclusively for sighted users. + +Sampath, H., Merrick, A., & Macvean, A. (2021). +Accessibility of Command Line Interfaces. +In Proceedings of the CHI Conference on Human Factors in Computing Systems (CHI '21). +ACM. +Available at: https://dl.acm.org/doi/fullHtml/10.1145/3411764.3445544. +This paper presents guidelines and common pitfalls to avoid when designing command-line interfaces that are accessible to screen reader users. + +[[devel-libs]] +== Libraries + +[[devel-at-spi]] +=== Gnome + +AT-SPI (Assistive Technology Service Provider Interface), package:accessibility/at-spi2-core[], is a framework that establishes a communication channel between applications and assistive technologies. +To install, execute: + +[source,shell] +.... +# pkg install at-spi2-core +.... + +AT-SPI offers a wide range of features. For more information, refer to the following resources: +https://gitlab.gnome.org/GNOME/at-spi2-core/-/blob/main/README.md[README], +https://gnome.pages.gitlab.gnome.org/at-spi2-core/atk/[Atk wiki], +https://gnome.pages.gitlab.gnome.org/at-spi2-core/libatspi/[AT SPI Wiki], +and https://wiki.gnome.org/Accessibility[GNOME Accessibility Team Wiki]. + +[TIP] +==== +Some wrappers are available: package:accessibility/rubygem-atk[] (Ruby), package:accessibility/py-atspi[] (Python), and package:accessibility/atkmm[] (C++). +==== + +[[devel-qt]] +=== QT + +package:accessibility/libqaccessibilityclient[] establishes a communication channel between applications and assistive technologies. +In particular, it provides a bridge between applications built with Qt and the AT-SPI framework crossref:development[devel-at-spi,previously described]. +For full documentation, refer to the https://api.kde.org/libqaccessibilityclient/html/index.html[API Reference] and the https://github.com/KDE/libqaccessibilityclient[official repository]. +To install: + +[source,shell] +.... +# pkg install libqaccessibilityclient +.... + +Libraries package:accessibility/qt5-speech[] and package:accessibility/qt6-speech[] provide access to a Text-To-Speech functionality (specifically to package:accessibility/speech-dispatcher[]). +Documentation is available at https://doc.qt.io/archives/qt-5.15/qtspeech-index.html and https://doc.qt.io/qt-6/qttexttospeech-index.html. +To install, run: + +[source,shell] +.... +# pkg install qt5-speech +# pkg install qt6-speech +.... + +=== Speech Synthesis + +package:accessibility/speech-dispatcher[] provides a simple, high level, and device independent layer for access to Speech Synthesizers. +To install, run: + +[source,shell] +.... +# pkg install speech-dispatcher +.... + +For detailed documentation, refer to the official Speech Dispatcher website: https://freebsoft.org/speechd. + +[TIP] +==== +A Python wrapper for the library is provided by the package:accessibility/py-speech-dispatcher[]. +==== + +[[devel-liblouis]] +=== Liblouis + +package:devel/liblouis[] provides an API for translating many languages to and from Braille. +To install, execute: + +[source,shell] +.... +# pkg install liblouis +.... + +The library provides many features, https://liblouis.io/documentation/[documented on the liblouis project website]. + +[TIP] +==== +Liblouis provides also a Python API, https://liblouis.io/documentation/liblouis.html#Python-bindings[Python bindings]. +==== + +[[devel-tools]] +== Tools + +package:accessibility/accerciser[] provides an accessibility inspection tool for applications developed for the extref:{handbook}desktop/#gnome-environment[GNOME] desktop environment. +To install it, run: + +[source,shell] +.... +# pkg install accerciser +.... + +For detailed usage and features, refer to man:accerciser[1]. +Additional documentation is available in the https://gitlab.gnome.org/GNOME/accerciser/-/blob/master/README.md[REAMDE.md] +and the https://help.gnome.org/users/accerciser/stable/index.html.en[Accerciser User Guide]. diff --git a/documentation/content/en/books/accessibility/help/_index.adoc b/documentation/content/en/books/accessibility/help/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/help/_index.adoc @@ -0,0 +1,89 @@ +--- +title: Chapter 1. Help +part: Part I. General +prev: books/accessibility/parti +next: books/accessibility/partii +description: Where to get help +tags: ["Accessibility", "Help"] +showBookMenu: true +weight: 3 +params: + path: "/books/accessibility/help/" +--- + +[[help]] += Help +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 1 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/help/ + +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::[] + +[[help-mailinglists]] +== Mailing Lists + +Mailing lists are the primary communication channel for the FreeBSD community, covering a wide range of topics related to the project. +Messages are typically written in plain text without graphical elements, making them well-suited for use with screen readers (both Braille displays and speech synthesizers). +A complete list of available mailing lists can be found at: https://lists.freebsd.org/. + +For accessibility issues, the main point of contact is the FreeBSD Accessibility Mailing List. +To subscribe, browse the archive, send messages, or manage your subscription, visit: https://lists.freebsd.org/subscription/freebsd-accessibility + +[[help-chat]] +== Chat + +FreeBSD users and developers are also active on IRC (Internet Relay Chat), where real-time communication takes place. +A complete list of servers and channels is available at: https://wiki.freebsd.org/IRC/Channels +Messages are typically exchanged in plain text, making IRC well-suited for screen readers (both Braille displays and speech synthesizers). + +[[help-ports-pkgs]] +== Ports and Packages + +If the issue pertains to an external tool installed through a extref:{handbook}ports[port or package], consider including the port maintainer in the discussion to ensure proper attention and resolution. + +To find out who maintains a specific port, navigate to the port's directory and run the command `make maintainer`. +For example, to find the maintainer of the package:www/edbrowse[] port, run: + +[source,shell] +.... +% cd /usr/ports/www/edbrowse +% make maintainer +.... + +To find the maintainer of an installed package, use the `pkg info -f _package_`. +For example: + +[source,shell] +.... +% pkg info -f edbrowse | grep Maintainer | awk '{print $3}' +.... diff --git a/documentation/content/en/books/accessibility/lowvision/_index.adoc b/documentation/content/en/books/accessibility/lowvision/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/lowvision/_index.adoc @@ -0,0 +1,393 @@ +--- +title: Chapter 4. Low Vision +part: Part II. Vision +prev: books/accessibility/colors +next: books/accessibility/blindness +description: Assistive technologies for low vision +tags: ["Accessibility", "Low Vision", "Magnify", "Desktop"] +showBookMenu: true +weight: 7 +params: + path: "/books/accessibility/lowvision/" +--- + +[[lowvision]] += Low Vision +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 4 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/lowvision/ + +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::[] + +[[lowvisin-intro]] +== Introduction + +This chapter outlines accessibility features available in graphical desktop environments designed for users with low vision, such as virtual magnifiers, easy-to-read fonts, and screen scaling. + +[[hidpi]] +== Desktop Size + +Graphical environments allow users to adjust the desktop display size, a feature commonly known as screen scaling or HiDPI scaling. +The goal is to enlarge desktop elements such as icons, text, and windows to improve visibility and accessibility. + +[[xfce-hidpi]] +=== XFCE + +To set a custom scaling factor, for example 4, run the following command: + +[source,shell] +.... +% xfconf-query -c xsettings -p /Gdk/WindowScalingFactor -s 4 +.... + +Alternatively, HiDPI scaling can be enabled with a fixed 2x factor using the graphical interface. +This option is available in the `_Appearance_` dialog, under the `_Settings_` tab as `_Window Scaling_`. +To open the `_Appearance_` dialog, execute: + +[source,shell] +.... +% xfce4-appearance-settings +.... + +[[lowvision-font]] +== Font + +The package:x11-fonts/atkinson-hyperlegible[] provides the _atkinson-hyperlegible_ font. +It is designed for good readability, the letter shapes aim to increase character recognition. +To install, execute: + +[source,shell] +.... +# pkg install atkinson-hyperlegible +.... + +The remainder of this section describes how to set up fonts in various graphical environments using _atkinson-hyperlegible_ as an example. + +[[xfce-fonts]] +=== XFCE + +XFCE allows you to select the font and size for window titles and content text, as well as the font size for icon labels. + +[source,shell] +.... +% xfconf-query -c xfwm4 -p /general/title_font -s "Atkinson Hyperlegible 15" <1> +% xfconf-query -c xsettings -p /Gtk/FontName -s "Atkinson Hyperlegible 15" <2> +% xfconf-query -c xsettings -p /Gtk/MonospaceFontName -s "Atkinson Hyperlegible 15" <3> +% xfconf-query -c xfce4-desktop -p /desktop-icons/use-custom-font-size -s true <4> +% xfconf-query -c xfce4-desktop -p /desktop-icons/font-size -s 15.0 <5> +.... + +<.> Set the window title font to _Atkinson Hyperlegible_, size 15. +<.> Set the window content font to _Atkinson Hyperlegible_, size 15. +<.> Set the monospace font within windows to _Atkinson Hyperlegible_, size 15. +<.> Enable custom font sizing for icons. +<.> Set the icon font size to 15.0. + +Alternatively, you can configure the same settings using the graphical XFCE configuration dialogs. + +To select the font for window titles, open the `_Window Manager_` dialog: + +[source,shell] +.... +% xfwm4-settings +.... + +To choose the font used inside windows, open the `_Appearance_` dialog and go to the `_Fonts_` tab: + +[source,shell] +.... +% xfce4-appearance-settings +.... + +[TIP] +==== +In the Fonts tab, you can also adjust options such as `_anti-aliasing_`, `_Hinting_`, `_Sub-pixel order_`, and `_Custom DPI_`. +For more details, see the https://docs.xfce.org/xfce/xfce4-settings/appearance#fonts[XFCE documentation]. +==== + +To set the font size for icons, open the `_Desktop_` dialog and go to the `_Desktop Icons_` tab where you can adjust the icon font size: + +[source,shell] +.... +% xfdesktop-settings +.... + +[[magnify]] +== Magnify + +This section describes various utilities that magnify portions of the screen, acting as virtual magnifying lenses. +Some tools continuously enlarge the area beneath the mouse cursor, while others do not. +Certain utilities automatically move the magnified window to follow the cursor, whereas others keep it fixed in place. + +.Screen magnifier utilities. +[options="header", cols="1,1,1,1"] +|=== +| Name | Auto Update | Auto Move Lens | Package + +| lupe +| Yes +| No +| package:x11/lupe[] + +| kmag +| Yes +| No +| package:accessibility/kmag[] + +| xlupe +| Yes +| No +| package:x11/xlupe[] + +| xmag +| No +| No +| package:x11/xmag[] + +| xzoom +| No +| No +| package:x11/xzoom[] + +|=== + +The rest of this section details the steps to install, configure, and launch the utilities. + +[[lupe]] +=== lupe + +The man:lupe[1] utility is a screen magnifier for the X Window System that updates the magnified area in real time. +To install it, run: + +[source,shell] +.... +# pkg install lupe +.... + +By default, lupe magnifies the screen content beneath the mouse pointer within a circular area (25×25 pixels) displayed at the center of the screen. +To start lupe, run: + +[source,shell] +.... +% lupe +.... + +To exit lupe, press the `q` key. + +[TIP] +==== +Start lupe with the `-noshape` option to display the magnified area in a separate, movable window. +Without this option, the magnifier is locked to the center of the screen. +==== + +[[kmag]] +=== kmag + +The man:kmag[1] utility provides a screen magnifier that displays a zoomed view of the area under the mouse cursor in a dedicated window. +The magnifier window includes a menu with various options and settings for customization. + +To install kmag, run: + +[source,shell] +.... +# pkg install kmag +.... + +To launch kmag, execute: + +[source,shell] +.... +% kmag +.... + +[[xlupe]] +=== xlupe + +The package:x11/xlupe[] utility is a screen magnifier for the X Window System that updates the magnified view in real time. +To install it, run: + +[source,shell] +.... +# pkg install xlupe +.... + +To launch xlupe, execute: + +[source,shell] +.... +% xlupe +.... + +The utility does not include a manual page, but it starts in a graphical window with buttons that allow you to configure its options interactively. + +[[xmag]] +=== xmag + +The man:xmag[1] utility is a basic screen magnifier for the X Window System. +Unlike other magnifiers, it does not update the magnified area in real time. + +To install it, run: + +To install, execute: + +[source,shell] +.... +# pkg install xmag +.... + +To launch xmag, execute: + +[source,shell] +.... +% mag +.... + +[NOTE] +==== +xmag does not display a magnified area immediately upon launch. +Click anywhere on the screen with the left mouse button to select a region, and xmag will open a window showing a magnified view of that area. +The application window includes a few buttons offering limited functionality. +==== + +[[xzoom]] +=== xzoom + +The man:xzoom[1] utility is a screen magnifier for the X Window System that updates the magnified view in real time. +To install it, run: + +[source,shell] +.... +# pkg install xzoom +.... + +To launch xzoom, execute: + +[source,shell] +.... +% xzoom +.... + +[NOTE] +==== +Unlike other magnifiers, xzoom does not automatically follow the mouse cursor or magnify the area beneath it in its own window. +Interaction is keyboard-driven, refer to man:xzoom[1] for available commands and usage details. +==== + +[[lowvision-mouse]] +== Mouse + +[[mouse-apparance]] +=== Apparance + +Some desktop environments allow you to change the size, color, and other graphical properties of the mouse cursor. + +[[xfce-mouse]] +==== XFCE + +XFCE allows you to set the size and color of the mouse pointer via `_Mouse and Touchpad_` dialog. +To run the dialog start: + +[source,shell] +.... +% xfce4-mouse-settings +.... + +Then click on the `_Theme_` tab to select a size and a style. + +[NOTE] +==== +Some themes, included the _Default_, do not support cursor size customization. +==== + +Alternatively, you can achieve the same result via the `xfconf-query` command. +The following example set the current theme cursur to size 50: + +[source,shell] +.... +% xfconf-query -c xsettings -n -p /Gtk/CursorThemeSize -s 50 +.... + +[[find-mouse-cursor]] +=== Find Cursor + +Some desktop environments provide a visul feedback of the mouse pointer's current position. + +[[xfce-find-mouse-cursor]] +==== XFCE + +Xfce draws large red circles around the mouse pointer. +Type: + +[source,shell] +.... +% xfce4-find-cursor +.... + +The above command draws circles for a few seconds. + +**Keyboard Shortcut** + +XFCE allows to add a keyboard shortcut. +Circles are drawn for as long as the shortcut keys are pressed. +To use the shortcut before enable the feature then choose the key combination to bind to `xfce4-find-cursor`. + +Example to enable and bind `Ctrl` + `Super` + `k`: +[source,shell] +.... +xfconf-query -c accessibility -p /FindCursor -s true +xfconf-query -c xfce4-keyboard-shortcuts -n -t 'string' -p '/commands/custom/k' -s xfce4-find-cursor +.... + +**Keyboard Shortcut via Dialogs** + +Alternatively, you can achieve the same result via the XFCE configuration dialogs. +First step, open the XFCE `_Accessibility_` dialog: + +[source,shell] +.... +% xfce4-accessibility-settings +.... + +Click on `_Mouse_` tab and enable the `_Show location of pointer on keypress_` checkbox. + +Second step, open the XFCE `_Keyboard_` dialog: + +[source,shell] +.... +% xfce4-keyboard-settings +.... + +Click on `_Application Shortcuts_` tab. +Click on `_+ Add_` button, it opens the `_Shortcut Command_` dialog. +Write _xfce4-find-cursor_ in the form, then click on the `_OK_` button. +Choose a key combination to bind to `xfce4-find-cursor` in the new dialog. diff --git a/documentation/content/en/books/accessibility/parti.adoc b/documentation/content/en/books/accessibility/parti.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/parti.adoc @@ -0,0 +1,14 @@ +--- +title: Part I. General +prev: books/accessibility/preface +next: books/accessibility/help +showBookMenu: true +weight: 2 +params: + path: "/books/accessibility/parti/" +--- + +[[parti-general]] += General + +The General Part includes miscellaneous information, settings, and tools that do not belong to a specific category. diff --git a/documentation/content/en/books/accessibility/partii.adoc b/documentation/content/en/books/accessibility/partii.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/partii.adoc @@ -0,0 +1,25 @@ +--- +title: Part II. Vision +prev: books/accessibility/help +next: books/accessibility/virtual-terminal +showBookMenu: true +weight: 4 +params: + path: "/books/accessibility/partii/" +--- + +[[partii-vision]] += Vision + +Section for Assistive technologies for vision accessibility. + +The operating system provides two main interfaces for user interaction: Virtual Terminal and several Desktop Environments. + +Virtual Terminal, commonly referenced and documented as man:vt[4] is the system's built-in extref:{handbook}ports[virtual console]. +It is installed by default, provides a command-line interface, and starts automatically at boot. +Its features relevant to vision accessibility are detailed in the crossref:virtual-terminal[virtual-terminal,Virtual Terminal] chapter. + +Desktop environments provide graphical elements, such as windows, menus, buttons, and so on. +They can be installed using extref:{handbook}ports[ports and packages]; +refer to Chapters extref:{handbook}x11[X Window System], extref:{handbook}wayland[Wayland], and extref:{handbook}desktop[Desktop Environments] of the FreeBSD Handbook. +This section explains how to install, configure, and use color schemes, themes, and visual accessibility features designed to support users with low vision or blindness in graphical environments. diff --git a/documentation/content/en/books/accessibility/preface/_index.adoc b/documentation/content/en/books/accessibility/preface/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/preface/_index.adoc @@ -0,0 +1,92 @@ +--- +title: Preface +prev: books/accessibility +next: books/accessibility/parti +description: Preface on assistive technologies available on FreeBSD +tags: ["preface"] +showBookMenu: true +weight: 1 +params: + path: "/books/accessibility/preface/" +--- + +[preface] +[[a11y-preface]] += Preface +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/ + +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::[] + +[[intended-audience]] +== Intended Audience + +This handbook is intended for anyone interested in the assistive technologies available in the FreeBSD operating system. +Users and administrators can learn how to configure the system for accessibility. +Developers will find resources and guidance to help them create, improve, and test accessible software. + +[[organization-book]] +== Organization of this Book + +This book is organized into sections, chapters, and paragraphs, all of which can be read independently and out of order. +The first section, _crossref:parti[parti-general,Part I. General]_, provides guidance on how to seek help and includes various miscellaneous topics. +The second section, _crossref:partii[partii-vision,Part II. Vision]_, focuses on assistive technologies for visual accessibility; +It is intentionally free of images to maximize accessibility +All sections and chapters are self-contained and can be read in any order. + +Chapters: + +_crossref:help[help,Help]_:: +Explains where and how to seek support within the FreeBSD community. + +_crossref:virtual-terminal[virtual-terminal,Virtual Terminal]_:: +Highlights features of the system's virtual console for visual accessibility. + +_crossref:colors[colors,Colors]_:: +Describes how to customize color settings in graphical environments for better visibility. + +_crossref:lowvision[lowvision,Low Vision]_:: +Introduces tools and settings for users with low vision. + +_crossref:blindness[blindness,Blindness]_:: +Covers accessibility tools and configurations for blind users, including screen readers, text-based utilities, and relevant ports. + +_crossref:development[development,Development]_:: +Offers guidelines and resources for developers to enhance accessibility for users with visual impairments. + +[[commands]] +== Commands + +FreeBSD offers a powerful command line interface that enables users to execute a wide range of text commands to set up and use the operating system. +This Handbook, like all official FreeBSD documentation, follows these command prompt conventions: + +- A command preceded by `%` can be executed by any regular user. +- A command preceded by `#` must be executed by the `root` user (the system administrator). + diff --git a/documentation/content/en/books/accessibility/virtual-terminal/_index.adoc b/documentation/content/en/books/accessibility/virtual-terminal/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/accessibility/virtual-terminal/_index.adoc @@ -0,0 +1,344 @@ +--- +title: Chapter 2. Virtual Terminal +part: Part II. Vision +prev: books/accessibility/partii +next: books/accessibility/colors +description: Available features in the virtual console useful for accessibility +tags: ["Accessibility", "Terminal"] +showBookMenu: true +weight: 5 +params: + path: "/books/accessibility/virtual-terminal/" +--- + +[[virtual-terminal]] += Virtual Terminal +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 2 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/accessibility/virtual-terminal/ + +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::[] + +[[vt4-intro]] +== Introduction + +Virtual Terminal, commonly referenced and documented as man:vt[4] is the system's built-in extref:{handbook}ports[virtual console]. +It is installed by default, provides a command-line interface, and starts automatically at boot. +This chapter presents an overview and examples of key features and utilities relevant to visual accessibility. + +[[vt4-colors]] +== Colors + +The Virtual Terminal supports color configuration both via configuration files and interactively through a dedicated utility. + +[[vt4-colors-loader]] +=== Loader.conf + +Colors can be set and saved using the man:loader.conf[5] file. +To change a default color, add a line in the following format: +`kern.vt.color._colornum_.rgb="_colorspec_"`, where: + + - `_colornum_` is the numeric identifier of the color to be customized (see the table below). + - `_colorspec_` is a specification of the color, either as a comma-separated RGB triplet (red, green, and blue, each value from 0 to 255) or as an HTML-style hexadecimal value. + +.Default palette: Color, color number, default color in rgb, default color in html. +[options="header", cols="1,1,1,1"] +|=== +| Color | _colornum_ | default _colorspec_ RGB | default _colorspec_ html + +| Black +| 0 +| 0,0,0 +| #000000 + +| Dark red +| 1 +| 127,0,0 +| #7f0000 + +| Dark green +| 2 +| 0,127,0 +| #00ff00 + +| Dark yellow +| 3 +| 196,161,0 +| #c4a100 + +| Dark blue +| 4 +| 51,102,163 +| #3366a3 + +| Dark magenta +| 5 +| 127,0,127 +| #7f007f + +| Dark cyan +| 6 +| 0,127,127 +| #007f7f + +| Light gray +| 7 +| 191,191,191 +| #bfbfbf + +| Dark gray +| 8 +| 115,130,138 +| #73828a + +| Light red +| 9 +| 255,0,0 +| #ff0000 + +| Light green +| 10 +| 0,255, 0 +| #00ff00 + +| Light yellow +| 11 +| 255,255,0 +| #ffff00 + +| Light blue +| 12 +| 115,158,207 +| #739ecf + +| Light magenta +| 13 +| 255,0,255 +| #ff00ff + +| Light cyan +| 14 +| 0,255,255 +| #00ffff + +| White +| 15 +| 255,255,255 +| #ffffff + +|=== + +[[vt4-example-loader-conf-colors]] +.Set background in white, text in black, boot messages in red. +[example] +==== +[.filename]#/boot/loader.conf# + +[.programlisting] +.... +# Background black to white +kern.vt.color.0.rgb="255,255,255" + +# Text light gray to black +kern.vt.color.7.rgb="0,0,0" + +# Boot white to red +kern.vt.color.15.rgb="255,0,0" + +.... +==== + +[[vidcontrol]] +=== Vidcontrol + +The man:vidcontrol[1] utility allows you to configure colors interactively. +Use the `show` option to display the list of available colors: + +[source,shell] +.... +% vidcontrol show +.... + +To set the foreground color, use `vidcontrol _color_`. +For example, to set the text color to green: + +[source,shell] +.... +% vidcontrol green +.... + +To set both foreground and background colors, use `vidcontrol _foreground_ _background_`. +For example, to set blue text on a green background: + +[source,shell] +.... +% vidcontrol blue green +.... + +Configurations made with man:vidcontrol are not persistent across shutdown. +To make the settings permanent, add the following line to man:rc.conf[5]: +`allscreens_flags="-c _foreground_ _background_"`. + +[[vt4-vidcontrol-colors-rc]] +.Set blue foreground and green background. +[example] +==== +[.filename]#/etc/rc.conf# + +[.programlisting] +.... +allscreens_flags="-c blue green" + +.... +==== + +[NOTE] +==== +Setting allscreens_flags="-c _colors_" in [.filename]#/etc/rc.conf# takes effect after the system boots. +To change the colors during the boot process, edit [.filename]#/boot/loader.conf# as crossref:virtual-terminal[vt4-colors-loader,previously described]. +==== + +[[vt4-resolution]] +== Resolution + +The `kern.vt.fb.default_mode="x"` option in man:loader.conf[5] allows you to configure the display resolution. +Technically, it specifies the display mode of the Virtual Terminal, allowing you to control the size of elements displayed on the screen. + +[[vt4-example-resolution]] +.Sets the width to 800 and the height to 600. +[example] +==== +[.filename]#/boot/loader.conf# + +[.programlisting] +.... +kern.vt.fb.default_mode="800x600" + +.... +==== + +[[vt4-font]] +== Font + +Virtual Terminal allows you to configure the font in use, and the system supports installing and utilizing additional fonts. + +[[vt4-select-font]] +=== Select a Font + +The utilities man:vidfont[1] and man:vidcontrol[1] can load a font from [.filename]#/usr/share/vt/fonts/#. +To list the currently available fonts: + +[source,shell] +.... +% ls /usr/share/vt/fonts +.... + +Usually a file name has the format `-x`, where: + + - `` is the font name. + - `x` is the size. + +man:vidfont[1] provides an interactive menu in a Text User Interface to select a font. +Run the following command: + +[source,shell] +.... +% vidfont +.... + +Alternatively, man:vidcontrol[1] provides a CLI, `vidcontrol -f _font_`. +Example for `spleen-32x64.fnt`: + +[source,shell] +.... +% vidcontrol -f spleen-32x64.fnt +.... + +[TIP] +==== +Tip: You can omit the _.fnt_ extension when specifying the file name. +For example, to load `spleen-32x64.fnt`, use: + +[source,shell] +.... +% vidcontrol -f spleen-32x64 +.... +==== + +Settings configured with either utility are not preserved after a reboot. + +[[vt4-vidcontrol-font-rc]] +.Select the font to load at each startup. +[example] +==== +[.filename]#/etc/rc.conf# + +[.programlisting] +.... +allscreens_flags="-f spleen-32x64.fnt" + +.... +==== + +[[vt4-new-font]] +=== New Fonts + +The man:vtfontcvt[8] utility allows you to convert a font into the .fnt format for use in the Virtual Terminal. +The converted font must be copied to [.filename]#/usr/share/vt/fonts/# and selected as crossref:virtual-terminal[vt4-select-font,previously described]. + +[[vt4-bell]] +== Bell + +The terminal bell can be activated by: + +[source,shell] +.... +# sysctl kern.vt.enable_bell=1 +.... + +To make the configuration persistent after reboot, save it in either man:loader.conf[5] or man:sysctl.conf[5]. + +[[vt4-example-bell]] +.Active the bell at each startup. +[example] +==== +[.filename]#/boot/loader.conf# +or +[.filename]#/etc/sysctl.conf# + +[.programlisting] +.... +kern.vt.enable_bell=1 + +.... +====