tjh.dev
1#! /usr/bin/env nix-shell
2#! nix-shell -I nixpkgs=. -i bash -p delta jq perl
3
4set -euo pipefail
5shopt -s inherit_errexit
6
7cat <<'EOF'
8This script attempts to automatically convert option descriptions from
9DocBook syntax to markdown. Naturally this process is incomplete and
10imperfect, so any changes generated by this script MUST be reviewed.
11
12Possible problems include: incorrectly replaced tags, badly formatted
13markdown, DocBook tags this script doesn't recognize remaining in the
14output and crashing the docs build, incorrect escaping of markdown
15metacharacters, incorrect unescaping of XML entities—and the list goes on.
16
17Always review the generated changes!
18
19Some known limitations:
20 - Does not transform literalDocBook items
21 - Replacements can occur in non-option code, such as string literals
22
23
24EOF
25
26
27
28build-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
43git diff --quiet || {
44 echo "Worktree is dirty. Please stash or commit first."
45 exit 1
46}
47
48echo "Building options.json ..."
49old_options=$(build-options-json)
50
51echo "Applying replacements ..."
52perl -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
74echo "Building options.json again ..."
75new_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}