Add some form of Nix Language reference

[enderger]

Introduce your stance
Currently, the documentation for the Nix Language is scattered across several manuals, with the main library functions in a non-searchable layout separate from the bultins.

Describe the issue
Currently, the reference material for the Nix Language is scattered across the manuals in a strongly inconvenient way. The language needs it's own documentation, preferably in the style of Clojuredocs and the Rust Documentation.

Additional context
I am currently working on a Nix-based project and have found the language's documentation hard to navigate and use.

[nova-nowiz]

Yes!
I would be happy to help on this, can we ping someone to get feedback on the proposition?

[toraritte]

Had a similar question on Stackoverflow almost exactly 2 years ago, and it looks like that the authoritative and most complete reference is the lexer file itself, and the slightly outdated chapter "4. The Nix Expression Language" in Eelco Dolstra's PhD thesis from 2006 - none of which are ideal.

[nova-nowiz]

There is actually also this part of the nix manual:
https://nixos.org/manual/nix/unstable/expressions/expression-language.html
It is really badly named so not easily discoverable unfortunately.
I've made an issue on this NixOS/nixos-homepage#705.

here is the link for the stable release:
https://nixos.org/manual/nix/stable/#ch-expression-language
It this case the naming is correct but it is not a single page so if you search on a search engine, it will most likely not return this page or in the case that the page is proposed, the user will most likely not take into account the Nix Manual as a good result as it is not precise enough.

[enderger]

@Narice please see my original comment, I know that documentation exists in some form, it just is not enough to work with due to it’s fragmentation across the Nix and Nixpkgs manuals. That, and the reference of Nixpkgs.lib lacks any form of navigation and hence fails as a reference quickly navigated.

[nova-nowiz]

Oh I see, so what you would like is a Nix language reference which also contain a reference of the standard nixpkgs library?
That would be indeed better to have a manual for the cli, and separately a manual only for the Nix language that goes in full depth on how to use the language in a practical manner, that makes sense.
I don't really know who to ping here but I would gladly participate in the restructuring process ;)

[fricklerhandwerk]

@Narice @enderger @toraritte feel free to ping me or get in touch Discourse. I will try to help with any effort improving documentation.

[nova-nowiz]

Would this be covered by NixOS/nix.dev#267?

[fricklerhandwerk]

The tutorial is not a reference. The manual is still incomplete in various subtle ways, so while this issue is very broad, it is in principle still valid, and will be for some time.