On Accessibility of Plain Text Files

1.0 Writing for screen readers and conventional readers                  line 18
1.1 Linearize                                                            line 28
1.2 Visually similar characters                                          line 41
1.3 Indentation                                                          line 50
2.0 Graphical and tabular information                                    line 63
2.1 Graphs and trees                                                     line 69
2.2 Tables                                                               line 80
3.0 Thanks                                                               line 95

Terminal applications and plain text files are potentially quite accessible,
despite the inherent lack of metadata for screen readers and navigational aids.
On cause of the lack of metadata, which also is plain text's greatest strength,
it is quite easy to make a mess of it all. These are my notes on the matter.


    1.0 Writing for screen readers and conventional readers

Text should (most of the time?) be easily accessible to as many as practically
possible. This means trying to write in a straightforward manner for the
intended audience as well as avoiding 'leet spelling and ASCII graphics. ASCII
graphics will just be an unskippable wall of "pipe-underscore-pipe" and so on to
the screen reader. It also means tabular data should not be presented in some
huge, drawn table.


    1.1 Linearize

I asked Devin Prater some questions on how to check for the quality of terminal
output for screen readers, one of the answers were "Really, reading it linearly
is the best way. Screen readers read from left to right, top to bottom. Blind
people can read the output line by line, word by word, character by character,
but that's about it. [...]"

In other words, I think if the output makes sense if you read it out loud to
somebody who can not see the terminal window, you are probably on the right
track.


    1.2 Visually similar characters

Stick strictly to the semantic meaning of the character. Mixing alphabets may
look cute, but the screen reader really does not care about the levity of
exchanging Latin capital letter X with Cyrillic capital letter HA. This problem
becomes even worse when mixing Kanji into Western languages for decorative
purposes.


    1.3 Indentation

Again, I quote the information mr Prater gave me "[...] often, blind people
don't have the reporting of indentation turned on. Some screen readers, like
NVDA on Windows or Orca on Linux, can report indentation, while others, like
VoiceOver on Mac (because of course Swift doesn't need it so no other
programming languages need it right? /s) and ChromeVox, don't report it. So it
doesn't hurt, but I probably won't get the semantic info."

In other words, indentation is OK to help somebody who navigates the file
visually, but it should not be necessary to make sense of the file.


    2.0 Graphical and tabular information

Diagrams, directed graphs, trees, etc, these are all commonly shown in a way
which depend on a graphical presentation, even in terminals.


    2.1 Graphs and trees

This is the advice I got from Devin Prater on directed graphs verbatim: "I'd say
showing what connects to what, or just narratively describing the graph, would
be the best option. Describing it would probably take less manual typing, and
you may be able to do it programmatically."

Again, we return to "Can you read it out loud?" and "Don't make it all overly
complicated." The latter of course holds any time anyway.


    2.2 Tables

For tables, I use the advice from HTML tables:

Present the legend textually. Remember relevant units, hearing "square
kilometres" repeated once for every number makes it easy to lose track of what
is important or relevant.

Stick to few columns. If hearing a large table read out loud, myself I would
prefer multiple tables and just two columns each over some huge table where
navigating linearly gets harder and harder for each column added. Also, few
columns is a lot more robust for those using a conventional terminal, especially
if they have to use a view with few columns of characters.


    3.0 Thanks

Thank you to Devin Prater (@devinprater@devin.masto.host) for answering my
questions regarding sanity checking, graphs and indentation.

Earlier edited 20220127T204733Z, 20220730T175231Z.

Simplified formatting.

Steinar Knutsen, 20230929T195527Z, 26A05487