However, the title of Viktor's post implies a valid suggestion. Everything you say you want to achieve could be done by leaving rst3 as is - never touching it again - and creating a new rst4. It would be no more work, and there would be no latent backwards compatibility issues.
In fact, it would make more sense because the goals of the new version are different from the old. A new name would be appropriate for that. On Saturday, March 27, 2021 at 11:43:35 AM UTC-4 Edward K. Ream wrote: > On Sat, Mar 27, 2021 at 6:06 AM Viktor Ransmayr <[email protected]> > wrote: > > *Can you explain what measures you use to decide, when you rework an >> available command / extension & accept (the possibility of) breaking >> backwards compatibility - and - when you create a new major version of a >> command / extension & keep the existing version available in order to >> guarantee backwards compatibility for Leo users?* >> > > An excellent question. It's not a distraction. > > It took me a moment just now to remember why I started on #1867 > <https://github.com/leo-editor/leo-editor/issues/1867> a few days ago. > > I was working on #1843 > <https://github.com/leo-editor/leo-editor/issues/1843>, re > @rst-insert-body & @rst-insert-tree. I thought it would take a few hours, > and then I would restart the sabbatical. But then I saw that #1868 > <https://github.com/leo-editor/leo-editor/issues/1868> (clickable links > based on gnx's) would make it easy to specify nodes to be copied *by hand* > into an @rst tree. > > All this led to the four Aha's in the first post > <https://groups.google.com/g/leo-editor/c/jVf479xQIiU/m/L0fLXGe_BQAJ>. I > saw that rst3 was trying to do something quite silly, namely supporting > Leo-style literate programming with a gazillion features. > > I also saw that the supposed problems with creating documentation are > really not Leo's concern. Documentation is hard. Writers may need different > words (on the same topic) depending on the exact context. So the "include > text by cloning" model is misguided. > > All these Aha's pointed to an inescapable conclusion: rst3 should do > *nothing* except: > > 1. Generate rST section references automatically. > 2. Handle the details of driving docutils. > > I stated this conclusion at the start of the first post, and restated it > at the end of the first post. I'm happy to continue to restate it, because > it is an earthquake in my thinking. Leo should leave writing to writers! > > Now then, what should I do with these Ahas? Do I leave rst3 in place and > add an rst4 command, as your title suggests? It's a fair question, and my > answer is a judgment call. > > Having said that, I am convinced that simplifying rst3 is best in the long > run: > > 1. Most importantly, the new rst3 command creates clearer thinking about > how writers should use Leo. Imo, the old way encouraged people to waste > their time. Now, the only way is the simple way. > > 2. I am thrilled to be able to delete most of (all of?) Leo's rst3 > reference <http://leoeditor.com/rstplugin3.html>. The path to power lies > in simplicity and generality, *not* endless features. The old way was > poor design. Nobody needs it. > > 3. The new code has collapsed in simplicity. In future, Leo's devs will be > able to understand leoRst.py. Right now, the simpler code is much easier to > test. Eventually I'll aim for 100% code coverage. > > *Summary* > > There may be one or two Leonistas who may have to revise their > documentation. I am convinced that even they will benefit by doing so. > > 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 on the web visit https://groups.google.com/d/msgid/leo-editor/e71cc368-4063-4da3-8479-5d22c2c02a9fn%40googlegroups.com.
