Update help url registrations for built-in reports and tools

[hgohel]

Add help_url to Reports, QuickViews, Graphical Reports, Web Reports, built-in tools and debug tools.

Commit on behalf of Emyoulation.

[hgohel]

@emyoulation Please review PR carefully - it includes these changes from your master branch.

[emyoulation]

Yes. It looks great! Thanks!

Next, it looks like I need to go back and find where built-in Rules plugins are registered.

[Nick-Hall]

This PR has translatable string changes which should be avoided in a maintenance release.

[hgohel]

@Nick-Hall Right, there are new strings. However, my understanding was that the new *_HELP strings contain part of a URL and wouldn't be translated. @emyoulation is that the intended usage?

[emyoulation]

If my understanding is correct, these are translatable URLs that will add strings to the Weblate.

Yes, that will ding the translation statistics. But if we do not have these help_urls for WikiContributor and translator (probably not developer since they can use the master branch) experimental purposes, then the documentation support for translators cannot evolve.

There are a LOT of issues about WikiMedia translated anchors, page forwarding, and possible use of the Weblate glossaries with a MediaWiki plug-in. So that will need a lot of test data.

[hgohel]

Got it. Did not know that URLs were translated. Thanks for clarifying. Lmk if this needs to be rebased to another branch.

[emyoulation]

That's a Software Architect call.
Whatever way that will facilitate @Nick-Hall approving a merge.

[Nick-Hall]

We don't really want to translate links to wiki pages. For example, consider the English link:

Gramps_5.2_Wiki_Manual_-_Reports#Graphs

The French link needs to be:

Gramps_5.2_Wiki_Manual_-_Reports/fr#Graphs

The page Gramps_5.2_Wiki_Manual_-_Reports/fr will redirect to Fr:Manuel_wiki_pour_Gramps_5.2_-_Rapports which should contain an anchor called Graphs. This hidden anchor will take the user to a heading called Rapports_graphiques.

We don't need the user to translate the original link to:

Fr:Manuel_wiki_pour_Gramps_5.2_-_Rapports#Rapports_graphiques

In the past I have seen a translator translate such a link without knowing what they are doing. We end up with broken links.

[emyoulation]

The complication with that is handling of Redirects in MediaWiki.

appending the language after the anchor just disables the redirect AND drops the anchor.
So https://gramps-project.org/wiki/index.php/Gramps_5.2_Wiki_Manual_-_Reports#Graphs/fr just sees the "#Graphs/fr" as a dead anchor and stays at https://gramps-project.org/wiki/index.php/Gramps_5.2_Wiki_Manual_-_Reports

Redirects drop the anchor. And even if they did not, the Translators are not preserving the English anchor.

To preserve the anchor on the redirect, I had to insert span ID in English, and insert the language redirection after the page URL rather than the anchor.

This meant using the url:
https://gramps-project.org/wiki/index.php/Gramps_5.2_Wiki_Manual_-_Reports/fr#Graphs

So the URL needs the language redirection in a weird place or the URL needs to be fully translated.

There are multiple roadblocks to smooth translation of anchored help_url targets. So we need multiple options in order to work out the correct solution.

At the very least, this requires building a Weblate URL glossary to find all the English target URLs and anchors in those URLs. With a checklist, we can assess the SCALE of the problem before deciding which solution has the least overhead. Right now, we know too little.

[Nick-Hall]

This meant using the url:
https://gramps-project.org/wiki/index.php/Gramps_5.2_Wiki_Manual_-_Reports/fr#Graphs

So the URL needs the language redirection in a weird place or the URL needs to be fully translated.

Correct. We don't need the URL translated. Gramps can add the language code after the page and before the heading.

At the very least, this requires building a Weblate URL glossary to find all the English target URLs and anchors in those URLs. With a checklist, we can assess the SCALE of the problem before deciding which solution has the least overhead. Right now, we know too little.

Yes. This is why I am hesitant to add more translatable URLs into a maintenance release. We could be making the problem worse.

[emyoulation]

In that case, how about just grepping those .gpr.py files to eliminate the translation underscore for the help_url attribute and merging the vanilla URLs?

[Nick-Hall]

That is certainly an option to consider for v5.3. We would have to think about how to handle non-wiki URLs though.

[emyoulation]

Perhaps the help_urls could be merged into the master branch fairly soon? Then consistent GUI for accessing the wiki help links in the different plugin types might emerge from the 5.3 cycle?

besides non-wiki URLs and addons, it could consider a relative link. Most of these GitHub hosted addons include a README.md with preliminary docs. And they convey to the local installation. We don't have any way to display markdown documents on the desktops. GitHub interprets the markdown to serve pure HTML though.

[dsblank]

Perhaps we can come up with a solution and enable for Gramps 6.0?

[Nick-Hall]

Links to wiki pages should not be translated. See my reply on 22nd Mar.

However it does look like we need to enhance display_help to cope with the case where section="" and webpage contains a page with a link.

[daleathan]

Links to wiki pages should not be translated. See my #1648 (comment) on 22nd Mar.

same conclusion https://gramps-project.org/bugs/view.php?id=13562

[tosky]

Links to wiki pages should not be translated. See my reply on 22nd Mar.

But what does this mean exactly? That there should be a pull request to make those strings not translatable?

[emyoulation]

It means that we submitted a PR will incorrectly formatted help_url attribute strings in the Gramps Plugin Registration for the core plugins. (5.2 expanded support for the attribute to all plugin types. Prior to 5.2, only Gramplets were allowed that attribute.)

So, we have to eliminate all the _( ) translation wrappers and re-submit

[Nick-Hall]

I've made the following changes:

• Enhanced the display_help function to accept a section in the webpage.
• Added a "Help" button to the report and tool selector dialog.
• Removed the translation from the help urls.
• Added anchors to the French wiki pages for reports and tools.

The new help buttons work with the English and French wiki pages. Note that I am still using the v5.2 wiki for testing.

Next we have to decide what other formats, if any, should be accepted in the help_url.

[emyoulation]

These changes could potentially close multiple MantisBT issues:

• 0013562: Help does not properly adapt to non-english wiki pages or allow anchors
• 0013224: built-in 5.2.0 .gpr.py files missing needed Prerequisites and help_url lines
• 0011068: Change Help button for [Fan Chart graphical] report (and other reports) to point to report page instead of report index page
• 0013467: Enhance "Report Selection" & "Tool Selection" dialogs to show additional information &"Detailed Info" dialog in "Plugin Manger"

[emyoulation]

The GitHub README.md markdown file is common to the repositories. And those file tend to be installed with the addons. GitHub has a server-side tool that converts the raw text into a nicely styled HTML page that a browser can read. However, when local instead on a server, the browser tends go into an endless loop instead. It recursively opens tabs when no local application is associated with the .md filetype.

If Gramps checked for no .md filetype association and set one in that case, then perhaps there could be a Addon Help fallback? If no help_url is in the Gramps Plugin Registration file (or when the specified addon help_url address gives a 404 error), perhaps it could check the local file directory for that Addon for a README.md and view it.

[Nick-Hall]

Added support for full "http://" and "https://" urls. I'm adding the language extension to these. Is that correct?

Also added some unit tests for the display_help utility function.

[Nick-Hall]

Added issue references to commit messages.

Rebased.