Accessibility of Docs on Win32: Navigation, Names and PyDoc

Discussion in 'Python' started by Veli-Pekka Tätilä, Oct 6, 2005.

  1. 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:

    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

    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.


    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ä ()
    Accessibility, game music, synthesizers and programming:
    Veli-Pekka Tätilä, Oct 6, 2005
    1. Advertisements

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Replies:
    Jukka K. Korpela
    Jul 24, 2006
  2. Laurahn
    Steven Cheng[MSFT]
    Feb 6, 2007
  3. Dylan Parry
    Aug 9, 2007
  4. BartlebyScrivener

    pydoc vs. pydoc scriptpy

    BartlebyScrivener, Oct 20, 2007, in forum: Python
    Oct 22, 2007
  5. Replies:
  6. KYG
    Ian Collins
    Aug 18, 2008
  7. Stéphane Wirtel
    Stéphane Wirtel
    Apr 19, 2007
  8. Al
    Henry Law
    Oct 16, 2005