* Manual updates, some style improvements.

6 files changed, 74 insertions, 52 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 23c663fbad65..d06539f9b687 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -4,7 +4,8 @@ XSLTPROC = $(xsltproc) $(xmlflags) \
  --param section.label.includes.component.label 1 \
  --param html.stylesheet \'style.css\' \
  --param xref.with.number.and.title 1 \
- --param toc.section.depth 3
+ --param toc.section.depth 3 \
+ --param admon.style \'\'
 
 man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 483c24e98715..ef056058d8dc 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -8,9 +8,10 @@
 
 <section><info><title>Obtaining Nix</title></info>
 
-<para>The easiest way to obtain Nix is to download a <link xlink:href="http://www.cs.uu.nl/groups/ST/Trace/Nix">source
-distribution</link>.  RPMs for Red Hat, SuSE, and Fedore Core are
-also available.</para>
+<para>The easiest way to obtain Nix is to download a <link
+xlink:href="http://www.cs.uu.nl/groups/ST/Trace/Nix">source
+distribution</link>.  RPMs for Red Hat, SuSE, and Fedora Core are also
+available.</para>
 
 <para>Alternatively, the most recent sources of Nix can be obtained
 from its <link
@@ -34,8 +35,9 @@ tar-file</link> of the head revision of the trunk.</para>
 
 <section><info><title>Prerequisites</title></info>
 
-<para>The following prerequisites only apply when you build from
-source.  Binary releases (e.g., RPMs) have no prerequisites.</para>
+<para><emphasis>The following prerequisites only apply when you build
+from source</emphasis>.  Binary releases (e.g., RPMs) have no
+prerequisites.</para>
 
 <para>A fairly recent version of GCC/G++ is required.  Version 2.95
 and higher should work.</para>
@@ -47,9 +49,9 @@ which are part of the <literal>libxml2</literal> and
 <link
 xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
 stylesheets</link> and optionally the <link
-xlink:href="http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip">
-DocBook XML 4.2 DTD</link>.  Note that these are only required if you
-modify the manual sources or when you are building from the Subversion
+xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
+schemas</link>.  Note that these are only required if you modify the
+manual sources or when you are building from the Subversion
 repository.</para>
 
 <para>To build the parser, very <emphasis>recent</emphasis> versions
@@ -103,15 +105,15 @@ $ autoreconf -i</screen>
 like.  You must have write permission to the
 <replaceable>prefix</replaceable> path.</para>
 
-<warning><para>It is advisable <emphasis>not</emphasis> to change the
-installation prefix from its default, since doing so will in all
-likelihood make it impossible to use derivations built on other
-systems.</para></warning>
+<warning><para>It is best <emphasis>not</emphasis> to change the
+installation prefix from its default, since doing so makes it
+impossible to use pre-built binaries from the standard Nixpkgs
+channels.</para></warning>
 
 <para>If you want to rebuilt the documentation, pass the full path to
-the DocBook XML catalog file (<filename>docbook.cat</filename>) and to
-the DocBook XSL stylesheets using the
-<option>--with-docbook-catalog=<replaceable>path</replaceable></option>
+the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using
+the
+<option>--with-docbook-rng=<replaceable>path</replaceable></option>
 and
 <option>--with-docbook-xsl=<replaceable>path</replaceable></option>
 options.</para>
diff --git a/doc/manual/nix-pack-closure.xml b/doc/manual/nix-pack-closure.xml
index 20e39157ce33..12eacf50207f 100644
--- a/doc/manual/nix-pack-closure.xml
+++ b/doc/manual/nix-pack-closure.xml
@@ -45,7 +45,7 @@ another machine:
 <screen>
 $ nix-pack-closure /nix/store/hj232g1r...-subversion-1.3.0 > svn.closure
 
-<lineannotation>Copy <!-- !!! <filename> --> svn.closure to the remote machine, then on the remote machine do:</lineannotation>
+<lineannotation>Copy <!-- !!! <filename> -->svn.closure to the remote machine, then on the remote machine do:</lineannotation>
 $ nix-unpack-closure &lt; svn.closure</screen>
 
 </para>
diff --git a/doc/manual/style.css b/doc/manual/style.css
index bf6fc3ecf43e..0598443efe4f 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -10,7 +10,6 @@ body
 {
     font-family: sans-serif;
     background: white;
-  
     margin: 2em 1em 2em 1em;
 }
 
@@ -34,7 +33,6 @@ h2 /* chapters, appendices, subtitle */
 div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 
 { 
     margin-top: 1.5em;
-/*    border-top: solid #005aa0; */
 }
 
 div.sect1 h2 /* sections */
@@ -42,6 +40,12 @@ div.sect1 h2 /* sections */
     font-size: 150%;
 }
 
