Proposal: @template nodes and related commands

[Edward K. Ream]

This proposal incorporates ideas from the "Semantics of coping clones" thread. Imo, this proposal solves all the problems that have been discussed, with additional benefits.

Motivating ideas

1. We want one or more indivisible (atomic) operations that copy a template and paste it following c.p. Because the operations are atomic, they will work as expected when done twice.

2. We want a flexible, general way of indicating which nodes are candidates for being clones after the paste.

3. We want to refer by name to templates defined in myLeoSettings.leo or leoSettings.leo.

@templates and @template nodes

Leo will support @templates and @template nodes in @settings trees. Only one @templates node should exist in an @setting tree.

Each @template node should be a direct child of the single @templates node. Each @template node will specify a template name, like @template django-template. The template consists of all the descendants of the @template node. A template can contain multiple nodes.

Template-related commands and methods

The prompt-for-template command will enter the minibuffer and aks the user for the name of a template. Tab completion will show the existing template names.

The c.insertTemplateByName(template_name) and c.insertTemplate(p) methods will make it easy to insert templates using @button or @command nodes.

All these commands and methods will be atomic: they will find a template, copy it to the clipboard, and then do paste-retaining clones.

Handling clones

All cloned nodes in the children of an @template tree become candidate clones. They will actually become clones if the paste-retaining-clones makes them clones.

Now we can see why the @templates node exists. It provides a convenient place to define clones outside of any @template (singular) node. In effect, these external clones mark nodes inside @template nodes as being candidate clones. There is no need to use marks.

Note: If the gnx of a cloned node in a template matches the gnx of any node in the file receiving the template, then the template node will become a clone after, say, c.insertTemplateByName. The user can "transfer" gnxs to templates in myLeoSettings.leo using paste-retaining-clones.

Summary

The scheme proposed here is more general and flexible than those discussed so far. It will require straightforward extensions of Leo's existing settings machinery. There is no need for an alternate version of paste-retaining-clones.

I encourage all questions and comments :-)

Edward

[Edward K. Ream]

On Wednesday, May 27, 2020 at 9:32:41 AM UTC-5, Edward K. Ream wrote:

There are several details about the proposal which I forgot to mention:

Writing the template

Writing the template is the tricky part. The write code will allocate new gnx's to all nodes that are not descendants of candidate clones.

If a node is a descendant of a candidate clone, then that node's gnx absolutely must not change! All clones (of the same node) are actually the same vnode. It makes no sense to have the children of "one" clone be different from the children of the "other" clone. Do you see?

Using the clipboard is optional

The benign "s" kwarg allows c.outlineCommands.pasteOutlineRetainingClones to get its input from a string instead of the clipboard. Therefore, the write code can might optionally write to a string rather than the clipboard. Otoh, writing to the clipboard may be better. I don't care much either way.

Edward

[vitalije]

I would only suggest to leave out settings file from the proposal.

It doesn't add anything substantial and it might lead to worse user experience (having to open settings file to change something, then save it and then restart Leo or reload settings).

Instead command can look in the current outline for the @templates node and work the same way as you proposed. This won't require any change to the configParser and config classes and user would be free to change template and immediately see the effects.

Vitalije

[Edward K. Ream]

On Wed, May 27, 2020 at 10:44 AM vitalije <vita...@gmail.com> wrote:

I would only suggest to leave out settings file from the proposal.

Sounds reasonable. If people want "global" settings that can be added later.

Hmm. If all templates are local, there is less need for prompt-for-template...

Edward

[Thomas Passin]

I'm liking this proposal.  My (limited) experience with writing commands is that at first, I only expect to use them within the one outline file I'm working on. The commands and shortcuts would live in the settings tree of that outline. Later, I may find I want to use them with other outlines.  At that time, I would copy my command and shortcut nodes to MyLeoSettings.leo.    So I wouldn't object to expecting a template to exist within a settings tree.  It could be local or global depending on what outline it was in.

I'm agnostic as to whether an @template tree could also be outside of a @settings tree.  But if it were outside, and the machinery already had been written that expects it to be in a @settings tree, then I think the extra effort to also process it somewhere else would not be needed.

[Edward K. Ream]

On Wed, May 27, 2020 at 2:08 PM Thomas Passin <tbp1...@gmail.com> wrote:

> I'm liking this proposal.  My (limited) experience with writing commands is that at first, I only expect to use them within the one outline file I'm working on. The commands and shortcuts would live in the settings tree of that outline.

When I awoke this morning, I saw that my proposal could collapse further, as follows:

1. We only need a single command, say duplicate-template, that can be applied to any node. This command will do the following:

- Write the selected node (including all descendants) to a string s, in clipboard format. See the next section for details.

- Call c.outlineCommands.pasteOutlineRetainingClones(s) to do paste-retaining clones.

2. You can apply duplicate-template applies to any node. This means that you can put templates anywhere, and there is no need for explicit support for @template <command-name>.

3. To transfer a node that you use as a template to another file, just copy the template and then do paste-retaining clones.  After that, you can adjust which nodes you want to be cloned. Clear?

Reassigning gnx's

The write code won't be easier said than done, because it won't have to change vnodes after the vnodes have been created. Instead, the write code only needs to create a clipboard-formatted string with the desired gnx's.

Leo's copy-node command just calls fc.putLeoOutline. The duplicate-template command will temporarily reassign gnx's before calling fc.putLeoOutline and then restore the original gnx's afterward.

Finally, the duplicate-command will do the paste-retaining clones, with the already correct gnxs. No change at all to the paste-retaining-clones code will be necessary.

Summary

A single command, duplicate-template, should suffice. This command will copy c.p as a template, and paste the resulting copy after c.p.

The command's write code is the heart of this command. The write code will copy c.p to a string, in clipboard format, as with the copy-node command. Unlike the copy-node command, the write code will temporarily allocate new gnx's to all nodes that are neither clones nor descendants of a clone.

All comments and questions are welcome.

Edward

[vitalije]

Look at this thread. I have implemented paste command that does what was asked for: keeps the identity of all nodes that have clones outside copied tree. Internal clones treats the same way as past-node.

Vitalije