Re-targeting missing online Help

Help
1

I am hoping to experiment with resetting a few mis-targeted Help buttons for various Gramplets. This would help me submit more actionable enhancement requests.

But my experiments in changing a Help button target have been failing.

Unfortunately, the wiki documentation for how to set the URL for an add-on Gramplet Help button is practically non-existent. I tried adding the line as it said and then re-started Gramps. But the Help button still tries to go to the original webpage. (‘Tries’ because that subsection never existed… and it is the wrong page anyway.)

How does the help_url line work in the .gpr.py add-on registration? Is the line order important? And is there Translation support?

The Gramplet Help is often overlooked because the button is only visible when a gramplet is detached from the sidebar/bottombar/dashboard. (Just like the Configure options get overlooked because the icon are in an unexpected place relative to the Gramplet.)

For instance, I wanted to tweak the Collections Clipboard Gramplet add-on to point its Help button to the specific wiki page. (Unfortunately, the default Help points at the generic built-in Gramplets page (with an invalid subsection). This particular gramplet didn’t have a help_url line at all.

There’s a 4 year old feature request to fallback the default to the generic add-on list subsection. And there’s a 6 year old GEPS that is partially addressed.

ClipboardGramplet.gpr.py

#------------------------------------------------------------------------
#
# Register the Gramplet
#
#------------------------------------------------------------------------

register(GRAMPLET,
         id="Collections Clipboard Gramplet",
         name=_("Collections Clipboard"),
         description = _("Gramplet for grouping collections of items to aid in data entry."),
         status = STABLE,
         version = '1.0.41',
         gramps_target_version = "5.1",
         height=200,
         gramplet = "ClipboardGramplet",
         fname="ClipboardGramplet.py",
         gramplet_title=_("Collections Clipboard"),
         )

revise version Line 12

         version = '1.0.42',

insert Line 14

         help_url="Collections_Clipboard_Gramplet",

(Collections Clipboard Gramplet version 1.0.41; Gramps version 5.1.3; Operating System: Win10)

2

Just tried this here - Linux, gramps 5.1.2 - and the change works for me; but only if you remove the gramplet from the dashboard then restart gramps.

cd ~/.gramps/gramps51/plugins/ClipboardGramplet
vim ClipboardGramplet.gpr.py
edit to include those above changes, save file
start gramps , remove Collections Gramplet (if it was included on your Dashboard display)
restart Gramps, add Collections Gramplet to your Dashboard, then detach the same and click on the Help button

Addon:Collections Clipboard Gramplet - Gramps opens in browser window
Help → Plugin Manager shows Version: 1.0.42

3

I am no expert but…

The Collections Clipboard is probably more complex than other addons because it is referencing the builtin regular Clipboard. This is why its Help button points to the help wiki for the builtin clipboard and not the addon clipboard.

____________

As to Help buttons on other addons I have found no addons with help_url in its gpr.py file. (I have not checked all of them… yet)

In the application .py file, every addon I have checked has used

def on_help_clicked(self, dummy):
    """ Button: Display the relevant portion of GRAMPS manual"""
    display_url(WIKI_PAGE)

display_url is a standard function defined in the gramps\gui\display.py code and imported in the Gramps Modules portion of the code.

from gramps.gui.display import display_url

WIKI_PAGE is defined in the Constants section.

WIKI_PAGE = 'https://gramps-project.org/wiki/index.php?title=BirthOrderTool'

So the page in the wiki is just simply defined by its complete URL

____________

In the display.py file there is another defined function display_help()

I Think ?? this function would take the help_url if set in a gpr.py file and of course if the function was imported.

I will test this theory tomorrow.unless someone with more knowledge either confirms or debunks the idea.

1 Like
4

OK. That’s the key then. Remove & re-add.

I would’ve thought a restart would re-register. Do you think that is a bug? There are 12 sidebars and 12 bottombars & a dashboard. That’s a lot of interface to clean for each update.

6

The behaviour we are encountering is not a bug, it’s a quirk of the way python works.

When a python program is first run / executed it generates, or regenerates if it detects a change, the associated .pyc (the compiled python) file ready for the application to use.
It may be a case that the gramplet .pyc file doesn’t get regenerated at the same time as Gramps itself, thus it requires its removal - but that’s probably by design. Others will be able to answer why that may be better than I can .

7

So perhaps some sort of forced re-registration would be a solution.

Thanks for the good answer & pointers.

I have no experience with translations. Do you suppose this insertion actually ought to be :

To support re-targeting the Help to a translated Help wiki page for translated Gramplet GUIs?

8

Hmmm. This is going to take a bit of wading to explore.

Thanks for the reply Dave!

9

I spent a bit of time on this and it really does start to get complicated.

Looking at ~/.gramps/gramps51/plugins/ClipboardGramplet/

There is a .pyc file placed in a directory named pycache and this would be from the *.py file in the parent directory. However, in that parent directory are 2 .py files

It appears that the gramplet .pyc files are generated (by Gramps) when they are added to the Dashboard by the user. (This actually makes sense as if you’ve never used a particular gramplet, this action makes it immediately available.)

The 2nd file .gpr.py file is dealt with separately by the PluginRegister , gen/plug/_pluginreg.py and that would be compiled upon the startup of Gramps. That’s also the file we are editing to get your help_url to change so it’s treated differently, even though they are part of the same object.

You can play around with .pyc deletions and the timing thereof but it doesn’t always do what is expected (in one case I had the version update as expected yet the help_url remained as an old version ? Go figure !)

I think it’s safest to just delete the gramplet / s from the Dashboard before restarting Gramps. It requires less coffee and truth tables remain simple and sane.

OR…

If you want to try a developers workaround. (Caveat: I assume you have a testing version where you make these edits, ie; not your working and most valued tree)

export PYTHONDONTWRITEBYTECODE=1

Add that to your environment, and start Gramps from / in that terminal.

You probably need to remove the existing .pyc files that we are dealing with…

~/.gramps/gramps/gen/plug/pycache/_pluginreg.cpython-37.pyc
~/.gramps/gramps51/plugins/ClipboardGramplet/pycache/ClipboardGramplet.cpython-37.opt-1.pyc

I did a test with this and it improves the process, but you’ll want to fully test it though.

With this, you can perform the edits to the ClipboardGramplet.py file, save it then delete the gramplet from the Dashboard, then open Help → plugin Manager → Check for updated addons now.
That last step will register your .gpr.py changes so that when you add the gramplet to the Dashboard your changes will be registered.
And all this without restarting Gramps itself.

I don’t know the mechanics of calling a translated page, but it would make sense to call one. However, what happens when there is no translated page, will it fallback to the english version? … or ideally generate a call to translate the english page perhaps?

2 Likes
10

I suspect that making a localization friendly help URL takes a bit more. It probably needs to have that subsection header added in another English checklist text file. Otherwise, it seems like the each translator would have to comb through the module’s Python code.

11

So … it … seems. Whew. I’m trying to learn a lot with this!

Thanks for taking the time to write that out!

12

The coding for Translation page implies that it IS that easy. But keeping the wiki page catalog from becoming a cluttered mess implies otherwise.

It seems like keeping the page/section title in english with a leading (or trailing) language code would make maintenance easier. It means less fumbling around when finding a newly inserted hotlink in the wiki. Or in the Category index.

Maybe the _() function call should include a hint. Like a hint that says “wikipage URL” or “wiki-subsection anchor”. (Hmmm. URL could ambiguous. This particular situation is relative to a https://www.gramps-project.org/wiki/index.php/ base URL. Yet ‘relative’ has a lot of ambiguous baggage in a genealogy. So that term cannot be in the hint either.)

Unfortunately, the wiki intro of the hint is unclear as to whether the string being translated or the the hint is before the vertical bar (|). It gives an example but then fails to properly reference the example’s EXACT TEXT in the explanatory text.

1 Like
13

The problem is that there are as many ways that the Help button are coded as there are coders.

As far as I can figure out, there are addons that utilize the help_url in their gpr.py files. Apparently the Help coded within the gtk files will utilize it with no further coding. But then an addon like Form will also code the button with the same information.

And then other coders will code the button as described above.

So if there are addons that you feel need to have their Help updated, simply try adding the help_url to their gpr.py file. That may be all it takes and you can file a bug accordingly. (Or also learn to file a Pull Request.)

Check out the code for the functions.

gramps\gui\display.py

14

This is NOT working for me.

After adding the help_url line to ClipboardGramplet.gpr.py the added information does get added to the URL. But it gets added to the existing URL that points to the builtin clipboard help and never opens the addon clipboard page.

15

Using “help_url”.
If it is in the gpr.py file, Gramps will set up the ‘Help’ button on floating Gramplets to start a web browsing session with the url.

If the help_url starts with “http://” it will be used as is.
Otherwise it will get the “http://gramps-project.org/wiki/index.php?title=” prepended to the help_url, and may get a language extension such as “/nl” appended at the end, if the operating language is one of ‘nl’ ‘fr’ ‘sq’ ‘mk’ ‘de’ ‘fi’ ‘ru’ ‘sk’.

You should NOT translate the help_url, unless you specifically want to create web pages with the translated names.

If you change any .py file, including the gpr.py file, you should shut down Gramps and restart it to see the results. Most of the contents of those file can be cached in memory so change may not bee seen until you restart.

2 Likes
16

After changing JUST those 2 lines in the
C:\Users<username>\AppData\Roaming\gramps\gramps51\plugins\ClipboardGramplet\ClipboardGramplet.gpr.py
I ran tests detaching the Collections Clipboard from every sidebar/bottombar/dashboard and from the built-in Clipboard. The clipboard help button opened:
Gramps 5.1 Wiki Manual - Navigation - Gramps

All the Collections Clipboard help buttons opened:
Addon:Collections Clipboard Gramplet - Gramps

I did have to “restore default gramplets” on all the split panes then re-add & detach the gramplets before the paths would reset.

17

Thanks for the reply. Expanded the wiki section with the provided information.

Is the appending of a language extension limited to just those operating languages? Or are they examples from a larger set?

I did not have success with Shut Down & Restart. The changes only seemed to re-register when the Gramplet was deleted from the Gramplet pane and re-added.

18

I just did that and the help_url is now sending it to the correct help page.

Very odd behavior. :woozy_face:

And in case someone is keeping track, I always relaunch Gramps to register changed files. Changing the version number would cause Gramps to ignore an addon’s update which may include more substantial code changes.

1 Like
19

And I have a clue to the problem.

In the user’s version folder (i.e. gramps51) are the ini files that control the view setups which include which addons are set in the bottom- and sidebars. One of the settings is help_url=.

Apparently this setting is only set at the time the addon is added to the view and not updated just because its gpr.py file changed.

2 Likes
20

OK. That makes it a bit messy for testing Manual Edits. I have verified that that adding in one pane leaves the other INIs untouched. Just as you suggested they might.

But I suppose that using the plug-in management tools will strip the appropriate sections from gramplet panes INIs during the updates too. That will be a good bit harder item to test.

23

I just did some experiments with Kari’s MultiMerge Gramplet. I was able to re-target its help_url to https://github.com/Taapeli/isotammi-addons/tree/master/source/multimergegramplet/README.md and filed an issue to change its .gpr.py file.

But several developers tend to bundle starter docs with the downloads. What would a help_url appear which points to a /docs/README.html path relative to the .gpr.py file location?

(Windoze does NOT have a built-in markdown viewer. Does Linux or macOS? Either way, converting the Markdown to HTML for a local file seems a prudent step to ensure maximum compatibility. GitHub’s server renders the README.md to HTML on the fly.)