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

@@ -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 != ""

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
+          > **Warning**
-    {
+          >
-        return {
+          > 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; }