Heads up: PR #4324 will need testing

[Edward K. Ream]

PR #4324 rewrites the code that handles Leo's directives. Imo, revising this code was essential. The new code has a simpler interface and is easier to understand. Work has gone well, aided by all of Python's code-checking tools.

This post highlights potential breaking changes that may arise from the PR. These changes:

- Arise from edge cases involving the subtle details about how Leo handles directives.

- Might cause Leo to write external files differently when next you write them.

The next section describes how to make your outlines immune from these effects.

Make all your @<file> nodes self-contained

We say that an @<file> node is self-contained if the write the contents of the external file will remain unchanged if you move the @<file> node within your outline. The following two guidelines will ensure that Leo will not change your external files unexpectedly:

- All @<file> nodes should contain exactly one @language directive.

- @comment, @delims, @encoding, @pagewidth and @tabwidth directives should only appear only in @<file> nodes.

Compatibility

I have taken care not to change Leo's operation unnecessarily. However, recent work has revealed unexpected edge cases in how Leo handles various directives. Some of these edge cases could be improved.

The code involved is complex. There are ample opportunities for mistakes in the PR. I may be mistaken about what the old code did. I may be mistaken about what the new could should do. Happily, the new code will be much easier to revise if I have made mistakes.

I think the changes are necessary. They are the precondition for handling issue #4323. It's not correct to think only of compatibility. That's looking only to the past. We must also look to the future. I'd like to ease the work of future maintainers and to help others to improve Leo.

Summary

There are ample opportunities for mistakes in the PR. There should be an extended period of testing. Some people may feel (temporary!) pain. However, the PR will benefit us all in the long run.

You can guard against problems by making all your @<file> nodes self-contained:

- Every @<file> node should contain exactly one @language directive.

- Don't put @comment, @delims, @encoding, @pagewidth and @tabwidth directives outside @<file> nodes.

All of your questions and comments are welcome.

Edward

[Edward K. Ream]

On Sun, Apr 6, 2025 at 4:41 AM Edward K. Ream <edre...@gmail.com> wrote:

> PR #4324 rewrites the code that handles Leo's directives.

Some clarifications:

I rewrote by cutting and pasting code from the old framework to the new. I intended to change nothing about how the new code actually works. Changes might come later, in one or more much smaller PRs.

I didn't mean to imply that all @<file> nodes should contain @comment, @delims or @encoding directives!

Far from it. It's probably best to avoid these three directives. Some details:

- Leo's default file encoding is c.config.default_derived_file_encoding or 'utf-8'.

  That is, @string default-file-encoding (utf-8) is the default when no @encoding directive applies.

- Python defaults to 'utf-8' encoding, so there is no need for a Python encoding line unless you use some other encoding.

- @comment and @delims are dangerous directives. Avoid them if at all possible.

All questions and comments are welcome.

Edward

[Thomas Passin]

On Sunday, April 6, 2025 at 5:41:51 AM UTC-4 Edward K. Ream wrote:

- @comment, @delims, @encoding, @pagewidth and @tabwidth directives should only appear only in @<file> nodes.

I strongly object to this one. I write files all the time that use @c and @pagewidth directives  even though they are not @files. Usually I expect to execute them using CTRL-b. Sometimes they are text files that use @pagewidth to help with readability. Sometimes I copy an @file to make changes and disable the original version by turning it into an @@file.

Sometimes I search for an old outline, maybe several years old, that has these now-forbidden directives in the wrong places. I'm not going to remember to check if the outline violates the new rules and then have to figure out how to rescue everything. I will just be thinking about the one @file I am interesting. If I make a change and save the outline, I don't want all the other @files to suddenly change or become unwritable.

Perhaps you could share the new requirements with us and we could have a discussion about them.

[Thomas Passin]

Just to be clear, I don't use @comment;I I do sometimes use @c/@ to comment out lines and I assumed that the same restrictions would apply to them.

[Edward K. Ream]

On Sun, Apr 6, 2025 at 7:51 AM Thomas Passin wrote:

