* Documented common environment variables.

1 files changed, 171 insertions, 150 deletions

diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index b0e581ff90..a8f2521280 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -1,188 +1,209 @@
-<nop>
+<sect1 id="sec-common-options"><title>Common options</title>
 
-<varlistentry>
-  <term><option>--help</option></term>
-  <listitem>
-    <para>
-      Prints out a summary of the command syntax and exits.
-    </para>
-  </listitem>
+<para>Most Nix commands accept the following command-line options:</para>
+
+<variablelist>
+
+<varlistentry><term><option>--help</option></term>
+  
+  <listitem><para>Prints out a summary of the command syntax and
+  exits.</para></listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--version</option></term>
-  <listitem>
-    <para>
-      Prints out the Nix version number on standard output and exits.
-    </para>
-  </listitem>
+<varlistentry><term><option>--version</option></term>
+  
+  <listitem><para>Prints out the Nix version number on standard output
+  and exits.</para></listitem>
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--verbose</option> / <option>-v</option></term>
+<varlistentry><term><option>--verbose</option> / <option>-v</option></term>
+
   <listitem>
-    <para>
-      Increases the level of verbosity of diagnostic messages printed
-      on standard error.  For each Nix operation, the information
-      printed on standard output is well-defined; any diagnostic
-      information is printed on standard error, never on standard
-      output.
-    </para>
+    
+  <para>Increases the level of verbosity of diagnostic messages
+  printed on standard error.  For each Nix operation, the information
+  printed on standard output is well-defined; any diagnostic
+  information is printed on standard error, never on standard
+  output.</para>
+
+  <para>This option may be specified repeatedly.  Currently, the
+  following verbosity levels exist:</para>
+
+  <variablelist>
+    
+    <varlistentry><term>0</term>
+    <listitem><para><quote>Errors only</quote>: only print messages
+    explaining why the Nix invocation failed.</para></listitem>
+    </varlistentry>
+      
+    <varlistentry><term>1</term>
+    <listitem><para><quote>Informational</quote>: print
+    <emphasis>useful</emphasis> messages about what Nix is doing.
+    This is the default.</para></listitem>
+    </varlistentry>
+      
+    <varlistentry><term>2</term>
+    <listitem><para><quote>Talkative</quote>: print more informational
+    messages.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>3</term>
+    <listitem><para><quote>Chatty</quote>: print even more
+    informational messages.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>4</term>
+    <listitem><para><quote>Debug</quote>: print debug
+    information.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>5</term>
+    <listitem><para><quote>Vomit</quote>: print vast amounts of debug
+    information.</para></listitem>
+    </varlistentry>
+    
+  </variablelist>
 
-    <para>
-      This option may be specified repeatedly.  Currently, the
-      following verbosity levels exist:
-    </para>
+  </listitem>
+  
+</varlistentry>
 
-    <variablelist>
-      <varlistentry>
-        <term>0</term>
-        <listitem>
-          <para>
-            <quote>Errors only</quote>: only print messages explaining
-            why the Nix invocation failed.
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>1</term>
-        <listitem>
-          <para>
-            <quote>Informational</quote>: print
-            <emphasis>useful</emphasis> messages about what Nix is
-            doing.  This is the default.
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>2</term>
-        <listitem>
-          <para>
-            <quote>Talkative</quote>: print more informational messages.
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>3</term>
-        <listitem>
-          <para>
-            <quote>Chatty</quote>: print even more informational messages.
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>4</term>
-        <listitem>
-          <para>
-            <quote>Debug</quote>: print debug information:
-          </para>
-        </listitem>
-      </varlistentry>
-      <varlistentry>
-        <term>5</term>
-        <listitem>
-          <para>
-            <quote>Vomit</quote>: print vast amounts of debug
-            information.
-          </para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
 
-  </listitem>
+<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>
+
+  <listitem><para>By default, output written by builders to standard
+  output and standard error is echoed to the Nix command's standard
+  error.  This option suppresses this behaviour.  Note that the
+  builder's standard output and error are always written to a log file
+  in
+  <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--no-build-output</option> / <option>-Q</option></term>
-  <listitem>
-    <para>
-      By default, output written by builders to standard output and
-      standard error is echoed to the Nix command's standard error.
-      This option suppresses this behaviour.  Note that the builder's
-      standard output and error are always written to a log file in
-      <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.
-    </para>
-  </listitem>
+<varlistentry><term><option>--max-jobs</option> / <option>-j</option></term>
+
+  <listitem><para>Sets the maximum number of build jobs that Nix will
+  perform in parallel to the specified number.  The default is 1.  A
+  higher value is useful on SMP systems or to exploit I/O latency.</para></listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--max-jobs</option> / <option>-j</option></term>
-  <listitem>
-    <para>
-      Sets the maximum number of build jobs that Nix will perform in
-      parallel to the specified number.  The default is 1.  A higher
-      value is useful on SMP systems or to exploit I/O latency.
-    </para>
-  </listitem>
+<varlistentry><term><option>--keep-going</option> / <option>-k</option></term>
+
+  <listitem><para>Keep going in case of failed builds, to the
+  greatest extent possible.  That is, if building an input of some
+  derivation fails, Nix will still build the other inputs, but not the
+  derivation itself.  Without this option, Nix stops if any build
+  fails (except for builds of substitutes), possibly killing builds in
+  progress (in case of parallel or distributed builds).</para></listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--keep-going</option> / <option>-k</option></term>
-  <listitem>
-    <para>
-      Keep going in case of failed builds, to the greatest extent
-      possible.  That is, if building an input of some derivation
-      fails, Nix will still build the other inputs, but not the
-      derivation itself.  Without this option, Nix stops if any build
-      fails (except for builds of substitutes), possibly killing
-      builds in progress (in case of parallel or distributed builds).
+<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term>
+
+  <listitem><para>Specifies that in case of a build failure, the
+  temporary directory (usually in <filename>/tmp</filename>) in which
+  the build takes place should not be deleted.  The path of the build
+  directory is printed as an informational message.
     </para>
   </listitem>
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--keep-failed</option> / <option>-K</option></term>
+<varlistentry><term><option>--fallback</option></term>
+
   <listitem>
