**** semantic_markup_options for as500:
I'm on a quest for a replacement for UIM source. It's old & ugly & has little tool support. A lightweight markup language seems like a good fit.
UIM refreshers (hastily put together): 1 https://hannagoodbar.com/posts/2017/01/prism-language-definition-for-ibm-uim-2017-version/ 2 https://blog.lightlyseared.online/2013/01/24/adding-help-text-to-cl-commands/ 3 https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_74/apis/uim1a.htm
troff/groff, which is still used by unix for man pages. Unix geeks who still worship Knuth use LaTex for complex docs, which can also be converted to troff.
The script kiddies love Markdown, because github sort-of pushes it. (But they support other formats too https://github.com/github/markup#markups). Unfornately it not expressive or standardized enough to be useful at enterprise scale. (Like, see what some people do to work around simple missing features: https://codepen.io/WestonThayer/pen/bExXOJ).
Pythonistas use reStructuredText. It's also supported by github. More powerful & standardized then Markdown, but less intuitive & arguably less pretty. (e.g., can't just copy/paste from ms word).
The docbook format is xml, so it's semantically pure & complete, but needs conversion to be presentable.
It also has a complex DTD.
pod is in perl for perl. you'd have to love perl to love pod.
asciidoc has all the features of docbook but can be treated as "Markdown with more coherent syntax" too [1].
"Great projects use it, including Git, WeeChat and Pacman!" [2]
textile is another one, but I don't know of a compelling reason adopt it.
For tooling, pandoc converts between lots of formats. It's written in Haskell, which might be a portability issue if you're on a new platform that just got in from Mars. https://pandoc.org/
Some references: 1 https://news.ycombinator.com/item?id=9089952 "Why not format man pages as markdown?" 1 https://news.ycombinator.com/item?id=11292280 "Don't use markdown for docmentation." 1 https://news.ycombinator.com/item?id=14551423 1 https://espadrine.github.io/AsciiDocBox/ (browswer-based rendering) 1 https://www.reddit.com/r/programming/comments/4ck2lu/why_you_shouldnt_use_markdown_for_documentation/
In case you're still tempted to use markdown: 1 https://kristaps.bsd.lv/lowdown/ 1 https://github.com/greg-js/markdown2troff Converts markdown to troff/groff (the man-page format) using just regular expressions 1 http://rtomayko.github.io/ronn/ronn.1 ronn - convert markdown files to manpages 1 https://github.com/nereusx/md2roff
Random asciidoc links: 1 http://asciidoc.org/ (asciidoc+ -> html, latex, troff, slidy, s5 (presentations).
1 You can avoid the markdown vs rst debate completely by using a restricted subset https://gist.github.com/dupuy/1855764.
But that's rather restrictive.
_No mdoc. Bleh.