From c3c858ac6d0c75bd95bd6913276ef20cf2495e96 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Thu, 3 Dec 2020 13:55:19 +0100
Subject: [PATCH] Make doc() return arbitrary Markdown rather than the contents
 of the "Description" section

Thus we can return the examples section (and any other sections) from
doc() and don't need examples() anymore.
---
 doc/manual/generate-manpage.nix |  2 +-
 src/nix/add-to-store.cc         | 26 ++++++++++++++++++++------
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 4a0b0290b..fbd7f3e7d 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -26,7 +26,7 @@ let
          + concatStrings (map ({ description, command }: "${description}\n\n```console\n${command}\n```\n\n") def.examples)
        else "")
     + (if def ? doc
-       then "# Description\n\n" + def.doc + "\n\n"
+       then def.doc + "\n\n"
        else "")
     + (let s = showFlags def.flags; in
        if s != ""
diff --git a/src/nix/add-to-store.cc b/src/nix/add-to-store.cc
index df51e72d5..022f0ea85 100644
--- a/src/nix/add-to-store.cc
+++ b/src/nix/add-to-store.cc
@@ -39,15 +39,29 @@ struct CmdAddToStore : MixDryRun, StoreCommand
     std::string doc() override
     {
         return R"(
+          # Description
+
           Copy the file or directory *path* to the Nix store, and
           print the resulting store path on standard output.
-        )";
-    }
 
-    Examples examples() override
-    {
-        return {
-        };
+          > **Warning**
+          >
+          > The resulting store path is not registered as a garbage
+          > collector root, so it could be deleted before you have a
+          > chance to register it.
+
+          # Examples
+
+          Add a regular file to the store:
+
+          ```console
+          # echo foo > bar
+          # nix add-to-store --flat ./bar
+          /nix/store/cbv2s4bsvzjri77s2gb8g8bpcb6dpa8w-bar
+          # cat /nix/store/cbv2s4bsvzjri77s2gb8g8bpcb6dpa8w-bar
+          foo
+          ```
+        )";
     }
 
     Category category() override { return catUtility; }