Update lookup-path.md

[toraritte]

Motivation

Updated this entry with 2 sentence taken from the nix.dev tutorial's lookup paths section as that resource makes it way easier to understand this concept.

Also added "file system" in front of "path value" because I found it an important clarification as "path" is an overloaded term.

Context

Trivial change; providing minor clarification.

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[roberth]

Also added "file system" in front of "path value" because I found it an important clarification as "path" is an overloaded term.

I understand the desire, but they won't have to point to the actual file system, so this addition could be misinterpreted as a restriction on which kinds of path values are ok to resolve to. While it currently somewhat accurate, it certainly won't be after either of:

• Lazy fetchTree outPath path values #10252
• Lazy trees #6530

Suggested change

	A lookup path is an identifier with an optional path suffix that resolves to a file system [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.
	A lookup path is an identifier with an optional path suffix that resolves to a [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.

[roberth]

Suggested change

	> Generally, `<nixpkgs>` points to the file system path of some revision of [Nixpkgs](https://nix.dev/reference/glossary#term-Nixpkgs).
	> Generally, if `<nixpkgs>` exists, it points to the file system path of some revision of [Nixpkgs](https://nix.dev/reference/glossary#term-Nixpkgs).

[roberth]

I think you meant

Suggested change

	> `<nixpkgs/lib>` points to the subdirectory `nixos` of the file system path `<nixpkgs>` points to:
	> `<nixpkgs/nixos>` points to the subdirectory `nixos` of the file system path `<nixpkgs>` points to:

[fricklerhandwerk]

I understand this is a confusing corner of the landscape, and we're in the process of further clarifying the lookup path mechanism and making the information easier to find. The example in the current form is certainly not ideal, but I think that, right now, trying to add more contextual information raises the amount of pedantry required to keep it correct beyond what's practical.

In the nix.dev tutorial we're free to be vague on the details in order to orient users. Here we must be precise, and for the sake of efficiency I suggest we focus on just that, which is why I also suggest to close this PR and keep in mind that this particular part still needs polish.

[roberth]

@fricklerhandwerk are you sure? I don't see how adding context makes it less precise. Less dense perhaps, but also more useful.

This decision feels too dogmatic. How are users supposed to find that information if they landed on "the authoritative Nix documentation" (my words, unfortunately not accurate) and it isn't there?

we're in the process of further clarifying the lookup path mechanism

I feel like it's pretty complete in terms of reference documentation, not just because we should steer people away from it. If anything is missing it's the context: what users need to know in practice in a world where channels and NIX_PATH are on the way out. I'm not a fan of undocumenting things, but focusing on the "need to know" things is exactly what a de facto soft-deprecated feature needs. (Plus some recommendations not to use it)

[roberth]

@fricklerhandwerk
How can @toraritte help with this?

Are these issues up to date? https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+NIX_PATH+label%3Adocumentation

[fricklerhandwerk]

Are these issues up to date? https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+NIX_PATH+label%3Adocumentation

Pretty much, yes. The top ones also document what needs to be done for better discoverability and completeness. I opened #11288 to finally address one of them.

what users need to know in practice in a world where channels and NIX_PATH are on the way out. [...] focusing on the "need to know" things is exactly what a de facto soft-deprecated feature needs.

That's what I'm aiming at, too. But maybe we can be more precise here rather than saying "if this and that exists, maybe we get a value"?

How can @toraritte help with this?

There's an information gap in how the contents of what <nixpkgs> resolves to come into being -- that's done by the installer, but we never say that. Adding that bit somewhere (maybe writing down the details on one of the installer pages and linking from this page to there) would help a lot to demystify what's going on. Then we don't need to be fuzzy about it any more.

By the way, me closing a PR is not a final verdict. Feel free to re-open it if you have a strong opinion.

[roberth]

I think the latter two edits are good additions.

me closing a PR is not a final verdict.

It does look that way though. I wouldn't have guessed that.

Maybe marking as draft would be ok in a situation like this, when also giving context for it, but more importantly we should try to make feedback actionable one way or another.

[toraritte]

Yes, I should have either a draft PR or ask first, I'm sorry. I thought that I firm grasp of the basics, but skipping almost a year in Nix/OS seems to mean that I have missed quite a lot - but that's a good thing that things are moving ahead so quickly! Thank you for both of your work!

[fricklerhandwerk]

#11437 addresses some of #11276 (comment)