pyrox.dev
1#! /usr/bin/env nix-shell
2#! nix-shell -I nixpkgs=. -i bash -p pandoc
3
4# This script is temporarily needed while we transition the manual to
5# CommonMark. It converts DocBook files into our CommonMark flavour.
6
7debug=
8files=()
9
10while [ "$#" -gt 0 ]; do
11 i="$1"; shift 1
12 case "$i" in
13 --debug)
14 debug=1
15 ;;
16 *)
17 files+=("$i")
18 ;;
19 esac
20done
21
22echo "WARNING: This is an experimental script and might not preserve all formatting." > /dev/stderr
23echo "Please report any issues you discover." > /dev/stderr
24
25outExtension="md"
26if [[ $debug ]]; then
27 outExtension="json"
28fi
29
30DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
31
32# NOTE: Keep in sync with Nixpkgs manual (/doc/Makefile).
33# TODO: Remove raw-attribute when we can get rid of DocBook altogether.
34pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
35targetLang="commonmark${pandoc_commonmark_enabled_extensions}+smart"
36if [[ $debug ]]; then
37 targetLang=json
38fi
39pandoc_flags=(
40 # Not needed:
41 # - diagram-generator.lua (we do not support that in NixOS manual to limit dependencies)
42 # - media extraction (was only required for diagram generator)
43 # - myst-reader/roles.lua (only relevant for MyST → DocBook)
44 # - link-manpages.lua (links should only be added to display output)
45 # - docbook-writer/rst-roles.lua (only relevant for → DocBook)
46 # - docbook-writer/labelless-link-is-xref.lua (only relevant for → DocBook)
47 "--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/docbook-reader/citerefentry-to-rst-role.lua"
48 "--lua-filter=$DIR/../../doc/build-aux/pandoc-filters/myst-writer/roles.lua"
49 "--lua-filter=$DIR/doc/unknown-code-language.lua"
50 -f docbook
51 -t "$targetLang"
52 --tab-stop=2
53 --wrap=none
54)
55
56for file in "${files[@]}"; do
57 if [[ ! -f "$file" ]]; then
58 echo "db-to-md.sh: $file does not exist" > /dev/stderr
59 exit 1
60 else
61 rootElement=$(xmllint --xpath 'name(//*)' "$file")
62
63 if [[ $rootElement = chapter ]]; then
64 extension=".chapter.$outExtension"
65 elif [[ $rootElement = section ]]; then
66 extension=".section.$outExtension"
67 else
68 echo "db-to-md.sh: $file contains an unsupported root element $rootElement" > /dev/stderr
69 exit 1
70 fi
71
72 outFile="${file%".section.xml"}"
73 outFile="${outFile%".chapter.xml"}"
74 outFile="${outFile%".xml"}$extension"
75 temp1=$(mktemp)
76 $DIR/doc/escape-code-markup.py "$file" "$temp1"
77 if [[ $debug ]]; then
78 echo "Converted $file to $temp1" > /dev/stderr
79 fi
80 temp2=$(mktemp)
81 $DIR/doc/replace-xrefs-by-empty-links.py "$temp1" "$temp2"
82 if [[ $debug ]]; then
83 echo "Converted $temp1 to $temp2" > /dev/stderr
84 fi
85 pandoc "$temp2" -o "$outFile" "${pandoc_flags[@]}"
86 echo "Converted $file to $outFile" > /dev/stderr
87 fi
88done