The new rst3 command is now in devel

[Edward K. Ream]

Devel now contains the completed #1867: radically simplify the rst3 command.

I have removed the "Rst Command Reference" chapter from LeoDocs.leo and from Leo's web site. I will soon add a new section to the "Customizing Leo" chapter.

As I stated earlier, the new rst3 command is a milestone in Leo's history:

- The new rst3 command supports user filters. The rst3 command calls these filters for every headline and body text of the rst3 tree, except for @rst-no-head, @rst-ignore and @rst-ignore-tree nodes.  User filters are a simpler, more general way of customizing documentation, without the former complex, rigid options.

- The new rst3 command shows how documentation writers can get the effect of half clones. More generally, the new rst3 command allows documentation to be composed using data anywhere in any open outline. User filters could, if desired, open other outlines.

- For most users, the new rst3 command will work exactly as before. Please create an issue if it doesn't.

Edward

[Edward K. Ream]

On Friday, April 2, 2021 at 7:25:01 AM UTC-5 Edward K. Ream wrote:

Devel now contains the completed #1867: radically simplify the rst3 command.

...

I have removed the "Rst Command Reference" chapter from LeoDocs.leo and from Leo's web site. I will soon add a new section to the "Customizing Leo" chapter.

Done in devel, and on Leo's web site, here.

All comments and corrections are welcome.

Edward

[Viktor Ransmayr]

Hello Edward,

Is it already possible to reproduce Leo's own documentation using the current state of the new / revised rst3 command?

With kind regards,

Viktor

[Viktor Ransmayr]

Hello Edward,

I started 'playing' with this commit & have to report the following ...

The current state of the new / revised rst3 command would break a lot of my outlines.

I'm using rst-based outline templates, very close to the test-template, that I've attached.

It did work w/o any problems until this last change. - Now it stopped to ...

* honor '@rst-preformat' - and - it stopped to ...
* honor the 'default_path=./TL/2021/01/CWxx/' in '@rst-options'

With kind regards,

Viktor

[Edward K. Ream]

On Fri, Apr 2, 2021 at 1:17 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

Is it already possible to reproduce Leo's own documentation using the current state of the new / revised rst3 command?

Yes. The new rst3 command generated all the files on Leo's web site. Notice the date at the bottom of each page, except the home page.

Edward

[Edward K. Ream]

On Fri, Apr 2, 2021 at 2:31 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

The current state of the new / revised rst3 command would break a lot of my outlines.

I'm using rst-based outline templates, very close to the test-template, that I've attached.

It did work w/o any problems until this last change. - Now it stopped to ...

* honor '@rst-preformat' - and - it stopped to ...
* honor the 'default_path=./TL/2021/01/CWxx/' in '@rst-options'

Thanks for this report. I'll make the required changes.

Edward

[Edward K. Ream]

On Fri, Apr 2, 2021 at 2:31 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

In the example file you sent, you could set:

@string rst3-default-path = ./TL/2021/01/CWxx/

in the .leo file's @settings tree. Would that work for you in general?

Edward

[Edward K. Ream]

On Fri, Apr 2, 2021 at 2:31 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

> The current state of the new / revised rst3 command would break a lot of my outlines.

I have just created #1876: Honor @rst-preformat. It should be easy to fix.

It would be straightforward to create a filter to do the same, but there is no reason to break existing @rst trees needlessly.

Edward

[Edward K. Ream]

On Fri, Apr 2, 2021 at 4:36 PM Edward K. Ream <edre...@gmail.com> wrote:

> I have just created #1876: Honor @rst-preformat. It should be easy to fix.

The ekr-rst-preformat branch contains the proposed fix. See PR #1877.

Please report any problems immediately.

Edward

[tbp1...@gmail.com]

My primary document built with Sphinx without trouble as far as I can see.  It has a tree with 15 @rst nodes, some of which are contain a @rst-no-head node. The built html files come to something over 500KB, so not huge but not a toy document, either. This tree does not call for any of the more complex things rst3 could apparently do, so it's not much of a test, I suppose.  But I'm happy!

Leo 6.4-devel, devel branch, build 6f2abe819a
2021-04-02 10:59:56 -0500
Python 3.8.6, PyQt version 5.15.1
Windows 10 AMD64 (build 10.0.19041) SP0

[Viktor Ransmayr]

Hello Edward,

Edward K. Ream schrieb am Samstag, 3. April 2021 um 00:09:31 UTC+2:

On Fri, Apr 2, 2021 at 4:36 PM Edward K. Ream <edre...@gmail.com> wrote:

> I have just created #1876: Honor @rst-preformat. It should be easy to fix.

