I use rst3 to generate Sphinx documentation and I have been happy with it. I was not aware of all these configuration options and have not missed them.
Instead of changing the rst3 code, we could consider just not telling people about these options, or advising them not to use any. Would not this give the same result without the time and risk of modifying the code? On Friday, March 26, 2021 at 8:03:59 AM UTC-4 Edward K. Ream wrote: > 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/ba07316e-bb7c-4eeb-9c3c-e766a8068751n%40googlegroups.com.
