Imo, the rst3 command is burdened with features that almost nobody uses. Instead, rst3 should do *nothing* except:
1. Generate rST section references automatically. 2. Handle the details of driving docutils. The present code is a horror show that supports a bewildering array of options and features. Alas, those features are hardly ever useful! *Aha 1*: The options and features arise from the "include text using clones" model of finding/including text. Imo, this model is not worth supporting. *Aha 2*: The options and features arise from a desire to support Literate Programming. But Leo's entire history, including the history of its documentation, shows that there is no need to intermingle code and novel-like comments. * Aha 3: *Authors, including writers of documentation, often *do *want links to other nodes, either in the same outline or in others. Leo's gnx's would be a good way to provide those links. Leo should support clickable links of the form gnx:<gnx>. I have just created #1868 <https://github.com/leo-editor/leo-editor/issues/1868> for this enhancement. *Aha 4*: The ekr-rst branch now contains support for #1843 <https://github.com/leo-editor/leo-editor/issues/1843>. Imo, these features are not worth doing! It is much more natural to put text into rst3 trees directly! *Discussion* I plan to simplify rst3, thereby making rst3 easier to learn and use. Leo a killer app for reStructuredText because rst3 automatically generates rST section headings from Leo's headlines, calculating headline levels from outline levels. The other features of the rst3 command arise from the desire to include code (or other documents) into an @rst tree* using clones*. Imo, this is a doomed attempt to make nodes do double duty. #1843 <https://github.com/leo-editor/leo-editor/issues/1843> is another such doomed attempt. Instead, including text by cutting and pasting will suffice. Leo's documentation shows that even cutting and pasting is hardly ever needed. Instead, we might insert links to PR's. *Summary* There is no coherent rationale for rst3's complexity. Including text using cut/paste will work for the vast majority of users. Adding support for gnx-based clickable links will help keep text up to date. The rst3 command should do *nothing* except: 1. Generate rST section references automatically. 2. Handle the details of driving docutils. Radically simplifying the rst3 command would have these benefits: 1. Easier to learn and to document. 2. Easier to maintain. 3. The simplified code would be a foundation for custom scripts. I have just created #1867 <https://github.com/leo-editor/leo-editor/issues/1867>: Radically simplify the rst3 command. I'll experiment with this project in the ekr-new-rst branch. All comments are welcome. 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/5b60571d-9e83-4586-8122-8ac58b59a71cn%40googlegroups.com.
