dotfiles

commit 8bb903d4f4e66193ca8def6a604d0284e892c47b
parent 8a529801047357a2cfab6a549e297175c6dd7535
Author: Kévin Le Gouguec <kevin.legouguec@gmail.com>
Date:   Sun, 14 Dec 2025 23:08:04 +0100

Add script to convert XDG specs into info manuals

I just hate having to whip out a browser every time I need to check
some basedir trivia.

Diffstat:
A
.local/bin/xdg-specs-build
 | 
82
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

1 file changed, 82 insertions(+), 0 deletions(-)
diff --git a/.local/bin/xdg-specs-build b/.local/bin/xdg-specs-build
@@ -0,0 +1,82 @@
+#!/bin/bash
+
+set -eu -o pipefail
+shopt -s inherit_errexit
+test "${DEBUG:-}" && set -x
+
+declare -r SRC_DIR=~/src/freedesktop.org/xdg-specs
+declare -r INSTALL_DIR=~/apps/xdg-specs
+declare -r TEXI_DIR="${INSTALL_DIR}"/texi
+declare -r INFO_DIR="${INSTALL_DIR}"/share/info
+
+find-specs ()
+{
+    # Ain't nobody got time for parsing spec-index.toml.
+    find "${SRC_DIR}" -name '*-spec.xml'
+}
+
+spec-title ()
+{
+    local -r docbook=$1
+    # Ain't nobody got time for querying XML.  See also:
+    # https://github.com/jgm/pandoc/issues/1950
+    # https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value
+    sed -nr s,'^ *<title>(.*)</title>$','\1',p "${docbook}" | head -n1
+}
+
+spec-id ()
+{
+    local -r docbook=$1
+    echo xdg-$(basename "${docbook}" -spec.xml)
+}
+
+texi-dir-prologue ()
+{
+    local -r docbook=$1
+    local -r texi_title=$(spec-title "${docbook}")
+    local -r texi_id=$(spec-id "${docbook}")
+
+    cat <<EOF
+@dircategory Software development
+@direntry
+* ${texi_title}: (${texi_id}).
+@end direntry
+EOF
+}
+
+build-spec ()
+{
+    shift   # mapfile callback: $1 = index.
+    local -r docbook=$1
+    local -r name=$(spec-id "${docbook}")
+    local -r texi=${TEXI_DIR}/${name}.texi
+    local -r info=${INFO_DIR}/${name}.info
+
+    pandoc -s -H <(texi-dir-prologue "${docbook}") \
+           -f docbook "${docbook}" -o "${texi}"
+
+}
+
+mkdir -p "${TEXI_DIR}" "${INFO_DIR}"
+# Create a /bin directory to coax
+# * my apps 'activate' script into adding it to PATH,
+# * info into finding the .info files, by virtue of inspecting PATH
+#   entries for share/info siblings.
+mkdir "${INSTALL_DIR}"/bin
+
+# I dream of a bash built-in like
+#   map FUNC [ARGS… --] GLOB…
+# but afaict that doesn't exist?  So here I am inflicting 'mapfile' &
+# 'xargs' violence.
+
+find-specs | mapfile -tc1 -Cbuild-spec
+
+# pandoc turns menu-spec.xml's
+#   <xref linkend="term-desktop-file-id"/>
+# into
+#   @ref{#term-desktop-file-id,,glossentry_title}
+# but makeinfo does not like those.  Quelch with --no-validate.
+makeinfo --no-validate "${TEXI_DIR}"/*.texi -o "${INFO_DIR}"
+
+find "${INFO_DIR}" -name '*.info' |
+    xargs -d'\n' -I'{}' install-info '{}' "${INFO_DIR}"/dir