Reorganize the language reference

[rhendric]

Problem

The Nix language reference (section 5 in the manual) is somewhat haphazardly organized and missing some details about the language. Could go into more detail if required but possibly not necessary; I think you may already agree.

Proposal

I'd like to restructure section 5 in the following way:

5. Nix Language

5.1. Data Types

This section would now contain details about the nine (ten if you count externals) data types that make up the set of values in Nix. Instead of including details about, e.g., string literal syntax, it would describe what a valid string is (immutable sequence of bytes plus context, not Unicode) and link to the string literal syntax documentation in 5.2. The sections currently numbered ‘5.2.3. String context’ and ‘5.4. Derivations’ would be moved under 5.1.

5.2. Language Syntax and Semantics

This section would be a complete accounting of all of the syntax in Nix, including literal syntax and the topics currently covered in ‘5.2. Language Constructs’. The section currently numbered ‘5.3. Operators’ would be moved under 5.2, or absorbed into it. It may include a hand-written #1102.

This enables, as an example, a single place to document the syntax of a bind, without being concerned with whether it belongs more with the let-expression stuff (currently 5.2) or with the attrset-literal stuff (currently 5.1).

Each syntactic form would be accompanied by an explanation of its evaluation semantics.

5.3 Initial Environment

This section would document every variable that is bound in the initial environment. It would include the contents of the sections currently numbered ‘5.5. Built-in Constants’ and ‘5.6 Built-in Functions’. It would be the place to elaborate on #7290.

This is possibly a duplicate of #7259? It seems we have a language reference; I just want to crisp it up.

@fricklerhandwerk thoughts?

Checklist

• [x] checked latest Nix manual (source)
• [x] checked open documentation issues and pull requests for possible duplicates

Priorities

Add :+1: to issues you find important.

[fricklerhandwerk]

Yes, absolutely. Small PRs appreciated, I'll absolutely prioritise merging anything following the plan in this issue.

[Ericson2314]

Derivations’ would be moved under 5.1.

A lot of the derivations material should first be covered in the store section. At that point, I think we may not even need a special page for builtins.derivation and builtins.deriationStrict, because we'll just be discussion how the argument for those functions maps on to derivation concepts that are discussed elsewhere.

[rhendric]

Ah, that makes sense!

I'll probably start by moving that section to Initial Environment along with the other builtins, then.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-07-24-nix-team-meeting-minutes-164/49811/1

[eclairevoyant]

Changing only the docs leads to rebuilding nix, is that an intended design?