Bug report #17486

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

Added by Harrissou Santanna over 2 years ago. Updated over 2 years ago.

Status:Closed
Priority:Normal
Assignee:-
Category:Translations and international
Affected QGIS version:master Regression?:No
Operating System: Easy fix?:No
Pull Request or Patch supplied:No Resolution:fixed/implemented
Crashes QGIS or corrupts data:No Copied to github as #:25383

Description

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:
- to match the languages that are provided in both places (for example, en_US <--> en, fr_FR <--> fr, ca <--> ca....)
- to return the english version when there's no correspondance (there are many more languages in application than in doc).
- Also note that for dev version, only english is provided so maybe always fallback to english when the provided link will likely return a not found page, eg, test catalan if requested and if not found test english. (don't quite know!)

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

wrong-uk-url.png - testing is not a translated doc (30 KB) Harrissou Santanna, 2017-11-22 04:55 PM

wrong_en_url.PNG - trying to open en_US instead of en (14.7 KB) Harrissou Santanna, 2017-11-22 05:35 PM

locale_system.PNG (5.55 KB) Harrissou Santanna, 2017-11-23 10:28 AM

History

#1 Updated by Harrissou Santanna over 2 years ago

  • Assignee deleted (QGIS Translation Team)

#2 Updated by Giovanni Manghi over 2 years ago

  • Status changed from Open to Feedback

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

#3 Updated by Harrissou Santanna over 2 years ago

  • Status changed from Feedback to Open

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.

#4 Updated by Giovanni Manghi over 2 years ago

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!

#5 Updated by Harrissou Santanna over 2 years ago

Giovanni Manghi wrote:

is there an issue filed on github? cheers!

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

#6 Updated by Alexander Bruy over 2 years ago

  • Priority changed from High to Normal
  • Status changed from Open to Feedback

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.

#7 Updated by Harrissou Santanna over 2 years ago

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 #17231 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.

#8 Updated by Alexander Bruy over 2 years ago

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 #17231 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.

#9 Updated by Harrissou Santanna over 2 years ago

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 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.

#10 Updated by Alexander Bruy over 2 years ago

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 uk_UA.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.

#11 Updated by Harrissou Santanna over 2 years ago

Hmm, which OS are you using?

Windows 10

#12 Updated by Alexander Bruy over 2 years ago

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?

#13 Updated by Harrissou Santanna over 2 years ago

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.

#14 Updated by Richard Duivenvoorde over 2 years ago

@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)...

#15 Updated by Richard Duivenvoorde over 2 years ago

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...

#16 Updated by Richard Duivenvoorde over 2 years ago

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?

#17 Updated by Harrissou Santanna over 2 years ago

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.

#18 Updated by Richard Duivenvoorde over 2 years ago

@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.

#19 Updated by Harrissou Santanna over 2 years ago

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

#20 Updated by Giovanni Manghi over 2 years ago

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!

#21 Updated by Harrissou Santanna over 2 years ago

  • Status changed from Feedback to Closed
  • Resolution set to fixed/implemented

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

Also available in: Atom PDF