[Feature Request] Support of MarkDown in documentation area

[smileham]

In order to better support Archi as a tool for producing reports and documentation it would be useful to support the richer formatting available in the MarkDown language. This is the same language as GitHub uses for documentation, so has become a fairly "industry standard".

[theunsfvo]

This would definately help a lot in terms of document generaton directly from element properties, I agree.

[jbsarrodie]

In fact this has been discussed some years ago....

The real requirement here is to be able to use "rich text" in documentation (and maybe in property value), but this raises several technical questions as Eclipse framework (which Archi is based on) doesn't provide a good component for that.

So another approach is to add MarkDown conversion on the Jasper or HTML report itself. FWIW we have no plan for that in the near future but any contribution is welcome ;-)

[Phillipus]

It does raise some questions as JB has noted. Off the top of my head:

• Should documentation be Markdown, HTML, or RTF (or option for all)?
• Are there Eclipse components to render in preview (HTML, yes)
• What happens on Exchange format export? Convert to plain text? Something else?

Not saying these things can't be answered, just noting that a solution is not necessarily simple.

[jbsarrodie]

My personnal opinion on this is that I would avoid RTF and use Markdown. The advantage with Markdown is that it is text at the end, so the conversion to plain text is straightforward. The only question is: does it exist an Eclipse component for that?

[MilennialZero]

+1. Great idea. And be able to zoom enlarge text in documentation. I'm working on a Surface Pro and the display text is v tiny. :-)

Jon McLeod Director McLeod Consultancy Pty Ltd GPO Box 813, Canberra ACT 2601 Australia Silver Member, The Open Group

On 11 Oct 2017, at 00:40, smileham notifications@github.com wrote:

In order to better support Archi as a tool for producing reports and documentation it would be useful to support the richer formatting available in the MarkDown language. This is the same language as GitHub uses for documentation, so has become a fairly "industry standard".

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[radeksvarz]

If anyone plans to implement it, please make it somehow optional. Some documentation might be imported, where the source does not know about Markdown and uses Markdown's codes.

Anyway +1 to zoom enlarge text in documentation

[MilennialZero]

"+1 to zoom enlarge text in documentation"

+1 yes please - going blind working on this Surface Book screen.

Jon McLeod Director McLeod Consultancy Pty Ltd GPO Box 813, Canberra ACT 2601 Australia Silver Member, The Open Group

On 14 Oct 2017, at 18:25, Radek notifications@github.com wrote:

+1 to zoom enlarge text in documentation

[Phillipus]

As "larger text in documentation" is a separate issue, we need a new GitHub issue feature request issue as it will likely expand to include larger text in other UI elements too - name field, for example.

[Phillipus]

Opened issue #296

[theunsfvo]

Has RTF or HTML been included in future planned versions?

[WatchTh1]

Could I ask if this feature in the current roadmap? MD/HTML/RTF documentation would be realy great,

[jbsarrodie]

Hi,

There is still no plan for that, and unfortunately nobody candidated to contribute code for it.

[nicorikken]

I've created an work-in-progress PR: https://github.com/archimatetool/archi/pull/559 I'm interested in feedback on this approach.

[softnotes]

It will SOOOO cool if simple markdown formatting can be dropped into the Label Expression and Documentation attribute with some cascading behaviour. Pretty please...

Never knew I would miss simple underlining and bullets this much!!!

[olwol]

Checking for possibilities to format text in documentation fields for reports generated, I found: http://jasperreports.sourceforge.net/sample.reference/styledtext/index.html ("How to format text using a styled text tags as markup language."). To some degree it already works in Archi 4.9.1. E.g., I can have \<b> bold text \</b> and it is shown in the HTML report as expected. But I doubt it to really use the Jasperreports functionality as this only works with HTML and it harms a PDF report created (where this is shown as entered into the description field instead of changing the style to bold face). Would it be possible to have this enabled for the reports generated? Of course, it will not help in showing the text formatted in Archi itself but it would give a first level of markup support for the Jasperreports generated from Archi, isn't it?

[Phillipus]

Checking for possibilities to format text in documentation fields for reports generated, I found: http://jasperreports.sourceforge.net/sample.reference/styledtext/index.html ("How to format text using a styled text tags as markup language."). To some degree it already works in Archi 4.9.1. E.g., I can have bold text and it is shown in the HTML report as expected. But I doubt it to really use the Jasperreports functionality as this only works with HTML and it harms a PDF report created (where this is shown as entered into the description field instead of changing the style to bold face). Would it be possible to have this enabled for the reports generated? Of course, it will not help in showing the text formatted in Archi itself but it would give a first level of markup support for the Jasperreports generated from Archi, isn't it?

You can already do that yourself by editing the elements.jrxml file and adding markup="styled" to textElement:

<band height="26">
    <printWhenExpression><![CDATA[$F{documentation} != null]]></printWhenExpression>
    <textField isStretchWithOverflow="true">
        <reportElement style="Documentation" positionType="Float" x="1" y="8" width="514" height="18"/>
        <textElement markup="styled"/>
        <textFieldExpression><![CDATA[$F{documentation}]]></textFieldExpression>
    </textField>
</band>

Then you can add tags in Archi's Documentation fields:

This is an <style isBold="true" isItalic="true" isUnderline="true">example text</style> element 
containing styled text. <style backcolor="yellow" isBold="true" isItalic="true">Styled text</style> 
elements are introduced by setting the <style forecolor="blue" isItalic="true">markup</style> attribute 
available for the <style isBold="true" forecolor="magenta">textElement</style> tag to <style forecolor="red" 
isItalic="true">styled</style> and by formatting the text content using nested <style isBold="true" 
forecolor="green">style</style> tags and simple HTML tags.

[olwol]

Thanks for this hint. I could not find the right place to set it for a Model's Purpose nor for a View's Documentation text within file elements.jrxml. I tried file style.jrtx instead. There, I added the markup="styled" instruction to the style definition of style Normal. Instead of markup="styled", I use markup="html". It is easier for me.

File style.jrtx:

<jasperTemplate>
    <style name="Normal" fontName="DejaVu Sans" fontSize="12" markup="html"/>

That way, it works good for reports created using File>Report>Jasper.

File>Report>HTML does not work that well. The following HTML

Model's Purpose:

This is a <b><i><u>static text</u></i></b>.
<ul style="color: red;">
<li> a </li>
<li> b </li>
</ul>
<ol>
<li> a </li>
<li> b </li>
</ol>

is not shown as a numbered list. I tried it within Archi as well as with Chrome. It also does not show bullets infront of the list items. Is it possible to make File>Report>HTML support markup as well?

[Phillipus]

I tried file style.jrtx instead

Yes, that's a better place for it.

~There's a GitHub branch jasper with this set. I've added markup="html".~

Edit: I've added markup="html" to the style.jrtx file in the master branch. This is available in Archi 4.9.2 beta 2.

[Phillipus]

is not shown as a numbered list. I tried it within Archi as well as with Chrome. It also does not show bullets infront of the list items.

This is because the HTML Report has its own style sheet in model.css. The style for lists is:

ul, li {
  list-style-type: none;
  cursor: default;
}

Because the HTML report has its own style-sheet I'm not sure that embedding HTML and CSS in text fields is very reliable.

[Phillipus]

It turns out that the adding markup="html" to the styles in style.jrtx means that new lines are not showing when the report is generated. I am reverting this change until further investigation.

[Phillipus]

Moved to https://github.com/archimatetool/archi/issues/1032