nixos/manpages: Explain -I option and how to build manpages

When running nixos-rebuild -I, the man page just said "-I path" which could be interpreted as
 "just a path to nixpkgs", which in fact it actually has the same meaning as NIX_PATH.

This is now made clear in the manual, so that when grepping "-I" and "NIX_PATH" one quickly finds
 the format of the option.

I don't know how to link to the "nix manual" as stated in the docbook, so I left that as it is.

Additionally, it wasn't clear to me how to actually build the man pages and view the changes I made.
That's now in the contributing-to-this-manual.chapter.md.

3 files changed, 70 insertions, 4 deletions

diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md
index 26813d1042d69..557599809222a 100644
--- a/nixos/doc/manual/contributing-to-this-manual.chapter.md
+++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md
@@ -1,6 +1,6 @@
 # Contributing to this manual {#chap-contributing}
 
-The DocBook and CommonMark sources of NixOS' manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
+The [DocBook] and CommonMark sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
 
 You can quickly check your edits with the following:
 
@@ -11,3 +11,25 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux
 ```
 
 If the build succeeds, the manual will be in `./result/share/doc/nixos/index.html`.
+
+**Contributing to the man pages**
+
+The man pages are written in [DocBook] which is XML.
+
+To see what your edits look like:
+
+```ShellSession
+$ cd /path/to/nixpkgs
+$ nix-build nixos/release.nix -A manpages.x86_64-linux
+```
+
+You can then read the man page you edited by running
+
+```ShellSession
+$ man --manpath=result/share/man nixos-rebuild # Replace nixos-rebuild with the command whose manual you edited
+```
+
+If you're on a different architecture that's supported by NixOS (check nixos/release.nix) then replace `x86_64-linux` with the architecture.
+`nix-build` will complain otherwise, but should also tell you which architecture you have + the supported ones.
+
+[DocBook]: https://en.wikipedia.org/wiki/DocBook
diff --git a/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml b/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml
index a9b0c6a5eefa1..99dc5ce30b4b1 100644
--- a/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml
+++ b/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml
@@ -1,7 +1,9 @@
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-contributing">
   <title>Contributing to this manual</title>
   <para>
-    The DocBook and CommonMark sources of NixOS’ manual are in the
+    The
+    <link xlink:href="https://en.wikipedia.org/wiki/DocBook">DocBook</link>
+    and CommonMark sources of the NixOS manual are in the
     <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual">nixos/doc/manual</link>
     subdirectory of the
     <link xlink:href="https://github.com/NixOS/nixpkgs">Nixpkgs</link>
@@ -19,4 +21,32 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux
     If the build succeeds, the manual will be in
     <literal>./result/share/doc/nixos/index.html</literal>.
   </para>
+  <para>
+    <emphasis role="strong">Contributing to the man pages</emphasis>
+  </para>
+  <para>
+    The man pages are written in
+    <link xlink:href="https://en.wikipedia.org/wiki/DocBook">DocBook</link>
+    which is XML.
+  </para>
+  <para>
+    To see what your edits look like:
+  </para>
+  <programlisting>
+$ cd /path/to/nixpkgs
+$ nix-build nixos/release.nix -A manpages.x86_64-linux
+</programlisting>
+  <para>
+    You can then read the man page you edited by running
+  </para>
+  <programlisting>
+$ man --manpath=result/share/man nixos-rebuild # Replace nixos-rebuild with the command whose manual you edited
+</programlisting>
+  <para>
+    If you’re on a different architecture that’s supported by NixOS
+    (check nixos/release.nix) then replace
+    <literal>x86_64-linux</literal> with the architecture.
+    <literal>nix-build</literal> will complain otherwise, but should
+    also tell you which architecture you have + the supported ones.
+  </para>
 </chapter>
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
index ea96f49fa9772..cab871661a755 100644
--- a/nixos/doc/manual/man-nixos-rebuild.xml
+++ b/nixos/doc/manual/man-nixos-rebuild.xml
@@ -134,7 +134,7 @@
    </arg>
    <arg>
     <option>-I</option>
-    <replaceable>path</replaceable>
+    <replaceable>NIX_PATH</replaceable>
    </arg>
    <arg>
     <group choice='req'>
@@ -624,7 +624,7 @@
 
   <para>
    In addition, <command>nixos-rebuild</command> accepts various Nix-related
-   flags, including <option>--max-jobs</option> / <option>-j</option>,
+   flags, including <option>--max-jobs</option> / <option>-j</option>, <option>-I</option>,
    <option>--show-trace</option>, <option>--keep-failed</option>,
    <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> /
    <option>-v</option>. See the Nix manual for details.
@@ -649,6 +649,20 @@
 
    <varlistentry>
     <term>
+     <envar>NIX_PATH</envar>
+    </term>
+    <listitem>
+     <para>
+      A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g &lt;nixpkgs&gt;). Example
+      <screen>
+          nixpkgs=./my-nixpkgs
+      </screen>
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>
      <envar>NIX_SSHOPTS</envar>
     </term>
     <listitem>