...
| 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://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
...