Hi Faidon, Quoting Faidon Liambotis (2022-01-24 15:03:44) > On Mon, Jan 24, 2022 at 02:12:06PM +0100, Jonas Smedegaard wrote: > > Personally I am of the opinion that more ideally such documentation > > should be treated as a source format with two targets - html and > > plaintext - and that both those target formats should be generated > > during package build and installed with the binary package(s). > > > > For Github-flavored Markdown I recommend to render both target > > formats using the command-line tool cmark-gfm. Here is an example > > of that: https://salsa.debian.org/debian/doctest/-/commit/d9b848b > > > > For most other flavors of Markdown I recommend to render using > > pandoc. Here is an example of that: > > https://salsa.debian.org/js-team/twitter-bootstrap3/-/commit/f138bf1 > > > > For Gitlab-flavored Markdown there are currently no parser in > > Debian, but depending on the actual markup used you might get away > > with pandoc + a filter (but may then give up on rendering as > > plaintext). Here is an example of that: > > https://salsa.debian.org/matrix-team/olm/-/commit/094396d > > > > Feel free to reach out if you need help juggling Markdown or using > > pandoc. I am no expert, but am interested, and am in touch with the > > author if all else fails ;-) > > I maintain "lowdown" in Debian. It supports several markup extensions > including several from GFM and CommonMark, and can output in HTML5, > roff (man/ms), LaTeX, ODF etc. It also has a terminal output mode, > that can be used to format and view Markdown documents in a pager. There are _many_ markdown tools... Lowdown indeed has some interesting features as interactive Markdown *reader* - thanks for mentioning. Package description however does not mention if _always_ a superset of markdown/CommonMark is parsed or the tool can be told to parse conservatively as well - perhaps relevant to add such information to the package long description? For *packaging* Markdown-authored documentation, where common format is html and plaintext, I still recommend to first consider more conservative and lightweight options¹, then more conservative yet heavy options² - i.e. only consider exciting tools when boring ones are unsuitable. - Jonas ¹ cmark is commonly regarded as one of the most conservative and lightweight - see e.g. https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/ ² yes pandoc is big but battle-tested and exact about which flavors are parsed. -- * Jonas Smedegaard - idealist & Internet-arkitekt * Tlf.: +45 40843136 Website: http://dr.jones.dk/ [x] quote me freely [ ] ask before reusing [ ] keep private
Attachment:
signature.asc
Description: signature