Hi Edward
Since ReST has come up ... I'll mention something that I have come
across recently.
IIUC, ReST itself gives you flexibility in what characters are use to
indicate sections, subsection, sub-sub ... etc. I think that rst3, maybe
pandoc, can infer what is what, and give the output you want.
However I have had to use a sphinx-based workflow recently where the format
has been more rigidly defined - for instance
=======
Level 1
=======
-------
Level 2
-------
Level 3
=======
Level 4:
-------
I think Leo has its own (perfectly reasonable, I am sure) idea of what
formats to use when generating ReST output - however the current usage
caused problems in my workflow.
So I would like to ask, if you are working in this area, to provide a way
of configuring the formats used for different section levels, so that I can
be accommodated.
Thanks again for Leo
Jon N
On Friday, March 26, 2021 at 12:03:59 PM UTC 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/1e6e2703-15cb-499e-bb77-a6826c272742n%40googlegroups.com.
