Similarities
doctools: [section {Section A}]
HTML: <h2>Section A</h2>
markdown: ## Section A
doctools: [emph {Some emphasized text}]
HTML: <emph>Some emphasized text</emph>
markdown: *Some emphasized text*
Markup in doctools not present in markdown (out of the box)
Tcl syntax notation: lsort -integer <aList>
doctools: [call [cmd lsort] [opt [-integer]] [arg aList]]
It can be done with Pandoc's markdown, just not with the basic syntax, here using class names:
[lsort]{.cmd} [-integer]{.opt} [aList]{.arg}
Reasons not to use doctools
Markdown uses least "noise" making that particular format human-readable for most parts, the markup is not looking as if it were programming/coding the text, making the documents accessible to people not wanting to "read code". That was the important issue in the invention of markdown in the first place - make writing and reading easy.
As an end goal, we want a pure Tcl toolchain and not rely on external tools such as Pandoc (so documentation can be built as part of the compile process when building Tcl, only having typical tools such as gcc, make etc. at hand). This is currently impossible, even with doctools. We would need to move tcllib modules such as doctools and its many dependencies into the core (and enhance them on the way to cover our needs). -- For markdown, we only need the tcllib markdown module (and textutil::tabify) and enhance it which is a bit easier to manage.