Description of problem: For Fedora Release Notes and About Fedora, we built an RPM which is installed by default. The actual body of the documents are Publican produced XML. However, when a document is packaged by Publican, one RPM is produced per language. Perhaps even worse, when these packages are installed, one menu item is produced per language. The was this is handled with manually packaging is to use yelp to display the document. Yelp uses "omf" files to determine what document to use for what language. All the localized text in these files is available from within the Publican document, so the normal msgmerge process may be used to localize them, although since Publican doesn't recognize the .omf, this is currently done in a script. There is supposed to be a similar application for KDE but we haven't fully explored that yet. An html equivalent of this process might also be a good approach, but this would require a new application, sort of htmlview on steroids (selecting the browser AND the language). Version-Release number of selected component (if applicable): 0.43, 0.44, 1.0 How reproducible: reproduceable Steps to Reproduce: 1. 2. 3. Actual results: At best, one menu item per language per document Expected results: On menu item for the document in the user's selected language which launches a document in his native language. Additional info: For some odd reason, yelp spells en_US as "C" which can be confusing. Example omf file attached
Created attachment 369937 [details] Example .omf file
The packaging rules used by publican are specifically target at stand alone documentation. They are not general purpose rules, nor is the aim to generate packages for all, even even a major subset of, the many packaging scenarios. (In reply to comment #0) > Description of problem: > For Fedora Release Notes and About Fedora, we built an RPM which is installed > by default. The actual body of the documents are Publican produced XML. > > However, when a document is packaged by Publican, one RPM is produced per > language. This is to decouple languages, it is directly related in being able to predict and schedule translation, and to be able to ship and update the languages independently. FYI we did try a single source RPM pre RHEL5, it was a very expensive decision and caused a large amount of grief. > Perhaps even worse, when these packages are installed, one menu item > is produced per language. Once the languages were decoupled this was the first feature requested. I believe it's directly related to the documentation being standalone; I don't think people would like it for help texts. I understand that the release notes is in the gray area between sub-package documentation and stand alone documentation, however I err on the side of caution on these things because if we ship it, we support it, and I don't want to support this functionality in the general use case. > The was this is handled with manually packaging is to use yelp to display the > document. Yelp uses "omf" files to determine what document to use for what > language. All the localized text in these files is available from within the > Publican document, so the normal msgmerge process may be used to localize them, > although since Publican doesn't recognize the .omf, this is currently done in a > script. We did look at using yelp several years ago, however it did not fit well with our aim of targeting the packaging of stand alone documentation. It is not too hard to amend a software spec file to use publican and generate a docs sub package, the publican package itself does this. Again I believe this relates to the gray release notes fall in to; not tightly coupled to a particular piece of software, but really standalone either. > There is supposed to be a similar application for KDE but we haven't fully > explored that yet. > > An html equivalent of this process might also be a good approach, but this > would require a new application, sort of htmlview on steroids (selecting the > browser AND the language). An HTML version can be achieved with no coding at all. Simply create a desktop file, use xdg-open and an HTML file with a bit of javascript. On RHEL5 this file: /usr/share/doc/HTML/en-US/index.html uses javascript to redirect the user to the welcome page for their language. It defaults to en-US if there is no translation for the users language. basic layout: /usr/share/applications/foo.desktop (1) /usr/share/docs/foo/index.html (2) /usr/share/docs/foo/en-US/index.html (3) /usr/share/docs/foo/de/index.html 1: Desktop contains 'Exec=xdg-open /usr/share/docs/foo/index.html' 2: uses window.navigator.language and an array to choose the language to redirect to. 3: publican generated HTML file > Version-Release number of selected component (if applicable): > 0.43, 0.44, 1.0 > > How reproducible: > reproduceable > > Steps to Reproduce: > 1. > 2. > 3. > > Actual results: > At best, one menu item per language per document > > Expected results: > On menu item for the document in the user's selected language which launches a > document in his native language. > > Additional info: > For some odd reason, yelp spells en_US as "C" which can be confusing. > > Example omf file attached I can not foresee any effort being put in to omf support in publican. It is improbable there will be work to produce a single source rpm from publican. It creates numerous problems for translation work flow and is generally only useful for documentation that is tightly coupled to software. In this scenario you should be building the docs package as a sub package of the software's package. You can still use publican to build and process your documentation, but you aren't going to be using the spec files publican generates. It is unlikely that there will be effort to make a single desktop entry for two reasons. One, the multiple entries were a requested feature. Two, the multiple source rpms makes it untidy. I must admit I find this one oddly tempting though o_O
Created attachment 374155 [details] example HTML for language based redirection
Jeff, your code worked sometimes. I don't fully understand why, but in hacking around it appears that window.navigator.language is only reliable in the <head> section. In most (but not all) cases it fails in the <body>. This might be an approach that resolves a number of issues. I'm not sure it is entirely satisfying (the document is still separate from the system help). But it does avoid the oddness of yelp and might also provide a nice solution for kde.
(In reply to comment #4) > Jeff, your code worked sometimes. I don't fully understand why, but in hacking > around it appears that window.navigator.language is only reliable in the <head> > section. In most (but not all) cases it fails in the <body>. Hi John I did some tests in firefox and konqueror on RHEL5.4 and rawhide. The method I used was to run: LANG=de_DE firefox http://documentation-stage.bne.redhat.com/docs LANG=de_DE konqueror http://documentation-stage.bne.redhat.com/docs This is an internal docs staging server with the following HTML in it: <body class="nojs"> <h1>Welcome to Red Hat Documentation</h1> <script type="text/javascript"> var lang = ""; if(window.navigator.userLanguage) lang = window.navigator.userLanguage; else lang = window.navigator.language; --- snip --- The rest of the code is exactly the same. window.navigator.userLanguage is an IE fix and can be ignored by the lucky people who can get away with that :( On RHEL both browsers are routed to the correct language page. On fedora konqueror behaves the same way, but firefox does not. I logged out and logged back in using a German locale and firefox isn't localized in rawhide, so it appears I can't test it :( It seems to me that if your browser is not localized for the language you are testing then you will get the default language, which is en_US. Doing all this testing reminded me that we had an issue with Firefox last year in RHEL, after a bit of digging I found the BZ, maybe this is biting in fedora as well? https://bugzilla.redhat.com/show_bug.cgi?id=445304 > This might be an approach that resolves a number of issues. I'm not sure it is > entirely satisfying (the document is still separate from the system help). I think it's a stretch to call Gnome help, system help. Actually calling yelp desktop help is a stretch since it's help for only 1 desktop. Calling it system help is just wrong. I've been working with the docs team for almost 5 years now, so you will have to forgive me for becoming pedantic about words, they just never stop :/ > But > it does avoid the oddness of yelp and might also provide a nice solution for > kde. Lets not forget lynx for the people who bugged me that our staging site not being accessible from the command line. No, I am not joking >_< Cheers, Jeff.
As there has been no solution found for the translation work flow bottleneck, which is unsupportable on the core usage of publican, this feature will not be added at this time.