is there a virtual package for viewing MD documentsDo you mean Markdown? Are there specialized viewers for it at all?
On Mon, Jan 24, 2022 at 10:36:50AM +0100, Jerome BENOIT wrote:
is there a virtual package for viewing MD documentsDo you mean Markdown? Are there specialized viewers for it at all?
is there a virtual package for viewing MD documents
(as the virtual package pdf-viewer is for PDF documents) ?
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
I am asking because a software that I am currently packaging has its documentsYou can likely read those with `less`.
in MarDown (GitHub flavour, I guess).
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.
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 ;-)
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.
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.
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.
cmark is a good option too; pandoc is as well, if bootstrapping is not
a concern.
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
Sysop: | Keyop |
---|---|
Location: | Huddersfield, West Yorkshire, UK |
Users: | 339 |
Nodes: | 16 (2 / 14) |
Uptime: | 00:17:29 |
Calls: | 7,466 |
Calls today: | 2 |
Files: | 12,691 |
Messages: | 5,627,864 |