Discuss: Radically simplify the rst3 command?

[Edward K. Ream]

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 for this enhancement.

Aha 4: The ekr-rst branch now contains support for #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 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: Radically simplify the rst3 command. I'll experiment with this project in the ekr-new-rst branch.

All comments are welcome.

Edward

[jkn]

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

[tbp1...@gmail.com]

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?

[jkn]

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

[Edward K. Ream]

On Fri, Mar 26, 2021 at 10:00 AM jkn <jkn...@nicorp.f9.co.uk> wrote:

IIUC, ReST itself gives you flexibility in what characters are use to indicate sections, subsection, sub-sub ... etc.

The rst3 command has always had a way to specify the exact characters, but that has been hidden in all the blah-blah-blah.

The new scheme will use something like:

    @string rst3-underline-characters = #=+*^~"'`-:><_

This might not work right this minute, because of problems interpreting '#', and quotes in the string. For now, the string is hard coded in the reloadSettings method, but that will be fixed soon.

Edward

[Edward K. Ream]

On Fri, Mar 26, 2021 at 10:42 AM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

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?

Imo, this work is worth doing. Yes, there is always a risk in modifying code. However, there several gains, which I've already discussed:

- Easier to learn.

- Easier to maintain. This will be important after I am gone.

- Easier to document.  This is a big deal.

I have already ripped out a lot of code. I am not looking back. Some unit tests are failing, but eventually they will be stronger than ever.

Edward

[jkn]

Hi Edward

    I confess I have had it on my list to look for a string something like that in the code...

Would such a scheme allow you to choose between "overline and underline" section levels, and "underline only"? I am not 100% sure of ReSTs own rules in this regard.

Thanks again, J^n

[Edward K. Ream]

On Friday, March 26, 2021 at 7:03:59 AM UTC-5 Edward K. Ream wrote:

Imo, the rst3 command is burdened with features that almost nobody uses.

I'd like to emphasize how deeply misguided the old code was. It attempted to offer a gazillion features to turn outlines into literate programs. Instead, a simpler, more general approach is to let the user be responsible for content, letting rst3 handle the syntactic grunge of turning headlines into rST section references.

Anyone can understand what I've said. Nobody, myself included could possibly remember the old details.

Furthermore, rST/docutils now supports syntax coloring with pygments, so people an easily make the output of their programs look good, provided they are willing to add just a bit of rST markup. That markup will be simpler than any conceivable rst3 feature.

My focus now is to provide the simplest, most general rst3 options that will specify how to call docutils.

Edward