!avYyleMexqjFHoqrME:nixos.org

Nix Documentation

420 Members
Discussion about documentation improvements around the Nix ecosystem84 Servers

You have reached the beginning of time (for this room).


SenderMessageTime
11 Jun 2023
@penguincoder:matrix.wolfie.pw@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:matrix.eno.space@pennae:matrix.eno.spacemdbook is big in that it has a lot of large dependencies (eg, the rust compiler)02:31:31
@pennae:matrix.eno.space@pennae:matrix.eno.spacegotta go now too02:32:10
@penguincoder:matrix.wolfie.pw@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
@jtojnar:matrix.orgJan 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:matrix.eno.space@pennae:matrix.eno.space
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
@jtojnar:matrix.orgJan Tojnaryeah, that sounds reasonable15:33:24
@jtojnar:matrix.orgJan Tojnar IIRC, the criteria were image standing alone in a paragraph, having title starting with fig: 15:36:26
@pennae:matrix.eno.space@pennae:matrix.eno.spaceah, that may have been the missing bit. we didn't add a title at all15:47:02
@pennae:matrix.eno.space@pennae:matrix.eno.spacepandoc docs make it look like that's not needed and the original didn't have a title either, so that wouldn't've done any good to minimize the diff anyway15:48:07
@proofconstruction:matrix.orgproofconstructionwhy would we need to "adopt" rust to use mdbook? we're not building the mdbook binary every time we render the docs (i hope)15:55:01
@pennae:matrix.eno.space@pennae:matrix.eno.spaceci might15:56:49
@pennae:matrix.eno.space@pennae:matrix.eno.space

just did a little test on manual build times after changes:

19.03     0:37
19.09     0:39
20.03     0:44
20.09     0:51
21.05     1:07
21.11     1:22
22.05     1:39
22.11     1:55
23.05     1:00
-docbook  0:13
16:07:43
@pennae:matrix.eno.space@pennae:matrix.eno.space that's timing the nix-build call that builds the manual, so the actual improvement in the manual build is going to be larger than it seems here 16:08:16
@pennae:matrix.eno.space@pennae:matrix.eno.spacethe final run spent half of its time in nix itself16:10:46
@pennae:matrix.eno.space@pennae:matrix.eno.space https://github.com/NixOS/nixpkgs/pull/237237
begone, foul simulacrum of paper
19:23:25
12 Jun 2023
@Ericson2314:matrix.orgJohn Ericsonhttps://git-scm.com/book/en/v2/Git-Internals-Git-Objects14:44:57
13 Jun 2023
@pennae:matrix.eno.space@pennae:matrix.eno.space https://github.com/NixOS/nixpkgs/pull/237557 there we go. nixos manual sans docbook 12:42:43
@pennae:matrix.eno.space@pennae:matrix.eno.spaceand nixpkgs isn't that far behind at this point12:42:51
@pennae:matrix.eno.space@pennae:matrix.eno.spacewe've got nixpkgs mostly done, just needs a few more changes to nixdoc that we'll take care of before too long (hopefully)12:49:05
@mrcjk:matrix.orgMarc Jakobi changed their profile picture.14:49:40
@julienmalka:matrix.orgJulien changed their display name from Julien to JulienMalka (stop speaking german when).14:53:11
@julienmalka:matrix.orgJulien changed their display name from JulienMalka (stop speaking german when) to Julien (stop speaking german when).14:53:49
@federicodschonborn:matrix.org@federicodschonborn:matrix.org changed their profile picture.20:55:52
@julienmalka:matrix.orgJulien changed their display name from Julien (stop speaking german when) to Julien.21:05:24
14 Jun 2023
@hexa:lossy.networkhexa left the room.16:14:58

Show newer messages


Back to Room ListRoom Version: 6