search

qgis / QGIS

QGIS is a free, open source, cross platform (lin/win/mac) geographical information system (GIS)
https://qgis.org
GNU General Public License v2.0
10.46k stars 2.99k forks source link

Help button does not work in its default implementation (returns a wrong url) #25383

Closed qgib closed 6 years ago

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ) Original Redmine Issue: 17486 Affected QGIS version: master Redmine category:translations_and_international

This is likely a QGIS-Documentation repo issue but more a dev issue than a doc writer's. And given that this is the place where devs are and it's directly related to the QGIS application behavior, let me report it here.

With the Help button (being) added to dialogs, user should directly be able to find the appropriate web page of the dialog he's using. It's a nice way to teach him the dialog features but also, and we could expect, for those who know, incitate them to directly fix issues in documentation. However, in its default implementation, it does not work. Afaict, in QGIS, a URL to user manual is built based on the current language and version used. Problem is that languages (or the code of languages) used in the application do not match what is provided in documentation, leading to a Not Found page. What is needed in the QGIS repository is:

Setting the priority to High, as not fixing this is like providing a broken feature by default and would not help for its adoption.

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

qgib commented 6 years ago

Author Name: Giovanni Manghi (@gioman)

If I understand correctly this need to be fixed in the QGIS web site, correct?

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

Yes, the fix has to be done in the QGIS-Documentation Github repository if that's the question. But the "entry point" of the issue is experienced in the application: when clicking a Help button.

qgib commented 6 years ago

Author Name: Giovanni Manghi (@gioman)

Harrissou Santanna wrote:

Yes, the fix has to be done in the QGIS-Documentation Github repository if that's the question. But the "entry point" of the issue is experienced in the application: when clicking a Help button.

is there an issue filed on github? cheers!

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

Giovanni Manghi wrote:

is there an issue filed on github? cheers!

A kind of. See https://github.com/qgis/QGIS-Documentation/issues/1834

qgib commented 6 years ago

Author Name: Alexander Bruy (@alexbruy)

QGIS help system does work as expected. As were outlined in QEP and as we all agreed during QEP and PR discussion, documentation site should be updated to provide corresponding redirections.

Also I don't see anything wrong with URLs construction. Tested with German, French and Ukrainian locales, result always correct

Ukrainian: http://docs.qgis.org/2.99/uk/docs/user_manual/introduction/qgis_configuration.html#options French: http://docs.qgis.org/2.99/fr/docs/user_manual/introduction/qgis_configuration.html#options German: http://docs.qgis.org/2.99/de/docs/user_manual/introduction/qgis_configuration.html#options

If issue exists, please provide exact steps to reproduce issue.

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

Alexander Bruy wrote:

QGIS help system does work as expected. As were outlined in QEP and as we all agreed during QEP and PR discussion, documentation site should be updated to provide corresponding redirections. Also I don't see anything wrong with URLs construction.

I'm not sure I said anything else, did I? I neither see anything wrong with the URL; you might mix the issues (see #25130 where I feel there's something to change in QGIS application side in the url construction). Please read my comments above (short version: I report it here because I'm looking for a dev willing to pick the issue):

This is likely a QGIS-Documentation repo issue but more a dev issue than a doc writer's. And given that this is the place where devs are and it's directly related to the QGIS application behavior, let me report it here.

Yes, the fix has to be done in the QGIS-Documentation Github repository if that's the question.

Alexander Bruy wrote:

Tested with German, French and Ukrainian locales, result always correct

Ukrainian: http://docs.qgis.org/2.99/uk/docs/user_manual/introduction/qgis_configuration.html#options French: http://docs.qgis.org/2.99/fr/docs/user_manual/introduction/qgis_configuration.html#options German: http://docs.qgis.org/2.99/de/docs/user_manual/introduction/qgis_configuration.html#options Unless I misunderstand you, allow me to be really dubious about that... 2.99 hence testing (aka master) is an english only doc so I'm afraid I can't reach any of the translated pages you provide (see eg wrong_uk_url screenshot). And using my french system locale, it expects fr_FR instead of fr as you cited above. If issue exists, please provide exact steps to reproduce issue.

Based on the previous remark (only english is provided) I'd be tempted to say: just click any help button. But let me be verbose with some steps:

So, to summarize, this issue report is to draw devs, I guess the know-how, attention on QGIS-Documentation (and the help system particularly has direct impact on QGIS application). Now, if nobody else experiences the issue or if it's not the place to report this kind of request, then I apologize for the trouble and feel free to close the issues.

qgib commented 6 years ago

Author Name: Alexander Bruy (@alexbruy)

Harrissou Santanna wrote:

I'm not sure I said anything else, did I? I neither see anything wrong with the URL; you might mix the issues (see #25130 where I feel there's something to change in QGIS application side in the url construction).

Maybe I misunderstand you, but in the ticket you said

Harrissou Santanna wrote:

However, in its default implementation, it does not work.

