diff options
author | pennae <github@quasiparticle.net> | 2022-06-28 21:29:56 +0200 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2022-06-28 23:29:23 +0200 |
commit | 8e3c7a1fd54577b49d56f40a58d6927e6027ce6a (patch) | |
tree | dd97f68565215d674341c7d256b561ceaad6e36c /maintainers/scripts | |
parent | f2bcc211d7fc313d6b83e666dc184c7fa0bebe7b (diff) |
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.
Diffstat (limited to 'maintainers/scripts')
-rwxr-xr-x | maintainers/scripts/mdize-module.sh | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/maintainers/scripts/mdize-module.sh b/maintainers/scripts/mdize-module.sh new file mode 100755 index 000000000000..c28710840e18 --- /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 +} |