Add some more info to the nixos-version manpage

nixos/doc/manual/man-nixos-version.xml

@@ -10,7 +10,7 @@
 
 <refnamediv>
   <refname><command>nixos-version</command></refname>
-  <refpurpose>show the version of nixpkgs NixOS was built from</refpurpose>
+  <refpurpose>show the NixOS version</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -23,58 +23,52 @@
 
 <refsection><title>Description</title>
 
-<para>This command describes the version of nixpkgs used to build
-NixOS.</para>
+<para>This command shows the version of the currently active NixOS
+configuration. For example:
 
-<para>By default the output includes:</para>
-
-<itemizedlist>
-  <listitem><para>The NixOS release</para></listitem>
-  <listitem><para>Number of commits since the release</para></listitem>
-  <listitem><para>Git SHA of the released commit</para></listitem>
-  <listitem><para>Codename of the NixOS release</para></listitem>
-</itemizedlist>
-</refsection>
-
-<refsection><title>Example</title>
-
-<para>Here is an example output, and corresponding information:
 <screen>$ nixos-version
 16.03.1011.6317da4 (Emu)
 </screen>
-</para>
 
-<informaltable>
-  <tgroup cols="2">
-    <thead>
-      <row>
-        <entry>Attribute</entry>
-        <entry>Value</entry>
-      </row>
-    </thead>
-    <tbody>
-      <row>
-        <entry>NixOS Release</entry>
-        <entry><literal>16.03</literal></entry>
-      </row>
-      <row>
-        <entry>Commit Count</entry>
-        <entry><literal>1011</literal></entry>
-      </row>
-      <row>
-        <entry>Commit SHA</entry>
-        <entry><literal>6317da4</literal></entry>
-      </row>
-      <row>
-        <entry>Release Codename</entry>
-        <entry><literal>Emu</literal></entry>
-      </row>
-    </tbody>
-  </tgroup>
-</informaltable>
-<para>
-</para>
+The version consists of the following elements:
 
+<variablelist>
+
+  <varlistentry>
+    <term><literal>16.03</literal></term>
+    <listitem><para>The NixOS release, indicating the year and month
+    in which it was released (e.g. March 2016).</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>1011</literal></term>
+    <listitem><para>The number of commits in the Nixpkgs Git
+    repository between the start of the release branch and the commit
+    from which this version was built. This ensures that NixOS
+    versions are monotonically increasing. It is
+    <literal>git</literal> when the current NixOS configuration was
+    built from a checkout of the Nixpkgs Git repository rather than
+    from a NixOS channel.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>6317da4</literal></term>
+    <listitem><para>The first 7 characters of the commit in the
+    Nixpkgs Git repository from which this version was
+    built.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>Emu</literal></term>
+    <listitem><para>The code name of the NixOS release. The first
+    letter of the code name indicates that this is the N'th stable
+    NixOS release; for example, Emu is the fifth
+    release.</para></listitem>
+  </varlistentry>
+
+</variablelist>
+
+</para>
 
 </refsection>
 
@@ -89,7 +83,8 @@ NixOS.</para>
     <term><option>--hash</option></term>
     <term><option>--revision</option></term>
     <listitem>
-      <para>The output will be the full hash of the git commit
+      <para>Show the full SHA1 hash of the Git commit from which this
+      configuration was built, e.g.
 <screen>$ nixos-version --hash
 6317da40006f6bc2480c6781999c52d88dde2acf
 </screen>