12 Jul 2021 |
Jan Tojnar | I also looked into https://github.com/jgm/lunamark (lua should be small enough hopefully) | 23:49:38 |
Jan Tojnar | looks pretty nice but that does not support commonmark | 23:49:55 |
ryantm | perhaps the answer is to make a fork of either cmark or cmark-gfm. | 23:51:12 |
Jan Tojnar | yeah, but that would be even more work | 23:51:35 |
ryantm | Or maybe convince the cmark people to add a better extensibility mechanism. | 23:51:35 |
Jan Tojnar | so at the moment, it feels to me like the MyST is the best choice effort-wise | 23:51:58 |
ryantm | Yeah, that makes sense. I think I'm probably going to keep following the less pragmatic approach of making mmdoc though because I like it. | 23:52:42 |
ryantm | Even if it can't be adopted for nixpkgs, I believe it could be a useful tool. | 23:53:15 |
Jan Tojnar | so the manpage directive is primarily motivated by the NixOS options description, which I intend to convert to markdown soon | 23:59:21 |
13 Jul 2021 |
Jan Tojnar | IMO, it is too much effort for description authors to look for online versions of the man pages | 00:00:27 |
Jan Tojnar | but for the common ones, it makes sense to link them (and we can do that automatically if we know it is a manpage) | 00:01:00 |
Jan Tojnar | ryantm: I guess alternative would be just checking all inline codes if they match a known manpage | 00:03:43 |
ryantm | What if we use the CommonMark syntax for links referenced in multiple places but "magically" populate it from outside? | 00:05:11 |
ryantm | Like [][tmpfiles.d(5)] | 00:05:58 |
Jan Tojnar | that lacks the fallback when no link is present | 00:06:28 |
Jan Tojnar | so it would be even more magic (e.g. in github rendering) | 00:07:02 |
Jan Tojnar | hmm, I guess the xrefs do too | 00:07:45 |
Jan Tojnar | finally got the db-to-md conversion script to work – even forces pandoc to use fenced code blocks | 00:13:27 |
Jan Tojnar | * you did good job, but the API will not allow you do much better | 00:30:07 |
Jan Tojnar | * you did good job, but the API will not allow you to do much better | 00:30:15 |
Jan Tojnar | ryantm: one of the reasons I want to do high-fidelity db-to-md is that we still have not decided on the set of features we want to support | 00:42:28 |
Jan Tojnar | if we carry over as much as possible, we can then decide we do not want to have manpage links | 00:43:02 |
Jan Tojnar | but if we drop them in conversion, it will be PITA to add them back | 00:43:23 |
Jan Tojnar | eventually, I want to make a RFC evaluating each feature individually, based on different criteria | 00:46:55 |
Jan Tojnar | but until then, I want to preserve everything that is reasonably simple to preserve | 00:47:38 |
ryantm | Sounds good. | 00:55:03 |
Jan Tojnar | ryantm: I want to recommend the db-to-md script from the PR instead of manual pandoc+prettier invocation | 00:58:31 |
Jan Tojnar | now that we convinced pandoc to use fenced code blocks, we should not even need prettier | 00:59:34 |
ryantm | Maybe we could avoid "footnote" link magic, but aggregating the "footnote" links across the whole set of documents. | 01:00:16 |
ryantm | By "footnote" link, I mean the [link][1] ones | 01:00:36 |