From a85f22164d56052f027e71718c99ec0a1c3d25d1 Mon Sep 17 00:00:00 2001
From: Brian Hicks <brian@brianthicks.com>
Date: Tue, 23 Jul 2019 14:05:38 -0500
Subject: [PATCH] nix-darwin: add docs

(cherry picked from commit 6239ce20afdc699fe8057d8fe1389d6895ad8730)
---
 doc/installation.xml | 76 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/doc/installation.xml b/doc/installation.xml
index 77f6e167e..0e4c904e5 100644
--- a/doc/installation.xml
+++ b/doc/installation.xml
@@ -230,7 +230,81 @@ home-manager.useUserPackages = true;
   <title>nix-darwin module</title>
 
   <para>
-   To be done.
+   Home Manager provides a module that allows you to prepare user
+   environments directly from the nix-darwin configuration file, which often is
+   more convenient than using the <command>home-manager</command> tool.
   </para>
+
+  <para>
+   To make the NixOS module available for use you must <option>import</option>
+   it into your system configuration. This is most conveniently done by adding
+   a Home Manager channel, for example
+  </para>
+
+<screen>
+<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput>
+<prompt>#</prompt> <userinput>nix-channel --update</userinput>
+</screen>
+
+  <para>
+   if you are following Nixpkgs master or an unstable channel and
+  </para>
+
+<screen>
+<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.03.tar.gz home-manager</userinput>
+<prompt>#</prompt> <userinput>nix-channel --update</userinput>
+</screen>
+
+  <para>
+   if you follow a Nixpkgs version 19.03 channel.
+  </para>
+
+  <para>
+   It is then possible to add
+  </para>
+
+<programlisting language="nix">
+imports = [ &lt;home-manager/nix-darwin&gt; ];
+</programlisting>
+
+  <para>
+   to your nix-darwin <filename>configuration.nix</filename> file, which will
+   introduce a new NixOS option called <option>home-manager</option> whose type
+   is an attribute set that maps user names to Home Manager configurations.
+  </para>
+
+  <para>
+   For example, a nix-darwin configuration may include the lines
+  </para>
+
+<programlisting language="nix">
+home-manager.users.eve = { pkgs, ... }: {
+  home.packages = [ pkgs.atool pkgs.httpie ];
+  programs.bash.enable = true;
+};
+</programlisting>
+
+  <para>
+   and after a <command>darwin-rebuild --switch</command> the user eve's
+   environment should include a basic Bash configuration and the packages atool
+   and httpie.
+  </para>
+
+  <note>
+   <para>
+    By default user packages will not be ignored in favor of
+    <option>environment.systemPackages</option>, but they will be intalled to
+    <option>/etc/profiles/per-user/$USERNAME</option> if
+   </para>
+
+<programlisting language="nix">
+home-manager.useUserPackages = true;
+</programlisting>
+
+   <para>
+    is added to the nix-darwin configuration. This option may become the default
+    value in the future.
+   </para>
+  </note>
  </section>
 </chapter>