Use cases for @rst

[Rob]

I find Leo's @rst commands especially useful in a variety of situations and thought other Leonistas might benefit from these use cases and ideas. I suspect these weren't what Edward had in mind when he added support for reStructuredText (rst) to Leo.

1. Use case #1; create `temporary` text files. I am a youth volleyball coach and twice a week I prepare detailed practice plans to share with my assistant coach and `quick print` them for easy reference while on the court (not allowed to use my phone while coaching). Each practice plan is a Leo outline under an @rst node. When complete, I simply invoke the rst3 command and Leo automagically creates the small text file that I need for just that day's practice. I print and share the file, then delete it (it's `temporary`). The outline still exists in my master Leo file for later reference if needed.
 
2. Use case #2; copy Leo's outline to the clipboard as rst with headline text. Two examples:

  1. I teach various classes which use a web application for creating content as well as teacher and student notes. I write each class session in a Leo @rst node. When complete, I use a rst-clipboard command (thanks Edward for the script!) to copy the outline and paste into the web application, complete with headline and body text (headlines marked up as expected in rst).

  2. Occasionally I might need a long email to have some rst-type structure (marked up headlines and body text). I write the email in Leo in an @rst node and use the rst-clipboard command, then paste from clipboard into the email.
 
3. Use case #3; create source files for pandoc conversions. Some of my clients need support documents in .docx or .odt format (occasionally .html). I prefer to write everything in reStructuredText markdown format. To accommodate my clients, I create the source document in Leo under an @rst node, then the rst3 command creates the source file which pandoc uses to generate the .docx, .odt (or whatever) `external` file the client needs. This workflow has many advantages for me, not the least of which is I can have one `master` Leo file for each client containing all of their support documents regardless of how many individual, discreet documents the client needs. Cloning nodes in also Leo makes it super easy to have common text snippets across multiple `external` documents.

@rst nodes are an invaluable tool in my everyday work. I'd love to hear how others might be using @rst in their workflow.

Rob...

[tbp1...@gmail.com]

For use cases 1 and 2, you could also try rendering with the Viewrendered3 plugin, then exporting the HTML to the browser.  If you have more than one node in the tree, check "Entire Tree" in the VR3 View Options menu.  If you go this route, you don't even need an @rst file node nor an external file to manage.  VR3 also has a minibuffer command vr3-open-markup-in-editor that opens the generated RsT markup in your editor, similar to the rst-clipboard command.  If you should ever want to insert math symbols or equations into your document, VR3 can be configured to render them beautifully via MathJax..

For use case 3, I did that once myself, to write the first draft of a tech note in .odt.  I liked writing it in Leo that way better than using Libreoffice or Word, because the outlining works so much easier and better with Leo.

Otherwise I  have mostly used @rst node trees to generate Sphinx documents.  So much better than if you had to manage all those documents separately by hand!

[Rob]

Thanks for that! However, when I try using vr3, I don't get the subtree headline text marked up, so I'm missing the structure context (VR3 window as well as external editor). Am I missing something?

Rob...

[Rob]

For comparison, I created a simple outline in Leo, then created two files; one using the rst3 command (rst_export.txt attached), the other using vr3-open-markup-in-editor (vr3_export.txt attached). As can be easily see, there's a big difference between the two. Using vr3, how do I get the output to show the headline text?

Rob...

[tbp1...@gmail.com]

The way it's supposed to work is that the node headline will become a title in the final markup unless the body already starts with that exact string.  There is a boolean setting, use_node_headline, to turn that on or off but it's supposed to be True by default.

I've attached an outline with a 2-node subtree that I use for testing, and also the VR3 rst output using the command vr3-open-markup-in-editor.  Open the outline, open VR3, and check the Entire Tree option.  Then highlight the parent (top) node of the tree.  The entire tree should render, including the node headlines as headings.  You can check that against the .rst file I've attached.

Note that This file contains some directives understood by VR3 that get translated into RsT in the output.  The rst3 command doesn't understand them, so just ignore that kind of difference.

The main point is that when the option is checked, the entire subtree starting at the selected node will be rendered.  If that node has no children then only that one node will be rendered.

