New Accessibility Handbook

[asiciliano]

Summary

This is the first review of the new Accessibility Handbook.

Preview: https://freebsd-accessibility-9d667f.gitlab.io/en/books/accessibility/index.html

The book aims to document assistive technologies for vision accessibility available in the system, covering both PORTS and BASE.

Index

Preface
    Intended Audience
    Organization of this Book
    Commands
Part I. General
Chapter 1. Help
    1.1. Mailing Lists
    1.2. Chat
    1.3. Ports and Packages
Part II. Vision
Chapter 2. Virtual Terminal
    2.1. Introduction
    2.2. Colors
    2.3. Resolution
    2.4. Font
    2.5. Bell
Chapter 3. Colors
    3.1. Introduction
    3.2. High Contrast Theme
    3.3. High Contrast Icons
    3.4. Color temperature
    3.5. Ports Collection
Chapter 4. Low Vision
    4.1. Introduction
    4.2. Desktop Size
    4.3. Font
    4.4. Magnify
    4.5. Mouse
Chapter 5. Blindness
    5.1. Introduction
    5.2. Screen Reader
    5.3. Ports Collection
    5.4. Editor
    5.5. Internet and WEB
    5.6. Liblouis
Chapter 6. Development
    6.1. Introduction
    6.2. Colors
    6.3. Command Line Interface
    6.4. Libraries
    6.5. Tools

To complete the fist version:

• Brightness, useful for photosensitive users, https://reviews.freebsd.org/D51285
• Examples related to KDE, https://reviews.freebsd.org/D51294
• Speech synthesizers, https://reviews.freebsd.org/D51286

Obviously, the work to improve this handbook does not end with Milestone 1 but will continue with future projects.

Off-topic to avoid repeated discussions. We have had a discussion in accessibility@, it will be important to add Section III on hearing accessibility and Section IV on interaction accessibility to the handbook in the future.

Sponsored by: The FreeBSD Foundation,

[pauamma_gundo.com]

documentation/content/en/books/accessibility/_index.adoc

60

I'd make "the FreeBSD accessibility mailing list" a link (either mailto: or https: to its subscription page), or maybe just give the list address.

documentation/content/en/books/accessibility/blindness/_index.adoc

63

That's slightly misleading. Per https://gnome.pages.gitlab.gnome.org/orca/help/preferences_braille.html, Orca (for instance) supports Braille if brltty is installed. The actual reason is that brltty doesn't (yet?) run on FreeBSD.

78

Audience check: should we expect readers of this to be familiar with the # or % convention for commands issued as root/non-root, or should the conventions text from the User Handbook be copied somewhere suitable in this one?

94–95

Audience check: would a first-time reader of this understand what "Super" refers to?

102

If I understand what you mean correctly.

294

Spurious ZWS

306

documentation/content/en/books/accessibility/book.adoc

59

Here too, I'd make "the FreeBSD accessibility mailing list" a link (either mailto: or https: to its subscription page), or maybe just give the list address.

documentation/content/en/books/accessibility/colors/_index.adoc

57–59

I'd make these 3 lines a bullet list. In addition, I'd clarify "ambient environment".

417

422

I'd specify whether increasing or decreasing priority.

documentation/content/en/books/accessibility/development/_index.adoc

60

61

174

documentation/content/en/books/accessibility/virtual-terminal/_index.adoc

93

For consistency with lowercase hex digits elsewhere in that table.

[asiciliano]

Thank you for the review, I'll update to fix.

documentation/content/en/books/accessibility/_index.adoc

60

OK, I'll add the link.

documentation/content/en/books/accessibility/blindness/_index.adoc

63

Yes, currently ORCA only communicates with a speech synthesizer on FreeBSD. Another project is planned to implement the Braille subsystem inside FreeBSD, probably by adapting BRLTTY.
I'll change from "They can communicate exclusively with speech synthesizers and do not support Braille displays." to "FreeBSD does not currently support Braille displays, so they rely exclusively on speech synthesizers."

78

