feat: markdown parsing

[nicorikken]

This is a work-in-progress pull request to tackle #293

I've chosen the easy Javascript route, rather than the (for me) complicated Java route. As a result the Markdown parsing is not present in the Archi UI itself, or in Jasper reports.

I'm interested in your feedback.

The results of this change:

[Phillipus]

From what I can see this loads a JS MD parsing library and converts any MD present in the Documentation field in the HTML Report.

I guess that's one approach, the other being to natively convert any MD via a Java library at the point of export. But as you say, "I've chosen the easy Javascript route, rather than the (for me) complicated Java route." So this would not work for Jasper.

@jbsarrodie is working on a new HTML report, and it might be better to have a more rounded solution combining MD support natively. But...you could distribute your report template as well.

[nicorikken]

From what I can see this loads a JS MD parsing library and converts any MD present in the Documentation field in the HTML Report.
I guess that's one approach, the other being to natively convert any MD via a Java library at the point of export. But as you say, "I've chosen the easy Javascript route, rather than the (for me) complicated Java route." So this would not work for Jasper.

Indeed that is the solution I came up with. Building it into Java seems better. That'll take me more time and effort to come up with a contribution. For that I have some additional questions:

• Where should the user choose for Markdown? Is it on by default, is it to be activated by each textbox, or is it to be activated at the moment of exporting?
• How to deal with markdown source in the editor? Automatic syntax highlighting? Perhaps a preview tab which shows the resulting HTML output.
• Other formats like RTF and XHTML have been mentioned in the GitHub issue tracker. Similiarly I'm a proponent of Asciidoctor. But I think the pragmatic approach is that Markdown is a very popular default, and a defacto standard. Other formats could be added later.

Perhaps there is a WYSIWYG editor available for Java that can be included.

@jbsarrodie is working on a new HTML report, and it might be better to have a more rounded solution combining MD support natively. But...you could distribute your report template as well.

Where can I view this work? Or what can I expect from this? Will it just put the documentation at a different location, or will there be a significant change in technology and structure?

[nicorikken]

So if I understand correctly, that would require modifying the getDocumentation call, as used in:

archi/com.archimatetool.jasperreports/src/com/archimatetool/jasperreports/data/FieldDataFactory.java

Lines 70 to 73 in 288941b

	if(DOCUMENTATION.equals(fieldName) && dataElement instanceof IDocumentable) {
	String s = ((IDocumentable)dataElement).getDocumentation();
	return StringUtils.isSet(s) ? s : null;
	}

And as used in

archi/tests/com.archimatetool.csv.tests/src/com/archimatetool/csv/importer/CSVImporterTests.java

Line 119 in 3c9f421

assertEquals("This is the Business Actor\r\nDocumentation\r\nHere \"\"\r\n", element.getDocumentation());

So either there would need to be an option for getting it as parsed Markdown, or a custom function.

Can Jasper Report deal with HTML data? In that case the HTML output can be used in both cases.

There is a variety of Java libraries for dealing with Markdown files: https://stackoverflow.com/questions/19784525/markdown-to-html-with-java-scala

Also for the UI inspiration can be drawn from Eclipse plugins like https://github.com/satyagraha/gfm_viewer

[jbsarrodie]

Hi,

My 2cts on this...

I personally like the idea of being able to use markdown in several places, but this has to be made optional, or else we'll impact reports for everyone.

You can find here the ideas I'm collecting for a new HTML export. This does not details my ideas around markdown though, so in short, here's how I see it:

• At first, provide a global "switch" that people can turn "on" on the report itself (and maybe that can be passed as a URL argument. When "on", descriptions are parsed as markdown and rendered accordingly. We could even make it not only a "on/off" but let people choose the markup language used.
• In the far future, we could maybe make it part of Archi itself, but this would require Archi to be able to render the rich text version, and jasper report should take care of it too.

[Phillipus]

If MD is supported we need:

1. Documentation field stays at it is. It simply contains text.
2. A previewer in Archi (and a library that is maintained, we don't want to keep fixing it or it's no longer supported)
3. Rendered in HTML report
4. Rendered in Jasper report
5. Consider what to do for exchange format export - strip Markup or leave as is? Other tools might not support MD

[Phillipus]

BTW - HTML already has a previewer - the inbuilt Browser component as this is used when creating hints for Canvas objects.

[nicorikken]

Check, thanks for the input. I'll see if I can contribute a Java-based Markdown renderer. I think this PR can be closed as a Java based solution is preferred.