8 files changed, 98 insertions, 15 deletions

diff --git a/src/nix/cat.cc b/src/nix/cat.cc
index 2ecffc9a5..fe2f0a241 100644
--- a/src/nix/cat.cc
+++ b/src/nix/cat.cc
@@ -62,6 +62,13 @@ struct CmdCatNar : StoreCommand, MixCat
         return "print the contents of a file inside a NAR file on stdout";
     }
 
+    std::string doc() override
+    {
+        return
+          #include "nar-cat.md"
+          ;
+    }
+
     void run(ref<Store> store) override
     {
         cat(makeNarAccessor(make_ref<std::string>(readFile(narPath))));
diff --git a/src/nix/dump-path.cc b/src/nix/dump-path.cc
index 256db64a9..63393ef9c 100644
--- a/src/nix/dump-path.cc
+++ b/src/nix/dump-path.cc
@@ -49,14 +49,11 @@ struct CmdDumpPath2 : Command
         return "serialise a path to stdout in NAR format";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To serialise directory 'foo' as a NAR:",
-                "nix nar dump-path ./foo"
-            },
-        };
+        return
+          #include "nar-dump-path.md"
+          ;
     }
 
     void run() override
diff --git a/src/nix/ls.cc b/src/nix/ls.cc
index 1f5ed6913..df67240f9 100644
--- a/src/nix/ls.cc
+++ b/src/nix/ls.cc
@@ -75,6 +75,8 @@ struct MixLs : virtual Args, MixJSON
 
         if (json) {
             JSONPlaceholder jsonRoot(std::cout);
+            if (showDirectory)
+                throw UsageError("'--directory' is useless with '--json'");
             listNar(jsonRoot, accessor, path, recursive);
         } else
             listText(accessor);
@@ -127,14 +129,11 @@ struct CmdLsNar : Command, MixLs
         expectArg("path", &path);
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To list a specific file in a NAR:",
-                "nix nar ls -l hello.nar /bin/hello"
-            },
-        };
+        return
+          #include "nar-ls.md"
+          ;
     }
 
     std::string description() override
diff --git a/src/nix/nar-cat.md b/src/nix/nar-cat.md
new file mode 100644
index 000000000..55c481a28
--- /dev/null
+++ b/src/nix/nar-cat.md
@@ -0,0 +1,19 @@
+R""(
+
+# Examples
+
+* List a file in a NAR and pipe it through `gunzip`:
+
+  ```console
+  # nix nar cat ./hello.nar /share/man/man1/hello.1.gz | gunzip
+  .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.4.
+  .TH HELLO "1" "November 2014" "hello 2.10" "User Commands"
+  …
+  ```
+
+# Description
+
+This command prints on standard output the contents of the regular
+file *path* inside the NAR file *nar*.
+
+)""
diff --git a/src/nix/nar-dump-path.md b/src/nix/nar-dump-path.md
new file mode 100644
index 000000000..26191ad25
--- /dev/null
+++ b/src/nix/nar-dump-path.md
@@ -0,0 +1,17 @@
+R""(
+
+# Examples
+
+* To serialise directory `foo` as a NAR:
+
+  ```console
+  # nix nar dump-path ./foo > foo.nar
+  ```
+
+# Description
+
+This command generates a NAR file containing the serialisation of
+*path*, which must contain only regular files, directories and
+symbolic links. The NAR is written to standard output.
+
+)""
diff --git a/src/nix/nar-ls.md b/src/nix/nar-ls.md
new file mode 100644
index 000000000..d373f9715
--- /dev/null
+++ b/src/nix/nar-ls.md
@@ -0,0 +1,24 @@
+R""(
+
+# Examples
+
+* To list a specific file in a NAR:
+
+  ```console
+  # nix nar ls -l ./hello.nar /bin/hello
+  -r-xr-xr-x                38184 hello
+  ```
+
+* To recursively list the contents of a directory inside a NAR, in JSON
+  format:
+
+  ```console
+  # nix nar ls --json -R ./hello.nar /bin
+  {"type":"directory","entries":{"hello":{"type":"regular","size":38184,"executable":true,"narOffset":400}}}
+  ```
+
+# Description
+
+This command shows information about a *path* inside NAR file *nar*.
+
+)""
diff --git a/src/nix/nar.cc b/src/nix/nar.cc
index e239ce96a..0775d3c25 100644
--- a/src/nix/nar.cc
+++ b/src/nix/nar.cc
@@ -9,7 +9,14 @@ struct CmdNar : NixMultiCommand
 
     std::string description() override
     {
-        return "query the contents of NAR files";
+        return "create or inspect NAR files";
+    }
+
+    std::string doc() override
+    {
+        return
+          #include "nar.md"
+          ;
     }
 
     Category category() override { return catUtility; }
diff --git a/src/nix/nar.md b/src/nix/nar.md
new file mode 100644
index 000000000..a83b5c764
--- /dev/null
+++ b/src/nix/nar.md
@@ -0,0 +1,13 @@
+R""(
+
+# Description
+
+`nix nar` provides several subcommands for creating and inspecting
+*Nix Archives* (NARs).
+
+# File format
+
+For the definition of the NAR file format, see Figure 5.2 in
+https://edolstra.github.io/pubs/phd-thesis.pdf.
+
+)""