ENB: Aha re snippets, gnx's and literate programming

[Edward K. Ream]

This Engineering notebook post discusses how to support code/text snippets in Leo. The Aha: gnx's are an underused resource!

I have been thinking about literate programming (LP), documentation, and related Leo issues. Some links:

- Dynamic Notebooks and Literate Programming

- #189: Better Support for UNL Navigation.

- #946: Create a way to isolate documentation in a subnode.

- #1035: References to nodes via gnx's or tags.

- Discussion of retiring @root.

These topics are all related to the wish to make Leo a better mimic of the original goals of LP, which morphs into the desire to allow references to snippets of code, especially in Leo's rst3 command.

Yesterday I realized that gnx's, the unique, unchanging part of each node, provides a way to identify snippets, much like org mode's code block:

@snippet <description>

<Lines of text or code>

@end-snippet

The snippet would be like a section definition. A snippet reference would be a text-based way of referring to a particular snippet.

Snippet references will contain the gnx of the node containing the snippet and the snippet description. Snippet descriptions need to be unique only within each Leo node.

Leo will search all open outlines for snippets, much like Leo searches for @button nodes when we right-click the @button node and choose "Find Script."

Using snippets in @rst trees

Inside @rst trees, Leo's rst3 command could support a new kind of @rst node:

  @rst-insert-snippet (description)

These nodes would insert the snippet into the rST output. The body text of @insert-snippet nodes would contain the gnx.

Using snippets in @file trees

Similarly, Leo might be able to incorporate snippets into external files using a new Leo directive:

     @insert-snippet (description)

Outlines must define all snippets referenced in @file trees. This constraint will likely ensure that the @file read logic will never fail to find snippets.

Summary

Using snippets, users, documents, and scripts can safely use text from all open outlines. Snippets are, in effect, permalinks, uniquely defined by the combination of gnx and description.

Snippets can become invalid only if the user permanently deletes the node containing the snippets.  Leo will provide tools for finding snippets, just as Leo can find the script corresponding to @button nodes.

Within @rst trees, snippets will provide all LP's features in a more Leonine way.

Snippets might also work in @file trees.  If so, snippets would provide most (all?) of the benefits of cross-file clones.

Edward

[tbp1...@gmail.com]

This sounds similar in concept to the scheme I came up with for the zettelkasten work.  Any zettel node can contain references to others by referring to their gnx.  To make it work in a practical way required a couple of scripts.  One of these scripts inserted the gnx of the node to be referenced, and also inserted a backlink into that node.

The big challenge in this kind of system is to keep everything in sync.  Trying to locate gnxs is fine;  trying to match any text that a person may edit is fragile and prone to getting out of sync.

[Edward K. Ream]

On Thu, Feb 25, 2021 at 7:14 AM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

This sounds similar in concept to the scheme I came up with for the zettelkasten work.  Any zettel node can contain references to others by referring to their gnx.  To make it work in a practical way required a couple of scripts.  One of these scripts inserted the gnx of the node to be referenced, and also inserted a backlink into that node.

Thanks for this reminder. I'll take another look at your work. Snippets would require similar scripts.

The big challenge in this kind of system is to keep everything in sync.  Trying to locate gnxs is fine;  trying to match any text that a person may edit is fragile and prone to getting out of sync.

Not a big problem, imo. Snippet descriptions need only be unique to a particular node. In the usual case, there will be only one snippet in the node, so the description isn't needed. A warning could be given if the description in the reference isn't the same as the description in the defintion. In any case, the gnx can't change, so it will be easy to have Leo link to the offending node.

Edward

[tbp1...@gmail.com]

One thing I found helpful in the zettelkasten node references.  When I inserted the gnx of a node into a referring node, I also inserted its headline.  The search script only used the gnx, but the headline was useful for the human looking at it.

An example:

:link: TomP.20200225100827.1 About Leo

[Edward K. Ream]

On Thu, Feb 25, 2021 at 8:58 AM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

One thing I found helpful in the zettelkasten node references.  When I inserted the gnx of a node into a referring node, I also inserted its headline.  The search script only used the gnx, but the headline was useful for the human looking at it.

Right. I'll do something similar.

Edward