which is not true. QGIS part works exactly in the same way as it should according to the QEP.

Alexander Bruy wrote:

Tested with German, French and Ukrainian locales, result always correct

Ukrainian: http://docs.qgis.org/2.99/uk/docs/user_manual/introduction/qgis_configuration.html#options French: http://docs.qgis.org/2.99/fr/docs/user_manual/introduction/qgis_configuration.html#options German: http://docs.qgis.org/2.99/de/docs/user_manual/introduction/qgis_configuration.html#options Unless I misunderstand you, allow me to be really dubious about that... 2.99 hence testing (aka master) is an english only doc so I'm afraid I can't reach any of the translated pages you provide (see eg wrong_uk_url screenshot). And using my french system locale, it expects fr_FR instead of fr as you cited above.

I'm afraid you are confused with release and development stuff here. Of course, you can't reach any of these URL's because there is no (and never will be) localized documentation for master. We provide documentation only for releases and you should not transfer development URLs to the release version. But URLs constructed correctly, there is a valid sequence of version, locale and documentation chapters. May I ask you how will look URL for 3.0 release? Won't it be something like http://docs.qgis.org/3.0/fr/docs/user_manual/introduction/qgis_configuration.html#options? If yes, what is the problem?

Also why you expect fr_FR instead of fr? Documentation site use fr for French, not fr_FR. Same with other languages. If you mean that you get URL's with fr_FR, then please provide more information about you environment, because I'm unable to reproduce it on my system. That's why I asked

If issue exists, please provide exact steps to reproduce issue.

Based on the previous remark (only english is provided) I'd be tempted to say: just click any help button. But let me be verbose with some steps:

Please, please, don't confuse development version and release version. Of course with development version you can't access localized docs because there is no localized docs for master. There is nothing wrong here and it was already discussed and explained several times. But if you want, you can access English version, just adjust your settings and remove locale from the base URL.

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

OK. "Balle à terre". There seems to be a lot of misunderstanding in both parts. I'll repeat myself: There's no problem in the way QGIS constructs the URL but people will have problem to use this option if nothing is done from the Docs side. And to be clear, I'm not blaming the work done in QGIS part. This feature Months ago, I raised some global concerns about how QGIS-Docs needs to handle QGIS help button in my "Docs wiki":https://github.com/DelazJ/QGIS-Documentation/wiki/On-the-road-to-QGIS3 and made a public call for ideas/plans/fixes in https://lists.osgeo.org/pipermail/qgis-community-team/2017-June/004843.html. I had a touch with Paolo (on behalf of PSC) but we didn't dig further. You'll see some answers or considerations about points you mention in your message (release vs dev, 3.0...) so to keep this discussion close to the initial request, I'll try to constrain my reply to reexplaining the issue I experienced.

1/ when I do not override the system locale option, the language is retrieved as fr_FR as you can see in the locale_system screenshot. So when I hit the help button, the docs link is constructed with fr_FR (it's not me expecting that, it's what Firefox tries to open) instead of fr

2/ when I override it with the "American English" (I do not have "English" in the drop-down list) and I hit the Help button, I get links with en_US (I already sent the screenshot for that) instead of en

