From c14ed3f8b2cbddb335227d2ff5188896e76b713f Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 9 Dec 2020 20:06:19 +0100
Subject: [PATCH] Add 'nix store' NAR-related manpages

---
 src/nix/cat.cc             |  7 +++++++
 src/nix/dump-path.cc       | 11 ++++-------
 src/nix/ls.cc              | 17 +++++++----------
 src/nix/store-cat.md       | 19 +++++++++++++++++++
 src/nix/store-dump-path.md | 23 +++++++++++++++++++++++
 src/nix/store-ls.md        | 27 +++++++++++++++++++++++++++
 6 files changed, 87 insertions(+), 17 deletions(-)
 create mode 100644 src/nix/store-cat.md
 create mode 100644 src/nix/store-dump-path.md
 create mode 100644 src/nix/store-ls.md

diff --git a/src/nix/cat.cc b/src/nix/cat.cc
index fe2f0a241..e28ee3c50 100644
--- a/src/nix/cat.cc
+++ b/src/nix/cat.cc
@@ -37,6 +37,13 @@ struct CmdCatStore : StoreCommand, MixCat
         return "print the contents of a file in the Nix store on stdout";
     }
 
+    std::string doc() override
+    {
+        return
+          #include "store-cat.md"
+          ;
+    }
+
     void run(ref<Store> store) override
     {
         cat(store->getFSAccessor());
diff --git a/src/nix/dump-path.cc b/src/nix/dump-path.cc
index 63393ef9c..c4edc894b 100644
--- a/src/nix/dump-path.cc
+++ b/src/nix/dump-path.cc
@@ -11,14 +11,11 @@ struct CmdDumpPath : StorePathCommand
         return "serialise a store path to stdout in NAR format";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To get a NAR from the binary cache https://cache.nixos.org/:",
-                "nix store dump-path --store https://cache.nixos.org/ /nix/store/7crrmih8c52r8fbnqb933dxrsp44md93-glibc-2.25"
-            },
-        };
+        return
+          #include "store-dump-path.md"
+          ;
     }
 
     void run(ref<Store> store, const StorePath & storePath) override
diff --git a/src/nix/ls.cc b/src/nix/ls.cc
index df67240f9..d48287f27 100644
--- a/src/nix/ls.cc
+++ b/src/nix/ls.cc
@@ -94,21 +94,18 @@ struct CmdLsStore : StoreCommand, MixLs
         });
     }
 
-    Examples examples() override
-    {
-        return {
-            Example{
-                "To list the contents of a store path in a binary cache:",
-                "nix store ls --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10"
-            },
-        };
-    }
-
     std::string description() override
     {
         return "show information about a path in the Nix store";
     }
 
+    std::string doc() override
+    {
+        return
+          #include "store-ls.md"
+          ;
+    }
+
     void run(ref<Store> store) override
     {
         list(store->getFSAccessor());
diff --git a/src/nix/store-cat.md b/src/nix/store-cat.md
new file mode 100644
index 000000000..da2073473
--- /dev/null
+++ b/src/nix/store-cat.md
@@ -0,0 +1,19 @@
+R""(
+
+# Examples
+
+* Show the contents of a file in a binary cache:
+
+  ```console
+  # nix store cat --store https://cache.nixos.org/ \
+      /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10/bin/hello | hexdump -C | head -n1
+  00000000  7f 45 4c 46 02 01 01 00  00 00 00 00 00 00 00 00  |.ELF............|
+  ```
+
+# Description
+
+This command prints on standard output the contents of the regular
+file *path* in a Nix store. *path* can be a top-level store path or
+any file inside a store path.
+
+)""
diff --git a/src/nix/store-dump-path.md b/src/nix/store-dump-path.md
new file mode 100644
index 000000000..4ef563526
--- /dev/null
+++ b/src/nix/store-dump-path.md
@@ -0,0 +1,23 @@
+R""(
+
+# Examples
+
+* To get a NAR containing the GNU Hello package:
+
+  ```console
+  # nix store dump-path nixpkgs#hello > hello.nar
+  ```
+
+* To get a NAR from the binary cache https://cache.nixos.org/:
+
+  ```console
+  # nix store dump-path --store https://cache.nixos.org/ \
+      /nix/store/7crrmih8c52r8fbnqb933dxrsp44md93-glibc-2.25 > glibc.nar
+  ```
+
+# Description
+
+This command generates a NAR file containing the serialisation of the
+store path *installable*. The NAR is written to standard output.
+
+)""
diff --git a/src/nix/store-ls.md b/src/nix/store-ls.md
new file mode 100644
index 000000000..836efce42
--- /dev/null
+++ b/src/nix/store-ls.md
@@ -0,0 +1,27 @@
+R""(
+
+# Examples
+
+* To list the contents of a store path in a binary cache:
+
+  ```console
+  # nix store ls --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
+  dr-xr-xr-x                    0 ./bin
+  -r-xr-xr-x                38184 ./bin/hello
+  dr-xr-xr-x                    0 ./share
+  …
+  ```
+
+* To show information about a specific file in a binary cache:
+
+  ```console
+  # nix store ls --store https://cache.nixos.org/ -l /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10/bin/hello
+  -r-xr-xr-x                38184 hello
+  ```
+
+# Description
+
+This command shows information about *path* in a Nix store. *path* can
+be a top-level store path or any file inside a store path.
+
+)""