V
Veli-Pekka Tätilä
Hi,
My first post here. I've found some serious accessibility flaws in the
Python 2.4 docs and wish they could be rectified over time. I'm very new to
Python and initially contacted docs at python org, However, I haven't gotten
a reply for a week or so, and figured out I could post here for a larger
audience, then.
Original message follows:
Hello,
I'm a visually impaired programmer concerned about the accessibility of
Python documentation. I'm still new to Python and mainly using Perl and
Java, largely because of the relatively inaccessible documentation in
Python.
I'd like to report three key issues that I've discovered related to Python
documentation as follows:
1. Navigation in Functions
A single page tends to contain a large number of functions with no way for
screen reader users to find the next function or get a quick overview of
what's on offer. Sighted folk can easily skim through the page but people
relying on screen reader programs or heavy magnification can concentrate
only on a very small area of the screen. This is often referred to as the
straw analogy because it resembles looking at the screen contents through a
thin straw.
Many of the more advanced Windows screen readers such as Freedom
Scientific's Jaws (the most popular) or Dolphin Supernova (the one I'm
using) can list and directly navigate to links, frames and headings on the
page provided that you are using Internet Explorer or HTML help. However,
these features are only marginally helpful in Python documentation.
I've looked at the source and it appears function names are bold tt elements
of class function. This representation has several drawbacks from an
accessibility point of view:
Firstly, there are no means for moving in terms of TT elements directly.
Secondly, TT elements cannot be listed or randomly navigated to from the
keyboard. And finally even the semantics are lost as the readre doesn't
announce the class function. In stead you are told meaningless details such
as that the function name is in Courier New 12 point and the parentheses
following the name are Times New Roman 13 point. Confronted with this info
alone, it is not at all clear that this formatting has special significance.
Some basic or very new screen readers like MIcrosoft Narrator, Gnome's
Gnopernicus or Apple's VoiceOver do even worse. You might not get the
formatting information at all, and many readres don't offer as wide and
extensive a variety of navigation functions as JAws or SUpernova do. One
quick-n-dirty solution is to find the function names in the HTML source but
it is very difficult to read because of all the numeric identifiers and HTml
tags themselves.
One easy fix would be to turn the function names preceeding their
documentation into headings. This would give the right semantics and allow
direct navigation for the more advanced readers. However, listing links, or
finding a link based on some text, are screen reader or Web browser specific
actions and not universally available.
Another way used in say JavaDoc is to include a separate navigation section
having function prototypes and the first sentence of their description at
the top of the file. While the link based method is generally effective,
some screen readres have difficulty in quickly returning to the top or
moving the focus to links close to something at the bottom of the page. In
addition to issues encountered with headings, many browsers only offer
sequential navigation from one link to the next using the tab key. SO if you
have dozens of functions, you need to press tab or shit+tab loads, or else
use some screen reader specific action to rapidly move to a particular link.
It should also be noted that one should use the whole prototype as a link
and not just the name as in JavaDoc. The reason is that if functions differ
by their signature alone, it is tedious to figure out which function is in
question based on the link name. HTMl guidelines recommend that links are
independent of their surroundings (context-free?).
To universally get rid of the lack of link listing or quick navigation
facilities, an additional HTML list box could be added. The items should be
in alphabetical order and there should be a separate default button for
actually jumping to the selected list item. Auto-jumps are bad because
traversing and reading the list item names from the keyboard can cause focus
changes. So you may be unexpectedly taken away from the list box and might
not have enough time to read the whole name or ponder whether it is the one
you want. If using list separators, they shouldn't be made of punctuation
characters alone because many screen reader users, me included, have
punctuation set to none and thus nothing is spoken. The navigation list
ought to have a clearly visible and unambiguous text label saying that it is
a navigation list. Do avoid the term menu because to Windows screen reader
users, list boxes are never prompted as being menus, unlike on the Mac.
Even list boxes do have their weaknesses. Some browsers, namely Internet
Explorer, can only navigate based on the first letter typed. Thus you cannot
move to a function named foo directly but have to press the f key several
times to go through all items beginning with f. Further more, it is
difficult to include function signatures in the list box without sorting the
list by return type which is mostly undesirable.
As a rule of thumb including both a navigation list and a list of links
should solve the accessibility problem quite nicely. However, making a
separate article for each function under a heading would be of benefit in
CHM files. This would allow you to use the screen-reader independent
navigation features of the tree control and directly arrive at the desired
function using the TOC. Maybe this tac could be used in HTML, too, where it
would help with some reader specific navigation issues related to anchors
pointing to the same page. YOu could also navigate at the file system level
which is something I do a lot in browsing Java and Perl documentation.
2. Function names
While I do realize many of the PYthon names are well established, in
hindsight a great many are not particularly speech friendly. Programming
languages tend to use case changes or underscores to indicate word boundries
and boost readability. Nearly all Windows readers take this into account and
are able to correctly pronounce the individual words in functions such as
getHostName (or get_host_name).
In Python, on the other hand, names that have no explicit word delimiters
are annoyingly common judjing by the built-ins. A name such as getattr is
taken as a single word which makes the pronounciation incorrect and the
meaning unclear without using a spell command or cursoring letter by letter.
But because the names have a lot of inertia, I reckon there's nothing you
can do. Of course one can use an exception dictionary to correct the
pronounciation but this is an approach that calls for constant tweaking.
3. Pydoc
The tools that have a GUI are currently highly inaccessible in Windows. In
addition to idle this includes pydoc. I'm not sure what GUI library is being
used but have found several serious issues. The best working part are the
menus which are usable. However, some menu separators are made of
punctuation and are selectable. In Win32 menu separators should never be.
Another minor thing is that the scroll bars don't have context menus unlike
in say Notepad. While most sighted folks are just mildly amused should they
discover that there's a context menu, it can really come in handy at times.
If one has very little sight or difficulties using the mouse it may be very
time consuming to find and hit the small scroll thumb and move it at the
exact bottom or top. Though there's a hotkey, another way is selecting the
same thing in the scroll bar's context menu.
The real serius issue with the Python GUis is that they don't support the
keybord and are not screen reader accessible, at least in Windows. When
using the dialogs, the only thing Dolphin Supernova recognizes is the title
bar. And as many blind people don't even have the mouse, adding support for
tabbing around and using the arrows would be essential. One way to think of
this is attempting to use a modern GUI without the mouse or the monitor.
As far as I know, the only accessible GUI framework on Linux is currently
GTK2, though QT
should have accessibility in the future. In Windows, things based on the
Win32 API supporting Active Accessibility should be usable (not all are, of
course including Visual Studio 2005 betas). TK appears to be very
inaccessible as are ports of GTK and the FireFOx GUI (currently). Java's
Swing is
theoretically accessible but only if you have a screen reader and
AccessBridge beta and separately install the AccessBridge component. And
after all this, the UI doesn't respect the colors I've chosen and feels
highly non-native.
Sadly, it seems the only way to get a truely accessible GUI would be to
design things on a per platform basis using the GUI framework that is
accessible Win32, GTK, Cocoa (Classic and X ain't accessible).
I think that's about all I wanted to report this time. I hope all three
issues can be taken care of in the long run. Additionally, it would be great
to get a version of the Python 2.4 docs that enables easy navigation using a
screen reader.
End of quote.
Addition:
System:
HP NX8220 laptop
Win XP Pro SP2 English with latest fixes
Dolphin Supernova 6.03 with latest map files
Python 2.4
My first post here. I've found some serious accessibility flaws in the
Python 2.4 docs and wish they could be rectified over time. I'm very new to
Python and initially contacted docs at python org, However, I haven't gotten
a reply for a week or so, and figured out I could post here for a larger
audience, then.
Original message follows:
Hello,
I'm a visually impaired programmer concerned about the accessibility of
Python documentation. I'm still new to Python and mainly using Perl and
Java, largely because of the relatively inaccessible documentation in
Python.
I'd like to report three key issues that I've discovered related to Python
documentation as follows:
1. Navigation in Functions
A single page tends to contain a large number of functions with no way for
screen reader users to find the next function or get a quick overview of
what's on offer. Sighted folk can easily skim through the page but people
relying on screen reader programs or heavy magnification can concentrate
only on a very small area of the screen. This is often referred to as the
straw analogy because it resembles looking at the screen contents through a
thin straw.
Many of the more advanced Windows screen readers such as Freedom
Scientific's Jaws (the most popular) or Dolphin Supernova (the one I'm
using) can list and directly navigate to links, frames and headings on the
page provided that you are using Internet Explorer or HTML help. However,
these features are only marginally helpful in Python documentation.
I've looked at the source and it appears function names are bold tt elements
of class function. This representation has several drawbacks from an
accessibility point of view:
Firstly, there are no means for moving in terms of TT elements directly.
Secondly, TT elements cannot be listed or randomly navigated to from the
keyboard. And finally even the semantics are lost as the readre doesn't
announce the class function. In stead you are told meaningless details such
as that the function name is in Courier New 12 point and the parentheses
following the name are Times New Roman 13 point. Confronted with this info
alone, it is not at all clear that this formatting has special significance.
Some basic or very new screen readers like MIcrosoft Narrator, Gnome's
Gnopernicus or Apple's VoiceOver do even worse. You might not get the
formatting information at all, and many readres don't offer as wide and
extensive a variety of navigation functions as JAws or SUpernova do. One
quick-n-dirty solution is to find the function names in the HTML source but
it is very difficult to read because of all the numeric identifiers and HTml
tags themselves.
One easy fix would be to turn the function names preceeding their
documentation into headings. This would give the right semantics and allow
direct navigation for the more advanced readers. However, listing links, or
finding a link based on some text, are screen reader or Web browser specific
actions and not universally available.
Another way used in say JavaDoc is to include a separate navigation section
having function prototypes and the first sentence of their description at
the top of the file. While the link based method is generally effective,
some screen readres have difficulty in quickly returning to the top or
moving the focus to links close to something at the bottom of the page. In
addition to issues encountered with headings, many browsers only offer
sequential navigation from one link to the next using the tab key. SO if you
have dozens of functions, you need to press tab or shit+tab loads, or else
use some screen reader specific action to rapidly move to a particular link.
It should also be noted that one should use the whole prototype as a link
and not just the name as in JavaDoc. The reason is that if functions differ
by their signature alone, it is tedious to figure out which function is in
question based on the link name. HTMl guidelines recommend that links are
independent of their surroundings (context-free?).
To universally get rid of the lack of link listing or quick navigation
facilities, an additional HTML list box could be added. The items should be
in alphabetical order and there should be a separate default button for
actually jumping to the selected list item. Auto-jumps are bad because
traversing and reading the list item names from the keyboard can cause focus
changes. So you may be unexpectedly taken away from the list box and might
not have enough time to read the whole name or ponder whether it is the one
you want. If using list separators, they shouldn't be made of punctuation
characters alone because many screen reader users, me included, have
punctuation set to none and thus nothing is spoken. The navigation list
ought to have a clearly visible and unambiguous text label saying that it is
a navigation list. Do avoid the term menu because to Windows screen reader
users, list boxes are never prompted as being menus, unlike on the Mac.
Even list boxes do have their weaknesses. Some browsers, namely Internet
Explorer, can only navigate based on the first letter typed. Thus you cannot
move to a function named foo directly but have to press the f key several
times to go through all items beginning with f. Further more, it is
difficult to include function signatures in the list box without sorting the
list by return type which is mostly undesirable.
As a rule of thumb including both a navigation list and a list of links
should solve the accessibility problem quite nicely. However, making a
separate article for each function under a heading would be of benefit in
CHM files. This would allow you to use the screen-reader independent
navigation features of the tree control and directly arrive at the desired
function using the TOC. Maybe this tac could be used in HTML, too, where it
would help with some reader specific navigation issues related to anchors
pointing to the same page. YOu could also navigate at the file system level
which is something I do a lot in browsing Java and Perl documentation.
2. Function names
While I do realize many of the PYthon names are well established, in
hindsight a great many are not particularly speech friendly. Programming
languages tend to use case changes or underscores to indicate word boundries
and boost readability. Nearly all Windows readers take this into account and
are able to correctly pronounce the individual words in functions such as
getHostName (or get_host_name).
In Python, on the other hand, names that have no explicit word delimiters
are annoyingly common judjing by the built-ins. A name such as getattr is
taken as a single word which makes the pronounciation incorrect and the
meaning unclear without using a spell command or cursoring letter by letter.
But because the names have a lot of inertia, I reckon there's nothing you
can do. Of course one can use an exception dictionary to correct the
pronounciation but this is an approach that calls for constant tweaking.
3. Pydoc
The tools that have a GUI are currently highly inaccessible in Windows. In
addition to idle this includes pydoc. I'm not sure what GUI library is being
used but have found several serious issues. The best working part are the
menus which are usable. However, some menu separators are made of
punctuation and are selectable. In Win32 menu separators should never be.
Another minor thing is that the scroll bars don't have context menus unlike
in say Notepad. While most sighted folks are just mildly amused should they
discover that there's a context menu, it can really come in handy at times.
If one has very little sight or difficulties using the mouse it may be very
time consuming to find and hit the small scroll thumb and move it at the
exact bottom or top. Though there's a hotkey, another way is selecting the
same thing in the scroll bar's context menu.
The real serius issue with the Python GUis is that they don't support the
keybord and are not screen reader accessible, at least in Windows. When
using the dialogs, the only thing Dolphin Supernova recognizes is the title
bar. And as many blind people don't even have the mouse, adding support for
tabbing around and using the arrows would be essential. One way to think of
this is attempting to use a modern GUI without the mouse or the monitor.
As far as I know, the only accessible GUI framework on Linux is currently
GTK2, though QT
should have accessibility in the future. In Windows, things based on the
Win32 API supporting Active Accessibility should be usable (not all are, of
course including Visual Studio 2005 betas). TK appears to be very
inaccessible as are ports of GTK and the FireFOx GUI (currently). Java's
Swing is
theoretically accessible but only if you have a screen reader and
AccessBridge beta and separately install the AccessBridge component. And
after all this, the UI doesn't respect the colors I've chosen and feels
highly non-native.
Sadly, it seems the only way to get a truely accessible GUI would be to
design things on a per platform basis using the GUI framework that is
accessible Win32, GTK, Cocoa (Classic and X ain't accessible).
I think that's about all I wanted to report this time. I hope all three
issues can be taken care of in the long run. Additionally, it would be great
to get a version of the Python 2.4 docs that enables easy navigation using a
screen reader.
End of quote.
Addition:
System:
HP NX8220 laptop
Win XP Pro SP2 English with latest fixes
Dolphin Supernova 6.03 with latest map files
Python 2.4