lib/options: deprecate docbook text and literalDocBook

deprecate literalDocBook by adding a warning (that will not fire yet) to
its uses and other docbook literal strings by adding optional warning
message to mergeJSON.

nixos/modules/misc/documentation.nix

@@ -99,7 +99,7 @@ let
               exit 1
             } >&2
         '';
-    inherit (cfg.nixos.options) warningsAreErrors;
+    inherit (cfg.nixos.options) warningsAreErrors allowDocBook;
   };
 
 
@@ -255,6 +255,23 @@ in
         '';
       };
 
+      nixos.options.allowDocBook = mkOption {
+        type = types.bool;
+        default = true;
+        description = lib.mdDoc ''
+          Whether to allow DocBook option docs. When set to `false` all option using
+          DocBook documentation will cause a manual build error; additionally a new
+          renderer may be used.
+
+          ::: {.note}
+          The `false` setting for this option is not yet fully supported. While it
+          should work fine and produce the same output as the previous toolchain
+          using DocBook it may not work in all circumstances. Whether markdown option
+          documentation is allowed is independent of this option.
+          :::
+        '';
+      };
+
       nixos.options.warningsAreErrors = mkOption {
         type = types.bool;
         default = true;