-    <para>
-      Specifies that in case of a build failure, the temporary
-      directory (usually in <filename>/tmp</filename>) in which the
-      build takes place should not be deleted.  The path of the build
-      directory is printed as an informational message.
-    </para>
+
+  <para>Whenever Nix attempts to realise a derivation for which a
+  closure is already known, but this closure cannot be realised, fall
+  back on normalising the derivation.</para>
+
+  <para>The most common scenario in which this is useful is when we
+  have registered substitutes in order to perform binary distribution
+  from, say, a network repository.  If the repository is down, the
+  realisation of the derivation will fail.  When this option is
+  specified, Nix will build the derivation instead.  Thus, binary
+  installation falls back on a source installation.  This option is
+  not the default since it is generally not desirable for a transient
+  failure in obtaining the substitutes to lead to a full build from
+  source (with the related consumption of resources).</para>
+
   </listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--fallback</option></term>
-  <listitem>
-    <para>
-      Whenever Nix attempts to realise a derivation for which a
-      closure is already known, but this closure cannot be realised,
-      fall back on normalising the derivation.
-    </para>
+<varlistentry><term><option>--readonly-mode</option></term>
 
-    <para>
-      The most common scenario in which this is useful is when we have
-      registered substitutes in order to perform binary distribution
-      from, say, a network repository.  If the repository is down, the
-      realisation of the derivation will fail.  When this option is
-      specified, Nix will build the derivation instead.  Thus,
-      binary installation falls back on a source installation.  This
-      option is not the default since it is generally not desirable
-      for a transient failure in obtaining the substitutes to lead to
-      a full build from source (with the related consumption of
-      resources).
-    </para>
-  </listitem>
+  <listitem><para>When this option is used, no attempt is made to open
+  the Nix database.  Most Nix operations do need database access, so
+  those operations will fail.</para></listitem>
+  
 </varlistentry>
 
 
-<varlistentry>
-  <term><option>--readonly-mode</option></term>
+<varlistentry id="opt-log-type"><term><option>--log-type</option>
+<replaceable>type</replaceable></term>
+
   <listitem>
-    <para>
-      When this option is used, no attempt is made to open the Nix
-      database.  Most Nix operations do need database access, so those
-      operations will fail.
-    </para>
+
+  <para>This option determines how the output written to standard
+  error is formatted.  Nix’s diagnostic messages are typically
+  <emphasis>nested</emphasis>.  For instance, when tracing Nix
+  expression evaluation (<command>nix-env -vvvvv</command>, messages
+  from subexpressions are nested inside their parent expressions.  Nix
+  builder output is also often nested.  For instance, the Nix Packages
+  generic builder nests the various build tasks (unpack, configure,
+  compile, etc.), and the GNU Make in <literal>stdenv-linux</literal>
+  has been patched to provide nesting for recursive Make
+  invocations.</para>
+
+  <para><replaceable>type</replaceable> can be one of the
+  following:
+
+  <variablelist>
+
+    <varlistentry><term><literal>pretty</literal></term>
+
+      <listitem><para>Pretty-print the output, indicating different
+      nesting levels using spaces.  This is the
+      default.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>escapes</literal></term>
+
+      <listitem><para>Indicate nesting using escape codes that can be
+      interpreted by the <command>log2xml</command> tool in the Nix
+      source distribution.  The resulting XML file can be fed into the
+      <command>log2html.xsl</command> stylesheet to create an HTML
+      file that can be browsed interactively, using Javascript to
+      expand and collapse parts of the output.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>flat</literal></term>
+
+      <listitem><para>Remove all nesting.</para></listitem>
+
+    </varlistentry>
+
+  </variablelist>    
+  
+  </para>
+
   </listitem>
+  
 </varlistentry>
 
-</nop>
\ No newline at end of file
+
+</variablelist>
+
+
+</sect1>
\ No newline at end of file