Hi - I think you misunderstand me a bit. I am *asking for* configuration options. The reason is that the workflow I have to use forces a particular format for the respective levels. Perhaps my comment about sphinx wasn't helpful - it may not be sphinx itself that is forcing this, but something that my company uses 'before' sphinx.
In any case, if I were used to writing ReST in the style I show above, and then used leo's rst3 command,, I might get a mildly nasty surprise. I think it would be good to have this configurable via @settings HTH, J^n On Friday, March 26, 2021 at 3:42:20 PM UTC [email protected] wrote: > 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/96cbd739-e8a6-4d25-8973-3d9190ee6e1dn%40googlegroups.com.
