MD or RST?

[Largo84]

Edward's recent post about simplifying Leo prompted a question that I've had for some time. How are markdown and reStructured Text different, and more importantly, why (or when) choose one over the other? My guess is that they are different 'dialects' of a similar language, but with somewhat different rules. I also notice that the output files (@clean or @file) differ in the handling of comment sections depending on which @language is selected; @language md creates comments as if the file were an xml or html file, whereas @language rest creates pure rst comments (..) Maybe it's just a personal preference, but others' insights on reasons for their choices would be most welcome.

Rob..........

[Jacob Peck]

Hi Rob,

I use markdown (and also coded up the initial markdown support in Leo!) because I'm used to it.  It's a much simpler (IMO) language to work with than RST for my needs.  Plus, it's basically muscle memory for me.

As for the comments thing -- markdown doesn't actually have comment syntax!  The entirety of a markdown file is supposed to be human readable content.  The workaround is using HTML comments, because the markdown spec states that a markdown parser shouldn't manipulate any elements that it can't identify, instead passing them verbatim to the finished document.

Here's the markdown spec if you're curious: https://daringfireball.net/projects/markdown/

-->Jake

On 3/25/2016 2:07 PM, Largo84 wrote:

Edward's recent post about simplifying Leo prompted a question that I've had for some time. How are markdown and reStructured Text different, and more importantly, why (or when) choose one over the other? My guess is that they are different 'dialects' of a similar language, but with somewhat different rules. I also notice that the output files (@clean or @file) differ in the handling of comment sections depending on which @language is selected; @language md creates comments as if the file were an xml or html file, whereas @language rest creates pure rst comments (..) Maybe it's just a personal preference, but others' insights on reasons for their choices would be most welcome.

Rob..........

--
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 leo-editor+...@googlegroups.com.
To post to this group, send email to leo-e...@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

[Edward K. Ream]

​​

On Fri, Mar 25, 2016 at 1:12 PM, Jacob Peck <gates...@gmail.com> wrote:

As for the comments thing -- markdown doesn't actually have comment syntax!  The entirety of a markdown file is supposed to be human readable content.  The workaround is using HTML comments, because the markdown spec states that a markdown parser shouldn't manipulate any elements that it can't identify, instead passing them verbatim to the finished document.

​Thanks.  I didn't know that.

I'm working on the viewrendered (vr) plugin as we speak.  The viewrendered pane now handles url links properly.  That is, you can single-click links. This has been broken basically forever.

Also, vr now handles @language reasonably, and degrades more gracefully if either the docutils (for rST) or markdown modules are missing.

I'll be retiring the viewrendered2 plugin asap, folding whatever features it might still uniquely provide into vr.

A bit later I plan to create simplified rst and md commands, much like the rst3 command but simpler.

Edward

[Chris George]

Is there any possibility to customize the markup characters used in markdown?

For example: There are currently a number of different "flavours" of markdown out there. Github uses a custom version that deviates from the norm. One of the most productive versions I have used is baked into piggydb, a note taking app I use. It uses the ' as the mark-up character, something that cuts keystrokes. eg. regular markdown uses * and _, both of which require a shift-char. If it is simple to make this configurable, it would be much appreciated.

Chris

[Terry Brown]

On Fri, 25 Mar 2016 15:34:01 -0500
"Edward K. Ream" <edre...@gmail.com> wrote:

> I'm working on the viewrendered (vr) plugin as we speak. The
> viewrendered pane now handles url links properly. That is, you can
> single-click links. This has been broken basically forever.
>
> Also, vr now handles @language reasonably, and degrades more
> gracefully if either the docutils (for rST) or markdown modules are
> missing.
>
> I'll be retiring the viewrendered2 plugin asap, folding whatever
> features it might still uniquely provide into vr.

That's great - just a note that the viewrendered pane shouldn't be a
singleton... you could have a particular instance bound to
`hide-viewrendered` etc. etc., but you be able to have more than one
viewrendered pane viewing different things at different times. This
functionality has existed to various degrees at various times, but
might be a bit fragile. For one thing it implies some vr panes track
the current tree position and some don't.

Let me know if I can help with any of the free_layout related aspects.

Cheers -Terry

[Offray Vladimir Luna Cárdenas]

Hi Rob,

I have been using both, ReST and markdown for academic/scholar writing inside and outside Leo, so here comes some comments from my experience.

- ReST, was more general and extensible, but being more pythonic used heavily indentation to define document blocks which at some time could be a nuance when you're trying to debug errors. It's a little bit to learn that markdown.

- Markdown is easier to write and learn and while without a common standard it's becoming the standard light markup for the web (GitHub, StackOverflow, Jupyter/IPython notebook, Discuss.org and others have support for it by default in its particular variants). With the emergence of Pandoc's markdown[1] and scholarly markdown the standardization and extensibility problems are being tackled by giving it a strong community of users writing complex texts and using the light serialization language yaml[3] for any data/feature that markdown can't use natively.

