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 -- With kind regards Veli-Pekka Tätilä ([EMAIL PROTECTED]) Accessibility, game music, synthesizers and programming: http://www.student.oulu.fi/~vtatila/
-- http://mail.python.org/mailman/listinfo/python-list
