From e9de689a6efca961099f1acfc574009f31a6f130 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Tue, 8 Dec 2020 18:09:30 +0100
Subject: [PATCH] Add 'nix search' manpage

---
 src/nix/search.cc | 25 ++++------------
 src/nix/search.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 20 deletions(-)
 create mode 100644 src/nix/search.md

diff --git a/src/nix/search.cc b/src/nix/search.cc
index 47770e128..9f864b3a4 100644
--- a/src/nix/search.cc
+++ b/src/nix/search.cc
@@ -41,29 +41,14 @@ struct CmdSearch : InstallableCommand, MixJSON
 
     std::string description() override
     {
-        return "query available packages";
+        return "search for packages";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To show all packages in the flake in the current directory:",
-                "nix search"
-            },
-            Example{
-                "To show packages in the 'nixpkgs' flake containing 'blender' in its name or description:",
-                "nix search nixpkgs blender"
-            },
-            Example{
-                "To search for Firefox or Chromium:",
-                "nix search nixpkgs 'firefox|chromium'"
-            },
-            Example{
-                "To search for packages containing 'git' and either 'frontend' or 'gui':",
-                "nix search nixpkgs git 'frontend|gui'"
-            }
-        };
+        return
+          #include "search.md"
+          ;
     }
 
     Strings getDefaultFlakeAttrPaths() override
diff --git a/src/nix/search.md b/src/nix/search.md
new file mode 100644
index 000000000..d182788a6
--- /dev/null
+++ b/src/nix/search.md
@@ -0,0 +1,72 @@
+R""(
+
+# Examples
+
+* Show all packages in the `nixpkgs` flake:
+
+  ```console
+  # nix search nixpkgs
+  * legacyPackages.x86_64-linux.AMB-plugins (0.8.1)
+    A set of ambisonics ladspa plugins
+
+  * legacyPackages.x86_64-linux.ArchiSteamFarm (4.3.1.0)
+    Application with primary purpose of idling Steam cards from multiple accounts simultaneously
+  …
+  ```
+
+* Show packages in the `nixpkgs` flake containing `blender` in its
+  name or description:
+
+  ```console
+  # nix search nixpkgs blender
+  * legacyPackages.x86_64-linux.blender (2.91.0)
+    3D Creation/Animation/Publishing System
+  ```
+
+* Search for packages underneath the attribute `gnome3` in Nixpkgs:
+
+  ```console
+  # nix search nixpkgs#gnome3 vala
+  * legacyPackages.x86_64-linux.gnome3.vala (0.48.9)
+    Compiler for GObject type system
+  ```
+
+* Show all packages in the flake in the current directory:
+
+  ```console
+  # nix search
+  ```
+
+* Search for Firefox or Chromium:
+
+  ```console
+  # nix search nixpkgs 'firefox|chromium'
+  ```
+
+* Search for packages containing `git'`and either `frontend` or `gui`:
+
+  ```console
+  # nix search nixpkgs git 'frontend|gui'
+  ```
+
+# Description
+
+`nix search` searches *installable* (which must be evaluatable, e.g. a
+flake) for packages whose name or description matches all of the
+regular expressions *regex*.  For each matching package, It prints the
+full attribute name (from the root of the installable), the version
+and the `meta.description` field, highlighting the substrings that
+were matched by the regular expressions. If no regular expressions are
+specified, all packages are shown.
+
+# Flake output attributes
+
+If no flake output attribute is given, `nix search` searches for
+packages:
+
+* Directly underneath `packages.<system>`.
+
+* Underneath `legacyPackages.<system>`, recursing into attribute sets
+  that contain an attribute `recurseForDerivations = true`.
+
+)""