| 11 Jun 2023 |
 @penguincoder:matrix.wolfie.pw | Where is the current manual located? | 00:53:28 |
 pennae | which one? rendered or source? | 00:54:36 |
| @penguincoder:matrix.wolfie.pw | Source! I’m curious about the above changes to your workflow and current state-of-the-world | 01:35:54 |
| pennae | nixpkgs and nixos manuals live in the nixpkgs repo, under doc and nixos/doc respectively | 01:37:02 |
| pennae | state of the world is basically "ugh" | 01:38:37 |
| pennae | there's a lot of legacy docbook workflow that's in an eternal state of being replaced but not quite gone yet, which is always very fun and makes docs build errors extremely Fun™ to debug | 01:40:44 |
| @penguincoder:matrix.wolfie.pw | Is it just built with CI? Much like a Unix system, I know CI. | 01:42:22 |
| pennae | ci does build docs for prs, docs for user systems are built by hydra but use the same expressions | 01:43:33 |
| pennae | or, if users added to the docs (eg via the module system), the docs are built on the user system. that's probably not the common case though | 01:44:28 |
| pennae | especially since the nixos docs build was excrutiatingly slow for the longest time and still spends way to much time in docbook even now, but that's on the way out at least | 01:45:10 |
| @penguincoder:matrix.wolfie.pw | Okay. Well, my current project at work is called “CI Speed”. Where are the jobs stored? I can piece together what they do and maybe find a quicker way to build it. | 01:50:23 |
| pennae | we've got the speed thing sorted out, it's just a question of removing the docbook interim stage | 01:52:55 |
| pennae | which is also for the most part just needs flipping a switch (and emplacing some dummy epubs that link to the html manual) | 01:53:56 |
| pennae | (i think last we benchmarked it the docbook-free nixos manual build took five seconds, vs five minutes it took a few releases ago before xsltproc got their shit together somewhat) | 01:55:33 |
| @penguincoder:matrix.wolfie.pw | Oh, that’s an impressive improvement in runtime. So the biggest challenge is just undesirable process and cruft? | 01:59:19 |
| pennae | that's one way to put it | 01:59:58 |
| pennae | docbook rendering has been (and still is to an extent) slow because xsltproc just isn't really up to the sizes of manuals we throw at it. and nobody likes writing docbook. | 02:01:09 |
| @penguincoder:matrix.wolfie.pw | Is porting an option? | 02:06:17 |
| @penguincoder:matrix.wolfie.pw | mdbook is nice | 02:06:31 |
| pennae | well, we've already written an entirely new system because mdbook was deemed too large 😬 | 02:06:57 |
| pennae | same principle though, if with a much larger markdown dialect that's more amenable to extension as we need | 02:07:27 |
| pennae | the nixos manual build is currently the only thing that uses this and is unfortunately a bit complicated, so it's not quite that easy to demonstrate unless you dig a lot | 02:10:40 |
| @penguincoder:matrix.wolfie.pw | Okay, that’s totally reasonable. Can you point me to that process?
Also: mdbook was too big? I thought it was small? | 02:26:43 |
| pennae | mdbook is big in that it has a lot of large dependencies (eg, the rust compiler) | 02:31:31 |
| pennae | gotta go now too | 02:32:10 |
| @penguincoder:matrix.wolfie.pw | I can understand that the Rust ecosystem is too much for a single step. Don’t get me wrong, I like it. But I can totally get why there would be resistance. As a single item, mdbook is not enough to adopt rust.
Thanks for your explantions pennae | 03:53:13 |
 Jan Tojnar | In reply to @pennae:matrix.eno.space
pandoc does not seem to natively support rendering docbook figures from image sources? excellent. what do you mean? In pandoc 2, there is https://github.com/jgm/pandoc/blob/2.19.2/src/Text/Pandoc/Writers/Docbook.hs#L235-L246 and you need to make sure it is figure in the Pandoc AST (e.g. when using markdown reader with implicit_figures extension) | 15:30:51 |
| pennae | In reply to @jtojnar:matrix.org
what do you mean? In pandoc 2, there is https://github.com/jgm/pandoc/blob/2.19.2/src/Text/Pandoc/Writers/Docbook.hs#L235-L246 and you need to make sure it is figure in the Pandoc AST (e.g. when using markdown reader with implicit_figures extension) that does not generate the same figures the graphviz block does. we haven't found any way to generate that node in about 10 minutes of searching, and then decided it's not worth the effort to convert the figure to markdown first if it's only to keep the diff between mauals small. it's just the one image after all | 15:32:44 |
| Jan Tojnar | yeah, that sounds reasonable | 15:33:24 |
| Jan Tojnar | IIRC, the criteria were image standing alone in a paragraph, having title starting with fig: | 15:36:26 |
