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

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

Priorities

Add 👍 to issues you find important.