Freewin - A Plugin That Provides Free Floating Edit/Render Windows

[tbp1...@gmail.com]

My new Freewin plugin has just been merged into the devel branch.  This plugin will open a smaller-than-Leo window that is dedicated to showing the node that was selected when the Freewin window was opened.

This window is provides a plain editing view, and can be switched to provide a view of the node's body rendered as Restructured Text.  The window is synchronized with its host node - editing changes in the window get reflected in the host node, and changes to the host node appear in the Freewin window.  The editor has all the basic editing functions, but no Leo-specific enhancements nor syntax coloring.

You can have any number of windows open at the same time, each linked to a different node.

You enable the plugin like any other, by adding its name to the enabled plugins node in your MyLeoSettings.leo file.

There is one command, to open a window, and no settings.  The open command is called z-open-freewin. I like to have it linked to a button, which you can do by adding an @setting to the @settings tree in either a specific outline or in myLeoSettings.leo.  The setting is like this:

Headline: @button Freewin 

Body: c.executeMinibufferCommand('z-open-freewin')

In my next post, I will explain how to customize Freewin's appearance and get the most out of theme switching.

[tbp1...@gmail.com]

Freewin windows display with either a light or dark theme, depending on whether your Leo theme is marked as light or dark. The colors are not picked up from the theme, but at least the light/dark character is maintained.

For the editing view, by default built-in stylesheets are used.  For the Restructured Text view, the default stylesheet used by Docutils is applied.  Unfortunately the same RsT stylesheet will be used for both light and dark themes, since Docutils has only one default stylesheet.

You can use your own stylesheets.  They must have specific names, and be located in your user's .leo/css directory.  I recommend that you copy the RsT stylesheets from Leo's leo/plugins/viewrendered3 directory, renaming them as you do so.  The plugin's Readme info has the details.  You can read them by invoking the Leo menu item Plugins/freewin/about. In summary:

                           Freewin Css Stylesheet Names

                           --------------------------------------------------

                                             Editor

                                            -----------

            Light                                                Dark

freewin_editor_light.css                    freewin_editor_dark.css

                                     RsT Rendering

                                    ------------------------

freewin_rst_light.css                          freewin_rst_dark.css

The VR3 RsT stylesheet displays a little on the large side, but I will soon be submitting a VR3 pull request that will  reduce the size.

Freewin works with PyQt5, or PyQt6 if that is installed. Unfortunately with PyQt6 the RsT dark theme renders as if there is no stylesheet.  This appearance is not the best, and it is not dark-themed.  This should be fixed when the Qt6 WebEngineView component is released, if not before.

My next post will cover the rationale for the plugin design, how I expected to use it, and and some other uses I have already found to be convenient.

[tbp1...@gmail.com]

This plugin came from a long thread we had on Google Groups more than a year ago.  The thread was about the possibility of using Leo as a "Zettelkasten", which translates as "Card Case".  The thread is at

Zettelkasten Thread

In brief, the zettelkasten system is a system for research and deep thinking in which small topics or thoughts are written on index cards.  The index cards each have an identifying number so they can be found and referred to.  The key feature is that the cards are to contain links to other cards, including to other, subsidiary thoughts about a given card.  After a period of use, the card case can contain a large number of carefully thought-out cards that are (hopefully) highly cross-referenced.  Eventually the card collection, it has been written, can become almost like a helping second brain, capable of coming up with unexpected or forgotten ides that can be pursued.

There are a few software systems that try to do the same job, but I didn't like any of the ones I tried, and in many of them the data was contained in a proprietary format.  Imagine if you had a decade of work and thoughts in one of them and then you had to move to another system!

Eventually, I came up with a system for Leo that involved a couple of command scripts and a way of using them. I thought that this system would not only emulate a card-case pretty well, with improved linking and searching, but that it should be fairly easy to write a script to output the data in a textual format in case one ever had to get the data out of Leo for some reason.

Then I got diverted and didn't do much more with the concept until recently.  I got interested in capturing genealogy and family history information.  This seemed like a good thing to use a zettelcasten system on.  I discovered a bug in one of the commands, tweaked another, and came up with a third.

