When dumping script documentation to the console (#947), it would be nice to interpret the markup.

bay12 discussion here

Would it be possible to make a print-like command for Lua (or just its own script) that accepts markdown syntax? It doesn't need to be 100% faithful (maybe use colors for bold and italic), but something that could make sense out of the same markdown text used in the documentation on GitHub.

Context: documentation for scripts is now contained in the script files, between tokens that (in lua) denote a multiline comment or string (comment only in Ruby). This text is marked up in "restructured text" format, which is similar to markdown but better for large documents, and used to generate the html docs. It is also used as in-console help for some scripts - unifying the interactive help, documentation, and comments for maintainers. An upgrade to the dfhack core command "help" is planned which will make the docs for all scripts available without adding -help flags on a per-script basis.

Dirst - I think what you want is for help text in the console to have some actual formatting, rather than just dumping all the markup characters. This is a logical extension of the open issue, and actually pretty easy to do. (though IMO it's plenty readable anyway...)

There are, I think, only a few main constructs to handle.

• bold, italics, and monospace can be handled by colors, and nesting is not supported.
• The title is always the first word, on it's own line, and underlined with its length in ===== on the next line -- another color would do.
• 'Definition lists' have the term (command) first between colons, then spaces to align and the explanation (possibly multiline) -- just color term and remove the colons.
• "::" indicates that the following (indented) block is monospaced; it should be replaced with ":" if on the end of a line or removed if nothing precedes it.
• leading and trailing empty lines should be stripped.
• cross-references are surrounded by single backticks -- another color.

It's not trivial, but nor would that be too difficult to implement in Lua.