Document the concept of search paths in a central place

[fricklerhandwerk]

Problem

Information about search path behavior is scattered all over the manual, and it's hard to find everything that's important to know.

Related, more information: #7848

Proposal

It's not obvious where that central place should be.

From an interface perspective, it's cross-cutting concern that cannot easily attached to any part of the system. There should still be references to the central documentation from the various entry points:

• configuration options (nix-path)
• environment variables (NIX_PATH)
• command line flags (-I)
• language features (builtins.nixPath (currently undocumented), <...> syntax)

Conceptually it's a parameter to the language evaluator.

@Ericson2314 proposes to publish builtins.nixPath documentation and put the information there, since that would constitute a narrow waist and one could imagine that the <...> syntax is just sugar around builtins.nixPath.

Checklist

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

Priorities

Add 👍 to issues you find important.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-04-17-nix-team-meeting-minutes-49/27379/1

[nixos-discourse]

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

https://discourse.nixos.org/t/tweag-nix-dev-update-47/27387/1

[fricklerhandwerk]

Partial implementation, providing such a central place in the documentation for nix-path:

• Automatically document builtin constants #8330
• document where the value of builtins.nixPath comes from #9113
• introduce lookup paths as a distinct language construct #9114
• reword documentation on lookup path resolution #9115