GNOME Bugzilla – Bug 689726
Please make links to gnome-help Ubuntu-friendly
Last modified: 2012-12-08 21:39:49 UTC
There are two links to gnome-help in the Orca help. These do not work in Ubuntu, because they have forked the gnome help and renamed it to ubuntu-help. Therefore, unless the gnome-user-guide package is installed (which is not by default, ubuntu-docs is), links to the gnome-help in other documents do not work. There is a downstream bug about this problem: https://bugs.launchpad.net/ubuntu/+source/gnome-orca/+bug/801601 This can be solved by using conditional expressions in the help: http://projectmallard.org/if/1.0/index.html The gnome-help already uses these to reduce the delta between Gnome and Ubuntu, so it would be great if Orca would jump this bandwagon. See http://git.gnome.org/browse/gnome-user-docs/tree/gnome-help/C/bluetooth-send-file.page for an example.
Created attachment 230808 [details] [review] Change the links to gnome-help to use conditionals
Thanks Attila for pushing me into creating a patch for this :).
Gabor, I think need listening the target too, because for example in library.gnome.org the help topics are converted with HTML format. This situation need using the GNOME Access Guide HTML version links (normal http links). If an Orca user reading help topics with online for Firefox with not an Unix system, help:gnome-help/a11y or help:ubuntu-help/a11y style links will be not working. The target:html, target:xhtml tokens provide possibility to handle this situation too. This situation need using following link the text: http://library.gnome.org/users/gnome-help/stable/a11y.html I will be testing this possibility. You examine the platform token. If the default environment is Unity in Ubuntu (this is the default an Official Ubuntu release), your links will be work. But, I think the Ubuntu GNOME Edition will be an official community release with Ubuntu 13.04. If the platform is not Unity (for example GNOME Shell because the user installed the gnome-shell package and using this environment), your links will be not working, because this situation Yelp will be try presenting help:gnome-help/a11y links. This is will be not working, because gnome-user-guide package are not part of default installation. Following tokens are possible to use the platform token, possible not all possibilities are documented: Token Description platform:linux The content applies to operating systems running the Linux kernel. platform:gnome-shell The content applies when running GNOME Shell, the core of GNOME 3. platform:x86 The content applies to CPUs using an x86 architecture. platform:touch The content applies for touchscreen devices, such as tablets. Attila
Created attachment 230880 [details] [review] Refreshed patch to make links work on Ubuntu and on the web too Updated patch to contain links to the web too. As per https://mail.gnome.org/archives/gnome-doc-list/2012-December/msg00003.html this is somewhat better, as it will work in the web version too. One more iteration can be expected, that will hopefully replace the link with a placeholder, but that currently does not work for me yet.
Created attachment 230885 [details] [review] A simplest version Gabor, sure need filtering a11y links related with user using Unity or other desktop environments? My this day experiences based with Ubuntu 13.04 daily live CD the manual builded current Orca master version presenting both Unity and GNOME3 classic sessions the a11y help. When I opening a11y page the Orca's help main page and I using Unity, I see unity related a11y help topics. When I opening the a11y help page in Orca's main help page and using for example GNOME3 classic session, I see right GNOME related a11y help topics, not Unity related document. I don't what doed Ubuntu developers different, but the help:gnome-help/a11y links works right in Ubuntu 13.04. I attaching a simplest patch with resolves only the HTML style links related problem. If future this solution will be not work because GNOME Documentation team members will be changing some thinks, please not use my solution. If this is the case, need using your fix I think. Attila
Created attachment 230886 [details] Screenshot the GNOME Classic session a11y help
Created attachment 230887 [details] Screenshot of the Unity environment presenting a11y help
I think it is entirely misguided to start patching things up for this kind of downstream misbehaviour. If Ubuntu is forking the docs, they need to pay the price to fix up all the cross-references...
@Matthias: Not to mention the fact that every indication is that Ubuntu is shipping GNOME 3.6 in Rascally Rabbit. So this change is in danger of not even being seen in the one place where it applies. @Gabor and Attila: I really appreciate your work on this, but I do agree with Matthias. I won't go so far as to call their customization "misbehaviour", but it *is* downstream customization -- one that, unlike Python 3, will never become upstream. Therefore, I'm afraid I'm going to close this out. But if you open it downstream and ping Luke, he'll undoubtedly get it added. Thanks and sorry!
Joanie, library.org online Orca documentation the html links conversion related sure not need doing anything with Orca side? Try following test: 1. Open http://library.gnome.org/users/orca/3.7 Page. 2. Open main page the Universal Access link. If an user try opening this link with not Unix and GNOME based operating system, will be not presenting a11y help the online version. Happening this issue if for example an Ubuntu based distribution not installed the gnome-user-guide package. Because the users this situation presenting online Orca documentation with Firefox and another web browsers, the external help topics need presenting the used applications, not Yelp. Look my latest patch if you have a little time. This is not only Ubuntu related customization, this patch handling an upstream issue the online documentation. Attila
Created attachment 231034 [details] Test demonstration the good working online HTML version Joanie, please repeat I prewious wrote test with the zip file awailable online HTML version after you looked the online version. I simple apply my patch with Orca help, copyed all help/C directory awailable files with a directory. After this, I ran yelp-build cache *.page and yelp-build html -o html *.page commands. If you extracted the zip file, open Firefox with html/index.html file, and click the universal access help link. Will be presenting A11y help documentation inside with Firefox, not Yelp. Attila
Just to be clear: This isn't about forking the docs. This is about running under environments other than GNOME Shell. We could do the same thing for running under GNOME 2 or XFCE or KDE or Windows or Android or anything else. Linking to help:gnome-help in your docs is tantamount to saying "we only care about running this program under GNOME 3". If that's your position, that's fine.
Good point Shaun. We want Orca running everywhere. :) Therefore I have just removed the links to the GNOME Accessibility help and put more generic text. Problem solved. http://git.gnome.org/browse/orca/commit/?id=135f15df455c4e118eb8ae7fc93c324b9e4a7c55