GNOME Bugzilla – Bug 474958
Orca has no onboard help
Last modified: 2007-10-12 19:32:52 UTC
Documentation Section: Orca has a help button (for example in the configuration gui), but no documentation is installed on the system; the help button is greyed out. This is a shame - it wouldn't be *too* difficult to turn the online documentation on the wiki into something helpful in xml for the accessibility guide or alternatively a separate document installed by orca. http://live.gnome.org/Orca/DocIndex Correct version: Other information:
I've posted a patch to bug 475110 which includes some material on orca taken from the wiki and inserted into the accessibility guide. I've posted it to that bug because it's included in a patch with some more substantial changes. If it's committed, I'll post here so that the help button can be pointed to the appropriate place.
*** Bug 480874 has been marked as a duplicate of this bug. ***
As per bug 475110 there has now been the relevant material added to the user-guide, so all that remains to fix this bug is to link the help button to it.
I've been told that "gnome_vfs_url_show (url)" in the call to use to do this. This is a non-blocking call. I now need to check to see if there is a Python wrapper for it.
Bug #475110's .xml file is under: /usr/share/gnome/help/gnome-access-guide/C/... Look at the way that accerciser does this and see if we can easily use that code.
Created attachment 97026 [details] [review] Patch to use the GNOME Accessibility Guide via yelp. A couple of concerns here: 1/ The patch calls: gnome.program_init('gnome-access-guide', '1.0', properties=props) This feels a bit weird, but as we don't have our own Orca help, then it seems to be what's needed. 2/ Is every distro going to have: /usr/share/gnome/help/gnome-access-guide/<lang>/gnome-access-guide.xml It's certainly on my Ubuntu system, but what about others? If it's not there, I think it's just going to quietly fail (that's what was happening when I was trying: gnome.program_init('orca', '1.0', properties=props))
> A couple of concerns here: > > 1/ The patch calls: > gnome.program_init('gnome-access-guide', '1.0', properties=props) > This feels a bit weird, but as we don't have our own Orca help, then > it seems to be what's needed. Yeah. In playing with this, we probably should have our own help. :-( I'm also kind of concerned about the current behavior: 1) There's no "Help" on the main window (should there be?) 2) The Orca preferences dialog is very persistent about staying on top, at least on my system. With this, the preferences dialog occludes the help window and I cannot view the help window until I dismiss the preferences dialog. These are both probably separate bugs. Does anyone experience #2 like I do?
(In reply to comment #6) > Created an attachment (id=97026) [edit] > Patch to use the GNOME Accessibility Guide via yelp. > > A couple of concerns here: > > 1/ The patch calls: > gnome.program_init('gnome-access-guide', '1.0', properties=props) > This feels a bit weird, but as we don't have our own Orca help, then > it seems to be what's needed. Lots of programs call gnome-user-guide, so calling gnome-access-guide is not really a concern. You should call the section #ats-2 so that the correct page of the gnome-access-guide (the one dealing with orca) opens. > 2/ Is every distro going to have: > /usr/share/gnome/help/gnome-access-guide/<lang>/gnome-access-guide.xml > It's certainly on my Ubuntu system, but what about others? > If it's not there, I think it's just going to quietly fail > (that's what was happening when I was trying: > gnome.program_init('orca', '1.0', properties=props)) It will be there if the gnome-access-guide is installed; this comes with gnome-user-{docs|guide} release and orca packages should probably depend on that. In Ubuntu, gnome-user-guide is part of the default desktop.
(In reply to comment #7) > These are both probably separate bugs. Does anyone experience #2 like I do? Yup. And this was on a box with a 21 inch wide screen monitor. While I could drag things around to see everything, the Orca Preferences window was covering up part of the Help window when I pressed the Help button.
From Matthew: >Lots of programs call gnome-user-guide, so calling gnome-access-guide is not > really a concern. But can a program call "gnome-user-guide" (or in our case "gnome-access-guide"), without having to do: gnome.program_init('gnome-access-guide', '1.0', properties=props) That's the concern here. > You should call the section #ats-2 Noted. I'll adjust for the next patch. From Will: > Does anyone experience #2 like I do? Me too. But that's not a problem for a blind person. ;-) Just a person who's sighted or has low vision. What do you suggest here? Should the Help button be move to the main Orca window? Thanks.
(In reply to comment #10) > From Matthew: > >Lots of programs call gnome-user-guide, so calling gnome-access-guide is not > > really a concern. > > But can a program call "gnome-user-guide" (or in our case > "gnome-access-guide"), > without having to do: > > gnome.program_init('gnome-access-guide', '1.0', properties=props) > > That's the concern here. If I were you I'd copy what another application does. Try nautilus, gnome-panel, or yelp itself: all of them link to a section in gnome-user-guide.
> From Will: > > Does anyone experience #2 like I do? > > Me too. But that's not a problem for a blind person. ;-) Just a person > who's sighted or has low vision. What do you suggest here? Should the > Help button be move to the main Orca window? I'm not sure of the right thing to do regarding the help button. When I look at an application such as gnome-terminal, it looks like its main window lets you get help via the Help menu and the preferences window lets you get help via a help button. So, maybe help is needed in two spots? The issue of the preferences dialog being on top all the time is definitely a troublesome one. Is this a fallout of the metacity focus grabbing logic? That is, because we need the Orca preferences dialog to appear when you press Insert+Space while in a different application, we need to workaround metacity's logic to prevent it from getting focus?
Matthew, thanks! I'll check them out. I think we need Mike's decisions on the Help button, but here are my thoughts: 1/ Currently, I don't know why the Preferences dialog is on the top. I don't think it should be. According to the Glade file, it's a top-level dialog but it's not modal. I'll investigate this further. 2/ I think the Help button should just move to the main window. The Preferences-window-on-top problem would then just goes away. Looking at the Orca pages in the gnome-access-guide, there doesn't appear to be a specific section just devoted to each of the options on each of the panes of the Preferences dialog (Matthew, please correct me if I'm wrong). The help is of a more general nature. It seems more natural to therefore position the Help button in a more general location. 3/ Having the Help button in the main window means that a new user is going to hopefully find it faster. Mike, if you think it should go there, then I'll need to know the order that they should be, i.e.: [ Help ] [ Preferences ] [ Quit ] and which button should have the default focus when the window is first displayed. Also, maybe now is the time to start thinking about having an Orca window with a menu bar. It would be kind of minimal. +---------------------------------------------+ | & Orca Screen Reader / Magnifier _ [ ] X | +---------------------------------------------+ | File Edit Help | +---------------------------------------------+ | Quit | Preferences | | Help Contents | +------+-------------+ +---------------+ | | About | | +---------------+ | | +---------------------------------------------+ The Help->About menu item would allow the user to easily determine the Orca version number and give us an opportunity to give credit to all the Orca contributors. You know, like a real GNOME desktop application. ;-) 4/ There should probably be an Orca hot-key combo to bring up the Help at any time. Maybe ORCA_MODIFIER-? ? Mike, please let me know how you'd like me to proceed. Thanks.
I like the idea of putting the help button on the orca main window. How about an order of: preferences, help, quit I'm really not in favor of adding a menubar.
Thanks Mike. I still need you to clarify some things before I proceed. 1/ What of the three buttons in the Orca main windows should be the one that initially has focus when the main window is shown? 2/ Should the Help button be removed from the Orca Preferences dialog? 3/ Should there be an Orca hotkey for displaying the help window? If yes, what should that be? Thanks.
> 1/ What of the three buttons in the Orca main windows should be the > one that initially has focus when the main window is shown? > preferences > 2/ Should the Help button be removed from the Orca Preferences dialog? > no > 3/ Should there be an Orca hotkey for displaying the help window? > If yes, what should that be? > orca+h
Created attachment 97086 [details] [review] Revised patch to implement the requested feature. Patch to hopefully implement the desired functionality. Thanks to Joanie who solved the always-on-top problem. Comments please...
> Thanks to Joanie who solved the always-on-top problem. Yeah! That looks like it did the trick. Woo woo! > Comments please... The help button looks really odd -- it's taller than the preferences or quit buttons, it's the only one with an icon, and it looks strange for it to be in the middle. I always tend to expect to find it on the upper right (e.g., in the menu bar) or lower left (e.g., in a dialog). Visually, to me it would look better if the other two buttons had icons and the help button was the last button in the row. For the icons to use, I think maybe the GTK_STOCK_QUIT icon and the GTK_STOCK_PREFERENCES icon might work. You can see these in the gtk-demo "Stock Item and Icon Browser" demo. Finally, I think F1 should also be bound to launch the help when the Orca main dialog or preferences dialog is up. That's the standard key for launching help in most apps. Thanks!
Created attachment 97088 [details] [review] Revised patch - version 2. Here's a version with all three buttons having stock icons and with the order: [Preferences][ Quit ][ Help ] I've also made all the buttons the same width.
Created attachment 97089 [details] [review] Third version. Here's a version with all three buttons have stock icons and the same width, with the order: [Preferences][ Quit ] [ Help ] In other words, there is a gap between the Quit and the Help buttons. Thoughts? I'll investigate the F1 help problem next. Thanks.
I prefer the one with the gap, but perhaps a slightly smaller gap.
Created attachment 97091 [details] [review] Fourth version. This version has all three buttons using stock icons, with labels width, and the order: [Preferences][Quit] [Help] with a smaller amounter of space between the Quit and the Help buttons. I like this one best.
I like this one the best as well. In addition to the smaller gap, I like that the buttons don't all take up the width of the Preferences button. Help and Quit seemed a bit too big before.
Created attachment 97092 [details] [review] Fifth version. Fifth version with a little Help button padding. I'm obsoleting the others. Let's work from this one.
Created attachment 97094 [details] [review] Adjust borders and resizing behavior for orca-mainwin.glade Just something to play with. Adjusts the left/right borders to be the same as top/bottom and keeps the gap between the preferences and quit buttons the same. Puts the Help button off to the right, and it stays there when you resize the window.
Created attachment 97095 [details] [review] Ignore that last one. This one includes all of Rich's other changes from his last patch
Created attachment 97096 [details] [review] Slightly adjusted version of last patch to work from svn trunk. I like this version. It's got my thumbs up.
(In reply to comment #27) > Created an attachment (id=97096) [edit] > Slightly adjusted version of last patch to work from svn trunk. > > I like this version. > It's got my thumbs up. > I like it. We can add the F1 stuff later. Now, I really need to apply the actual patch that contains the contents of the help and take a look at it.
(In reply to comment #28) > (In reply to comment #27) > > Created an attachment (id=97096) [edit] > > Slightly adjusted version of last patch to work from svn trunk. > > > > I like this version. > > It's got my thumbs up. > > > > I like it. We can add the F1 stuff later. Now, I really need to apply the > actual patch that contains the contents of the help and take a look at it. > Hey - Looks good with the actual help content, too. :-) Now, this contains a UI change, which I think is needed. This means we need to request a freeze break for gnome-2-20. But, I think it is worthwhile to request it. Rich, what do you think?
It's certainly worth trying. They can only say no. Alternatively, what about updating the Orca wiki with the command to run instead which will bring up the equivalent in yelp?
(In reply to comment #30) > It's certainly worth trying. They can only say no. Do you want to take it or do you want me to do so? > Alternatively, what about updating the Orca wiki with > the command to run instead which will bring up the > equivalent in yelp? Ha! If they are on the WIKI, they already have the same stuff in the help text because the help text was derived from the WIKI. :-)
> Do you want to take it or do you want me to do so? I want you to do so. Does that mean you want me to commit the patch?
(In reply to comment #32) > > Do you want to take it or do you want me to do so? > > I want you to do so. OK - I'll write it up. > Does that mean you want me to commit the patch? I think it's OK to commit for trunk, but we cannot do so for gnome-2-20 until we get the break request approved.
> I think it's OK to commit for trunk, Okay. It's going to unfortunately have to wait a while. I replaced a 512MB DRAM with a 1GB in my Ferrari and I can no longer boot Ubuntu Gutsy (get's a kernel panic). Of course it could be a coincidence, and the "sudo apt-get dist-upgrade" I did today could have broken something. Who knows. Windows Xp works fine on this machine and it see all 1.5GB's of memory. You can add memory to a Linux system and then just reboot can't you? You don't have to build a new kernel or something? I'm unfortunately dead in the water at the moment w.r.t. testing and checking in patches.
> Okay. It's going to unfortunately have to wait a while. > I replaced a 512MB DRAM with a 1GB in my Ferrari and I > can no longer boot Ubuntu Gutsy (get's a kernel panic). Yech! Sounds like a koinkydinky to me. It *should* just work.
> I think it's OK to commit for trunk, ... Latest patch committed to SVN trunk. Moving to "[pending]" state.
I just tested this with trunk. The dialog seems good and the help appeared as I would expect.
Latest patch also committed to the gnome-2-20 branch.
Thanks Mike. Closing as FIXED.