| 12 Jul 2021 |
 Jan Tojnar | I meant for the option documentation | 23:09:32 |
| Jan Tojnar | it will also allow us to swap the links locally (in the produced manpage) | 23:10:21 |
 ryantm | Jan Tojnar: What's stopping mmdoc from being a contender for you? | 23:28:24 |
| Jan Tojnar | ryantm: I though it was mostly meant as temporary demo | 23:29:07 |
| ryantm | Jan Tojnar: I made it because the NixOS manual needs a small closure-size renderer. I was hoping it could be made be good enough for all the manuals though, for consistency sake. | 23:30:27 |
| ryantm | I also like how fast it is. It should be pretty easy to set up some live-reload kind of thing. | 23:31:49 |
| Jan Tojnar | then there is the issue with extensibility – it is basically impossible to do anything more interesting without forking cmark-gfm | 23:35:55 |
| Jan Tojnar | and the other C library I found (lowmark) is extensible but basically frozen | 23:36:56 |
| ryantm | Maybe we do not need too much extensibility. The more we extend it, the more complicated it is for authors to use. I think that is part of the point of moving away from DocBook. | 23:38:11 |
| Jan Tojnar | yeah, but the RFC also agreed that the plain CommonMark is too little | 23:41:35 |
| Jan Tojnar | and even basic stuff like admonitions is currently super hacky | 23:42:12 |
| Jan Tojnar | if we want to maintain our own solution, it should be at least easy, IMO | 23:44:15 |
| ryantm | Fair enough. I did throw together the extensions I added very quickly. | 23:46:33 |
| ryantm | I'm planning to keep working on mmdoc, and I have some time over the next couple weeks, so hopefully I can improve it a bunch. | 23:48:00 |
| Jan Tojnar | you did good job, the API will not allow you do much better | 23:48:47 |
| 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 |
