| 12 Jan 2024 |
 infinisil | So the dependency chain is strictly NixOS -> Nixpkgs -> Nix. There's no arrows back | 01:11:00 |
| infinisil | So generally I don't think there should be explanations of concepts making use of such back-arrows.
However, in order to find information, I'd be in favor of a mechanism that automatically inserts back-links in all documentation | 01:12:06 |
| infinisil | So if Nixpkgs links from stdenv.mkDerivation's docs to the ones for derivation, in the derivation docs you'd see a little "this page is linked to from the stdenv.mkDerivation docs" link | 01:12:48 |
 @qyriad:matrix.org | In reply to @infinisil:matrix.org
9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs this helps you understand how the Nix ecosystem is implemented, not how it's used or how and why it's useful | 01:13:33 |
 @9999years:matrix.org | i mean it would certainly be useful to say in the nix manual "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in nixpkgs" | 01:13:47 |
| @9999years:matrix.org | having recently helped several beginners get started with nix i can confirm this sort of thing trips new users up pretty consistently | 01:14:18 |
| infinisil | 9999years: Maybe yeah, but also, I've thought multiple times before to just ditch builtins.derivation and use builtins.strictDerivation instead in Nixpkgs, which would then outdate the docs on the Nix side | 01:15:08 |
| infinisil | The Nix codebase generally really doesn't know how it's used. And there could be various Nixpkgs versions that are each implemented differently | 01:16:11 |
| @9999years:matrix.org | yeah i mean, this is one of the issues with nix's docs -- nixpkgs and nix are deeply intertwined, but they can't be versioned together, even trivial stuff like lib | 01:16:47 |
| infinisil | I think such automated back-links might be a good compromise tbh | 01:17:01 |
| infinisil | Needs a unified docs building infrastructure though | 01:17:11 |
| @9999years:matrix.org | yeah automated back-links would be great. i still think additional human-written context would be useful but back-links would be a fantastic start | 01:17:28 |
| @9999years:matrix.org | (and lots more backlinks) | 01:17:42 |
| @qyriad:matrix.org | agreed | 01:17:50 |
| @qyriad:matrix.org | automated backlinks would be great, but why should we compromise on providing clear, understandable information in documentation? | 01:18:18 |
| infinisil | Wrong docs are imo worse than missing docs | 01:18:35 |
| @9999years:matrix.org | e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv | 01:18:48 |
| infinisil | And if we write information about Nixpkgs in Nix, that can easily become wrong | 01:18:53 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv oh wow it doesn't even do that? o.o | 01:19:03 |
| @9999years:matrix.org | i'm not saying we should have a ton of nixpkgs docs, but we should feel comfortable referring to high-level nixpkgs concepts that are unlikely to change (like mkDerivation, the override and overlay systems, etc.) | 01:19:33 |
| infinisil | I'd be okay with that yeah | 01:19:51 |
