Currently help files are xmls with a complicated schema. The analogy is .1 man files (but much more verbose).
Idea of platyPS project: instead of editing xml files directly, let’s author CommonMark files in a particular way (with all necessary information) and generate this xml help files as a build step.
It enables a simple collaboration story: MD is easy to edit in the browser on GitHub.
We called this particular way to author MD files a schema.
I tried to find any project that formalize the idea of markdown schema, but didn’t succeed.
We came up with a loose way to describe it.
Couple questions:
Markdown was designed to be rendered as html. Is our approach (another way to render it) something generally acceptable/useful?
Does it make sense to formalize the concept of MD schema? If yes, what’s the good way to describe such schema?
For 1), of course, it is acceptable to use Markdown for anykind of rendering output. The only thing that you may have to consider is : 1) the Markdown parser should provide an API to iterate over a markdown AST and 2) you may have to restrict/forbid some Markdown constructs not compatible with your output (e.g HTML blocks and HTML inlines for example)
For 2), sure, though, I would not bother formalizing a MD schema in a first step (instead of coding a specific AST extractor) unless you plan to have multiple schemas and want to automate this process. Then it is up to the implem of the Markdown parser, it should provide at least an access to the AST to produce your final AST (in your case that would contain additionnal AST nodes for: parsers/ast for // comments, multiline desc {{...}} and inline desc {...}), or you can add your own new parsers that will directly output a final AST. The second approach might be easier to deal and more robust (depending on the Markdown parser that you could use)
home-written markdown parser (btw, I’m excited about your announcement and waiting to try it out)
We are discussing a new schema at the moment.
Although, we probably would not try to generate transformers from formal schema, the question of schemes on top of markdown pop up again.
If it’s something generally useful (or already existing) we can collaborate with the community.
Way back in 2004, when John Gruber introduced Markdown, one of the goals stated in the opening paragraph was that it would be “easy-to-write.” By introducing a strict schema, it sounds to me like you’re hiding complexity, but not getting rid of it. Sites like Read the Docs have become popular because they turn Markdown (and reStructuredText) into HTML natively, and there’s no such thing as invalid input (worst-case scenario is you get poorly-formatted text). I understand the desire to want to move away from XML as an authoring language, but you might look at something more structured for an intermediary, so the author can understand the constraints she is under.