diff --git a/documentation/content/en/books/accessibility/blindness/_index.adoc b/documentation/content/en/books/accessibility/blindness/_index.adoc index 1ff0beeb44..98b3552acc 100644 --- a/documentation/content/en/books/accessibility/blindness/_index.adoc +++ b/documentation/content/en/books/accessibility/blindness/_index.adoc @@ -1,321 +1,467 @@ --- 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 (extref:{handbook}desktop/#kde-environment[KDE Plasma], extref:{handbook}desktop/#xfce-environment[XFCE], extref:{handbook}desktop/#gnome-environment[GNOME]) provide a keyboard shortcut to launch Orca: `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]. +[[speech-synthesizer]] +== Speech Synthesizer + +The purpose of the speech synthesizer is to provide audio output for screen readers by converting on-screen text to speech. +This section explains how to install speech synthesizers, perform a basic functionality test, and locate their documentation for further configuration. + +[NOTE] +==== +Information about the FreeBSD audio subsystem can be found in extref:{handbook}multimedia[Multimedia] and in the man:sound[4] manual page. +==== + +[[espeak-ng]] +=== eSpeak NG + +The package:audio/espeak-ng[] package provides man:espeak-ng[1], a multilingual speech synthesizer. + +To install, run: + +[source,shell] +.... +# pkg install espeak-ng +.... + +To test, execute the following command: + +[source,shell] +.... +% espeak-ng "Hello World, FreeBSD!" +.... + +eSpeak NG is a versatile and feature-rich utility. +For more information, consult its manual page, man:espeak-ng[1], and the https://github.com/espeak-ng/espeak-ng/blob/master/docs/index.md[official online documentation]. + +[[flite]] +=== Flite + +package:audio/flite[] is a speech synthesizer that is part of the http://festvox.org[FestVox] project. +It is designed as a small and fast alternative to crossref:blindness[festival, Festival], built using the FestVox suite. +To install, run: + +[source,shell] +.... +# pkg install flite +.... + +To test, execute the following commands: + +[source,shell] +.... +% flite "Hello world, BSD!" +% flite_time 10:30 +The time is now, exactly half past ten, in the morning. +.... + +The project does not provide a manual page. +Documentation is available in [.filename]#/usr/local/share/doc/flite/README.md# and http://www.festvox.org/flite/doc/index.html[online]. + +[[festival]] +=== Festival + +The package:audio/festival[] package provides man:festival[1], a multilingual speech synthesizer. +To install, run: + +[source,shell] +.... +# pkg install festival +.... + +Festival needs at least one festvox-_voice_ package to generate a synthetic voice. +Run the following command to list available voice packages: + +[source,shell] +.... +% pkg search festvox +.... + +Then install a voice package. +For example, to install the American English male voice festvox-kal16-1.4.0, run: + +[source,shell] +.... +# pkg install festvox-kal16 +.... + +To test, execute: + +[source,shell] +.... +% echo "Hello world, BSD!" | festival --tts +.... + +[TIP] +==== +In the case of the error `Can't access NAS server`, example: + +[source,shell] +.... +% echo "Hello world, BSD!" | festival --tts +Can't access NAS server % +.... + +Add the following line to [.filename]#/usr/local/share/festival/lib/siteinit.scm#: + +[.programlisting] +.... +(Parameter.set 'Audio_Method 'freebsd16audio) +.... +==== + +For more information about Festival, consult its manual page, man:festival[1], and the http://www.festvox.org/docs/manual-2.4.0/festival_toc.html[official online documentation]. + +[[speech-dispatcher]] +=== Speech Dispatcher + +The Speech Dispatcher project provides a high-level device independent layer for access to speech synthesis. +To install package:accessibility/speech-dispatcher[], run: + +[source,shell] +.... +# pkg install speech-dispatcher +.... + +To test, execute: + +[source,shell] +.... +% spd-say "Hello world, FreeBSD!" +.... + +Speech Dispatcher provides two manual pages, man:spd-say[1] and man:speech-dispatcher[1], as well as https://freebsoft.org/speechd[online documentation]. + +[TIP] +==== +The package:audio/festival-freebsoft-utils[] package provides additional features for crossref:blindness[festival,Festival] to interact with Speech Dispatcher. +Refer to the https://freebsoft.org/festival-freebsoft-utils[online documentation] to know more. +==== + [[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-webapps]] +=== Web Apps + +Some web applications can use APIs to send output to audio devices. +Refer to crossref:blindness[speech-synthesizer,Speech Synthesizer] to install a utility and the corresponding library. + +The extref:{handbook}desktop/#firefox[Firefox] browser can report the error message: `You can’t use speech synthesis because the Speech Dispatcher library is missing` or https://support.mozilla.org/en-US/kb/speechd-setup[other errors]. +To solve, install crossref:blindness[speech-dispatcher,Speech Dispatcher]. + [[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.