| 4 Nov 2023 |
 antifuchs | just noticed the entire lib.meta attrset of functions isn't documented in the nixpkgs manual yet... they have source code comments, but none of the functions can be found. I'd be happy to try and craft a PR for that, but am wondering if I'm missing some policy / better taxonomy or something? | 14:33:35 |
|  @qyriad:matrix.org joined the room. | 14:44:14 |
 fricklerhandwerk | In reply to @antifuchs:asf.computer
just noticed the entire lib.meta attrset of functions isn't documented in the nixpkgs manual yet... they have source code comments, but none of the functions can be found. I'd be happy to try and craft a PR for that, but am wondering if I'm missing some policy / better taxonomy or something? That would be great. I don’t know any details, but IIRC it just needs some wiring up in the table of contents. And then likely fixing a lot of rendering bugs, but that could be done later as well. | 14:45:49 |
| antifuchs | nice! ok, I'll see what I can do (: | 14:46:05 |
| antifuchs | fricklerhandwerk: while I have your attention on the library TOC, do you think it (https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library) should be sorted alphabetically? the order doesn't make much sense to me and that makes it difficult to find things that are missing | 15:03:08 |
| fricklerhandwerk | In reply to @antifuchs:asf.computer
fricklerhandwerk: while I have your attention on the library TOC, do you think it (https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library) should be sorted alphabetically? the order doesn't make much sense to me and that makes it difficult to find things that are missing Sure, I wouldn’t know why not.
Side note: I’m not that involved in the Nixpkgs manual because the Nix manual and nix.dev are enough to deal with, so my knowledge and opinions are quite superficial. There are likely other people who will have more substantial things to say: infinisil Robert Hensing (roberth) @pennae alejandrosame come
to mind. | 15:24:25 |
| antifuchs | oh, haha! I see (: | 15:24:37 |
| antifuchs | would love to hear from you all about that - I have a newfound passion for documenting library functions (: | 15:28:45 |
| antifuchs | here's the first PR, to add the lib.meta attrset of functions to the ToC: https://github.com/NixOS/nixpkgs/pull/265478 | 15:49:25 |
 proofconstruction | Thanks for picking up a shovel! | 15:49:49 |
| @qyriad:matrix.org | I had no idea these functions existed before, so thank you for that! | 15:52:17 |
| antifuchs | I would love to make the ToC be auto-generated with an assertion that when adding a section, a tagline is added too | 17:45:05 |
| antifuchs | (this seems difficult, as the lib/ dir is pretty jumbled) | 18:06:41 |
 @olafklingt:matrix.org | In reply to @antifuchs:asf.computer
here's the first PR, to add the lib.meta attrset of functions to the ToC: https://github.com/NixOS/nixpkgs/pull/265478 maybe this project is interesting to you https://nix-community.github.io/docnix/reference/lib/meta/lib-meta-addmetaattrs/ it builds from a fork of nixpkgs not sure how substantial the difference is. | 18:29:17 |
| antifuchs | Oooh, I didn’t know about that yet! Looks very useful indeed | 18:32:43 |
| 5 Nov 2023 |
|  @atka:matrix.org joined the room. | 01:18:52 |
 infinisil | antifuchs: I do think the order is somewhat important. In particular lib.path, lib.filesystem and lib.sources/lib.fileset should be in that order, because they build up on the previous one | 10:54:23 |
| infinisil | But then again, the path library also isn't that important, maybe it ahould come last :P | 10:55:04 |
| infinisil | I guess I don't care very much tbh :) | 10:55:20 |
| antifuchs | hahaha, makes sense | 14:02:03 |
| antifuchs | if there are logical groupings, maybe we can arrange them via subsections? but I think in source, having the library attributes be alphabetical would make it much easier to do a mental tally | 14:02:40 |
| 6 Nov 2023 |
 Robert Hensing (roberth) | In reply to @infinisil:matrix.org
antifuchs: I do think the order is somewhat important. In particular lib.path, lib.filesystem and lib.sources/lib.fileset should be in that order, because they build up on the previous one that's too much inference, and nobody expect much from an ordered lists, because dependency graphs > 3 nodes are basically never ordered lists | 11:51:53 |
| Robert Hensing (roberth) | subsections can only represent trees, and only if they're not too deep, so those are not suitable either | 11:52:51 |
| infinisil | I guess just an introductory section giving an overview of all sublibraries would be better | 11:53:22 |
| Robert Hensing (roberth) | if at all. Most library reference material doesn't bother with that kind of thing | 11:54:04 |
| Robert Hensing (roberth) | not sure that we should | 11:54:11 |
 alejandrosame | In reply to @antifuchs:asf.computer
fricklerhandwerk: while I have your attention on the library TOC, do you think it (https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library) should be sorted alphabetically? the order doesn't make much sense to me and that makes it difficult to find things that are missing For reference documentation I'm also more into alphabetical order and then linking as necessary to building blocks (for example, the proposal in https://github.com/NixOS/nixpkgs/issues/250376).
Other types of documents can order as they want, ofc, since the whole point is to set up an order that makes sense for storytelling, task completion, etc.
| 12:20:20 |
| proofconstruction | In reply to @infinisil:matrix.org
I guess just an introductory section giving an overview of all sublibraries would be better This would be better as a page on nix.dev | 14:36:53 |
| infinisil | Hmm I think reference docs can also use overviews of its parts, it doesn't really fit into tutorials, guides or explanation | 14:39:47 |
| fricklerhandwerk | Overviews are important, and should be right there with the reference docs. Reference will change, and while the prose overview may not catch up immediately, it's way easier to keep it in sync when it's in-tree. | 14:56:28 |
