Joel's essay
We had no idea what to expect initially when writing the perks. None of us had worked in a plugin based system before, nor had we used python, nor had we worked with LSR or GNOME accessibility or even GNOME. One of our teammates had not even used Linux before. So naturally, what we are about to say about our experience with LSR should be taken with those facts in mind.
There were several large problems that we faced. The first was learning and understanding the framework. The second, and perhaps most significant, was having to deal with underlying bugginess. Most of this bugginess was in GNOME or the GNOME accessibility framework, but there were a few bugs in LSR itself. Peter made sure to fix those for us as soon as we told him.
Learning the framework was somewhat difficult because of the lack of good overall high-level documentation. There was a tutorial for making a Gaim perk and we found this very useful, but it was hard to branch out from there. We had to read the LSR epydoc to figure things out, which was not the optimal solution. That said, LSR in general, for an open source project, has very good documentation. So many projects have next to none, not even low-level documentation. And once we had a better feel for how the framework worked, development proceeded at a hastened pace. The framework is overall fairly simple. All of the necessary information for reading the screen is provided to the callback functions in the perk and any additional information can easily be found out through API methods. One thing that I would like to complain about is the way in which information about a widget had to be retrieved. You have to walk a hierarchy using numeric indices. There's no pointer based method, at least not one that was apparent to me. This was a bit tedious, but I realize there's no better way to go directly to a component, especially given the way things are often named in GNOME.
And speaking of GNOME, the biggest enemy to this project was GNOME itself. As I mentioned above, LSR bugs were few and quickly fixed. Not so with GNOME and the accessibility layer. The GNOME calculator had one showstopper bug that was strange and extremely frustrating. When there is an error in the equation entered, the status bar displays an error message. Ideally, some sort of event should be fired indicating that text changed in the status bar. Indeed, such an event was fired, but only some of the time. Other times, the calculator would simply send no events, and without events, LSR and consequently our perk could do nothing to read the error message. A blind user would have no way of knowing that anything was wrong, except perhaps by silence. Gedit had several bugs, one of which caused it to crash when LSR tried to get spell-checking information for red-underlined words in the document. With neither of these bugs were there workarounds. There were also bad design decisions. There is no button press event. Thus, the only way to know if a button was pressed in calculator, was to see if anything changed in the equation box. This was not the optimal solution, by far. After a lot of thinking and playing around, I managed to hack together a sort of state machine that kept track of changes in the equation box and read the proper thing when input was entered. I would have rather had access to button press events. As you might imagine, we spent a lot of time discovering the existence of these bugs and then trying to work around them. We would have been able to get a lot more done had they not been there.
Cristóbal's follow-up
Like Joel, I had experience working in Linux before starting this project, but not on GNOME. Starting out with so many unknowns, In retrospect I should have experimented more, generating perks and throwing in calls to see what happens. Instead I spent too much time reading and trying to get an abstract grasp of LSR and Perks in particular. Having spent the time upfront and then realizing that I was ill-equipped to quickly write perks was frustrating.
Another very frustrating aspect of the work for me was the fact that my intuition about interfaces and behavior was useless in approaching gedit, for example. Peter was very helpful in responding to questions and suggesting when our thinking didn't match what a visually impaired user would expect. We were highly limited by the existing GNOME user interface. Worse, once it was clear what a visually impaired user would expect, several times it was clear that we would have to go with a next-best option. The example that comes to mind is the statusbar in gedit, which comes up with "No misspelled words" if you try to pull up the check spelling dialog and there aren't any misspelled words. Firstly, the statusbar doesn't jump out for sighted users, but beyond that, watching for that text in our perk was impractical. We settled on no action being the indicator that there were no misspelled words.
I would like to echo Joel's frustrations with the GNOME accessibility layer. The strangest thing for me was realizing that there is no event generated for button presses. With gcalctool, for example, it would have been fantastic to listen for a button press event and act based on that, but it gets worse. Even if there were an event generated by the button press, there's no guarantee that when LSR got it the text input field would have been updated already, eg. LSR receives the event checks the text field and sees no change, and later the field is actually updated. Basically for buttons that change something in the same window and what you're interested in saying when the button is pressed is not the text of the button itself, you have to use the same logic you would have without the button press event. This feels very broken. There should be a way to know, when a button is pressed, what change it caused or at least where it caused it.
I think we've both expressed a lot of frustration here because we'd like to see improvements, not because of any bad feelings about LSR or our project. In fact, we learned a lot about GNOME, LSR, assistive technologies, etc. etc. during this project and would like to continue to contribute. I would encourage anyone who wants to contribute a perk to dive in and try to make a working perk that does one simple action and build on that. We started with goals that were big enough that it took us awhile to realize we needed to adjust our thinking and focus on a few perks. Had we spent a week upfront experimenting with making perks, we likely would not have set unreasonable goals for ourselves.
Andy Shi's follow-up
Well, at this point, you might have realized that I am the one who "had not even used Linux before". Indeed, being a novice to the Linux world is quite a challenge for me, not to mention programming under Linux. The complexity level of this project and the frustrating learning curve have driven me to the level of "insanity". In fact, for quite a few times, I have thought about bailing out, but now I am glad that I have not done so simply because of the enjoyment that we got out of this incredible journey and the difference that we made in the blind people's lives. We are actually changing lives here. Well, sort of...
The journey started with the installation of dual boot (windows and fedora core 6) on my laptop computer. For the first time, I laid my hands on Linux and LSR, messing around and tweaking the default settings. The first documentation and tutorial that I read about LSR were on gaim perk. With no prior experience on Python or LSR framework, trying to comprehend that tutorial was extremely painful with several hours of work spent in vain. Thankfully, our client, Peter Parente, was very generous and helpful. If we sent him a question, he would respond immediately the following morning and he was also readily available on the IRC server. In addition, I was working with teammates who know a lot about Linux and are more knowledgeable than me. With all these resources in hand, I was able to stride through the J-learning curve slowly but steadily.
Like Cristobal and Joel, I also had many frustrations with GNOME desktop, LSR, and its tools. I really hated the fact that the Accerciser was not compatible with LSR, thats is, it was frozen whenever the LSR was launched. So throughout the implementation, I had to "open, close, open, close..." the Accerciser (it's fixed now). Another problem that annoyed me the most is bugginess associated with GNOME Desktop application, as Cristobal and Joel mentioned above. Thus when our perks stopped behaving as they should, we couldn't really tell whether it's a bug within our perks or within the GNOME Desktop application. That was annoying.
Finally, I'd like to conclude my reflection on this project by encouraging people who are interested in LSR to participate and contribute to this wonderful open source project. I really like this project and I think I will continue to work on it after the semester is over.