- @comment, @delims, @encoding, @pagewidth and @tabwidth directives should only appear only in @<file> nodes.

I strongly object to this one. I write files all the time that use @c and @pagewidth directives  even though they are not @files.

Good point. What do you think of the following amendments?

- All @<file> nodes should contain @tabwidth and @pagewidth directives.

- An @encoding directive needs to appear in an @<file> node only if the encoding in the directive

  doesn't match the encoding in  the @string default-file-encoding setting.

- As always, avoid @comment and @delims directives if possible.

Edward

[Edward K. Ream]

On Sunday, April 6, 2025 at 7:02:32 AM UTC-5 Edward K. Ream wrote:

I rewrote by cutting and pasting code from the old framework to the new. I intended to change nothing about how the new code actually works. Changes might come later, in one or more much smaller PRs.

I plan to use Leo's git-diff-pr command to double-check all my changes. I'll reorganize the diffs so that they highlight the code (old and new) that pertains to each separate directive. This reorganization is a new review pattern for me. "Distilling" the relevant code from the old code base will be challenging. There is no guarantee that the new code will be equivalent to the old even after these checks.

Edward

P.S. I will allow myself to include new checks (and associated warnings) if a particular directive is used in a way that doesn't conform to what I consider good style. But perhaps such checks might be better left to later PRs.

EKR

[Jacob Peck]

I also have an objection, albeit a minor one — I use @tabwidth all over the place — and most of my Leo work doesn’t have any external files at all.

I understand that the appropriate setting could alleviate this, but I have occasional reasons to use different tab widths in different (parent) nodes within the same outline.

Jake

On Apr 6, 2025, at 8:51 AM, Thomas Passin <tbp1...@gmail.com> wrote:



--
You received this message because you are subscribed to the Google Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/leo-editor/0ec3c4d7-f83d-435a-af3f-d920c4a222d4n%40googlegroups.com.

[Thomas Passin]

On Sunday, April 6, 2025 at 9:07:59 AM UTC-4 Edward K. Ream wrote:

On Sun, Apr 6, 2025 at 7:51 AM Thomas Passin wrote:

- @comment, @delims, @encoding, @pagewidth and @tabwidth directives should only appear only in @<file> nodes.

I strongly object to this one. I write files all the time that use @c and @pagewidth directives  even though they are not @files.

Good point. What do you think of the following amendments?

- All @<file> nodes should contain @tabwidth and @pagewidth directives.

I don't see why they can't be set to the default setting if missing.  And if not defaulted, what should happen if they aren't present?  Let's keep the cognitive load low be not requiring the user to remember things that aren't really necessary.

 

- An @encoding directive needs to appear in an @<file> node only if the encoding in the directive

  doesn't match the encoding in  the @string default-file-encoding setting.

That sounds right.

[Edward K. Ream]

On Sun, Apr 6, 2025 at 11:41 AM Thomas Passin <tbp1...@gmail.com> wrote:

>> - All @<file> nodes should contain @tabwidth and @pagewidth directives.

> I don't see why they can't be set to the default setting if missing.

That's what has always happened, and that's what will continue to happen.

> And if not defaulted, what should happen if they aren't present? 

All directives requiring defaults have them. That won't change.

> Let's keep the cognitive load low.

The discussion is about edge cases that may affect how Leo writes external files. Depending on your outline, your defaults, and your use cases, you may be able to do without any directives. But for power users, including myself, issue #4323 may bite you if you don't follow the guidelines.

The suggested guidelines ensure that you may move your @<file> nodes without changing how Leo writes files or colors nodes. That shouldn't be too much of a cognitive load :-)

Edward

[Edward K. Ream]

On Sun, Apr 6, 2025 at 10:36 AM Jacob Peck <gates...@gmail.com> wrote:

I also have an objection, albeit a minor one — I use @tabwidth all over the place — and most of my Leo work doesn’t have any external files at all.

That's perfectly fine. The guidelines apply only if your outline does contain @<file> nodes. To repeat, the guidelines ensure that Leo won't change the contents of your external files no matter where you move their corresponding @<file> nodes.

Edward