ENB: Unbreakable UNLs: a status report

[Edward K. Ream]

This Engineering Notebook post discusses PR #3215, especially Thomas's valid concerns about compatibility. Despite mistakes, work is going well. Our collaboration has been a great success.

Consider this post an update to the PR's requirements, hehe.

Hot spots

The PR touches many files, but only the following are of concern:

- g.findUNL resolves legacy (path-based) unls (to a position).

- g.findGNX resolves new (gnx-based) unls.

- g.handleUNL opens other outlines using the file part of a legacy unl.

- LeoQtLog.put contained an ugly hack, now removed.

- p.get_UNL returns the (clickable) unl for p. This is not the same as p.gnx!

- backlink.py uses complex code found in g.handleUNL.

- The new section << About clickable links >> documents unls.

Testing

I have rewritten a unit test, TestGlobals.test_g_findGNX, but this test does not cover clicks in unls! I use leo/test/test.leo to test clickable links and error messages by hand.

File parts are broken

The PR mishandles the file part of legacy unls. I removed too much code in g.handleUNL. However, the legacy code was also buggy. It resolved file parts using Leo-specific paths!

Imo, g.handleUNL (or a new delegate) needs a new setting, say @data unl_path_prefixes. g.handleUNL will parse these data to create a dictionary. Keys will be outline names (as found in unls); values will be the first argument to os.path.join. So this setting will help convert outline names to absolute paths.

Aha! gnx-oriented unls should be allowed to contain file parts!

g.findUNL and g.findGNX now search for matches in all (open) outlines. This search was a failed experiment. I'll remove the code.

Compatibility

Two of Thomas's plugins break when p.get_UNL returns a gnx-based unl. We can't let that happen :-)

Otoh, I won't create a setting telling what p.get_UNL returns. That's too big a "mode switch" in Leo's heart. Such a switch would double Leo's testing load.

Most of Leo's core, including most plugins, should work regardless of what p.get_UNL returns. In most cases, all that matters is that Leo resolves unls to the proper position. Let's call this the round-trip property of unls. 

I'll also revise the backlink plugin. It contains horrid legacy code from g.handleUNL. This code must go.

A new setting, say @string unl-kind, will tell what kind of unl appears in the status line.

Summary

I'll work with Thomas to ensure his plugins survive this PR with minimal changes. Most of Leo's core and plugins should continue to work as they are.

See the PR for the complete to-do list. The highlights:

- Make file parts work again.

- Allow file parts in gnx-oriented unls.

- @string unl-kind will tell what appears in the status line.

- @data unl_path_prefixes will contain prefixes to convert relative paths (in unls) to absolute paths.

Please continue testing. You can use test.leo to test clickable unls and error messages.

Keep your comments and bug reports coming! There is no rush.

Edward