Background

As I see the increasing use of shared code repository tools for document management, I'm also starting to look at the different markup languages available to us and in common use. This page holds some of my notes on the topic.

Andrew Hughes, Leadership Council Chair, 2016-09-12

Code repository services

Markup Languages suitable for Kantara purposes

Note: I don't have a bias towards/against any markup language here. So if there is an imbalance in positive v negative review links it is not intentional.

Name	Home URL	Info and reviews	Comparison articles	Works well with...
Markdown		http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ http://www.adamhyde.net/whats-wrong-with-markdown/	http://hyperpolyglot.org/lightweight-markup
AsciiDoc		http://asciidoctor.org/docs/what-is-asciidoc/	http://hyperpolyglot.org/lightweight-markup
reStructuredText (RST)		https://en.wikipedia.org/wiki/ReStructuredText	http://hyperpolyglot.org/lightweight-markup	Python

Other thoughts

This might not be a popular position, but what if:

• DocBook or LaTeX for the canonical version of the document. 
• A Markdown variant published to github to allow open issue tracking and modification suggestions

A possible 'flow':

• During initial document creation, use any document editor to author large chunks of material then export to Markdown loaded into a github project
• Issues, forks, branches, merges are used to improve the text
• At a suitable point in time, use pandoc to convert the Markdown document to DocBook or LaTeX
• Regenerate the Markdown as an export from the DocBook or LaTeX
• Continue with issues, forks, branches, merges to improve the text
• Editor decides when and how to bring the updates back into the canonical document

For low to moderately structured documents this should work without too much pain. Kantara DTDs and stylesheets can be created to unify presentation and output structure.

For highly structured documents there could be significant work keeping the Markdown and canonical versions synchronized. In particular if the Markdown rendering is unable to preserve or passthrough DocBook or LaTeX tags/elements - but there are several reports that passthrough of structured elements should be possible with some Markdown variants.

Historical Posts from meetings and email reflectors

Page attachments