ENB: Rethinking UNL's

[Edward K. Ream]

UNL's are supposed to be a way of referring to nodes (positions). Alas, the machinery for handling such things is riddled with kwargs (keyword arguments) and other problems.

Imo, the present code is attempting to solve related problems by fiddling with kwargs. Instead, it would likely be better to solve the following tasks separately:

Task 1: clickable links

The mypy, pylint, and pyflakes commands create clickable links to erroneous lines.  At present, the code that creates and handles these links uses the UNL machinery, but in fact this is not necessary.  Indeed, these commands create callbacks bound to mouse-click events. There is no need to use UNL's at all.

The clickable links are "ephemeral". They exist in the log pane. Leo never saves them. The links are guaranteed to exist when they are created, and the links are unlikely to become unusable in normal practice. The necessary data are:

- The name of an external file.

- A line number (offset) within the entire external file.

Task 2: bookmarks and backlinks

Terry Brown's bookmarks and backlink plugins use UNL's to create more permanent data.  The necessary data are:

- The name of the .leo file.

- A description of the position of the desired node.

Archived positions probably did not exist when Terry created these two plugins, but archived positions would be a natural alternative to UNL's.

Task 3: The status line

Leo displays the UNL of c.p in the status line. The format is:

- The path to the .leo file.

- A list of ancestor headlines, separated by "- - >" (without the spaces).

I don't recall whether Leo supports moving to other nodes based on control-clicking these text UNL's.

Plans

Imo, it would be best to use separate code and data for each task.

At present, all UNL's eventually become a plain string, with an arcane format for handling various offsets within lines, nodes, and files. It would be better to represent the necessary data in a task-specific way, possibly with a Python dict, just like JSON.

Summary

Leo's UNL-related code needs a thorough review.  Callbacks probably do not need UNL's at all.

PR #2406 will describe the work. Issue #2376 must wait until the dust clears.

All questions and suggestions are welcome.

Edward

[Edward K. Ream]

On Tuesday, February 8, 2022 at 10:33:53 AM UTC-6 Edward K. Ream wrote:

UNL's are supposed to be a way of referring to nodes (positions). Alas, the machinery for handling such things is riddled with kwargs (keyword arguments) and other problems.

Imo, the present code is attempting to solve related problems by fiddling with kwargs. Instead, it would likely be better to solve the following tasks separately:

Still true, but there is a hitch. It's natural to represent UNL's as strings, so that they can be the target of <a> elements in the log pane. This fact makes it more clumsy to use alternative representations such as archived positions or JSON. You could say that the html tail is wagging the dog, but the problem is real.

Edward

[Edward K. Ream]

On Tuesday, February 8, 2022 at 10:33:53 AM UTC-6 Edward K. Ream wrote:

It's natural to represent UNL's as strings, so that they can be the target of <a> elements in the log pane. This fact makes it more clumsy to use alternative representations such as archived positions or JSON. You could say that the html tail is wagging the dog, but the problem is real.

The present code in PR #2406 works, and perhaps I should leave it as it is. Still, it's tempting to try to simplify UNL's and the related code.

The general strategy:

- Create a single simplified UNL format for all UNL's. g.findUNL will support this new format and legacy UNL formats.

- Avoid using UNL's for special purposes. For example, the status line can and should show simplified UNL's without help.

- The backlink and bookmarks plugins will generate new UNL's from now on. g.findUNL will ensure that legacy links will continue to work.

- Add unit tests for the backlink and bookmarks plugins.

Summary

The present code works. There is no guarantee that further simplifications will be successful, but imo it's worth a try.

Edward

[Edward K. Ream]

On Friday, February 11, 2022 at 7:05:02 AM UTC-6 Edward K. Ream wrote:

> The present code works. There is no guarantee that further simplifications will be successful, but imo it's worth a try.

Aha: Create a new branch, based on ekr-unl2 (not devel), called something like ekr-unl2-kwargs. The Aha is that the branch name indicates what the base branch is. The new branch will allow me to experiment safely.

Edward

[Edward K. Ream]

On Friday, February 11, 2022 at 9:13:41 AM UTC-6 Edward K. Ream wrote:

>> The present code works. There is no guarantee that further simplifications will be successful, but imo it's worth a try.

I have just discovered an Easter Egg in the status line class: right-clicking the status line opens a popup menu that contains a "Toggle UNL mode" item. I would like to delete that item and instead always show the simplified UNL.  We shall see how that works out :-)

Edward

[tbp1...@gmail.com]

I discovered that a few days ago myself.  I've become interested in UNLs for a project, so I'm starting to learn about them.  It seems to me that this feature provides a way for a person to get the correct escaped form of an UNL to paste into a page for navigation purposes.  That could be valuable.  OTOH, a command that could directly put the selected node's escaped UNL into the clipboard would do the same job, and arguably be a better way to do it.  After all, the only purpose for that little "Easter Egg" must be for a user to select Copy from its menu.

[Edward K. Ream]

On Fri, Feb 11, 2022 at 4:10 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

I discovered that a few days ago myself.  I've become interested in UNLs for a project, so I'm starting to learn about them.  It seems to me that this feature provides a way for a person to get the correct escaped form of an UNL to paste into a page for navigation purposes. 

Imo, the status line should always show a UNL suitable for navigation. I'm working on it now.

OTOH, a command that could directly put the selected node's escaped UNL into the clipboard would do the same job, and arguably be a better way to do it. 

I'll add that command if it doesn't already exist :-)

Edward

[tbp1...@gmail.com]

Speaking of Easter Eggs, do you remember the one in quicksearch (i.e., the Nav pane)?  I found it in the code this morning, and it's even called an easter egg by a comment.  Typing "m" shows you all marked nodes, and typing "h" shows the history list (I think that is the history of the minibuffer, isn't it?).  Wish I had known earlier - I would have used "m" a lot. (see ~/git/leo-editor/leo/core/LeoPyRef.leo#Code-->Plugins-->User interface--> Qt only plugins-->@file ../plugins/quicksearch.py-->class LeoQuickSearchWidget (QWidget)-->quick_w.returnPressed).

[jkn]

Hi Edward

    Is your 'aha' here the idea of 'hierarchical' git branch names? I do that myself but have never been sure how common or recommended a practice it is.

I tend to use to underscores to separate out the hierarchy; I have seen other use the slash  character, but only going one deep:

git checkout -b test/...

git checkout -b bugfix/...

I haven't checked whether there is a technical reason for only going one deep ... except for the issue of losing track of branches, which of course I've never done, ooh no...

J^n

[Edward K. Ream]

On Sat, Feb 12, 2022 at 5:40 AM jkn <jkn...@nicorp.f9.co.uk> wrote:

> Is your 'aha' here the idea of 'hierarchical' git branch names?

Yes.  And not just names, but the branch structure itself.

> I haven't checked whether there is a technical reason for only going one deep ... except for the issue of losing track of branches, which of course I've never done, ooh no...

Hehe.  One level had better suffice.

Edward

[Edward K. Ream]

On Fri, Feb 11, 2022 at 4:25 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

Speaking of Easter Eggs, do you remember the one in quicksearch (i.e., the Nav pane)? 

Nope :-)

Edward