Why gnx-based unls are important

[Edward K. Ream]

This post explains why PR #3215 (gnx-based unls) is a milestone in Leo's history.

gnx-based unls are a fundamental resource comparable in importance to @clean and cff:

- Unls won't break if you rename or move a node.

- Leo supports platform-independent cross-file unls.

- Creating gnx-based unls is dead easy.

Leo now contains significant new resources related to gnx-based unls:

@data unl-path-prefixes helps resolve unls to different paths on different platforms. Most users need to know only about this setting.

Leo provides two other resources for plugins:

g.parsePathData parses such @data nodes to a python dict.

g.openUNLFile(c, s) resolves s (the file part of an unl) to a commander, defaulting to c if no resolution is possible. This function contains an Easter Egg. It will return c immediately if s specifies the active outline.

Plugins can monkey-patch g.openUNLFile to gain complete control over how Leo resolves unls.

Summary

gnx-based unls are a fundamental resource comparable in importance to `@clean` and cff. Creating unbreakable cross-file unls is dead easy.

Leonistas will likely find creative new uses for unls. For example, a script could scan a document, possibly contained in different outlines, converting unls to links for markup/reStructuredText.

Most users need to know only about the @data unl-path-prefixes setting. g.parsePathData parses such @data nodes to a python dict.

Plugins can monkey-patch g.openUNLFile to gain complete control over how Leo resolves unls.

All of your questions and comments are welcome.

Edward

P.S. Plugins can also alter @data unl-path-prefixes programmatically by calling c.config.set. Like this:

c.config.set(kind='data', name='unl-path-prefixes', val=lines)

Unit tests for leoGlobals do this using LeoUnitTest._set_setting. Take a look :-)

EKR

[jkn]

Apologies for not fully following all of the recent good work here. I meant to mention this earlier but just wanted to check this 'platform independent' part.

On my Linux box, I get something in the lower 'status bar' like(*)

    unl:///home/jkn/path/to/myfile.leo#node-->subnode-->subnode

but when I run on my windows machine, the same file (shared via NextCloud) will not be  like this, shurely? What happens if I move my .leo file to a different location? Apologies if I am missing something fundamental...

(*) slightly separate point - right click in that area shows 'copy/CTRL+C and 'select-all/CTRL+A'. It seems like I have to do CTRL+A followed by CTRL+C. I'd suggest that if you have no part of the ... gurl? ... selected, then CTRL+C should implicitly select the whole entity before copying

Sorry if this is muddying the waters...

    Jon N

[Thomas Passin]

On Wednesday, July 5, 2023 at 12:57:33 PM UTC-4 jkn wrote:

Apologies for not fully following all of the recent good work here. I meant to mention this earlier but just wanted to check this 'platform independent' part.

On my Linux box, I get something in the lower 'status bar' like(*)

    unl:///home/jkn/path/to/myfile.leo#node-->subnode-->subnode

but when I run on my windows machine, the same file (shared via NextCloud) will not be  like this, shurely? What happens if I move my .leo file to a different location? Apologies if I am missing something fundamental...

I don't think the concept of operations for the new UNLs has been fully worked out yet (Edward may disagree!).  You could think of these old-style path-based UNLs to be something like URLs.  They are relative to the server (in this case, relative to some file system).  It's an interesting question as to what should or would happen for a network file system location.

 

(*) slightly separate point - right click in that area shows 'copy/CTRL+C and 'select-all/CTRL+A'. It seems like I have to do CTRL+A followed by CTRL+C. I'd suggest that if you have no part of the ... gurl? ... selected, then CTRL+C should implicitly select the whole entity before copying

I brought this up in another thread, and the response was that the the statusbar code was too tricky to tinker with lightly.  I wanted to have the "Copy" item disabled if nothing had been selected.  It's probably a Qt thing.

 

[Edward K. Ream]

On Wed, Jul 5, 2023 at 11:57 AM jkn <jkn...@nicorp.f9.co.uk> wrote:

On my Linux box, I get something in the lower 'status bar' like(*)

    unl:///home/jkn/path/to/myfile.leo#node-->subnode-->subnode

but when I run on my windows machine, the same file (shared via NextCloud) will not be  like this, shurely? What happens if I move my .leo file to a different location?

You are using a path-based (legacy) unl. Happily, Leo's new link-resolution logic will work on both path-based and gnx-based links.

Everything will work provided you define @data unl-path-prefixes in your myLeoSettings.leo file on each platform. These data should define an absolute path (platform-specific) for various .leo files.

For example, suppose you want to create unbreakable links to x.leo, y.leo, and z.leo throughout your outlines.

The body text of @data unl-path-prefixes should look like this:

x.leo: <full path to the directory containing x.leo>

y.leo: <full path to the directory containing y.leo>

z.leo: <full path to the directory containing z.leo>

That's all!!! Now your clickable links (within x/y/z.leo) will never break!

@data unl-path-prefixes is a defining feature of the new scheme. Links/unls no longer require long/absolute file names.

Edward

[Edward K. Ream]

On Wed, Jul 5, 2023 at 12:14 PM Thomas Passin <tbp1...@gmail.com> wrote:

> I don't think the concept of operations for the new UNLs has been fully worked out yet.

I know of no problems whatsoever with gxn-based unls.

Leo's new link-resolution code significantly improves the operation of legacy (path-based) links/unls.

Please comment in PR #3424 if you have a specific complaint.

Edward

[jkn]

How does the current scheme address the situation of two identically-named files in different directories?

[Edward K. Ream]

On Wed, Jul 5, 2023 at 5:27 PM jkn <jkn...@nicorp.f9.co.uk> wrote:

How does the current scheme address the situation of two identically-named files in different directories?

No. Perhaps I should restore the code that allows full paths for new unls. Otoh, I think this is mostly a theoretical concern.

Edward

[HaveF HaveF]

Everything will work provided you define @data unl-path-prefixes in your myLeoSettings.leo file on each platform. These data should define an absolute path (platform-specific) for various .leo files.

Does that means I can set  @data unl-path-prefixes  in my current leo file @settings node to specify a specific x.leo file path?

Btw, I do believe gnx-based unls is important, but the current display format lack some readability. 

Could it possible to add some readable path string to the end of the unls? just for human?

unl:gnx:///Users/mac/.leo/workbook.leo#mac.20230706111222.1

could be better:

unl:gnx:///Users/mac/.leo/workbook.leo#mac.20230706111222.1?2023-07-06/leo-note

If we don't support this, we have to describe what the current unl is about...

 

[Thomas Passin]

This is why I am sticking with the legacy format for the status bar.

[lewis]

In myLeoSettings.leo I have:

@string unl-status-kind = gnx

However the status bar still shows legacy format, it does not show links in the gnx format:

unl:gnx//G:/My Drive/editor/workbook.leo#lewis.20170803232020.1

Do I need to add another setting?

[Edward K. Ream]

On Wed, Jul 5, 2023 at 10:27 PM HaveF HaveF <iamap...@gmail.com> wrote:

Everything will work provided you define @data unl-path-prefixes in your myLeoSettings.leo file on each platform. These data should define an absolute path (platform-specific) for various .leo files.

 

Does that means I can set  @data unl-path-prefixes  in my current leo file @settings node to specify a specific x.leo file path?

Yes. I have been meaning to point out this fact.

This morning I'll be writing a new Engineering Notebook post discussing the fine points of PR #3215, aka the big PR.

This post will be pre-writing for comments in PR #3424, aka the tweaks PR.

The big PR already has too many comments. Comments in the tweaks PR will form the basis for our discussions.

Edward

[Edward K. Ream]

Works for me in devel.

Does your local .leo file define @string unl-status-kind = legacy ?

Edward

[lewis]

Sorry, I realise my previous post was unclear.

The status bar still shows legacy format

unl://G:/My Drive/editor/workbook.leo#Home

[Edward K. Ream]

On Wed, Jul 5, 2023 at 10:53 PM Thomas Passin <tbp1...@gmail.com> wrote:

This is why I am sticking with the legacy format for the status bar.

What do you mean by "This"?

Edward

[Edward K. Ream]

On Thu, Jul 6, 2023 at 7:54 AM lewis <lewi...@fastmail.com.au> wrote:

Sorry, I realise my previous post was unclear.

The status bar still shows legacy format

unl://G:/My Drive/editor/workbook.leo#Home

I repeat. Everything works for me.  Examples (with settings as shown in myLeoSettings.leo):

@string unl-status-kind = gnx

unl:gnx://ekr.leo#ekr.20200316054710.1

vs:

@string unl-status-kind = legacy

unl://ekr.leo#--- recent settings & scripts--> Recursive import script

Edward

[Thomas Passin]

[lewis]

No, the local file does not have @string unl-status-kind = legacy

Only myLeoSettings.leo has @string unl-status-kind = gnx

Strange. Both my desktop and laptop have this behaviour. I'll keep investigating.

[Thomas Passin]

I have @string unl-status-kind = legacy set in myLeoSettings.leo, and the status bar does show the path-based UNL.  I added a setting @string unl-status-kind = gnx to my workbook, restarted Leo, and for that outline, I see gnx-style addresses in the status bar.

