maintainers/scripts/mdize-module.sh

   1 #! /usr/bin/env nix-shell
   2 #! nix-shell -I nixpkgs=. -i bash -p delta jq perl
   3
   4 set -euo pipefail
   5 shopt -s inherit_errexit
   6
   7 cat <<'EOF'
   8 This script attempts to automatically convert option descriptions from
   9 DocBook syntax to markdown. Naturally this process is incomplete and
  10 imperfect, so any changes generated by this script MUST be reviewed.
  11
  12 Possible problems include: incorrectly replaced tags, badly formatted
  13 markdown, DocBook tags this script doesn't recognize remaining in the
  14 output and crashing the docs build, incorrect escaping of markdown
  15 metacharacters, incorrect unescaping of XML entities—and the list goes on.
  16
  17 Always review the generated changes!
  18
  19 Some known limitations:
  20   - Does not transform literalDocBook items
  21   - Replacements can occur in non-option code, such as string literals
  22
  23
  24 EOF
  25
  26
  27
  28 build-options-json() {
  29     nix-build --no-out-link --expr '
  30         let
  31             sys = import ./nixos/default.nix {
  32                 configuration = {};
  33             };
  34         in
  35         [
  36             sys.config.system.build.manual.optionsJSON
  37         ]
  38     '
  39 }
  40
  41
  42
  43 git diff --quiet || {
  44     echo "Worktree is dirty. Please stash or commit first."
  45     exit 1
  46 }
  47
  48 echo "Building options.json ..."
  49 old_options=$(build-options-json)
  50
  51 echo "Applying replacements ..."
  52 perl -pi -e '
  53     BEGIN {
  54         undef $/;
  55     }
  56
  57     s,<literal>([^`]*?)</literal>,`$1`,smg;
  58     s,<replaceable>([^»]*?)</replaceable>,«$1»,smg;
  59     s,<filename>([^`]*?)</filename>,{file}`$1`,smg;
  60     s,<option>([^`]*?)</option>,{option}`$1`,smg;
  61     s,<code>([^`]*?)</code>,`$1`,smg;
  62     s,<command>([^`]*?)</command>,{command}`$1`,smg;
  63     s,<link xlink:href="(.+?)" ?/>,<$1>,smg;
  64     s,<link xlink:href="(.+?)">(.*?)</link>,[$2]($1),smg;
  65     s,<package>([^`]*?)</package>,`$1`,smg;
  66     s,<emphasis>([^*]*?)</emphasis>,*$1*,smg;
  67     s,<citerefentry>\s*
  68         <refentrytitle>\s*(.*?)\s*</refentrytitle>\s*
  69         <manvolnum>\s*(.*?)\s*</manvolnum>\s*
  70       </citerefentry>,{manpage}`$1($2)`,smgx;
  71     s,^( +description =),\1 lib.mdDoc,smg;
  72 ' "$@"
  73
  74 echo "Building options.json again ..."
  75 new_options=$(build-options-json)
  76
  77
  78 ! cmp -s {$old_options,$new_options}/share/doc/nixos/options.json && {
  79     diff -U10 \
  80         <(jq . <$old_options/share/doc/nixos/options.json) \
  81         <(jq . <$new_options/share/doc/nixos/options.json) \
  82         | delta
  83 }