PR #4324 <https://github.com/leo-editor/leo-editor/pull/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 <https://github.com/leo-editor/leo-editor/issues/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 -- 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 [email protected]. To view this discussion visit https://groups.google.com/d/msgid/leo-editor/abed71ad-cb55-4f96-8504-cff2c516d823n%40googlegroups.com.
