Hm, what about this instead? After this code example:

$ nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
...

place

Note: the nixos prefix tells us that we want to get the package from the nixos channel and works only in CLI tools. In declarative configuration use pkgs prefix (variable).

A note about pkgs being a variable is fine, but it isn't root channel. It is root's nixos channel. Not sure how to communicate this better.

The HEAD commit formerly did not have the content it's description implied (rather it was just a revert commit iirc). I have force pushed [1] to make the commit match your suggestion @danbst

[1] I assume that's acceptable because as far as I know, I'm the only one checking out this branch

Let me know if I read this right: the pkgs variable points to the nixos channel, but we can't access the nixos channel by name, because the user can only refer to variables passed into the scope of the Nix expression.

Suggested modification:

Note: the nixos prefix tells us that we want to get the package from the nixos channel and works only in CLI tools. In declarative configuration, use pkgs as a prefix, i.e. pkgs.app_name_goes_here. The reference, pkgs, is a variable name that refers to the nixos channel.

I'm thinking readers will interpret the word "variable" as the meaning of "variable" from the procedural programming paradigm (stored value), rather than the functional paradigm ("let" binding). The reader needs to be introduced to the nomenclature of let-bound variables when he/she first encounters the concept. The "alias" or "pointer" metaphor seems like a natural way to explain it. My sentence before my suggested modification would be a succinct way to let users know there's a difference. It's fairly unambiguous without getting too technical and jargony.

The use of "He-who-should-not-be-named" to refer to Voldemort in Harry Potter should be a good analogy, especially since Voldemort refers to another name, Tom Riddle, as well (the irony!).

It is root's nixos channel.

Is the nixos channel owned by root? This would seem to imply that there is a nixos channel not owned by root. What's the story here?

Is the nixos channel owned by root? This would seem to imply that there is a nixos channel not owned by root. What's the story here?

It's possible to define nixos channel in user's channels. It can be used by nixos-rebuild build, but won't be used by nixos-rebuild switch, because you call usually sudo nixos-rebuild switch, thus root's channel is active.

as for variable thing: I really really wish we had documentation with ability to add comments in-place to each section. Like Google Docs annotations, or Mercurial book (which has comments to each paragraph).

Let me know if I read this right:

correct!

I'm thinking readers will interpret the word "variable" as the meaning of "variable" in the procedural programming paradigm (stored value), rather than the functional paradigm ("let" binding).

That depends on reader. I like to think about let-bindings as immutable variables, because you can reassign them whenever you want. But I also like your suggestion.