Documentation on the proper use of sections in the current version of leo

[Shakeeb]

As an old user of leo who has started again with current versions, is it still possible to use <<section>> definitions and references everywhere with  tangle and untangle. These commands are still available but I can't seem to seem to find documentation for section use.

In my recent experiments with sections there is no issue for a <<section id>> which is defined in a child node, but if I try to re-use the definition through the outline (for a repeatable pattern for example), it doesn't work so well. Indeed, I recently got stuck trying, in an @clean file, to re-use a section definition above @others in the the @others nodes, which didn't work.

S

[Edward K. Ream]

On Mon, Jun 22, 2020 at 1:09 AM Shakeeb <shakeeb...@gmail.com> wrote:

As an old user of leo who has started again with current versions, is it still possible to use <<section>> definitions and references everywhere with  tangle and untangle. These commands are still available but I can't seem to seem to find documentation for section use.

Yes, Leo supports sections everywhere. They are documented here. However, sections should also be documented in Leo's Users Guide, in a chapter called "Markup Reference".  I've just created #1610 for this.

In my recent experiments with sections there is no issue for a <<section id>> which is defined in a child node, but if I try to re-use the definition through the outline (for a repeatable pattern for example), it doesn't work so well. Indeed, I recently got stuck trying, in an @clean file, to re-use a section definition above @others in the the @others nodes, which didn't work.

The typical way is to clone the "reused" definition and move a clone as a child of each node containing a section reference. Does this work for you?

Edward

[Shakeeb]

On Tuesday, June 23, 2020 at 12:06:40 PM UTC+3, Edward K. Ream wrote

In my recent experiments with sections there is no issue for a <<section id>> which is defined in a child node, but if I try to re-use the definition through the outline (for a repeatable pattern for example), it doesn't work so well. Indeed, I recently got stuck trying, in an @clean file, to re-use a section definition above @others in the the @others nodes, which didn't work.

The typical way is to clone the "reused" definition and move a clone as a child of each node containing a section reference. Does this work for you?

This works, but frankly I find it a little unintuitive. If I define a section at any point in the tree, I would expect that in any body of a child of the section definition node you can naturally refer to the content of the section without having to clone.

For example if I have a block of code which I define in a section <<error cleanup>>, It would be a great to just refer to the <<error cleanup>> in the code of any child nodes without having to clone. From an implementation point of view, it's just a recursive substitution (on rendering).

To be honest, I have never used clones in any project, I tried a few times, but they distracted me from the natural structure of the outline, and there were issues about them back then that irritated me. But that's just me.

Incidentally, there'a nice symmetry with wikis with the concept outline above

<<section>> defined in a node, can be referred anywhere in the body of a node as <<section>> or =<<section>>

[[WikiWord]] defined in a node, using it as WikiWord or [[WikiWord]] can link back to the defining  node.

S

 

[Edward K. Ream]

On Tue, Jun 23, 2020 at 8:28 AM Shakeeb <shakeeb...@gmail.com> wrote:

The typical way is to clone the "reused" definition and move a clone as a child of each node containing a section reference. Does this work for you?

This works, but frankly I find it a little unintuitive. If I define a section at any point in the tree, I would expect that in any body of a child of the section definition node you can naturally refer to the content of the section without having to clone.

It's the other way around. If you refer to a section, the definition of the section must appear in one of the node's descendants. This behavior is never going to change.

Edward

[Félix]

Might have other sections with same name elsewhere in the tree, that have different content, so it has to be descendents only. otherwise, making two structures of 'insect' : and ant and a fly, I would have to distinguish section names with <<torso ant>>, <<antenna ant>>, <<torso fly>>, <<antenna fly>> instead of just <<torso>> and <<antenna>> in their respective descendants. 

[Shakeeb]

 Edward K. Ream wrote:

It's the other way around. If you refer to a section, the definition of the section must appear in one of the node's descendants. This behavior is never going to change.

I wasn't suggesting to change a current feature that is out in the wild (a 10 year transition from python2 to python3, taught us otherwise :-)

However, perhaps one can conceive conceive of an (analogous/orthogonal?) features that fit how programmers already think:

- <<section>> : use abstraction, define later 

- [[WikiWord]] two-way wiki references

- {{variable}} variable substitution -- define once, user later

- ((includes)) transclusion -- define once, include later 

In each of the above the double-bracket type is a headline, and then the magic happens in the bodies.

S

S

[Edward K. Ream]

On Wed, Jun 24, 2020 at 1:07 AM Shakeeb <shakeeb...@gmail.com> wrote:

 ...perhaps one can conceive conceive of an (analogous/orthogonal?) features that fit how programmers already think:

- <<section>> : use abstraction, define later 

- [[WikiWord]] two-way wiki references

- {{variable}} variable substitution -- define once, user later

- ((includes)) transclusion -- define once, include later 

In each of the above the double-bracket type is a headline, and then the magic happens in the bodies.

Please file an enhancement request, discussing in detail what each should do.

Better yet, you could write a plugin :-)

Edward

[T. Vlainić]

That functionality was present in old Leo versions (around 4.3) with @root-code directive.

[Shakeeb]

Fair enough :-), I will try to expand on this and write it up. 

S

 

[Shakeeb]

On Wednesday, June 24, 2020 at 7:51:14 PM UTC+3, T. Vlainić wrote:

That functionality was present in old Leo versions (around 4.3) with @root-code directive.

 Thank you for that. For a moment, I was confused about whether I experienced the feature or not (-:

S

 

[Edward K. Ream]

On Wed, Jun 24, 2020 at 11:51 AM T. Vlainić <tvla...@gmail.com> wrote

> That functionality was present in old Leo versions (around 4.3) with @root-code directive.

The @root code still exists to support existing code. However, its documentation has (on purpose) been removed. So you could say this feature has been deprecated.

Edward