The attached outline also has a second top-level subtree which has the same content as the first, but it's set up to produce an @rst3 file when that command is run.  There are other ways you could set it up, but I like doing  it this way.  If you select the top content node (the first child of the @rst node), VR3 will not think that @rst VR3 Example is supposed to be included as a headline. 

On Wednesday, January 12, 2022 at 2:10:19 PM UTC-5 Rob wrote:

[tbp1...@gmail.com]

@Rob, could you include the actual Leo outline (or at least the whole @rst tree part)?

One difference will be the choice of symbols for the headings.  For the headings generated from the node headlines, the symbol markup is  baked into VR3 so it will probably be different from the ones generated by the rst3 command.

[tbp1...@gmail.com]

Oops, I missed actually attaching the files.

[Rob]

OK, after I added the @bool vr3-insert-headline-from-node setting, it now works as you explained it would. A few thoughts:

1. I think I prefer the vr3 method of marking up the node headline text (headings) to the rst3 method (it's easier to spot in the text output).
2. vr3 adds 2-3 extra blank lines between nodes to the output compared to rst3, not sure why. Is that fixable?
3. The  @bool vr3-insert-headline-from-node setting was apparently *not* True by default. Should that be changed in the plugin documentation or fixed in code? (I saw the setting and assumed it was True by default.)

On balance, I may end up using vr3 instead of rst3 for my use cases #1 and #2, depending on how much effort it will take to clean up the extra blank lines in the output. Thanks for directing me to that. Prior to this I only occasionally used the original vr plugin and hadn't even loaded vr3.

Rob...

[tbp1...@gmail.com]

Glad you got it working.  I don't know why the default setting isn't True. That's a bug and I'll get it fixed.  As for extra blank lines, I put them in because sometimes the RsT processor barfs when it thinks it needs a blank line, and it was much easier to just add extra lines than to get it all perfect.  They never matter for rendered output, anyway.  If it's really important to you, send me an outline with an example and I'll see what I can do.

BTW, in case you would rather use Markdown instead of RsT,  VR3 works the same way with MD. You just have to tell it that you are using MD, and there are three ways to do that:

1. Select MD in the Default Kind menu, or

2. Start each node's body with @language md or

3. Start the headline of the top-level node with @md .

Well, there's a fourth way as well, via a setting.

Actually, VR3 will work the same way with Asciidoc too.  I don't really recommend that because 1) it can be a bit of a pain to get an Asciidoc processor going, and 2) all the available Asciidoc processors are very slow to render, which is a nuisance if you want to do some editing and see the output immediately.  But the output looks good, and the markup is very readable.

See my next post for another use case, one that may not be obvious but is close to my heart.

[tbp1...@gmail.com]

VR3 is very good for small-scale program development, especially when you need to do experiments to learn how to make something work.  You can do Literate Programming with ease (on a small scale), and you can can do all this without even needing to save program files.

You just write @language rest (or md, or asciidoc) at the start of any section that isn't code - notes, reminders, design issues, whatever you want.  When you want to insert code, put in a line @language python and write a code block.  Or any language supported by Leo, really, but only Python code will execute in Leo.  You can mix any number of code and non-code blocks in a node.  @language blocks cannot carry over from one node to the next.

VR3 does not understand @others and <<named sections>> (maybe someday ...).

If it's python code, you can run it by executing it in VR3.  If you want to extract only the code, you select the View Options item Code Only.  Then export to your browser, and you can select and copy the code, then paste into an editor.  Or you can use the minibuffer command vr3-open-markup-in-editor.  You would need to remove all the lines like .. code:: python and unindent all the text one step, which is not hard but copying from the browser is a bit easier.

I use VR3 like this quite a bit.  It's not so suitable for large programs, but within its range it's very convenient.

[Edward K. Ream]

On Wed, Jan 12, 2022 at 11:11 AM Rob <lar...@gmail.com> wrote:

I find Leo's @rst commands especially useful in a variety of situations and thought other Leonistas might benefit from these use cases and ideas. I suspect these weren't what Edward had in mind when he added support for reStructuredText (rst) to Leo.

Interesting question. It's on my list to document filters for the rst3. For now, here are the links:

1. https://groups.google.com/g/leo-editor/c/_NOfUwJPNng/m/wkl8i-KoBgAJ
2. https://groups.google.com/g/leo-editor/c/WXIQUPr88Xw/m/8-SL-BMKBwAJ

Edward