RE: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec

Hi Paul,

Thanks for you constructive comments. Our plan is to spend some time discussing this during tomorrowâs Ad-Hoc meeting.

Chris

From: tosca@lists.oasis-open.org <tosca@lists.oasis-open.org> On Behalf Of Paul L.
Sent: Monday, February 24, 2020 8:20 PM
To: Tal Liron <tliron@redhat.com>
Cc: tosca@lists.oasis-open.org
Subject: RE: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec

Thanks for your helpful information and all the resources, Tal. Feel free to ask Chris if he would schedule a time for that discussion in the ad hoc first, if youâd prefer, although that is not required. Just drop Chris and me a line a couple of days notice before a TC meeting, please, when/if you are ready to propose the change more formally.

Regards,

Paul

From: Tal Liron <tliron@redhat.com>
Sent: Monday, February 24, 2020 10:56 PM
To: Paul L. <paul.lipton@live.com>
Cc: tosca@lists.oasis-open.org
Subject: Re: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec

On Mon, Feb 24, 2020 at 7:32 PM Paul L. <paul.lipton@live.com> wrote:

More seriously, may I assume that there are commands and specialized markup to learn? Presuming yes, then is there some sort of WYSIWYG mode that can generate tags for people who prefer that form of editing? Also, can it import a Word file into a specific section of the text and attempt to autogenerate tags so that contributions written in Word can be more easily integrated? Just curious.

The Markdown language is one of the simplest markup languages. In most cases it looks pretty much like regular old text. Here's a quick primer -- which really covers pretty much the entire language. Tables are a bit more complex, but they are complex in Word, too. In some cases they are actually easier in Markdown.

Yes, there is a WYSIWYG mode that behaves pretty much like any word processor. There is no shortage of good editors. For our intended use I was specifically looking for an editor with good collaboration tools, especially a way to embed comments. There aren't many choices for that -- I evaluated the popular ones and zeroed in on StackEdit as one that seems to tick all the boxes. You can give it a look yourself, within minutes you should get a feel for how it would work. To see the commenting feature, just select some text with your mouse and you will see a little dialog icon appear on the side. Click that and it will let you comment.

We can't exactly import from Word to Markdown. There are conversion tools to help us get started if we like, but some manual work is needed. I don't think we would even need those tools: in just 30 minutes I managed to convert two chapters from the spec, as a trial, just by copying and pasting from opening the Word doc in LibreOffice. The TOSCA spec doesn't really need anything fancy. We just have headings, paragraphs of text, tables, embedded YAML, and a few images. We don't even use footnotes (though Markdown can do those, too).

Moving Word comments to StackEdit is trickier. But honestly there aren't that many in the spec. Assuming we do want to use it for our offline editorial work, it won't be too difficult to make a transition. Compared to the rest of the work we want to do for TOSCA 2.0, this would seem to be the easiest part. :)

If youâre interested in showing the tool to the TC, perhaps with some examples of from the standard, I could leave the Zoom open after the TC meeting of March 12^th ends, or perhaps after a later TC meeting for 30 minutes. No pressure. Just a thought.

I would be happy to, though I thought I might present it in the ad hoc first and see if there's enough interest there.

tosca message