diff options
Diffstat (limited to 'documentation/content/en/books')
13 files changed, 2126 insertions, 8 deletions
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 +.... +==== + +[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 index 0000000000..a93a93f7c7 --- /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 index 0000000000..bd47be8307 --- /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 index 0000000000..4b71057c0e --- /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/<Ctrl><Super>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 index 0000000000..f8172c17f5 --- /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 index 0000000000..2001639e9c --- /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 index 0000000000..52f00faeaf --- /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 index 0000000000..277669171b --- /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="<width>x<height>"` 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 `<name>-<width>x<height>`, where: + + - `<name>` is the font name. + - `<width>x<height>` 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 + +.... +==== diff --git a/documentation/content/en/books/developers-handbook/sockets/_index.adoc b/documentation/content/en/books/developers-handbook/sockets/_index.adoc index a85deb7394..49249aa3c7 100644 --- a/documentation/content/en/books/developers-handbook/sockets/_index.adoc +++ b/documentation/content/en/books/developers-handbook/sockets/_index.adoc @@ -383,7 +383,7 @@ Now, let us try to fill it out. Let us assume we are trying to write a client for the _daytime_ protocol, which simply states that its server will write a text string representing the current date and time to port 13. We want to use TCP/IP, so we need to specify `AF_INET` in the address family field. `AF_INET` is defined as `2`. -Let us use the IP address of `192.43.244.18`, which is the time server of US federal government (`time.nist.gov`). +Let us use the IP address of `132.163.96.1`, which is the time server of US federal government (`time.nist.gov`). .Specific example of sockaddr_in image::sainfill.png[] @@ -402,7 +402,7 @@ struct in_addr { In addition, `in_addr_t` is a 32-bit integer. -The `192.43.244.18` is just a convenient notation of expressing a 32-bit integer by listing all of its 8-bit bytes, starting with the _most significant_ one. +The `132.163.96.1` is just a convenient notation of expressing a 32-bit integer by listing all of its 8-bit bytes, starting with the _most significant_ one. So far, we have viewed `sockaddr` as an abstraction. Our computer does not store `short` integers as a single 16-bit entity, but as a sequence of 2 bytes. @@ -414,7 +414,7 @@ Suppose we coded something like this: .... sa.sin_family = AF_INET; sa.sin_port = 13; -sa.sin_addr.s_addr = (((((192 << 8) | 43) << 8) | 244) << 8) | 18; +sa.sin_addr.s_addr = (((((132 << 8) | 163) << 8) | 96) << 8) | 1; .... What would the result look like? @@ -485,7 +485,7 @@ One would be to _reverse_ the values in our code: .... sa.sin_family = AF_INET; sa.sin_port = 13 << 8; -sa.sin_addr.s_addr = (((((18 << 8) | 244) << 8) | 43) << 8) | 192; +sa.sin_addr.s_addr = (((((1 << 8) | 96) << 8) | 163) << 8) | 132; .... This will _trick_ our compiler into storing the data in the _network byte order_. @@ -546,7 +546,7 @@ Or it may outright _refuse_ any request for specific code. [[sockets-first-client]] ===== Our First Client -We now know enough to write a very simple client, one that will get current time from `192.43.244.18` and print it to [.filename]#stdout#. +We now know enough to write a very simple client, one that will get current time from `132.163.96.1` and print it to [.filename]#stdout#. [.programlisting] .... @@ -576,7 +576,7 @@ int main() { sa.sin_family = AF_INET; sa.sin_port = htons(13); - sa.sin_addr.s_addr = htonl((((((192 << 8) | 43) << 8) | 244) << 8) | 18); + sa.sin_addr.s_addr = htonl((((((132 << 8) | 163) << 8) | 96) << 8) | 1); if (connect(s, (struct sockaddr *)&sa, sizeof sa) < 0) { perror("connect"); close(s); @@ -799,7 +799,7 @@ if (INADDR_ANY) .... Its value is `0`. -Since we have just used `bzero` on the entire structure, it would be redundant to set it to `0` again. +Since we have just used `memset` to set zeroes on the entire structure, it would be redundant to set it to `0` again. But if we port our code to some other system where INADDR_ANY is perhaps not a zero, we need to assign it to `sa.sin_addr.s_addr`. Most modern C compilers are clever enough to notice that INADDR_ANY is a constant. As long as it is a zero, they will optimize the entire conditional statement out of the code. @@ -1020,7 +1020,7 @@ int main(int argc, char *argv[]) { We now can type a domain name (or an IP address, it works both ways) on the command line, and the program will try to connect to its _daytime_ server. Otherwise, it will still default to `time.nist.gov`. -However, even in this case we will use `gethostbyname` rather than hard coding `192.43.244.18`. +However, even in this case we will use `gethostbyname` rather than hard coding `132.163.96.1`. That way, even if its IP address changes in the future, we will still find it. Since it takes virtually no time to get the time from your local server, you could run daytime twice in a row: diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc index 35091a88c3..622021e234 100644 --- a/documentation/content/en/books/porters-handbook/uses/_index.adoc +++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc @@ -2761,6 +2761,13 @@ BROKEN_SSL_REASON_libressl= needs features only available in OpenSSL ==== +[[uses-sudo]] +== `sudo` + +Possible arguments: (none) + +Adds a run time dependecy on package:security/sudo[]. + [[uses-tar]] == `tar` |