Use markdown for purpose, use, misuse, etc on archetypes

Description

While doing archetype translations, I saw some use and misuse nodes that have a lot of text and some custom format. It would be good to provider markdown capabiliites by encouraging to make those sections markdown, and use the markdown on tools for display those sections formatted, and maybe generate formatted documentation from archetypes.

Environment

None

Activity

Show:
openEHR ADM
May 6, 2015, 1:56 PM

If markdown is going to be used, it will need to conform to this specification - http://commonmark.org/ , which is a spec designed by Github, StackExchange and other people. I don't see anything else that could be trusted.

Shinji Kobayashi
May 6, 2015, 3:11 PM

I do not have much motivation to include markdown to ADL formalism as a parser implementer, because formalism in formalism could be problematic to parse them.
I confirmed the ADL parser implementation of JavaCC, and the parser does not seem to cause parse error on parsing V_STRING by Markdown syntax. But i am not sure about the result. We need careful tests, before we adopt to write markdown on editors and other tools.
I think Markdown text is not DV_TEXT, but DV_PARSABLE.

Pablo Pazos
May 6, 2015, 3:14 PM

Hi Shinji, this wouldn't need extra parsing, is just for interpretation and display formatted text at the UI level.

Koray Atalag
May 7, 2015, 10:51 PM

Just some food for additional thought - we are using https://readthedocs.org/ for all our documentation needs which include markdown features but a whole raft of other features that play nicely with software and specifications development. It has GitHub and Bitbucket integration too. So potentially we can consider this as a tool for specifications development and publication (e.g. has pdf creation).

Markdown's own documentation is actually on this: http://markdown-guide.readthedocs.org/en/latest/

Have a look maybe we can learn something from this.
Note that at my organisation we develop domain specific modelling languages and software for computational physiology.

Thomas Beale
May 8, 2015, 12:16 PM

just had a look - what about numbered headings? Multi-level bulleting? Indexes? Docs made from tool-based and static content? PDF generation? etc...

Reporter

Pablo Pazos

Components

Priority

Major
Configure