Problem

As a documentation maintainer I want to guide users into understanding the Nix language.

What's confusing is that quite many builtins are also available in the global scope for no apparent reason, although the manual says that this global attribute set is there to avoid polluting the namespace:

• abort
• baseNameOf
• builtins (yes, recursively)
• derivation
• derivationStrict
• dirOf
• fetchGit
• fetchMercurial
• fetchTarball
• fromTOML
• import
• isNull
• map
• placeholder
• removeAttrs
• scopedImport
• throw
• toString

@sternenseemann: a list including __* builtins

It would not suffice saying that these are for backwards compatibility, as some of them were introduced after Nix 2.0.

Checklist

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

Proposal

Be deliberate about it. Only make the following builtins available globally and tell why:

For general convenience:

• import
• map
• toString

For convenience when testing and debugging:

• abort
• throw
• derivation

There may be another group for backwards compatibility, but that should, with appropriate grace periods:

• throw a warning
• throw an error
• cease existing