search

NixOS / nix

Nix, the purely functional package manager
https://nixos.org/
GNU Lesser General Public License v2.1
11.44k stars 1.44k forks source link

Reorganize the language reference #10970

Open rhendric opened 2 days ago

rhendric commented 2 days ago

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

Priorities

Add :+1: to issues you find important.

fricklerhandwerk commented 2 days ago

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

Ericson2314 commented 2 days ago

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 commented 2 days ago

Ah, that makes sense!

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