In use, a physical card case would have you spreading out a number of related cards on a table or desk so you could see them all at the same time.  That is the main rationale behind the Freewin plugin.  The Freewin view of a node emulates a note card laid out on a desk.  It is editable for convenience, and the RsT rendered view makes for better viewing when you don't have to do editing. (My original concept uses a few RsT features - I will illustrate that in a following post).

This is convenient, and if you have a second screen you could lay out a lot more cards.

As for other uses, Freewin is useful any time you need to refer to one node while working in another.  I used it during the development of Freewin itself.  Several times I was developing code improvements in another outline (my Workbook.leo outline), and I needed to fold them into Freewin with changes to fit the details of the Freewin surrounding code.  Keeping the Workbook code in a Freewin window made this process much easier.

Developing Freewin has involved a lot of dog-fooding!

In a followup post I will give some examples how I use RsT features.  It turns out that the main one I use will make it fairly easy to parse the data into a structured for, such as RDF or topic maps.

[tbp1...@gmail.com]

The main Restructured Text feature that I have found useful is the "field list"  These are lines that start with :somename: like the circled ones in the first attached image.  These render well in the RsT view, are easy to type and read in the editing pane, and can be easily parsed for a variety of purposes.

Each line in the field list can represent some fact.  in essence, they are "triples" much like RDF triples - they contain a subject, which is implied by the topic of the card, name a property, and give its value.

The ID of a card is its Leo "gnx", or node id, and a small script inserts it into the body when the "zettel" node is created.  Another script parses the id when the cursor is on a field list line and jumps to that node.  So navigation is simple.

Names surrounded by RsT markup like `some name`_ are navigation targets when the rendered RsT is viewed in a web browser.  This can be accomplished by rendering in the Viewrendered3 plugin and exporting the HTML.  These links only can work when their target is in the set of nodes that is rendered.  This generally means an entire tree or subtree.

This first image, freewin_example_1, shows the Freewin editing view.  The second attached image file shows the same node in the rendered view.  Note that this image used a dark theme stylesheet.  It is the same one used by the current version of the VR3 plugin.  Without a dark theme stylesheet, the rendered view would not be dark, and the default Docutils stylesheet is not as dramatically rendered as this example.

The third attached image shows the same node when the entire tree is rendered in the VR3 pane.  This screen shot only shows a part of the tree, but it is enough to show that the `somename`_ style RsT links are functional - because their targets are included in the source.  A rendering this long is best viewed after export to a browser.

Of course it is not necessary to construct your nodes this way in order to use Freewin. This style of using RsT features is simply a way I have found useful for building a collection of linked "index cards".  I will be opening a new thread on this subject, so if you are interested keep a lookout for it.

The fourth screen shot shows an actual example in which I first developed some code in a node in the Workbook, and then modified it to work as production code in Freewin.  I kept the Freewin window open on the prototype code as I worked, and was able to copy and paste parts from.  Note that the RsT rendered view is useless here, because the RsT processor does not know that the page is a page of code and therefore renders it as if it were ordinary text.

As I prototyped this code, I ran it in the VR3 plugin pane (not shown here).  So I did not actually need to create and manage an external file.  This particular code checks to see if an RsT stylesheet was found.  If so, it configures Docutils to not include a stylesheet, and inserts a cached copy of our own into the RsT output.  If no RsT stylesheet was found, then Docutils is configured to include its own stylesheet instead.  Without this code, Docutils would open and read the styesheet file over and over again for each rendering, which might happen when one or a few characters were typed (the RsT rendering updates as the underlying Leo node is edited).

I found this process to be very helpful, even though the Freewin editor view is not syntax-colored.

[Edward K. Ream]

On Wednesday, June 16, 2021 at 4:21:43 PM UTC-5 tbp1...@gmail.com wrote:

My new Freewin plugin has just been merged into the devel branch.  This plugin will open a smaller-than-Leo window that is dedicated to showing the node that was selected when the Freewin window was opened.

Many thanks for this work. 

Rev 15d4f66 in devel fixes freewin.py so that it no longer causes two unit tests to fail.

Edward

[Alexey Tikhonov]

It is an excellent extension! Thanks!