[1] http://pandoc.org/
[2] http://scholmd.org/
[3] https://en.wikipedia.org/wiki/YAML

In the case of Leo integration I found that was easier to me made my own custom writers/tree-traversals using markdown instead of ReST, because of the simplicity of the former over the last.

Hope this helps,

Offray

On 25/03/16 13:07, Largo84 wrote:

Edward's recent post about simplifying Leo prompted a question that I've had for some time. How are markdown and reStructured Text different, and more importantly, why (or when) choose one over the other? My guess is that they are different 'dialects' of a similar language, but with somewhat different rules. I also notice that the output files (@clean or @file) differ in the handling of comment sections depending on which @language is selected; @language md creates comments as if the file were an xml or html file, whereas @language rest creates pure rst comments (..) Maybe it's just a personal preference, but others' insights on reasons for their choices would be most welcome.

Rob..........

[Edward K. Ream]

On Fri, Mar 25, 2016 at 4:14 PM, 'Terry Brown' via leo-editor <leo-e...@googlegroups.com> wrote:

> I'll be retiring the viewrendered2 plugin asap, folding whatever
> features it might still uniquely provide into vr.

That's great - just a note that the viewrendered pane shouldn't be a
singleton... you could have a particular instance bound to
`hide-viewrendered` etc. etc., but you be able to have more than one
viewrendered pane viewing different things at different times.

​I see a ViewRenderedProvider.​

 

​Ah, I see what you mean.  The ns_provides method uses a cached controller if it exists.  It looks like the code you want is commented out:

    return ViewRenderedController(self.c)

I'll make the change now.
​

This
functionality has existed to various degrees at various times, but
might be a bit fragile.  For one thing it implies some vr panes track
the current tree position and some don't.

Let me know if I can help with any of the free_layout related aspects.

​Thanks.  I'll keep this in mind.​

Actually, I was thinking that the various "Provider" classes really only provide arguments to splitter.register_provider. And at last I see the call to register_provider for the ViewRenderedController class: it's in the ctor for the ViewRenderedProvider class.

I just don't see the need for the Provider classes. Why not just provide the info as arguments to register_provider?  The call to register_provider will always happen in a context where the data are easily available, so having a separate "encapsulation" class seems like overkill.

Furthermore, why not have the "id" be WhateverProvider.__class__.__name__?  This works provided that each Provider class actually has a distinct name.

What do you think?  Would it be somehow inconvenient to dispense with the Provider classes?

Edward

[Edward K. Ream]

On Fri, Mar 25, 2016 at 7:25 PM, Edward K. Ream <edre...@gmail.com> wrote:

​> ​

It looks like the code you want is commented out:

​> ​

return ViewRenderedController(self.c)

​Yikes. ​

 

​The global controllers dict is used all over the place.

I suppose entries in this dict could be lists of ViewRenderedControlllers, but do we really want to connect multiple vr panes to a single outline?  I'm pretty confused.

EKR

[gatesphere]

The details are murky now, but I remember a while back fixing a few bugs when viewrendered2 came about -- IIRC, the various help/docstring/plugin docs commands pretty much expect there to be a single vr pane.  I have no idea if that's still the case.

Just a heads up.
-->Jake

[Edward K. Ream]

​It sure looks that way to me.

BTW, the subtle differences between VR and VR2 are making ​my head spin.  I'm thinking that one way forward would be to base VR2 on VR.  That is, VR2 would use import leo.plugins.viewrendered and use the VR version of ViewRenderedController, perhaps with a mode bit, or just monkey patching the VR html_class ivar.

In other words, I would really like the only difference between the VR and VR2 plugins to be the value of the html_class ivar.  I'm not sure that makes sense, but it sure doesn't make sense to have two different almost-but-not-quite-identical ViewRenderedController classes!

Peter Mills, if you are following this, I'd like your comments.

Edward

[Peter Mills]

Sorry for the late reply.

I agree Edward, although rather than having VR2 based on VR, I think there should only be one viewrendered-type plugin. Having two must confuse a lot of users!

A few comments:

• There was a proposal in 2015 to merge VR2 and VR2 - https://groups.google.com/forum/?hl=en-GB#!searchin/leo-editor/VR2/leo-editor/cgmkazlacxg/YDrBKCyUBFMJ

• As I mentioned in that thread:

  “.. it was always intended to be merged with VR later on because of all the common code that remained and the confusion caused by the multiple VR plugins. Also, when installed, VR2 masquerades as VR anyway, to retain compatibility with the pane management etc.”