I considered this issue myself. The solution was to add, in the description of "Section 2" in partii.adoc where this chapter is located, links to relevant sections of the main FreeBSD Handbook: Ports and Packages, Installing X11, Installing Wayland, and so on. Surely, once the Accessibility Handbook is published, links from the main Handbook to this one will also be added.

I will further add a Commands section in the Preface of this Handbook to explain % and #.

94–95

Ok, I'll add a [TIP] with a short description of the default 'Super" key and a link to https://en.wikipedia.org/wiki/Super_key_(keyboard_button)].

102

OK, I'll change.

294

OK, I'll fix.

306

OK, I' ll change.

documentation/content/en/books/accessibility/book.adoc

59

OK, I'll add the link.

documentation/content/en/books/accessibility/colors/_index.adoc

57–59

OK, I'll make a bullet list, and change from "adjusting screen colors based on the ambient environment," to "Adapting screen color temperature for optimal viewing in daylight and nighttime conditions."

417

Ok, I'll fix.

422

Ok, 'll add decreasing.

documentation/content/en/books/accessibility/development/_index.adoc

60

OK, I'll change.

61

OK, I'll change.

174

OK, I'll change.

documentation/content/en/books/accessibility/virtual-terminal/_index.adoc

93

OK, I'll change.

[asiciliano]

Thank you very much for the review. I’ve updated the diff to incorporate the suggestions and improvements.

[pauamma_gundo.com]

One minor nit I missed the first time through, but I think what's already written works as is. Do you plan to commit this in stages, or in a single commit once complete?

documentation/content/en/books/accessibility/parti.adoc

15

[asiciliano]

documentation/content/en/books/accessibility/parti.adoc

15

OK, I'll fix.

[asiciliano]

Thank you for the review, I updated the diff to fix.

[asiciliano]

This comment was removed by asiciliano.

[asiciliano]

In D50894#1169940, @pauamma_gundo.com wrote:

One minor nit I missed the first time through, but I think what's already written works as is. Do you plan to commit this in stages, or in a single commit once complete?

I would like to commit this review as a single commit.

The plan for the Accessibility Handbook is as follows:

Phase 1 – Document Existing Visual Accessibility Features

1. Commit this review in a single commit to publish the book.
2. Immediately after, I will submit and commit another review covering the missing sections: speech synthesizers, screen brightness, and KDE specific examples.

I am considering submitting the second review (2) even before the first one (1) is committed, or alternatively merging the missing sections directly into this review. This is to avoid blocking progress on the handbook or delaying the start of new projects.

Phase 2 – New Feature Development
Implement additional accessibility features for the "Accessibility Vision" project and document them in the handbook.

Phase 3 – Ongoing Maintenance and Future Improvements
I will continue maintaining and updating the handbook in the coming years.

[pauamma_gundo.com]

In D50894#1170037, @asiciliano wrote:

In D50894#1169940, @pauamma_gundo.com wrote:

One minor nit I missed the first time through, but I think what's already written works as is. Do you plan to commit this in stages, or in a single commit once complete?

I would like to commit this review as a single commit.

OK.

[grahamperrin]

In the preview, some of the navigation buttons don't work, for example:

• Next at https://freebsd-accessibility-9d667f.gitlab.io/en/books/accessibility/partii/index.html
• Prev at https://freebsd-accessibility-9d667f.gitlab.io/en/books/accessibility/development/index.html

[carlavilla]

For me you can go ahead.
It's a big document and I think it will be better if we put it in production and we improve it in latter commits.

[asiciliano]

In D50894#1177756, @grahamperrin wrote:

In the preview, some of the navigation buttons don't work, for example:

• Next at https://freebsd-accessibility-9d667f.gitlab.io/en/books/accessibility/partii/index.html
• Prev at https://freebsd-accessibility-9d667f.gitlab.io/en/books/accessibility/development/index.html

Thanks for the report.
I checked the "Prev" and "Next" links on my laptop using the local server via make run, they work correctly.
The broken links in the preview are definitely caused by some mistake I made when running make html (from https://docs.freebsd.org/en/books/fdp-primer/doc-build/) , since I noticed the same issue in other generated handbooks on my laptop.
I’ll ask the doc team for guidance and continue investigating.