Transition to leoInteg.leo

[Edward K. Ream]

Hi Félix,

This long post discusses the transition to using leoInteg.leo as the primary sources for the leoInteg project. I'd like your comments.

Iirc, you said in our zoom time that you eventually want to have all sources for the project in leoInteg.leo. There are pros and cons to doing so now. I'll discuss these pros and cons below.  But first...

Updating ekr-leoInteg.leo

Yesterday I updated ekr-leoInteg.leo, my personal copy of leoInteg.leo. Recall that I used a recursive import script to create the original version of this file. It contains @clean nodes for all the .ts files.  Because the file uses @clean, the following steps were needed to update the file:

Step 1. Move ts comments from the end of one node to the beginning of the next node.

The move-lines-to-next-node command automates this step. There is a special case for comments just before an @others. And there is a likely bug in this case: the @others can get duplicated. I'm aware of these glitches. They are no big deal.

Step 2. Delete nodes whose corresponding methods have been deleted or moved.

Step 3. Split nodes containing new or moved nodes. The parse-body command automates this process. However, I then had to move comments as in step 1.

Step 4. Move code for clarity.

Sometimes the ts importer creates a new child node where in fact it would be clearer to put the "subsidiary" code back in the parent. To do this, I replaced the @others in parent node with the child node's text, properly indented. This happened for some .then clauses.

Step 5. Using the import script, add @clean nodes for any new .ts files.

I mention this for completeness. It's not usually necessary.

The actual procedure

Whenever I made a significant change to ekr-leoInteg.leo I did the following:

- Save ekr-leoInteg.leo.

- Check the git diffs.

- git checkout .

- Reload ekr-leoInteg.leo.

- Make any changes suggested by the git diffs.

- Re-save ekr-leoInteg.leo.

- Repeat until the diffs go away (except for trailing whitespace in the file).

I found several mistakes this way. I'm confident that ekr-leoInteg.leo is a faithful, Leonine, representation of all the .ts files, as they existed when I was updating ekr-leoInteg.leo.

Pros and cons

The procedure given above illustrates most of the minuses of using leoInteg.leo as the basis for work on leoInteg :-) I must update leoInteg.leo every time the sources change. I'm willing to do this. A script should help. See below.

The procedure would change (and likely be simpler) if @file were used instead of @clean. In that case, you (we) would create, delete and move nodes in leoInteg.leo. After changing code in vs code, we would use Leo's refresh-from-disk to update leoInteg.leo. These steps could be called more cons...

The pros to using Leo are as always: a much better view of the code, and outline-oriented commands such as git-diff and clone-find. There is additional benefit: using leoInteg.leo will be a more realistic test of the leoInteg project. It will likely reveal features that would be useful to have sooner rather than later.

A transition script

A script (not written yet) should help to keep leoInteg.leo up to date. In effect, loading any file containing @clean nodes does a refresh-from-disk on all the @clean nodes. The script can delete any non-organizer node (a node without children) that has no p.b. The script can split any nodes for which the parse-body command contains more than one child.

I plan to work on this script today.

Conclusions

We both agree: leoInteg.leo should eventually contain the primary sources for all .py and .ts files in the leoInteg project.  The question is, when should this happen? Imo, you alone should make this choice. That is, you should use the work flow that is most convenient for you.

ekr-leoInteg.leo now contains an up to date version of all the sources. I'll push ekr-leoInteg.leo to a new ekr branch later today.

I'll be happy to keep ekr-leoInteg.leo (or leoInteg.leo) up to date every time you push to dev. I'll wait for your permission to do that.

All comments welcome.

Edward

[Edward K. Ream]

On Thursday, July 16, 2020 at 7:15:52 AM UTC-5, Edward K. Ream wrote:

> ekr-leoInteg.leo now contains an up to date version of all the sources. I'll push ekr-leoInteg.leo to a new ekr branch later today.

Done.

Imo, using @file instead of @clean in leoInteg.leo should be an eventual goal. Indeed, that "external" .ts files will be less important, so the sentinel comments shouldn't be a big deal. But I'll leave the timing to you, Félix.

Edward

[Edward K. Ream]

On Thursday, July 16, 2020 at 7:15:52 AM UTC-5, Edward K. Ream wrote:

> A script (not written yet) should help to keep leoInteg.leo up to date.

Completed in the ekr branch. @button mark-changed is short and simple. It only marks nodes that we might want to delete or split. This makes it safe.

In retrospect, this script seems essential when using @clean.

Edward

[Edward K. Ream]

On Thu, Jul 16, 2020 at 9:05 AM Edward K. Ream <edre...@gmail.com> wrote:

> > A script (not written yet) should help to keep leoInteg.leo up to date.

> Completed in the ekr branch. @button mark-changed is short and simple.

This script highlights another strength of the desktop version of Leo, namely full access to all of Leo's sources. In contrast, vs code does not provide such access. Yes, it's a reasonable choice to limit access to so-called contribution points, but Leo's way makes quick scripts so much easier to write.

Edward