• (re Jake’s comment) Multiple VR2 panes was not only possible but incorporated into the design and GUI. VR2’s “Lock to node” option allowed a VR2 pane to stay rendering the nominated node, even when another VR2 pane was opened (using freelayout) and followed the highlighted node. This could in theory be extended to several VR2 panes locked to their own nodes. Alas, this “lock to node” feature broke somewhere in the very necessary conversion to Python3 code (the fix is not that hard though).

  Now that I test this (not having had multiple VR2 panes open for a long while), I find that a second VR2 pane refuses to open. It definitely used to work well. Similarly, with a VR2 pane open, getting help on a plugin would open a second VR2 pane (which also doesn’t work now).

• As Edward points out, VR2 is essentially a modified copy of VR that uses the QWebView renderer and a little GUI. This makes maintenance of both a chore because updates to the VR code has to be redone on VR2 in order to keep them in sync.

• I still use only VR2 (in fact this post has had it's html copied and pasted out of VR2) so I know it still does most of the things it was intended for, although I do sometimes patch in some fixes, like for the above “lock to node” bug.

In summary, I’d suggest (depending on how well VR2 has kept up with VR’s updates) that VR2 is essentially a superset of VR functionality, and should become the only VR plugin. If there is something that the VR renderer has that VR2’s QWebview pane cannot reproduce, then incorporating that would be good. It must be a superset of VR functionality to allow us to drop VR. Worst case, if necessary, would be to have a configuration item to choose which renderer the only VR plugin uses.

Of course we would need to fix some bugs in VR2 too ;-). I think I have a bit better handle on “git” these days, so I could probably be able to successfully submit a pull request as Edward suggested in the earlier discussion ;-)

Peter

[Terry Brown]

On Mon, 28 Mar 2016 03:51:38 -0700 (PDT)
Peter Mills <peter.m...@gmail.com> wrote:

> Sorry for the late reply.
>
> I agree Edward, although rather than having VR2 based on VR, I think

> there should only be *one* viewrendered-type plugin. Having two must

> confuse a lot of users!

I think all Peter's comments are on target, really the existence of two
VR plugins was only historical accident, and what we want is the union
of features from both implementations. Peter's recollection of the
ability to have multiple VR panes matches mine.

Best wishes on the thumb, Edward.

Cheers -Terry

> A few comments:
>
> -

>
> There was a proposal in 2015 to merge VR2 and VR2 -
> https://groups.google.com/forum/?hl=en-GB#!searchin/leo-editor/VR2/leo-editor/cgmkazlacxg/YDrBKCyUBFMJ

> -

>
> As I mentioned in that thread:
>
> “.. it was always intended to be merged with VR later on because
> of all the common code that remained and the confusion caused by the
> multiple VR plugins. Also, when installed, VR2 masquerades as VR
> anyway, to retain compatibility with the pane management etc.”

> -

>
> (re Jake’s comment) Multiple VR2 panes was not only possible but
> incorporated into the design and GUI. VR2’s “Lock to node” option
> allowed a VR2 pane to stay rendering the nominated node, even when
> another VR2 pane was opened (using freelayout) and followed the
> highlighted node. This could in theory be extended to several VR2
> panes locked to their own nodes. Alas, this “lock to node” feature
> broke somewhere in the very necessary conversion to Python3 code (the
> fix is not that hard though).
> Now that I test this (not having had multiple VR2 panes open for a
> long while), I find that a second VR2 pane refuses to open. It
> definitely used to work well. Similarly, with a VR2 pane open,
> getting help on a plugin would open a second VR2 pane (which also
> doesn’t work now).

> -

>
> As Edward points out, VR2 is essentially a modified copy of VR
> that uses the QWebView renderer and a little GUI. This makes
> maintenance of both a chore because updates to the VR code has to be
> redone on VR2 in order to keep them in sync.

> -

>
> I still use only VR2 (in fact this post has had it's html copied
> and pasted out of VR2) so I know it still does most of the things it
> was intended for, although I do sometimes patch in some fixes, like
> for the above “lock to node” bug.
>
> In summary, I’d suggest (depending on how well VR2 has kept up with
> VR’s updates) that VR2 is essentially a superset of VR functionality,

> and should become the *only* VR plugin. If there is something that

> the VR renderer has that VR2’s QWebview pane cannot reproduce, then
> incorporating that would be good. It must be a superset of VR
> functionality to allow us to drop VR. Worst case, if necessary, would

> be to have a configuration item to choose which renderer the *only*

[Edward K. Ream]

On Mon, Mar 28, 2016 at 5:51 AM, Peter Mills <peter.m...@gmail.com> wrote:

In summary, I’d suggest (depending on how well VR2 has kept up with VR’s updates) that VR2 is essentially a superset of VR functionality, and should become the only VR plugin.

​I agree, but this is far from easy, given the two different code bases.  I've tried several times to merge them. My head has exploded each time.

Last week I tried a more incremental approach. I'll omit the details, but it may allow me to keep my sanity.  It's second on the list, after fixing #156.

Imo, the new plugin should be called VR2, and the old plugin deprecated, but that will happen only after further testing. I'll definitely keep in mind that multiple VR panes should be possible, and make sure the locking option works.

Edward