Leo 6.7.4-devel, devel branch, build 947ea935f5
2023-07-06 08:01:34 -0500
Python 3.11.4, PyQt version 6.4.3
Windows 10 AMD64 (build 10.0.19045) SP0

[lewis]

I updated to build 947ea935f5 and the status bar now shows gnx format.

Previously build c4434257ff was installed.

[Edward K. Ream]

On Thu, Jul 6, 2023 at 8:05 AM Thomas Passin wrote:

What do you mean by "This"?

What @iamap wrote:

"Btw, I do believe gnx-based unls is important, but the current display format lack some readability. 

Could it possible to add some readable path string to the end of the unls? just for human?

Enough. Let's use what we have. There is no need for complex feature proposals that solve non-existent problems.

The workaround: put a comment above the url/unl. An example from my leoPy.leo:

=== PR #3215: mypy links
unl:gnx://leoPy.leo#ekr.20230318040137.1

Clicking on the unl:gnx: link takes me to the node whose headline is "=== PR #3215: mypy links".

Yesterday I discussed using such links as a lightweight alternative to clones.

Edward

[Edward K. Ream]

On Thu, Jul 6, 2023 at 8:06 AM lewis <lewi...@fastmail.com.au> wrote:

No, the local file does not have @string unl-status-kind = legacy

Only myLeoSettings.leo has @string unl-status-kind = gnx

Strange. Both my desktop and laptop have this behaviour. I'll keep investigating.

What branch are you in?

Edward

[Edward K. Ream]

On Thu, Jul 6, 2023 at 8:19 AM Thomas Passin <tbp1...@gmail.com> wrote:

I have @string unl-status-kind = legacy set in myLeoSettings.leo, and the status bar does show the path-based UNL.  I added a setting @string unl-status-kind = gnx to my workbook, restarted Leo, and for that outline, I see gnx-style addresses in the status bar.

Thanks for testing!

Edward

[Edward K. Ream]

On Thu, Jul 6, 2023 at 8:26 AM lewis <lewi...@fastmail.com.au> wrote:

I updated to build 947ea935f5 and the status bar now shows gnx format.

Previously build c4434257ff was installed.

Good. Keep on testing. Detours don't matter :-)

Edward

[lewis]

On laptop build 947ea935f5 works correctly.
However on PC 947ea935f5 does not show gnx-style format.

Here is log from PC updating to build 947ea935f5

$ git pull
remote: Enumerating objects: 85, done.
remote: Counting objects: 100% (85/85), done.
remote: Compressing objects: 100% (43/43), done.
remote: Total 85 (delta 58), reused 69 (delta 42), pack-reused 0
Unpacking objects: 100% (85/85), 47.31 KiB | 13.00 KiB/s, done.
From https://github.com/leo-editor/leo-editor
   d845b1024..947ea935f  devel                 -> origin/devel
 * [new branch]          ekr-3423-node-history -> origin/ekr-3423-node-history
   2534f31b7..9c1261cd8  ekr-dmypy             -> origin/ekr-dmypy
   f587fb5f7..f3ae2e5cb  ekr-tweak-unls        -> origin/ekr-tweak-unls
   d845b1024..947ea935f  felix-server5         -> origin/felix-server5
Updating d845b1024..947ea935f
Fast-forward
 leo/plugins/freewin.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

I repeated git pull:

$ git pull
Already up to date.

[HaveF HaveF]

947ea935f5 works for me. MacOS

--

--
Sincerely,

HaveF

[Thomas Passin]

My computer is a Dell Windows-10 laptop.  The status bar display seems to be working as intended.

[lewis]

I noticed myLeoSettings.leo file has node structure:
@settings
UNLs
    >@string unl-status-kind = gnx

Any Leo user knows that "This @settings tree contains all active settings. Settings outside this tree have no effect."
I moved the UNLs node under @settings and all fixed. :)

Why did I make that mistake? I copied the UNLs node from leoSettings.leo file. The first UNLs node I saw was a clone which is outside the @settings tree.
What is the reason for using clones in leoSetting.leo file?

[HaveF HaveF]

I noticed myLeoSettings.leo file has node structure:
@settings
UNLs
    >@string unl-status-kind = gnx

What is the reason for using clones in leoSetting.leo file?

I guess this is just Edward's cff workflow :D It's just not cleaned up

--

--
Sincerely,

HaveF

[Edward K. Ream]

Right. I make clones of what I'm doing and move the clones to the end of the outline.

One of the checklist items for any release is to remove top-level clones from various outlines.

Edward

[Thomas Passin]

I asked about the duplicate somewhere else (can't find it just now).  Edward said the extra node wasn't harmful and would be a reminder for him which he would remove later.

[lewis]

OK thanks. It's my mistake when editing my settings.