From 6f19c776db280a46e84d6e84d83814445869ef37 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 17 Aug 2020 19:33:18 +0200
Subject: [PATCH] Start generation of the nix.1 manpage

---
 .gitignore                                    |  2 +
 doc/manual/generate-manpage.jq                | 42 +++++++++++++++++++
 doc/manual/local.mk                           |  8 +++-
 doc/manual/src/SUMMARY.md                     |  2 +
 .../src/command-ref/experimental-commands.md  |  8 ++++
 src/libutil/args.cc                           |  3 +-
 6 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100644 doc/manual/generate-manpage.jq
 create mode 100644 doc/manual/src/command-ref/experimental-commands.md

diff --git a/.gitignore b/.gitignore
index d456d7da3..b8028e665 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,6 +25,8 @@ perl/Makefile.config
 /doc/manual/*.1
 /doc/manual/*.5
 /doc/manual/*.8
+/doc/manual/nix.json
+/doc/manual/src/command-ref/nix.md
 
 # /scripts/
 /scripts/nix-profile.sh
diff --git a/doc/manual/generate-manpage.jq b/doc/manual/generate-manpage.jq
new file mode 100644
index 000000000..cf06da0c8
--- /dev/null
+++ b/doc/manual/generate-manpage.jq
@@ -0,0 +1,42 @@
+def show_flags:
+
+.flags
+| map_values(select(.category != "config"))
+| to_entries
+| map(
+    "  - `--" + .key + "`"
+    + (if .value.shortName then " / `" + .value.shortName + "`" else "" end)
+    + (if .value.labels then " " + (.value.labels | map("*" + . + "*") | join(" ")) else "" end)
+    + "  \n"
+    + "    " + .value.description + "\n\n")
+| join("")
+;
+
+def show_synopsis:
+
+"`" + .command + "` " + (.args | map("*" + .label + "*" + (if has("arity") then "" else "..." end)) | join(" ")) + "\n"
+
+;
+
+"# Synopsis\n\n"
++ ({"command": "nix", "args": .args} | show_synopsis)
++ "\n"
++ "# Common flags\n\n"
++ show_flags
++ (.commands | to_entries | map(
+    "# Operation `" + .key + "`\n\n"
+    + "## Synopsis\n\n"
+    + ({"command": ("nix " + .key), "args": .value.args} | show_synopsis)
+    + "\n"
+    + "## Description\n\n"
+    + .value.description + "\n\n"
+    + (if (.value.flags | length) > 0 then
+        "## Flags\n\n"
+        + (.value | show_flags)
+      else "" end)
+    + (if (.value.examples | length) > 0 then
+        "## Examples\n\n"
+        + (.value.examples | map("- " + .description + "\n\n  ```console\n  " + .command + "\n  ```\n" ) | join("\n"))
+        + "\n"
+       else "" end)
+  ) | join(""))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index c9104ad7e..8f917316d 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -4,7 +4,7 @@ MANUAL_SRCS := $(call rwildcard, $(d)/src, *.md)
 
 # Generate man pages.
 man-pages := $(foreach n, \
-  nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \
+  nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 nix.1 \
   nix-collect-garbage.1 \
   nix-prefetch-url.1 nix-channel.1 \
   nix-hash.1 nix-copy-closure.1 \
@@ -24,6 +24,12 @@ $(d)/%.8: $(d)/src/command-ref/%.md
 $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
 	$(trace-gen) lowdown -sT man $^ -o $@
 
+$(d)/src/command-ref/nix.md: $(d)/nix.json $(d)/generate-manpage.jq
+	jq -r -f doc/manual/generate-manpage.jq $< > $@
+
+$(d)/nix.json: $(bindir)/nix
+	$(trace-gen) $(bindir)/nix dump-args > $@
+
 # Generate the HTML manual.
 install: $(docdir)/manual/index.html
 
diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md
index 5f6817674..4089caf8a 100644
--- a/doc/manual/src/SUMMARY.md
+++ b/doc/manual/src/SUMMARY.md
@@ -60,6 +60,8 @@
     - [nix-hash](command-ref/nix-hash.md)
     - [nix-instantiate](command-ref/nix-instantiate.md)
     - [nix-prefetch-url](command-ref/nix-prefetch-url.md)
+  - [Experimental Commands](command-ref/experimental-commands.md)
+    - [nix](command-ref/nix.md)
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
 - [Glossary](glossary.md)
diff --git a/doc/manual/src/command-ref/experimental-commands.md b/doc/manual/src/command-ref/experimental-commands.md
new file mode 100644
index 000000000..cfa6f8b73
--- /dev/null
+++ b/doc/manual/src/command-ref/experimental-commands.md
@@ -0,0 +1,8 @@
+# Experimental Commands
+
+This section lists experimental commands.
+
+> **Warning**
+>
+> These commands may be removed in the future, or their syntax may
+> change in incompatible ways.
diff --git a/src/libutil/args.cc b/src/libutil/args.cc
index bf5e7ce95..ad83a2414 100644
--- a/src/libutil/args.cc
+++ b/src/libutil/args.cc
@@ -238,6 +238,7 @@ nlohmann::json Args::toJSON()
     }
 
     auto res = nlohmann::json::object();
+    res["description"] = description();
     res["flags"] = std::move(flags);
     res["args"] = std::move(args);
     return res;
@@ -371,7 +372,7 @@ MultiCommand::MultiCommand(const Commands & commands)
     : commands(commands)
 {
     expectArgs({
-        .label = "command",
+        .label = "subcommand",
         .optional = true,
         .handler = {[=](std::string s) {
             assert(!command);