From 0212feeed66d2eb0a9365ca4d55cb2dad3bc4ade Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Fri, 29 Sep 2006 14:16:41 +0000
Subject: [PATCH] * Document nix-install-package and the nixpkg file format.

---
 doc/manual/Makefile.am             |   3 +-
 doc/manual/manual.xml              |  48 ++++----
 doc/manual/nix-install-package.xml | 192 +++++++++++++++++++++++++++++
 doc/manual/package-management.xml  |   2 +-
 doc/manual/style.css               |  29 +++--
 5 files changed, 240 insertions(+), 34 deletions(-)
 create mode 100644 doc/manual/nix-install-package.xml

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index d06539f9b6..ea8cb3e9ad 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -10,7 +10,8 @@ XSLTPROC = $(xsltproc) $(xmlflags) \
 man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
  nix-prefetch-url.1 nix-channel.1 \
- nix-pack-closure.1 nix-unpack-closure.1
+ nix-pack-closure.1 nix-unpack-closure.1 \
+ nix-install-package.1
 
 FIGURES = figures/user-environments.png
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index ea85a7da59..7c9f8b1d6f 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -38,45 +38,49 @@
     <xi:include href="opt-common.xml" />
     <xi:include href="env-common.xml" />
     <xi:include href="conf-file.xml" />
-    <section xml:id="sec-nix-env">
-      <title>nix-env</title>
-      <xi:include href="nix-env.xml" />
-    </section>
     <section xml:id="sec-nix-build">
       <title>nix-build</title>
       <xi:include href="nix-build.xml" />
     </section>
-    <section>
-      <title>nix-store</title>
-      <xi:include href="nix-store.xml" />
-    </section>
-    <section xml:id="sec-nix-instantiate">
-      <title>nix-instantiate</title>
-      <xi:include href="nix-instantiate.xml" />
-    </section>
-    <section>
-      <title>nix-collect-garbage</title>
-      <xi:include href="nix-collect-garbage.xml" />
-    </section>
     <section xml:id="sec-nix-channel">
       <title>nix-channel</title>
       <xi:include href="nix-channel.xml" />
     </section>
     <section>
-      <title>nix-push</title>
-      <xi:include href="nix-push.xml" />
+      <title>nix-collect-garbage</title>
+      <xi:include href="nix-collect-garbage.xml" />
+    </section>
+    <section xml:id="sec-nix-env">
+      <title>nix-env</title>
+      <xi:include href="nix-env.xml" />
+    </section>
+    <section xml:id="sec-nix-install-package">
+      <title>nix-install-package</title>
+      <xi:include href="nix-install-package.xml" />
+    </section>
+    <section xml:id="sec-nix-instantiate">
+      <title>nix-instantiate</title>
+      <xi:include href="nix-instantiate.xml" />
     </section>
     <section>
-      <title>nix-pull</title>
-      <xi:include href="nix-pull.xml" />
+      <title>nix-pack-closure</title>
+      <xi:include href="nix-pack-closure.xml" />
     </section>
     <section>
       <title>nix-prefetch-url</title>
       <xi:include href="nix-prefetch-url.xml" />
     </section>
     <section>
-      <title>nix-pack-closure</title>
-      <xi:include href="nix-pack-closure.xml" />
+      <title>nix-pull</title>
+      <xi:include href="nix-pull.xml" />
+    </section>
+    <section xml:id="sec-nix-push">
+      <title>nix-push</title>
+      <xi:include href="nix-push.xml" />
+    </section>
+    <section>
+      <title>nix-store</title>
+      <xi:include href="nix-store.xml" />
     </section>
     <section>
       <title>nix-unpack-closure</title>
