docs: Add a short sections on helpers (#1093)

docs/man/default.nix

@@ -3,17 +3,45 @@
   runCommand,
   installShellFiles,
   nixos-render-docs,
-}:
-runCommand "nixvim-configuration-reference-manpage" {
-  nativeBuildInputs = [installShellFiles nixos-render-docs];
-} ''
-  # Generate man-pages
-  mkdir -p $out/share/man/man5
-  nixos-render-docs -j $NIX_BUILD_CORES options manpage \
-    --revision unstable \
-    --header ${./nixvim-header.5} \
-    --footer ${./nixvim-footer.5} \
-    ${options-json}/share/doc/nixos/options.json \
-    $out/share/man/man5/nixvim.5
-  compressManPages $out
-''
+  pandoc,
+}: let
+  capitalizeHeaders = ''
+    local text = pandoc.text
+
+    function Header(el)
+        if el.level == 1 then
+          return el:walk {
+            Str = function(el)
+                return pandoc.Str(text.upper(el.text))
+            end
+          }
+        end
+    end
+  '';
+
+  manHeader =
+    runCommand "nixvim-general-doc-manpage" {
+      nativeBuildInputs = [pandoc];
+      inherit capitalizeHeaders;
+    } ''
+      mkdir -p $out
+      cat \
+        ${./nixvim-header-start.5} \
+        <(pandoc --lua-filter <(echo "$capitalizeHeaders") -f gfm -t man ${../helpers.md}) \
+        ${./nixvim-header-end.5} \
+        >$out/nixvim-header.5
+    '';
+in
+  runCommand "nixvim-configuration-reference-manpage" {
+    nativeBuildInputs = [installShellFiles nixos-render-docs];
+  } ''
+    # Generate man-pages
+    mkdir -p $out/share/man/man5
+    nixos-render-docs -j $NIX_BUILD_CORES options manpage \
+      --revision unstable \
+      --header ${manHeader}/nixvim-header.5 \
+      --footer ${./nixvim-footer.5} \
+      ${options-json}/share/doc/nixos/options.json \
+      $out/share/man/man5/nixvim.5
+    compressManPages $out
+  ''

docs/man/nixvim-header-end.5

@@ -0,0 +1,3 @@
+.SH "OPTIONS"
+.PP
+You can use the following options in a NixVim module.

docs/man/nixvim-header-start.5

@@ -10,6 +10,3 @@ NixVim options specification
 .SH "DESCRIPTION"
 .PP
 This page lists all the options that can be used in NixVim. It can either be used as a Home-Manager module, an NixOS module or a standalone package. Please refer to the installation instructions for more details.
-.SH "OPTIONS"
-.PP
-You can use the following options in a NixVim module.