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/CAMF8tS3q2gUpnUmanDbvHbPcPeXZ9cpKVDRnH-s%3DaEegkCLCow%40mail.gmail.com.