diff --git a/doc/manual/nix-install-package.xml b/doc/manual/nix-install-package.xml
new file mode 100644
index 0000000000..b696fa03fc
--- /dev/null
+++ b/doc/manual/nix-install-package.xml
@@ -0,0 +1,192 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+  
+<refnamediv>
+  <refname>nix-install-package</refname>
+  <refpurpose>install a Nix Package file</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-install-package</command>
+    <arg><option>--non-interactive</option></arg>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--profile</option></arg>
+        <arg choice='plain'><option>-p</option></arg>
+      </group>
+      <replaceable>path</replaceable>
+    </arg>
+    <sbr />
+    <group choice='req'>
+      <arg choice='req'>
+        <option>--url</option>
+        <arg choice='plain'><replaceable>url</replaceable></arg>
+      </arg>
+      <arg choice='req'>
+        <arg choice='plain'><replaceable>file</replaceable></arg>
+      </arg>
+    </group>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-install-package</command> interactively
+installs a Nix Package file (<filename>*.nixpkg</filename>), which is
+a small file that contains a store path to be installed along with the
+URL of a <link linkend="sec-nix-push"><command>nix-push</command>
+manifest</link>.  The Nix Package file is either
+<replaceable>file</replaceable>, or automatically downloaded from
+<replaceable>url</replaceable> if the <option>--url</option> switch is
+used.</para>
+
+<para><command>nix-install-package</command> is used in <link
+linkend="sec-one-click">one-click installs</link> to download and
+install pre-built binary packages with all necessary dependencies.
+<command>nix-install-package</command> is intended to be associated
+with the MIME type <literal>application/nix-package</literal> in a web
+browser so that it is invoked automatically when you click on
+<filename>*.nixpkg</filename> files.  When invoked, it restarts itself
+in a terminal window (since otherwise it would be invisible when run
+from a browser), asks the user to confirm whether to install the
+package, and if so downloads and installs the package into the user’s
+current profile.</para>
+
+<para>To obtain a window, <command>nix-install-package</command> tries
+to restart itself with <command>xterm</command>,
+<command>konsole</command> and
+<command>gnome-terminal</command>.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+  
+  <varlistentry><term><option>--non-interactive</option></term>
+
+    <listitem><para>Do not open a new terminal window and do not ask
+    for confirmation.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--profile</option></term>
+    <term><option>-p</option></term>
+
+    <listitem><para>Install the package into the specified profile
+    rather than the user’s current profile.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+
+<refsection><title>Examples</title>
+
+<para></para>
+
+<para>To install <filename>subversion-1.4.0.nixpkg</filename> into the
+user’s current profile, without any prompting:
+
+<screen>
+$ nix-install-package --non-interactive subversion-1.4.0.nixpkg</screen>
+
+</para>
+
+<para>To install the same package from some URL into a different
+profile:
+
+<screen>
+$ nix-install-package --non-interactive -p /nix/var/nix/profiles/eelco \
+    --url http://nix.cs.uu.nl/dist/nix/nixpkgs-0.10pre6622/pkgs/subversion-1.4.0-i686-linux.nixpkg</screen>
+
+</para>
+
+</refsection>
+
+
+<refsection><title>Format of <literal>nixpkg</literal> files</title>
+
+<para>A Nix Package file consists of a single line with the following
+format:
+
+<screen>
+NIXPKG1 <replaceable>manifestURL</replaceable> <replaceable>name</replaceable> <replaceable>system</replaceable> <replaceable>drvPath</replaceable> <replaceable>outPath</replaceable></screen>
+
+The elemens are as follows:
+
+<variablelist>
+
+  <varlistentry><term><literal>NIXPKG1</literal></term>
+  
+    <listitem><para>The version of the Nix Package
+    file.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>manifestURL</replaceable></term>
+  
+    <listitem><para>The manifest to be pulled by
+    <command>nix-pull</command>.  The manifest must contain
+    <replaceable>outPath</replaceable>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>name</replaceable></term>
+  
+    <listitem><para>The symbolic name and version of the
+    package.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>system</replaceable></term>
+  
+    <listitem><para>The platform identifier of the platform for which
+    this binary package is intended.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>drvPath</replaceable></term>
+  
+    <listitem><para>The path in the Nix store of the derivation from
+    which <replaceable>outPath</replaceable> was built.  Not currently
+    used.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>outPath</replaceable></term>
+  
+    <listitem><para>The path in the Nix store of the package.  After
+    <command>nix-install-package</command> has obtained the manifest
+    from <replaceable>manifestURL</replaceable>, it performs a
+    <literal>nix-env -i</literal> <replaceable>outPath</replaceable>
+    to install the binary package.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+  
+</para>
+
+<para>An example follows:
+
+<screen>
+NIXPKG1 http://.../nixpkgs-0.10pre6622/MANIFEST subversion-1.4.0 i686-darwin \
+  /nix/store/4kh60jkp...-subversion-1.4.0.drv \
+  /nix/store/nkw7wpgb...-subversion-1.4.0</screen>
+
+(The line breaks (<literal>\</literal>) are for presentation purposes
+and not part of the actual file.)
+
+</para>
+
+</refsection>
+
+
+</refentry>
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index f916d21f36..d796c7f2b2 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -476,7 +476,7 @@ available in the subscribed channels.</para>
 </section>
 
 
-<section xml:id="sec-one-click"><title>One-click installations</title>
+<section xml:id="sec-one-click"><title>One-click installs</title>
 
 <para>TODO</para>
 
diff --git a/doc/manual/style.css b/doc/manual/style.css
index 0598443efe..2d97b95e6d 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -35,19 +35,15 @@ div.chapter > div.titlepage h2, div.appendix > div.titlepage h2
     margin-top: 1.5em;
 }
 
-div.sect1 h2 /* sections */
+div.section > div.titlepage h2 /* sections */
 {
     font-size: 150%;
-}
-
-/* Extra space between sections. */
-div.section > div.titlepage h2
-{ 
-    margin-top: 1.2em;
+    margin-top: 1.5em;
 }
 
 div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
 {
+    margin-top: 1.4em;
     font-size: 125%;
 }
 
@@ -73,7 +69,7 @@ div.example
     padding: 6px 6px;
     margin-left: 0em;
     margin-right: 0em;
-    background: #eeeeee;
+    background: #f4f4f8;
 }
 
 pre.programlisting
@@ -94,7 +90,7 @@ pre.screen
     margin-left: 1.5em;
     margin-right: 1.5em;
     color: #600000;
-    background: #eeeeee;
+    background: #f4f4f8;
     font-family: monospace;
     /* font-size: 90%; */
 }
@@ -186,9 +182,14 @@ tt, code
     
 }
 
+div.variablelist dd p
+{
+    margin-top: 0em;
+}
+
 div.variablelist dd
 {
-    margin-bottom: 1em;
+    margin-left: 1.5em;
 }
 
 .default
@@ -251,3 +252,11 @@ table.productionset table.productionset
 {
     font-family: monospace;
 }
+
+strong.command
+{
+//    font-family: monospace;
+//    font-style: italic;
+//    font-weight: normal;
+    color: #400000;
+}
\ No newline at end of file