+/* Extra space between sections. */
+div.section > div.titlepage h2
+{ 
+    margin-top: 1.2em;
+}
+
 div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
 {
     font-size: 125%;
@@ -67,8 +71,8 @@ div.example
 {
     border: 1px solid #6185a0;
     padding: 6px 6px;
-    margin-left: 3em;
-    margin-right: 3em;
+    margin-left: 0em;
+    margin-right: 0em;
     background: #eeeeee;
 }
 
@@ -86,9 +90,9 @@ pre.programlisting
 pre.screen
 {
     border: 1px solid #6185a0;
-    padding: 6px 6px;
-    margin-left: 3em;
-    margin-right: 3em;
+    padding: 3px 3px;
+    margin-left: 1.5em;
+    margin-right: 1.5em;
     color: #600000;
     background: #eeeeee;
     font-family: monospace;
@@ -100,24 +104,39 @@ pre.screen
                                Notes, warnings etc:
  ***************************************************************************/
 
-.note,.warning
+.note, .warning
 {
-    margin-top: 1em;
-    margin-bottom: 1em;
     border: 1px solid #6185a0;
-    padding: 0px 1em;
+    padding: 3px 3px;
+    margin-left: 1.5em;
+    margin-right: 1.5em;
+    margin-bottom: 1em;
+    padding: 0.3em 0.3em 0.3em 0.3em;
     background: #fffff5;
 }
 
-div.note,div.warning
+div.note, div.warning
 {
     font-style: italic;
 }
 
-div.warning h3
+div.note h3, div.warning h3
 {
     color: red;
     font-size: 100%;
+//    margin: 0 0 0 0;
+    padding-right: 0.5em;
+    display: inline;
+}
+
+div.note p, div.warning p
+{
+    margin-bottom: 0em;
+}
+
+div.note h3 + p, div.warning h3 + p
+{
+    display: inline;
 }
 
 div.note h3
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index fb6e1bd63c9c..9a61205b7334 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -7,7 +7,7 @@
 <para>This section provides solutions for some common problems.</para>
 
 
-<sect1><title>Berkeley DB: <quote>Cannot allocate memory</quote></title>
+<section><title>Berkeley DB: <quote>Cannot allocate memory</quote></title>
 
 <para>Symptom: Nix operations (in particular the
 <command>nix-store</command> operations <option>--gc</option>,
@@ -30,10 +30,10 @@ $ rm __db.00*</screen>
 
 </para>
 
-</sect1>
+</section>
 
 
-<sect1><title>Collisions in <command>nix-env</command></title>
+<section><title>Collisions in <command>nix-env</command></title>
 
 <para>Symptom: when installing or upgrading, you get an error message such as
 
@@ -69,10 +69,10 @@ to implement some conflict resolution policy.  E.g., the script could
 be modified to rename conflicting file names, or to pick one over the
 other.</para>
 
-</sect1>
+</section>
 
 
-<sect1><title><quote>Too many links</quote> error in the Nix
+<section><title><quote>Too many links</quote> error in the Nix
 store</title>
 
 
@@ -108,7 +108,7 @@ more than 32,000 subdirectories per directory, such as ReiserFS.
 ReiserFS lies to the kernel by reporting a link count of 1 if it
 exceeds the limit.)</para>
 
-</sect1>
+</section>
   
 
 
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml
index 6f52eb93b35f..0bdb00b04524 100644
--- a/doc/manual/writing-nix-expressions.xml
+++ b/doc/manual/writing-nix-expressions.xml
@@ -11,7 +11,7 @@ simple example (a Nix expression for GNU Hello), and then moves
 on to a more in-depth look at the Nix expression language.</para>
 
 
-<sect1><title>A simple Nix expression</title>
+<section><title>A simple Nix expression</title>
 
 <para>This section shows how to add and test the <link
 xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello
@@ -47,7 +47,7 @@ need to do three things:
 </para>
 
 
-<sect2><title>The Nix expression</title>
+<section><title>The Nix expression</title>
 
 <example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
 (<filename>default.nix</filename>)</title>
@@ -188,10 +188,10 @@ perl = perl;</programlisting>
 
 </para>
 
-</sect2>
+</section>
 
 
-<sect2><title>The builder</title>
+<section><title>The builder</title>
 
 <example xml:id='ex-hello-builder'><title>Build script for GNU Hello
 (<filename>builder.sh</filename>)</title>
@@ -303,10 +303,10 @@ shell script is evaluated with Bash's <option>-e</option> option,
 which causes the script to be aborted if any command fails without an
 error check.</para>
 
-</sect2>
+</section>
 
 
-<sect2><title>Composition</title>
+<section><title>Composition</title>
 
 <example xml:id='ex-hello-composition'><title>Composing GNU Hello
 (<filename>all-packages-generic.nix</filename>)</title>
@@ -401,10 +401,10 @@ some fragments of
 
 </calloutlist>
 
-</sect2>
+</section>
 
 
-<sect2><title>Testing</title>
+<section><title>Testing</title>
 
 <para>You can now try to build Hello.  The simplest way to do that is
 by using <command>nix-env</command>:
@@ -501,10 +501,10 @@ Just pass the option <option>-j <replaceable>N</replaceable></option>,
 where <replaceable>N</replaceable> is the maximum number of jobs to be
 run in parallel.  Typically this should be the number of CPUs.</para>
 
-</sect2>
+</section>
 
 
-<sect2><title>The generic builder</title>
+<section><title>The generic builder</title>
 
 <para>Recall from <xref linkend='ex-hello-builder' /> that the builder
 looked something like this:
@@ -587,14 +587,14 @@ In fact, <varname>mkDerivation</varname> provides a default builder
 that looks exactly like that, so it is actually possible to omit the
 builder for Hello entirely.</para>
 
-</sect2>
+</section>
 
 
-</sect1>
+</section>
 
 
 
-<sect1><title>The Nix expression language</title>
+<section><title>The Nix expression language</title>
 
 <para>The Nix expression language is a pure, lazy, functional
 language.  Purity means that operations in the language don't have
@@ -1290,11 +1290,11 @@ character, or inline/multi-line, enclosed within <literal>/*
 </simplesect>
 
 
-</sect1>
+</section>
 
 
 
-<sect1 xml:id='sec-standard-environment'><title>The standard environment</title>
+<section xml:id='sec-standard-environment'><title>The standard environment</title>
 
 <para>The standard build environment in the Nix Packages collection
 provides a basic environment for building Unix packages.  It consists
@@ -1547,7 +1547,7 @@ $ make
 is the source itself, which resides in
 <filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
 
-</sect1>
+</section>
 
 
 </chapter>