We need in QGIS-Documentation to map these languages to what is really provided by our Docs otherwise, each time someone hits a help button, he'll then need to manually replace the language part (this is true for french and maybe american but also for all the languages that are not present in QGIS-Docs). Or add another help link in the Options dialog, which I'm not sure the average user will do (reason why I said the default implementation, meaning the whole system without any change from the user, does not work for a part of the world and won't return a valid page until the next LTR doc is released for another part).

I hope that this helps to clarify my comments and answers you.

qgib commented 6 years ago

Author Name: Alexander Bruy (@alexbruy)

Harrissou Santanna wrote:

1/ when I do not override the system locale option, the language is retrieved as fr_FR as you can see in the locale_system screenshot. So when I hit the help button, the docs link is constructed with fr_FR (it's not me expecting that, it's what Firefox tries to open) instead of fr

2/ when I override it with the "American English" (I do not have "English" in the drop-down list) and I hit the Help button, I get links with en_US (I already sent the screenshot for that) instead of en

Hmm, which OS are you using? Because on Linux with default locale ukUA.UTF-8 without overriding locale in QGIS settings I get correct URL. Also if I override locale either via QGIS settings or by defining different LC* environment variables resulting URL still correct, no fr_FR or similar codes, only two-letter code.

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

Hmm, which OS are you using? Windows 10

qgib commented 6 years ago

Author Name: Alexander Bruy (@alexbruy)

Seems this happens only with languages which have different variations, like en_US and en_GB, pt_PT and pt_BR. As I can see documentation website also has same codes in the URLs, look for example at Portuguese docs for Brasil and Portugal. Do you think we should drop them or maybe just handle case of en_US locale?

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

i could have sworn that i got a wrong link with fr_FR but i might have dreamed it: only en_US locale seems to be not return the right language, afaics.

qgib commented 6 years ago

Author Name: Richard Duivenvoorde (@rduivenvoorde)

@Harrissou: some background: at a certain point in time be decided to NOT use language_country ISO codes (like nl_BE, fr_FR) to minimize the amount of translations. We ONLY use the language code: fr, de, nl, en etc. BUT some countries (Brazil, Portugal) considered their pt-language so different from each other that they really wanted 2 different translations. That is the reason why only there is pt_PT en pt_BR (en if I'm correct a khmer one which had another problem).

Also we tried to synchronize these 'language-codes' between QGIS-application, QGIS documentation, Transifex etc.

If I'm correct, the logic from Alexander just used those language codes (so is NOT looking into the locale of the Operating System).

Testing here: if I start (translated) QGIS 2.18 with:

qgis --lang nl

it successfully starts QGIS in dutch, but if I then click Help/Inhoudsopgave (F1) I go to https://docs.qgis.org/2.18/en/docs/user_manual/ mmm, this should be https://docs.qgis.org/2.18/nl/docs/user_manual/ ...

Mmm, will look into this and report back which url exactly is fired, and if we redirect or not...

If there is something in the website we should fix, please let me know (as we are going to move the sites to another server in near future)...

qgib commented 6 years ago

Author Name: Richard Duivenvoorde (@rduivenvoorde)

For 2.18, at least 'en' seems hardcoded:

https://github.com/qgis/QGIS/blob/release-2_18/src/app/qgisapp.cpp#L9184

as in translation I do not think 'en' will be translated to 'fr' or 'uk' :-)

This could be fixed, though this is I think only used for the F1/help icon isn't it?

But..., you were talking about master.... What I see there is: IF QGIS is run with locale 'nl' then QGIS points rightfully to http://docs.qgis.org/testing/nl/docs/user_manual/index.html which ... should be redirected to the english version, as there are no translations yet.

So THAT is a web server (my) problem...

qgib commented 6 years ago

Author Name: Richard Duivenvoorde (@rduivenvoorde)

Ok, I think that I have done the right redirectMatches now at docs.qgis.org to redirect a given language url to the right english one for testing.

EG, the help button in the open vector dialog is pointing to: http://docs.qgis.org/2.99/nl/docs/user_manual/managing_data_source/opening_data.html#loading-a-layer-from-a-file which will be redirected to: docs.qgis.org/testing/en/docs/user_manual/managing_data_source/opening_data.html#loading-a-layer-from-a-file

If not, or you see other problems, please let me know

Can this issue be closed then?

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

For 2.18, at least 'en' seems hardcoded: https://github.com/qgis/QGIS/blob/release-2_18/src/app/qgisapp.cpp#L9184 as in translation I do not think 'en' will be translated to 'fr' or 'uk' :-)

Actually, I do translate this kind of links, even though Transifex complains. As long as it's a valid link, I find it normal to translate instead of sending the user to an english page he'll then have to switch to french. BUT... this is not the issue here.

EG, the help button in the open vector dialog is pointing to: http://docs.qgis.org/2.99/nl/docs/user_manual/managing_data_source/opening_data.html#loading-a-layer-from-a-file which will be redirected to: docs.qgis.org/testing/en/docs/user_manual/managing_data_source/opening_data.html#loading-a-layer-from-a-file Yes, this part of the issue I was raising is fixed (combined to the en_US bug Alex fixed days ago). Thanks to you! What is remaining is the link for languages that are NOT provided in QGIS-Documentation. Try to open an icelandic help from QGIS. It'll still tries /testing/is/ and fails instead of switching to /testing/en/.

So THAT is a web server (my) problem...

Does it mean that any issue regarding the web side should be reported to you ? Only you are in charge of this? In which case, sorry for having moved the discussion here.

qgib commented 6 years ago

Author Name: Richard Duivenvoorde (@rduivenvoorde)

@Harrissou: well yes, most server stuff is my problem... Though I do not have a solution yet for the url's which are actually 404 (like pointing to a non available translation).

Also note that all this here, should only have an effect in master (only in master we go to either a zip or the online help via this class:

https://github.com/qgis/QGIS/blob/master/src/gui/qgshelp.cpp

I just created a Pull Request

https://github.com/qgis/QGIS/pull/5844

which made that a valid(!) help url like:

https://docs.qgis.org/2.99/en/docs/user_manual/working_with_ogc/ogc_client_support.html

to be not shown. Reason was that the check of a valid url did not handle the 301 redirection we (apparently) use.

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

What is the status of this report? Are all raised issues considered as fixed now? Thanks.

qgib commented 6 years ago

Author Name: Giovanni Manghi (@gioman)

Harrissou Santanna wrote:

What is the status of this report? Are all raised issues considered as fixed now? Thanks.

Agree, can the involved people close or tag this open, as necessary? thanks!

qgib commented 6 years ago

Author Name: Harrissou Santanna (@DelazJ)

From the initial message, all requests are done so closing.