The ekr-rst-preformat branch contains the proposed fix. See PR #1877.

Works like a charm. - Thanks a lot for the quick fix!

With kind regards,

Viktor

[Viktor Ransmayr]

Hello Edward,

The workflow I've been using for many years is as follows:

* Keep notes in an outline / .leo file, which I change every year.

* Store notes as HTML files, one for every day in a given week.

* The directory structure I've been using is "./ <type>/<year>/<month>/<week>".

As far as I know, I can have only a single @settings tree per outline.

Therefore, I don't see how this could work - unless - Leo is checking for / honoring 'default-path=..." - settings inside the @rst content tree?

With kind regards,

Viktor

[Edward K. Ream]

On Fri, Apr 2, 2021 at 8:11 PM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

My primary document built with Sphinx without trouble as far as I can see.  It has a tree with 15 @rst nodes, some of which are contain a @rst-no-head node. The built html files come to something over 500KB, so not huge but not a toy document, either. This tree does not call for any of the more complex things rst3 could apparently do, so it's not much of a test, I suppose.  But I'm happy!

Glad to hear it. Thanks for the feedback.

Edward

[Edward K. Ream]

On Sat, Apr 3, 2021 at 3:12 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

H

The ekr-rst-preformat branch contains the proposed fix. See PR #1877.

Works like a charm. - Thanks a lot for the quick fix!

You're welcome. However, after some thought I am not going to support @rst-preformat.

Instead, I'll create a conversion script, available via a new command, say 'convert-legacy-rst-trees', that will do the following:

1. Convert @rst-preformat nodes as follows:

- Change @rst-preformat to @rst-no-head.

- Change p.b by adding an initial line containing "::" and indenting all other non-blank lines by 4 spaces.

 

2. Scan for nodes containing `@ @rst-options` outside of @rst trees, converting them as follows:

- If the node contains default_path=<path>, change the headline to @path <path>

This should give the desired effect, because the rst3 honors @path inside @rst trees.  I'll tweak the conversion script as necessary to make everything work.

Edward

[Edward K. Ream]

On Sat, Apr 3, 2021 at 4:53 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

* The directory structure I've been using is "./ <type>/<year>/<month>/<week>".

As far as I know, I can have only a single @settings tree per outline.

Therefore, I don't see how this could work - unless - Leo is checking for / honoring 'default-path=..." - settings inside the @rst content tree?

As I said in the other reply, you will have to run the new 'convert-legacy-rst-trees command on your files. This will create @path nodes that should make your existing @rst trees work.

The result should be clearer and more flexible than the old way.  What do you think?

Edward

[Viktor Ransmayr]

Hello Edward,

Fine with me. - Let me know, when this new command is available in the 'devel' branch & I'll give it a try on some of my outlines.

With kind regards,

Viktor

[Edward K. Ream]

On Sat, Apr 3, 2021 at 7:40 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

Fine with me. - Let me know, when this new command is available in the 'devel' branch & I'll give it a try on some of my outlines.

Will do. Thanks.

Edward

[Edward K. Ream]

On Saturday, April 3, 2021 at 7:40:12 AM UTC-5 viktor....@gmail.com wrote:

> Let me know, when this new command is available in the 'devel' branch & I'll give it a try on some of my outlines.

The rst-convert-legacy-outline command (alias: convert-legacy-rst-outline) is in devel at rev deb634.

It seems to work with the test outline you sent. Let me know if you find any problems.

Edward

[Viktor Ransmayr]

Hello Edward,

I used the new command successfully on one outline. - It did convert everything properly ...

I'm now having one question on how to deal with large content copied from somewhere to the recommended successor for '@rst-preformat' nodes, i.e. '@rst-no-head' nodes:

Is there already a command available in Leo, that inserts a given number of 'blank' characters before each of the copied lines?

Being able to simply copy / paste any number of lines into a '@rst-preformat' node -  w/o the need of any post-processing - was the big advantage of this now 'deprecated' node type!

With kind regards,

Viktor

[Edward K. Ream]

On Sun, Apr 4, 2021 at 4:44 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

I used the new command successfully on one outline. - It did convert everything properly ...

Glad to hear it.

Is there already a command available in Leo, that inserts a given number of 'blank' characters before each of the copied lines?

Yes. indent-region, bound to Tab.  Select lines and hit tab. The selection doesn't have to be "exact", so long as it includes some characters from the first and last lines.

indent-region uses the tab width setting in effect. That should suffice, because you can hit Tab as many times as you need. Also, Shift-Tab (unindent-region) does the reverse.

Edward

[Viktor Ransmayr]

