[Nix-dev] Nix User Guide comments

[Clemens Tolboom]

Hi there,

to begin with: Thanks for the Nix User Guide.

here are some comments / suggestions on the Nix User Guide

;-) do not get offended by words like should, etc ... no harm intended.

General

I miss a cross reference table to
- thesis
- release notes
- etc
there are some links in the note at the end of chapter 1.

The command switches are in mixed style
- I'm in favour of the gnu style ;-) because of age...long term(s)
memory ;-)

Chapter 2

Point 1

This should be Point 1 alternative: You can pick up an RPM ...

Point 1 alternative 2:
(I use ubuntu and did the following)
1. apt-get --install alien
2. alien nix-x.y.z.rpm # creates a deb file
3. dpkg -i nix_x.y.z.deb
4. create user nix
5. chown -R nix:nix /nix

Point 1.9 (an extra point because you are now a nix user)
About ~/bashrc: maybe a code example is nice to have
ie echo source /nix/etc/... >> ~/.bashrc
I was not that familiar with bash. And this line is in the thesis.

Point 2
Maybe a warning about subscribing to the unstable channel: do not
install nix as a nix user because from then on you are on the unstable
nix software. (See my FATAL post)

Point 3
An better progress indication would be nice: It now showed 8 time 1/1
instead of 1/8 ...2/8 ... 8/8

Chapter 3

General: I should stick to /nix instead of prefix. 
- It's you own advice 'use /nix' and maybe prevents some errs. 'i
installed nix in /x/y/z and moved is to ...' kind of ...

Paragraph 3.4
Example 'rmp -U' shows a downgrade ;-)
- maybe all refs to versions should be upgraded to 0.10pre

Paragraph 3.6
I don't understand how to use nix for i.e. user 'fred'
- is it possible to add that here.

Chapter 4

Paragraph 4.1

'You can download the latest version from'
- Maybe this url is better: http://nix.cs.uu.nl/dist/nix/overviews.xhtml
(See post 'TOC suggestion)

Why do i want to download the latest nixpkgs?
- I guess that i need it to build from source.
- But not for development? (Chapter 5)
- I did the quick start. Do i still have to get a new nixpkgs file?

How do I unpack this file? Its extension is nixpkg
- Is nar the way?
- Do i need a directory structure for this?

I don't understand the "nix-channel --add" versus the "nix-pull
manifest" construct.
- Appendices A.9 and A.11 doesn't clear my clouds

Just before Paragraph 4.2 the command nix-env -I nixpkgs-version is not
advised in a footnote.
- I missed the footnote ;-(
- Is it sticky in the next session? Then i would vote for not mention it
in the user guide. It's not a fatal command but will introduce strange
side effect.

Chapter 5

Paragraph 5.1

As I understand one can build ones own nix expressions. 
- But then I guess I need a directory layout.
Steps to take (I want to build http://littlewizard.sourceforge.net/)
1. get a nixpkgs-version with the most matching library versions for the
component to build.
2. unpack it in build-littlewizard directory
3. create a default.nix in
build-littlewizard/pkgs-version/games/littlewizard
4. add new nix expression to
build-littlewizard/pkgs-version/system/all-packages-generic.nix

Paragraph 5.3

On Linux the compiler is patched
- I guess one needs a patched compiler for any platform in reaching
closure?
- What to do on ie Solaris, HP/UX, FreeBSD, Windows etc?

The text on hooks deserves a paragraph of their own?
- Where are the deploy phase hooks? (Thesis part III?)
Ie when a user issues a 'nix-env --install "service-x" the preDeploy
should grab a port number from /etc/service based on the 'uid'

Appendix

A.4 nix-env
Versions.
Is the number scheme based on the name of the nix expression?
- The dash - is mandatory?
- Number schemes like 1.2-3 are wrong?
I read somewhere (thesis?) that the name is not important but reading
this part i guess 
- upgrades are based on the names
- versions MUST use dots to separate
Maybe a warning in chapter 5 should be in place.

Queries examples
Comment after MPlayer-1.0pre3 suggest that versions are equal ie pre7
but the status indicates ...
- What is wrong here? pre3 should be pre7?
- Is it possible to have the same version numbers and get a status --S?
Yes, differently build but
- Alarm ... how to query such differences?
- Is this worth a separate example?

A.5 nix-build

I don't understand the warning about renaming/removing the symlink :-(

Appendix E

After a lot of releases this get huge.
- Maybe a separate document should do?

E.1 Release 0.10

warning
- slighted instead of slightly


Clemens out