GNOME Bugzilla – Bug 590734
RFE: Improve documentation about the a11y configuration
Last modified: 2009-09-03 09:23:01 UTC
The section about the accessibility configuration in the help file of gdm (docs/C/gdm.xml) lists the four gconf keys that GDM provides to control its accessibility features, but it does not explain how these relate to the different accessibility tools installed in the system. You will find an ascii file attached to this thread that proposes an enhanced version of the Accessibility Configuration section for the gdm.xml file. (I first tried to enhance the xml file itself, but I did not completely understand the structure of the file in the editor that I was using; consequently I decided to provide the text in ascii format.) I will also attach the desktop files indicated in the enhanced documentation to this thread. Hoping that my enhanced version of the Accessibility Configuration (section 5.6. in http://library.gnome.org/admin/gdm/2.26/configuration.html.en) will be appropriate to replace the currently available text.
Created attachment 139866 [details] Improved version of the Accessibility Configuration section
Created attachment 139867 [details] desktop file for dwelling indicated in the improved documentation
Created attachment 139868 [details] desktop file for the onscreen keyboard named onboard
Created attachment 141378 [details] [review] patch with changes. I updated the docs, much as you suggest. However, I did reword it a bit to make things a bit more clear. Please let me know if you notice any errors or if you have further suggestions for improvement.
Fixed in master.
Thanks for adding my suggestions to the docs. I just had a look at it and found 2 typos and a sentence that I don't understand (the last sentence of the second paragraph of the section with the title "GDM Accessibility Dialog And Gconf Keys"). So I created a patch to fix the typos and tried to also improve a few other things. As I only have very little experience with patching, I hope that I created the patch correctly. (For the case of a problem with the patch, I will also upload the modified gdm.xml file.) Finally, be aware that I used gedit to modify the gdm.xml file and edited some tags by hand. It should be correct, but I don't know how to test it.
Created attachment 142337 [details] [review] fix typos and little improvements
Created attachment 142338 [details] the modified gdm.xml file
Created attachment 142342 [details] [review] updated patch Thanks for your attention to detail, and for the updated patch. Here is an updated patch that I actually applied, based on your recommendations. It incorporates most of your changes with some minor exceptions. Each <listitem> entry should have its own description, rather than using the same description for multiple keys. So I am keeping the listitems separate. I really don't see the value in breaking the list of configuration options into two sections (GDM Configuration Keys and Assistive Tools GConf Keys). There are only 4 a11y related keys to worry about, and I think the descriptions make it clear enough how they work. Also you made this suggestion: - For example, if GNOME is distributed with GOK as the default on-screen - keyboard, then this could be replaced with a different program if - desired. To replace GOK with the on-screen keyboard application - "onboard" and additionally activate the assistive tool "mousetweaks" - for dwelling support, then the following configuration is needed. + GNOME is distributed with GOK as the default on-screen keyboard. To + replace GOK with the on-screen keyboard application "onboard" and + additionally activate the assistive tool "mousetweaks" for dwelling + support, the following configuration is needed. Note that different distros may use different default a11y programs with GDM. The docs should avoid trying to suggest what is installed on the system by default since it may not be true. So I did not change this wording. +</p> <p>Hosted by <a href="http://www.redhat.com/">Red Hat</a>.</p> <p>Powered by <a href="http://hjemli.net/git/cgit/">cgit</a></p> </div> The above section is not a part of the GDM docs, but seems something that Red Hat adds. If you want this fixed, you probably need to file a bug with Red Hat.
Hi Brian, Thanks for taking my new suggestions and patch into account. * I divided the 4 gconf keys into two sections to emphasize that they have different functions: the first starts the accessibility infrastructure, while the 3 others are linked to individual assistive tools. But I have no problems with leaving them separate, especially as you improved the description of the 3 keys. * "default on-screen keyboard": I was looking differently at it: for me GOK is the default onscreen keyboard of GNOME, even if a distribution is using GNOME with a different onscreen keyboard, for example onboard. In that case, I would say that the distribution uses onboard as default onscreen keyboard, but I would not extend it to say that in that case, onboard would also be the default onscreen keyboard of GNOME. Now, I understand why you turned it that way. Your updated patch is ok for me, too.
Thanks. I think the docs are now in much better shape than they were before you offered your help. Thanks a lot. In general, it's better if the docs do not try to suggest what the default AT programs are since it may not be accurate for a particular distro and that can cause confusion for the reader. Yes, GOK is the default onscreen keyboard for GNOME, but when people think of GNOME they think of GNOME as it is provided by their distro, which may not exactly match the upstream definition of what GNOME is. Especially on distros designed for unique use-cases (e.g. a mobile GNOME may use very different programs than netbook GNOME, desktop GNOME, and terminal server GNOME). But they all might use GDM.
Thanks for the explanation. I am pleased that I could help.