maintainers/scripts/db-to-md.sh

   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
   7 debug=
   8 files=()
   9
  10 while [ "$#" -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
  20 done
  21
  22 echo "WARNING: This is an experimental script and might not preserve all formatting." > /dev/stderr
  23 echo "Please report any issues you discover." > /dev/stderr
  24
  25 outExtension="md"
  26 if [[ $debug ]]; then
  27     outExtension="json"
  28 fi
  29
  30 DIR="$( 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.
  34 pandoc_commonmark_enabled_extensions=+attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute
  35 targetLang="commonmark${pandoc_commonmark_enabled_extensions}+smart"
  36 if [[ $debug ]]; then
  37     targetLang=json
  38 fi
  39 pandoc_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
  56 for 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
  88 done