From 8e3c7a1fd54577b49d56f40a58d6927e6027ce6a Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Tue, 28 Jun 2022 21:29:56 +0200
Subject: [PATCH 1/2] maintainers: add a helper script for the options doc
 conversion

this script can be used to attempt an automatic conversion of option
docs for most modules. it'll also show a diff of options.json before and
after the changes, which should be a good form for checking for unwanted
changes. we specifically show a json diff rather than an xml diff
because newline changes in json are "\n" added are removed, and those
are easier for diff tools to pick out and show in a meaningful way for
this process.

it does *not* check for incorrectly applied changes though, those aren't
easy enough to do automatically for this script.
---
 maintainers/scripts/mdize-module.sh | 79 +++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100755 maintainers/scripts/mdize-module.sh

diff --git a/maintainers/scripts/mdize-module.sh b/maintainers/scripts/mdize-module.sh
new file mode 100755
index 00000000000..c28710840e1
--- /dev/null
+++ b/maintainers/scripts/mdize-module.sh
@@ -0,0 +1,79 @@
+#! /usr/bin/env nix-shell
+#! nix-shell -I nixpkgs=. -i bash -p delta jq perl
+
+set -euo pipefail
+shopt -s inherit_errexit
+
+cat <<'EOF'
+This script attempts to automatically convert option descriptions from
+DocBook syntax to markdown. Naturally this process is incomplete and
+imperfect, so any changes generated by this script MUST be reviewed.
+
+Possible problems include: incorrectly replaced tags, badly formatted
+markdown, DocBook tags this script doesn't recognize remaining in the
+output and crashing the docs build, incorrect escaping of markdown
+metacharacters, incorrect unescaping of XML entities—and the list goes on.
+
+Always review the generated changes!
+
+
+EOF
+
+
+
+build-options-json() {
+    nix-build --no-out-link --expr '
+        let
+            sys = import ./nixos/default.nix {
+                configuration = {};
+            };
+        in
+        [
+            sys.config.system.build.manual.optionsJSON
+        ]
+    '
+}
+
+
+
+git diff --quiet || {
+    echo "Worktree is dirty. Please stash or commit first."
+    exit 1
+}
+
+echo "Building options.json ..."
+old_options=$(build-options-json)
+
+echo "Applying replacements ..."
+perl -pi -e '
+    BEGIN {
+        undef $/;
+    }
+
+    s,<literal>([^`]*?)</literal>,`$1`,smg;
+    s,<replaceable>([^»]*?)</replaceable>,«$1»,smg;
+    s,<filename>([^`]*?)</filename>,{file}`$1`,smg;
+    s,<option>([^`]*?)</option>,{option}`$1`,smg;
+    s,<code>([^`]*?)</code>,`$1`,smg;
+    s,<command>([^`]*?)</command>,{command}`$1`,smg;
+    s,<link xlink:href="(.+?)" ?/>,<$1>,smg;
+    s,<link xlink:href="(.+?)">(.*?)</link>,[$2]($1),smg;
+    s,<package>([^`]*?)</package>,`$1`,smg;
+    s,<emphasis>([^*]*?)</emphasis>,*$1*,smg;
+    s,<citerefentry>\s*
+        <refentrytitle>\s*(.*?)\s*</refentrytitle>\s*
+        <manvolnum>\s*(.*?)\s*</manvolnum>\s*
+      </citerefentry>,{manpage}`$1($2)`,smgx;
+    s,^( +description =),\1 lib.mdDoc,smg;
+' "$@"
+
+echo "Building options.json again ..."
+new_options=$(build-options-json)
+
+
+! cmp -s {$old_options,$new_options}/share/doc/nixos/options.json && {
+    diff -U10 \
+        <(jq . <$old_options/share/doc/nixos/options.json) \
+        <(jq . <$new_options/share/doc/nixos/options.json) \
+        | delta
+}

From 20f5ebdd3cec7df91fc4e9805a7d002d0f7fc0ae Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 5 Jul 2022 19:15:11 +0200
Subject: [PATCH 2/2] maintainers/mdize-module: Add known limitations

---
 maintainers/scripts/mdize-module.sh | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/maintainers/scripts/mdize-module.sh b/maintainers/scripts/mdize-module.sh
index c28710840e1..e2d2e5467aa 100755
--- a/maintainers/scripts/mdize-module.sh
+++ b/maintainers/scripts/mdize-module.sh
@@ -16,6 +16,10 @@ metacharacters, incorrect unescaping of XML entities—and the list goes on.
 
 Always review the generated changes!
 
+Some known limitations:
+  - Does not transform literalDocBook items
+  - Replacements can occur in non-option code, such as string literals
+
 
 EOF