Hello Edward,

Thanks for this info. - I'm happy with the way the conversion script is dealing with  the changed "@rst-options / default path=..." handling.

I'm not (yet?) confident / really happy about the removal of the "@rst-preformat" option.

The first one is a one-time conversion action & everything's taken care of for the users.

For the second one, you're asking the users to perform more steps **every** time. - At least for me the workflow is not as smooth as before!

I'll keep this VM on Leo's devel branch & try to see how it works out for me in the next days ...

With kind regards,

Viktor

[Edward K. Ream]

On Sun, Apr 4, 2021 at 1:27 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

Thanks for this info. - I'm happy with the way the conversion script is dealing with  the changed "@rst-options / default path=..." handling.

Glad to hear it.

I'm not (yet?) confident / really happy about the removal of the "@rst-preformat" option.

The first one is a one-time conversion action & everything's taken care of for the users.

For the second one, you're asking the users to perform more steps **every** time. - At least for me the workflow is not as smooth as before!

Imo, the new way is just simpler:

- It's no easier to type @rst-preformat than @rst-no-head.

- @rst-preformat is less flexible than usual because it can't create a headline.

- Any node in an @rst-tree can contain preformatted text.

- Adding a "::" and indenting following text is too easy to justify special headlines.

I was happy to create the conversion script, but imo @rst-preformat is not needed for new writing.

Edward

[Viktor Ransmayr]

Hello Edward,

Edward K. Ream schrieb am Montag, 5. April 2021 um 07:51:32 UTC+2:

On Sun, Apr 4, 2021 at 1:27 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

...

I'm not (yet?) confident / really happy about the removal of the "@rst-preformat" option.

The first one is a one-time conversion action & everything's taken care of for the users.

For the second one, you're asking the users to perform more steps **every** time. - At least for me the workflow is not as smooth as before!

Imo, the new way is just simpler:

- It's no easier to type @rst-preformat than @rst-no-head.

- @rst-preformat is less flexible than usual because it can't create a headline.

- Any node in an @rst-tree can contain preformatted text.

- Adding a "::" and indenting following text is too easy to justify special headlines.

I was happy to create the conversion script, but imo @rst-preformat is not needed for new writing.

After having worked for a couple of days with the @rst-no-head approach I fully agree with your call.

Concerning the conversion script I've found one more issue, where I'd like to hear your opinion:

* The script does create an @path directive in the header of the node - but - it does not remove for example the

@ @rst-options
default_path=./TL/2021/01/CWxx/
@c 

in the @path body. - Did you consider removing the now 'useless' default_path' statement - or - the @rst-options section in general?

With kind regards,

Viktor

[Edward K. Ream]

On Fri, Apr 9, 2021 at 3:15 AM Viktor Ransmayr <viktor....@gmail.com> wrote:

>> I was happy to create the conversion script, but imo @rst-preformat is not needed for new writing.

> After having worked for a couple of days with the @rst-no-head approach I fully agree with your call.

Oh good :-) Thanks for the feedback.

@ @rst-options

default_path=./TL/2021/01/CWxx/
@c 

in the @path body. - Did you consider removing the now 'useless' default_path' statement - or - the @rst-options section in general?

I did consider it, but the node might have other (now useless) settings. Rather than destroy potentially useful data, I chose to leave the nodes as they are. It should be no great inconvenience to remove the body text of those nodes. You could use a multi-line regex in a short script.

Edward

[Viktor Ransmayr]

Hello Edward,

Edward K. Ream schrieb am Freitag, 9. April 2021 um 19:03:13 UTC+2:

@ @rst-options

default_path=./TL/2021/01/CWxx/
@c 

in the @path body. - Did you consider removing the now 'useless' default_path' statement - or - the @rst-options section in general?

I did consider it, but the node might have other (now useless) settings. Rather than destroy potentially useful data, I chose to leave the nodes as they are. It should be no great inconvenience to remove the body text of those nodes. You could use a multi-line regex in a short script.

Thanks for your explanation. - At the moment I think I'll go a slightly different direction - and -  will try create a customized version of the "convert-legacy-rst-outline" command provided by you.

I'll report back here, if & when I have something that works for my outlines.

With kind regards,

Viktor

[Edward K. Ream]

On Fri, Apr 9, 2021 at 2:52 PM Viktor Ransmayr <viktor....@gmail.com> wrote:

Thanks for your explanation. - At the moment I think I'll go a slightly different direction - and -  will try create a customized version of the "convert-legacy-rst-outline" command provided by you.

I'll report back here, if & when I have something that works for my outlines.

Sounds reasonable. Good luck.

Edward