Re: generic viewer for md files
On Mon, Jan 24, 2022 at 10:36:50AM +0100, Jerome BENOIT wrote: > is there a virtual package for viewing MD documents Do you mean Markdown? Are there specialized viewers for it at all? -- WBR, wRAR signature.asc Description: PGP signature
Re: generic viewer for md files
Andrey Rahmatullin writes: > On Mon, Jan 24, 2022 at 10:36:50AM +0100, Jerome BENOIT wrote: >> is there a virtual package for viewing MD documents > Do you mean Markdown? Are there specialized viewers for it at all? The only one I know is https://metacpan.org/pod/sdview, but that's not packaged in Debian (yet). - ilmari
Re: generic viewer for md files
Hi Jerome, Quoting Jerome BENOIT (2022-01-24 10:36:50) > is there a virtual package for viewing MD documents > (as the virtual package pdf-viewer is for PDF documents) ? I assume that by MD you mean markdown... No, Debian has no general virtual "markdown-viewer" package. Unlike PDF and DjVu, Markdown is by design sloppy which has lead to a multitude of "flavors", so I suspect it is unlikely that we can find any common baseline that such virtual package should promise to provide. Possibly it would make sense to define a "commonmark-github-flavored-viewer" since that is a reasonably popular flavor? Here are some markdown viewers/editors currently in Debian: * grip * formiko * mdp * pampi * ghostwriter * kookbook * retext Why do you ask? Because you are looking for markdown viewers or because you are packaging one and want to declare it as such, or...? - Jonas -- * Jonas Smedegaard - idealist & Internet-arkitekt * Tlf.: +45 40843136 Website: http://dr.jones.dk/ [x] quote me freely [ ] ask before reusing [ ] keep private signature.asc Description: signature
Re: generic viewer for md files
Hello All, thanks for your replies. On 24/01/2022 12:10, Jonas Smedegaard wrote: Hi Jerome, Quoting Jerome BENOIT (2022-01-24 10:36:50) is there a virtual package for viewing MD documents (as the virtual package pdf-viewer is for PDF documents) ? I assume that by MD you mean markdown... indeed No, Debian has no general virtual "markdown-viewer" package. Unlike PDF and DjVu, Markdown is by design sloppy which has lead to a multitude of "flavors", so I suspect it is unlikely that we can find any common baseline that such virtual package should promise to provide. Possibly it would make sense to define a "commonmark-github-flavored-viewer" since that is a reasonably popular flavor? Here are some markdown viewers/editors currently in Debian: * grip * formiko * mdp * pampi * ghostwriter * kookbook * retext Why do you ask? Because you are looking for markdown viewers or because you are packaging one and want to declare it as such, or...? I am asking because a software that I am currently packaging has its documents in MarDown (GitHub flavour, I guess). So my understanding now is that there is no point to look for a generic MD viewer. Therefore I am now considering to convert them in PDF and/or HTML documents. Cheers, Jerome - Jonas -- Jerome BENOIT | calculus+at-rezozer^dot*net https://qa.debian.org/developer.php?login=calcu...@rezozer.net AE28 AE15 710D FF1D 87E5 A762 3F92 19A6 7F36 C68B OpenPGP_signature Description: OpenPGP digital signature
Re: generic viewer for md files
On Mon, Jan 24, 2022 at 12:46:40PM +0100, Jerome BENOIT wrote: > I am asking because a software that I am currently packaging has its documents > in MarDown (GitHub flavour, I guess). You can likely read those with `less`. Alternatively, software is likely to ship a build script for e.g. HTML in which case you should use it (see https://www.debian.org/doc/debian-policy/ch-docs.html#preferred-documentation-formats). -- WBR, wRAR signature.asc Description: PGP signature
Re: generic viewer for md files
Quoting Jerome BENOIT (2022-01-24 12:46:40) > On 24/01/2022 12:10, Jonas Smedegaard wrote: > > Quoting Jerome BENOIT (2022-01-24 10:36:50) > >> is there a virtual package for viewing MD documents > >> (as the virtual package pdf-viewer is for PDF documents) ? [...] > > Why do you ask? Because you are looking for markdown viewers or > > because you are packaging one and want to declare it as such, or...? > > I am asking because a software that I am currently packaging has its > documents in MarDown (GitHub flavour, I guess). > > So my understanding now is that there is no point to look for a > generic MD viewer. > > Therefore I am now considering to convert them in PDF and/or HTML > documents. It is quite common nowadays for software projects to ship at least core documentation in (github- or Gitlab-flavored) Markdown (or CommonMark, a non-sloppy spec'ed slight subset of Markdown). As others replying here have indicated, the easiest is to ship such files as-is, assuming that the reader is geeky enough to read it raw. 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 ;-) - Jonas -- * Jonas Smedegaard - idealist & Internet-arkitekt * Tlf.: +45 40843136 Website: http://dr.jones.dk/ [x] quote me freely [ ] ask before reusing [ ] keep private signature.asc Description: signature
Re: generic viewer for md files
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. Upstream is at https://kristaps.bsd.lv/lowdown/ and the package in Debian is just "lowdown". Upstream is very responsive, so if you miss a particular feature please file a bug (preferrably upstream, but I can also forward) It's written in plain C and has no dependencies apart from libbsd. That is of note, because pandoc is notorious for being hard to bootstrap (because of Haskell) and the only other alternative I had explored for my use case was ronn, which is in Ruby and thus also has a complicated dependency chain. (Depending on your package, you may or may not care about your build-dependency chain; I did.) Regards, Faidon 1: https://kristaps.bsd.lv/lowdown/
Re: generic viewer for md files
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 signature.asc Description: signature
Re: generic viewer for md files
On Mon, Jan 24, 2022 at 04:29:54PM +0100, Jonas Smedegaard wrote: > 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? lowdown describes itself primarily as a translator rather than a reader (that part is already in the package description). There are indeed many customization options with regards to disabling various features, whether markup extension-related (Markdown, CommonMark, GFM, MultiMarkdown, PHP Extra) or otherwise, such as --parse-no-cmark. lowdown(1) and lowdown(5) have all the details (in the package or on the website). I'll try to find a way to document that in the long description in a future upload; thank you for the suggestion. > 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. Agreed, and why I recommended lowdown as a pretty conservative and lightweight option. cmark is a good option too; pandoc is as well, if bootstrapping is not a concern. Regards, Faidon
Re: generic viewer for md files
Quoting Faidon Liambotis (2022-01-24 20:08:01) > On Mon, Jan 24, 2022 at 04:29:54PM +0100, Jonas Smedegaard wrote: > > 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. > > Agreed, and why I recommended lowdown as a pretty conservative and > lightweight option. Sorry if I was unclear: I recommend *conservative* options over *pretty conservative* options. :-P See e.g. "accurate" and "robust" at https://github.com/commonmark/cmark (didn't find any comparable claims at lowdown Homepage). > cmark is a good option too; pandoc is as well, if bootstrapping is not > a concern. Use to avoid bootstrapping being a concern. - Jonas -- * Jonas Smedegaard - idealist & Internet-arkitekt * Tlf.: +45 40843136 Website: http://dr.jones.dk/ [x] quote me freely [ ] ask before reusing [ ] keep private signature.asc Description: signature
Re: generic viewer for md files
Thanks again for your hints. Finally I converts my MarkDown documents in HTML with pandoc. Cheers, Jerome On 24/01/2022 12:46, Jerome BENOIT wrote: Hello All, thanks for your replies. On 24/01/2022 12:10, Jonas Smedegaard wrote: Hi Jerome, Quoting Jerome BENOIT (2022-01-24 10:36:50) is there a virtual package for viewing MD documents (as the virtual package pdf-viewer is for PDF documents) ? I assume that by MD you mean markdown... indeed No, Debian has no general virtual "markdown-viewer" package. Unlike PDF and DjVu, Markdown is by design sloppy which has lead to a multitude of "flavors", so I suspect it is unlikely that we can find any common baseline that such virtual package should promise to provide. Possibly it would make sense to define a "commonmark-github-flavored-viewer" since that is a reasonably popular flavor? Here are some markdown viewers/editors currently in Debian: * grip * formiko * mdp * pampi * ghostwriter * kookbook * retext Why do you ask? Because you are looking for markdown viewers or because you are packaging one and want to declare it as such, or...? I am asking because a software that I am currently packaging has its documents in MarDown (GitHub flavour, I guess). So my understanding now is that there is no point to look for a generic MD viewer. Therefore I am now considering to convert them in PDF and/or HTML documents. Cheers, Jerome - Jonas -- Jerome BENOIT | calculus+at-rezozer^dot*net https://qa.debian.org/developer.php?login=calcu...@rezozer.net AE28 AE15 710D FF1D 87E5 A762 3F92 19A6 7F36 C68B OpenPGP_signature Description: OpenPGP digital signature
