From 7ced41f5db9c3acee3227634d16ec1143b7e769e Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Mon, 15 Jul 2024 03:58:10 +0200
Subject: [PATCH 01/25] package.json: add moxygen

Signed-off-by: Tim Janik <timj@gnu.org>
---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index e1b17af4..d3f57d07 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
     "markdown-it": "^14.1.0",
     "material-icons": "^1.13.12",
     "mathjax": "^3.2.2",
+    "moxygen": "^0.8.0",
     "nodemon": "^3.1.0",
     "npm-run-all": "^4.1.5",
     "postcss": "^8.4.38",

From f3cb9f0cc247042433938837e3687f524edd7622 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Tue, 16 Jul 2024 03:10:52 +0200
Subject: [PATCH 02/25] package.json: update Vue, Electron, Lit and development
 dependencies

Signed-off-by: Tim Janik <timj@gnu.org>
---
 package.json | 62 ++++++++++++++++++++++++++--------------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/package.json b/package.json
index d3f57d07..a32f0048 100644
--- a/package.json
+++ b/package.json
@@ -9,71 +9,71 @@
     "ui/rebuild": "exec make ui/rebuild -j`nproc`"
   },
   "dependencies": {
-    "vue": "=3.4.27"
+    "vue": "=3.4.31"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.24.5",
-    "@eslint/eslintrc": "^3.0.2",
+    "@babel/eslint-parser": "^7.24.8",
+    "@eslint/eslintrc": "^3.1.0",
     "@fontsource/charis-sil": "^5.0.13",
     "@fontsource/inconsolata": "^5.0.18",
-    "@html-eslint/eslint-plugin": "^0.24.1",
-    "@html-eslint/parser": "^0.24.1",
+    "@html-eslint/eslint-plugin": "^0.25.0",
+    "@html-eslint/parser": "^0.25.0",
     "@puppeteer/replay": "^3.0.0",
-    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@tailwindcss/aspect-ratio": "^0.4.2",
     "@tailwindcss/container-queries": "^0.1.1",
     "@tailwindcss/forms": "^0.5.7",
     "@tailwindcss/typography": "^0.5.13",
-    "colorjs.io": "^0.5.0",
+    "colorjs.io": "^0.5.2",
     "css-color-converter": "^2.0.0",
     "csstree-validator": "^3.0.0",
-    "electron": "^31.0.1",
-    "eslint": "^9.2.0",
+    "electron": "^31.2.1",
+    "eslint": "^9.7.0",
     "eslint-formatter-unix": "^8.40.0",
     "eslint-plugin-html": "^8.1.1",
-    "eslint-plugin-jsdoc": "^48.2.3",
-    "eslint-plugin-lit": "^1.12.0",
-    "eslint-plugin-tailwindcss": "^3.15.1",
-    "eslint-plugin-unused-imports": "^3.2.0",
-    "eslint-plugin-vue": "^9.25.0",
+    "eslint-plugin-jsdoc": "^48.7.0",
+    "eslint-plugin-lit": "^1.14.0",
+    "eslint-plugin-tailwindcss": "^3.17.4",
+    "eslint-plugin-unused-imports": "^4.0.0",
+    "eslint-plugin-vue": "^9.27.0",
     "fork-awesome": "^1.2.0",
-    "globals": "^15.3.0",
+    "globals": "^15.8.0",
     "jsdoc": "^4.0.3",
     "jsdoc-api": "^8.0.0",
     "jsdoc-tsimport-plugin": "^1.0.5",
-    "lit": "^3.1.3",
+    "lit": "^3.1.4",
     "markdown-it": "^14.1.0",
     "material-icons": "^1.13.12",
     "mathjax": "^3.2.2",
     "moxygen": "^0.8.0",
-    "nodemon": "^3.1.0",
+    "nodemon": "^3.1.4",
     "npm-run-all": "^4.1.5",
-    "postcss": "^8.4.38",
+    "postcss": "^8.4.39",
     "postcss-advanced-variables": "^4.0.0",
     "postcss-cli": "^11.0.0",
     "postcss-color-hwb": "^3.0.0",
-    "postcss-discard-comments": "^7.0.0",
+    "postcss-discard-comments": "^7.0.1",
     "postcss-discard-duplicates": "^7.0.0",
     "postcss-functions": "^4.0.2",
-    "postcss-lab-function": "^6.0.16",
+    "postcss-lab-function": "^6.0.19",
     "postcss-nested": "^6.0.1",
     "postcss-scss": "^4.0.9",
-    "prettier": "^3.2.5",
-    "prettier-plugin-tailwindcss": "^0.5.14",
+    "prettier": "^3.3.3",
+    "prettier-plugin-tailwindcss": "^0.6.5",
     "printf-ts": "^2.0.1",
-    "puppeteer-core": "^22.11.0",
-    "rollup": "^4.17.2",
-    "sass": "^1.77.0",
-    "signal-polyfill": "^0.1.0",
-    "stylelint": "^16.5.0",
-    "stylelint-config-standard": "^36.0.0",
+    "puppeteer-core": "^22.13.0",
+    "rollup": "^4.18.1",
+    "sass": "^1.77.8",
+    "signal-polyfill": "^0.1.1",
+    "stylelint": "^16.7.0",
+    "stylelint-config-standard": "^36.0.1",
     "stylelint-config-standard-scss": "^13.1.0",
-    "tailwindcss": "^3.4.3",
+    "tailwindcss": "^3.4.5",
     "tailwindcss-children": "^2.1.0",
-    "terser": "^5.31.0",
-    "typescript": "^5.4.5",
+    "terser": "^5.31.2",
+    "typescript": "^5.5.3",
     "zcam-js": "^0.0.9"
   }
 }

From 1193d9e158b6a969b29870f613b0657f7ee959de Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Tue, 16 Jul 2024 03:24:17 +0200
Subject: [PATCH 03/25] ui/eslintrc.js: allow attrs w/o newlines

Signed-off-by: Tim Janik <timj@gnu.org>
---
 ui/eslintrc.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ui/eslintrc.js b/ui/eslintrc.js
index 5ed843d4..1a992ce5 100644
--- a/ui/eslintrc.js
+++ b/ui/eslintrc.js
@@ -33,6 +33,7 @@ export default [
       "@html-eslint/quotes": OFF, // TODO: "warn",
       "@html-eslint/indent": OFF,
       "@html-eslint/no-extra-spacing-attrs": OFF,
+      "@html-eslint/attrs-newline": OFF,
     }
   },
 

From a804d132db1c3da700612a1404b9fb39ff25f460 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Mon, 15 Jul 2024 12:43:09 +0200
Subject: [PATCH 04/25] misc/Dockerfile.jammy: update build dependencies, add
 mkdocs

Signed-off-by: Tim Janik <timj@gnu.org>
---
 misc/Dockerfile.jammy | 54 +++++++++++++++++++++++++++++--------------
 1 file changed, 37 insertions(+), 17 deletions(-)

diff --git a/misc/Dockerfile.jammy b/misc/Dockerfile.jammy
index 4c33f87b..1b053d24 100644
--- a/misc/Dockerfile.jammy
+++ b/misc/Dockerfile.jammy
@@ -12,31 +12,51 @@ RUN ln -sf bash /bin/sh && ls -al /bin/sh
 RUN apt-get update \
   && apt-get -y upgrade \
   && apt-get install -y \
-	     sudo build-essential curl cmake libglib2.0-dev \
-	     build-essential pkg-config git curl ccache curl unzip gawk g++ \
-	     clang clang-tidy clang-tools castxml cppcheck libboost-system-dev \
+	     sudo build-essential curl cmake libglib2.0-dev libzstd-dev \
+	     build-essential pkg-config git ccache unzip gawk \
+	     castxml cppcheck libboost-system-dev \
 	     imagemagick librsvg2-bin libxml2-utils libxml2-dev python3 python3-pip \
 	     python3-lxml python3-pandocfilters pandoc graphviz universal-ctags \
-	     libasound2-dev libflac-dev libopus-dev libjack-dev libzstd-dev \
+	     libasound2-dev libflac-dev libopus-dev libjack-dev \
+	     libvorbis-dev libmpg123-dev libmp3lame-dev \
 	     gettext libgconf-2-4 libgtk2.0-dev libgtk-3-dev squashfs-tools zstd \
 	     libgtk-3-0 libxss1 libgbm1 libnss3 \
+	     lsb-release wget software-properties-common \
 	     xvfb twm ffmpeg doxygen \
   && apt-get clean
 
-# Install nodejs-18 and clang-17
-RUN curl -sL https://deb.nodesource.com/setup_20.x | bash - \
-  && apt-get install -y nodejs wget lsb-release software-properties-common gnupg \
-  && wget https://apt.llvm.org/llvm.sh -O llvm.sh && chmod +x llvm.sh \
-  && yes | ./llvm.sh 17 && rm ./llvm.sh \
-  && apt install -y clang-tidy-17 \
-  && apt-get clean
+# Install recent clang++
+RUN \
+  --mount=type=cache,target=/var/cache/apt \
+  curl -fsSLO https://apt.llvm.org/llvm.sh && chmod +x llvm.sh \
+  && yes | ./llvm.sh 18 && rm -f ./llvm.sh \
+  && apt-get install -y clang-tidy-18 libclang-18-dev \
+  && update-alternatives \
+       --install /usr/bin/clang         clang           /usr/bin/clang-18 0 \
+       --slave   /usr/bin/clang++       clang++         /usr/bin/clang++-18  \
+       --slave   /usr/bin/clang-tidy    clang-tidy      /usr/bin/clang-tidy-18 \
+  && apt-get autoremove -y
+
+# Nodejs - https://github.com/nodesource/distributions#nodejs
+RUN \
+  --mount=type=cache,target=/var/cache/apt \
+  mkdir -p /etc/apt/keyrings \
+  && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+  && rm -f nodesource-repo.gpg.key \
+  && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \
+  && apt-get update \
+  && apt-get install -y nodejs \
+  && apt-get autoremove -y
 
-# Install TeX and Poxy for documentation builds
-RUN pip install poxy \
+# Install TeX and mkdocs for documentation builds
+RUN pip install mkdocs-material mkdoxy poxy \
   && apt-get install -y texlive-xetex fonts-sil-charis texlive-binaries texlive-fonts-extra \
   && apt-get clean
 
-# Become non-root
-RUN groupadd --gid 1000 ubuntu && useradd --uid 1000 --gid 1000 --create-home --shell /bin/bash ubuntu \
-  && echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu
-USER ubuntu
+# Become non-root, use Github action VM user: uid=1001(runner) gid=127(docker)
+RUN groupadd -g 127 docker && useradd -u 1001 -g 127 -m -d /github/home -s /bin/bash runner \
+  && echo "runner ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/runner
+USER runner
+
+# docker build -t ghcr.io/tim-janik/anklang-ci:jammy-latest -f misc/Dockerfile.jammy misc
+# docker run -ti --rm -v $PWD:/hostwd ghcr.io/tim-janik/anklang-ci:jammy-latest

From d890d46884671000abef324ce9f6076651632997 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Mon, 15 Jul 2024 03:58:10 +0200
Subject: [PATCH 05/25] doc/mkdocs.yml: build modernized docs with mkdocs,
 mkdoxy

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/mkdocs.yml | 105 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 doc/mkdocs.yml

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
new file mode 100644
index 00000000..b91da7ab
--- /dev/null
+++ b/doc/mkdocs.yml
@@ -0,0 +1,105 @@
+site_name: Anklang Documentation
+site_url: https://mydomain.org/mysite
+site_dir: site
+docs_dir: mkdocs
+
+# docker run --rm -it -v${PWD}:/docs -p 127.0.0.1:8001:8000 ghcr.io/tim-janik/anklang-ci:mkdocs-latest
+# docker run --rm -it -v${PWD}:/docs --entrypoint '' squidfunk/mkdocs-material sudo chown 1000:1000 -R /docs/.
+
+repo_url: https://github.com/tim-janik/anklang
+repo_name: Anklang.git
+
+
+plugins:
+  - search
+  - privacy
+  - offline
+  - tags
+  #- blog
+  #- git-revision-date-localized:
+  #    type: timeago
+  #    fallback_to_build_date: true
+  #    enable_creation_date: true
+
+  - mkdoxy:
+      projects:
+        AnklangCxx: # name of project must be alphanumeric + numbers (without spaces)
+          src-dirs: ../ase/ ../devices/  # path to source code (support multiple paths separated by space) => INPUT
+          full-doc: True # if you want to generate full documentation
+          doxy-cfg: # standard doxygen configuration (key: value)
+            FILE_PATTERNS: "*.c .h *.cc *.hh *.js *.md *.dox" # specify file patterns to filter out
+            RECURSIVE: True # recursive search in source directories
+
+nav:
+  - Introduction: ch-intro.md
+  - Installation: ch-install.md
+  - Using Anklang:
+    - Anklang Overview: ch-editing.md
+    - User Interface:
+      - Clip-List: cliplist.md
+      - Piano-Ctrl: piano-ctrl.md
+      - Piano-Roll: pianoroll.md
+    - Manual Pages: ch-man-pages.md
+  - Development:
+    - Development Overview: ch-development.md
+    - UI Development:
+      - JS Scripting: scripting-docs.md
+      - Web Components: ch-component.md
+      - Component API: jsdocs.md
+    - AnklangCxx:
+      - C++ Class-Tree: class-tree.md
+      - 'Links': 'AnklangCxx/links.md'
+      - 'Class List': 'AnklangCxx/annotated.md'
+      - 'Class Members': 'AnklangCxx/class_members.md'
+      - 'Namespace List': 'AnklangCxx/namespaces.md'
+      - 'Namespace Members': 'AnklangCxx/namespace_members.md'
+      - 'Files': 'AnklangCxx/files.md'
+    - Internals:
+      - Making Releases: ch-releasing.md
+      - Interpolation Notes: ch-appendix.md
+
+# TODO: Piano-Ctrl lacks tools icons
+
+
+theme:
+  name: material
+  language: 'en'
+  #features:
+  #  - navigation.footer
+  features:
+    - search.suggest
+    - search.highlight
+    - search.share
+    - toc.integrate
+    - navigation.tracking
+    #- navigation.tabs
+    - navigation.sections
+    #- navigation.expand
+    - navigation.path
+
+  # taken from https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+
+
+
+copyright: Copyright &copy; 2024 Anklang Project
+
+extra:
+  generator: false
+  social:
+    - icon: fontawesome/brands/mastodon
+      link: https://social.tchncs.de/@timj

From a44f34400a75ae9c236b7c5cd73439289cb7ad6f Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Mon, 15 Jul 2024 03:58:10 +0200
Subject: [PATCH 06/25] doc/Makefile.mk: add mkdocs rule

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 909751ae..bcdd7cd6 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -250,3 +250,58 @@ doc/uninstall: FORCE uninstall--doc/style/install.files
 uninstall: doc/uninstall
 
 doc/all: $(doc/install.files)
+
+
+# == mkdocs ==
+doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters)
+$>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist) $>/mkdocs/cxx-api.md
+	@$(QECHO) RUN mkdocs
+	$Q rm -rf $>/site/
+	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
+	$Q ( cd $> && mkdocs build )
+mkdocs:
+	rm -rf $>/mkdocs/
+	$(MAKE) $>/site/search/search_index.js
+define doc_doxygen_xmlcfg
+	PROJECT_NAME           = "Anklang C++ API"
+	PROJECT_NUMBER         = $(version_short)
+	OUTPUT_DIRECTORY       = $>/doxygen/
+	ALLOW_UNICODE_NAMES    = YES
+	EXTRACT_LOCAL_CLASSES  = NO
+	HIDE_UNDOC_MEMBERS     = YES
+	HIDE_UNDOC_CLASSES     = YES
+	HIDE_FRIEND_COMPOUNDS  = YES
+	INTERNAL_DOCS          = YES
+	HIDE_COMPOUND_REFERENCE= YES
+	SHOW_INCLUDE_FILES     = NO
+	INLINE_INFO            = NO
+	SHOW_USED_FILES        = NO
+	SHOW_FILES             = NO
+	INPUT                  = ase/ devices/
+	VERBATIM_HEADERS       = NO
+	HTML_COLORSTYLE_SAT    = 60
+	HTML_DYNAMIC_MENUS     = NO
+	GENERATE_HTML	       = NO
+	GENERATE_LATEX	       = NO
+	GENERATE_XML           = YES
+	XML_PROGRAMLISTING     = NO
+	PREDEFINED             = "ASE_CLASS_DECLS(x)="
+	HIDE_UNDOC_RELATIONS   = YES
+	COLLABORATION_GRAPH    = NO
+	GROUP_GRAPHS           = NO
+	INCLUDE_GRAPH          = NO
+	INCLUDED_BY_GRAPH      = NO
+	GRAPHICAL_HIERARCHY    = NO
+	DIRECTORY_GRAPH        = NO
+	DOT_IMAGE_FORMAT       = svg
+endef
+export doc_doxygen_xmlcfg
+$>/doxygen/xml/index.xml:
+	@$(QECHO) RUN doxygen
+	$Q cat > $>/Doxyfile  <<<$$doc_doxygen_xmlcfg
+	$Q rm -rf $>/doxygen/ && doxygen $>/Doxyfile
+doxygen-xml: $>/doxygen/xml/index.xml
+$>/mkdocs/cxx-api.md: $>/doxygen/xml/index.xml		| $>/mkdocs/
+	@$(QECHO) RUN moxygen
+	$Q node_modules/.bin/moxygen -h -n -o $@ $>/doxygen/xml/
+

From 9ae09e035f0ecb095e97dbc007c2a117d2a8fc53 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Mon, 15 Jul 2024 12:43:09 +0200
Subject: [PATCH 07/25] doc/Makefile.mk: extend mkdocs, add pdf

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index bcdd7cd6..727077b1 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -254,7 +254,8 @@ doc/all: $(doc/install.files)
 
 # == mkdocs ==
 doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters)
-$>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist) $>/mkdocs/cxx-api.md
+$>/site/search/search_index.js: # $>/mkdocs/anklang-cxx.pdf $>/mkdocs/anklang-cxx.html
+$>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
 	$Q rm -rf $>/site/
 	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
@@ -282,7 +283,6 @@ define doc_doxygen_xmlcfg
 	HTML_COLORSTYLE_SAT    = 60
 	HTML_DYNAMIC_MENUS     = NO
 	GENERATE_HTML	       = NO
-	GENERATE_LATEX	       = NO
 	GENERATE_XML           = YES
 	XML_PROGRAMLISTING     = NO
 	PREDEFINED             = "ASE_CLASS_DECLS(x)="
@@ -294,14 +294,22 @@ define doc_doxygen_xmlcfg
 	GRAPHICAL_HIERARCHY    = NO
 	DIRECTORY_GRAPH        = NO
 	DOT_IMAGE_FORMAT       = svg
+	LATEX_CMD_NAME         = xelatex
+	COMPACT_LATEX          = YES
+	LATEX_HIDE_INDICES     = YES
 endef
 export doc_doxygen_xmlcfg
-$>/doxygen/xml/index.xml:
+$>/doxygen/latex/refman.tex: doc/Makefile.mk
 	@$(QECHO) RUN doxygen
 	$Q cat > $>/Doxyfile  <<<$$doc_doxygen_xmlcfg
 	$Q rm -rf $>/doxygen/ && doxygen $>/Doxyfile
-doxygen-xml: $>/doxygen/xml/index.xml
-$>/mkdocs/cxx-api.md: $>/doxygen/xml/index.xml		| $>/mkdocs/
-	@$(QECHO) RUN moxygen
-	$Q node_modules/.bin/moxygen -h -n -o $@ $>/doxygen/xml/
+$>/doxygen/xml/index.xml: $>/doxygen/latex/refman.tex
+$>/mkdocs/anklang-cxx.pdf: $>/doxygen/latex/refman.tex	| $>/mkdocs/
+	@$(QGEN)
+	$Q cd $>/doxygen/latex/ && $(MAKE)
+	$Q cp $>/doxygen/latex/refman.pdf $@
+$>/mkdocs/anklang-cxx.html: $>/doxygen/xml/index.xml	| $>/mkdocs/
+	@$(QGEN)
+	$Q node_modules/.bin/moxygen -h -n -o $>/anklang-cxx.md $>/doxygen/xml/
+	$Q pandoc $>/anklang-cxx.md -o $@ && rm -f $>/anklang-cxx.md
 

From 08b8fdd3db7cc74b48febbd8a44764cdc78ebee0 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 18 Jul 2024 18:41:51 +0200
Subject: [PATCH 08/25] .github/workflows/pages.yml: build docu with mkdocs and
 deploy pages

Signed-off-by: Tim Janik <timj@gnu.org>
---
 .github/workflows/pages.yml | 59 +++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 .github/workflows/pages.yml

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 00000000..249b174f
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,59 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# Linting: xclip -sel c <.github/workflows/pages.yml # https://rhysd.github.io/actionlint/
+#
+name: Deploy site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["trunk"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    container: { image: 'ghcr.io/tim-janik/anklang-ci:jammy-latest' }
+    steps:
+      - name: Checkout Anklang
+        run: |
+          pwd && ls -al
+          rm -rf * .[^.]* ..?*
+          git clone --recurse-submodules https://github.com/tim-janik/anklang.git .
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - run: echo -e 'prefix=/\n CC=clang \n CXX=clang++ \n CLANG_TIDY=clang-tidy ' > config-defaults.mk
+      - run: make mkdocs -j`nproc`
+      - run: ls -al out/site/
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./out/site/
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

From 3c329a8585f3e8ac69305d718e10765754ff10e7 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 18 Jul 2024 23:31:44 +0200
Subject: [PATCH 09/25] doc/index.md: add mkdocs front page

* doc/Makefile.mk: add index.md to docs
* doc/mkdocs.yml: add index.md to nav

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk |  2 +-
 doc/index.md    | 11 +++++++++++
 doc/mkdocs.yml  |  1 +
 3 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 doc/index.md

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 727077b1..ccdbb46b 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -253,7 +253,7 @@ doc/all: $(doc/install.files)
 
 
 # == mkdocs ==
-doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters)
+doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters) doc/index.md
 $>/site/search/search_index.js: # $>/mkdocs/anklang-cxx.pdf $>/mkdocs/anklang-cxx.html
 $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 00000000..41418535
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,11 @@
+**Anklang**
+
+
+
+## Anklang: Craft Your Audio, Live and Free
+
+Join us in collaborating on Anklang, an experimental, digital audio workstation for live music composition and audio synthesis.
+Join the journey, contribute, and help us improve it.
+
+[Quick Start](https://github.com/tim-janik/anklang/releases)
+[Roadmap & Ideas](https://github.com/tim-janik/anklang/issues/52)
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index b91da7ab..51f941a0 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -31,6 +31,7 @@ plugins:
             RECURSIVE: True # recursive search in source directories
 
 nav:
+  - Home: index.md
   - Introduction: ch-intro.md
   - Installation: ch-install.md
   - Using Anklang:

From 7696c81ea978cf1ddc17ef7fe6322183cf9c90a0 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Fri, 19 Jul 2024 19:33:04 +0200
Subject: [PATCH 10/25] doc/mkdocs.yml: enable markdown_extensions

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/mkdocs.yml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index 51f941a0..bf7d7a51 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -104,3 +104,14 @@ extra:
   social:
     - icon: fontawesome/brands/mastodon
       link: https://social.tchncs.de/@timj
+
+markdown_extensions:
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg

From b5343e9c6c48a5b255914ed2b3f675555f9fde6b Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Fri, 19 Jul 2024 19:33:04 +0200
Subject: [PATCH 11/25] doc/tut-play.md: add "Tutorial 1: Starting to Play
 Notes"

* doc/Makefile.mk: add doc/tut-play.md to doc files
* doc/mkdocs.yml: add doc/tut-play.md to nav

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk |  2 +-
 doc/mkdocs.yml  |  2 ++
 doc/tut-play.md | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 doc/tut-play.md

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index ccdbb46b..91ae7a08 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -253,7 +253,7 @@ doc/all: $(doc/install.files)
 
 
 # == mkdocs ==
-doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters) doc/index.md
+doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters) doc/index.md doc/tut-play.md
 $>/site/search/search_index.js: # $>/mkdocs/anklang-cxx.pdf $>/mkdocs/anklang-cxx.html
 $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index bf7d7a51..efc35c6b 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -34,6 +34,8 @@ nav:
   - Home: index.md
   - Introduction: ch-intro.md
   - Installation: ch-install.md
+  - Tutorials:
+    - "Tutorial 1: Starting to Play Notes": tut-play.md
   - Using Anklang:
     - Anklang Overview: ch-editing.md
     - User Interface:
diff --git a/doc/tut-play.md b/doc/tut-play.md
new file mode 100644
index 00000000..041959fe
--- /dev/null
+++ b/doc/tut-play.md
@@ -0,0 +1,38 @@
+## Tutorial 1: Starting to Play Notes
+
+**Starting to Play Notes with Anklang**
+
+Welcome to Anklang, an open-source digital audio workstation for live music composition and audio synthesis.
+This tutorial will guide you through the basics of creating a new project and adding your first sounds.
+
+### Step 1: Create a New Project
+
+To start, navigate to the ++"🖿"++ "File" menu and select ++"New Project"++. This will create a fresh canvas for your audio creation.
+
+### Step 2: Add a Track
+
+To see the track menu, right-click into the track area, e.g. on the "Master" track and select ++"Add Track"++ to create a new track for your project. This will be the foundation for your audio composition.
+
+### Step 3: Add a Device
+
+In the lower left corner of the window, click the :material-equalizer: "Show Device Stack" icon. This will display the device stack for your track. Click the ++"\+"++ menu icon to create a new ++"BlepSynth"++ device in the track. BlepSynth is a built-in synthesizer that will generate sound for your track.
+
+### Step 4: Access the Piano Roll Editor
+
+In the lower left corner, next to the "Show Device Stack" icon, click the :musical_score: "Show Piano Roll Editor" icon. This will open the piano roll editor, where you can create and arrange notes for your track. You can also use the ++"^"++ hotkey to toggle between the "Show Device Stack" and "Show Piano Roll Editor" modes, depending on what you need to work on.
+
+### Step 5: Draw Notes
+
+In the piano roll editor, click the piano roll tool menu and select ++"✎ Pen 3"++ or press the ++3++ key on your keyboard when inside the piano roll. This will allow you to draw notes directly onto the piano roll. Use mouse clicks to add notes to the current clip. Experiment with different pitches and durations to create your melody.
+
+### Step 6: Play Your Creation
+
+Click the ++"▶"++ playback button or press the ++"Space"++ bar to hear your composition come to life. The same button can be used to stop playback when you're done listening.
+
+### Step 7: Experiment with Sound
+
+Click the :material-equalizer: "Show Device Stack" icon again to return to the device stack. During playback, tweak the knobs of the BlepSynth device to explore different sounds and timbres. Adjust the parameters to shape your audio and create unique textures.
+
+That's it! You've just started creating music with Anklang. Feel free to explore the interface, add more tracks, devices, and clips to develop your project further. If you encounter any issues or have ideas for improvement, please don't hesitate to [report them](https://github.com/tim-janik/anklang/issues) or [join the discussions](https://github.com/tim-janik/anklang/discussions).
+
+Happy creating!

From 4a82ac00018cfeacc89011faaaee940ca84d09a7 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Fri, 19 Jul 2024 21:42:37 +0200
Subject: [PATCH 12/25] doc/how-audio.md: add "Howto Setup Audio (Linux)"

* doc/Makefile.mk: add doc/how-audio.md to doc files
* doc/mkdocs.yml: add doc/how-audio.md to nav

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk  |  2 +-
 doc/how-audio.md | 41 +++++++++++++++++++++++++++++++++++++++++
 doc/mkdocs.yml   |  2 ++
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 doc/how-audio.md

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 91ae7a08..e9a08255 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -253,7 +253,7 @@ doc/all: $(doc/install.files)
 
 
 # == mkdocs ==
-doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters) doc/index.md doc/tut-play.md
+doc/mkdocs.mdlist ::= $(doc/manual-chapters) $(doc/internals-chapters) doc/index.md doc/tut-play.md doc/how-audio.md
 $>/site/search/search_index.js: # $>/mkdocs/anklang-cxx.pdf $>/mkdocs/anklang-cxx.html
 $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
diff --git a/doc/how-audio.md b/doc/how-audio.md
new file mode 100644
index 00000000..73019654
--- /dev/null
+++ b/doc/how-audio.md
@@ -0,0 +1,41 @@
+# Howto: Setting Up Audio Devices in Anklang on Linux
+
+Anklang relies on a properly configured audio system to function correctly.
+This guide will walk you through the steps to ensure your audio devices are set up and working with Anklang on Linux.
+
+### Step 1: Verify Audio Device Drivers
+
+Most Linux systems come with ALSA (Advanced Linux Sound Architecture) device drivers for audio devices.
+Additionally, they usually run either [Pulseaudio](https://wiki.archlinux.org/title/PulseAudio) or [Pipewire](https://docs.pipewire.org/) as their sound system.
+Make sure your audio devices are properly detected and configured on your system.
+You can do this by:
+
+* Configuring audio devices via GNOME ++"Settings"++ → ++"🎵 Sound"++ (if you're using GNOME)
+* Running [`pavucontrol`(1)](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Users/Troubleshooting/#baselinetest) from the terminal to adjust audio settings
+
+### Step 2: Adjust Audio Device Volume and Microphone Sensitivity
+
+Use [`alsamixer`(1)](https://man.archlinux.org/man/alsamixer.1) from the terminal to adjust audio device volume and microphone sensitivity:
+
+* Press ++"F6"++ to select the sound card
+* Press ++"F5"++ to display all channels
+* Use cursor keys to navigate and adjust volume
+* Press ++"M"++ to mute/unmute channels
+
+### Step 3: Configure Anklang Audio Preferences
+
+Once your audio devices are confirmed to work correctly, start Anklang and open the ++"🖿"++ "File" menu. Select ++"Preferences"++ (or press ++"Ctrl-,"++) to access the preferences dialog. All detected devices and some special entries are in the  the "PCM driver" menu:
+
+* ++"PulseAudio Sound Server"++ or a similar entry will appear if a user space sound system is detected.
+* ++"Null PCM Driver"++ will simulate an audio device that cannot be listened to (useful for testing or development)
+* ++"Automatic Driver Selection"++ will first look for a running user space sound system like PulseAudio/Pipewire and route sound through it. If that's not available, the first non-busy sound device is automatically selected (USB and onboard devices being preferred over HDMI devices)
+* Individual devices can also be selected directly from the menu
+
+### Step 4: Select and Test Your Audio Device
+
+Choose your desired audio device from the "PCM driver" drop-down menu. Changing the audio device selection has an instant effect. To test, load a (demo) song and confirm playback works through the selected device. If you encounter issues, ensure your audio devices are properly configured in your Linux system (Step 1 and 2).
+
+By following these steps, you should be able to successfully set up your audio devices in Anklang on Linux. If you still encounter problems or have questions, please don't hesitate to
+[report them](https://github.com/tim-janik/anklang/issues) or [join the discussions](https://github.com/tim-janik/anklang/discussions).
+
+Happy creating with Anklang!
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index efc35c6b..ed633fd0 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -36,6 +36,8 @@ nav:
   - Installation: ch-install.md
   - Tutorials:
     - "Tutorial 1: Starting to Play Notes": tut-play.md
+  - Howtos:
+    - "Howto: Setting Up Audio (Linux)": how-audio.md
   - Using Anklang:
     - Anklang Overview: ch-editing.md
     - User Interface:

From 3c924728ef319e0b1eae1c238d48b89c464f189a Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Fri, 19 Jul 2024 23:44:38 +0200
Subject: [PATCH 13/25] doc/mkdocs.yml: use new nav structure

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/mkdocs.yml | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index ed633fd0..1a2783c3 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -32,34 +32,34 @@ plugins:
 
 nav:
   - Home: index.md
-  - Introduction: ch-intro.md
-  - Installation: ch-install.md
-  - Tutorials:
+  - "Get Started: Intro & Tutorials":
+    - Introduction: ch-intro.md
+    - Installation: ch-install.md
+    - Anklang Overview: ch-editing.md
     - "Tutorial 1: Starting to Play Notes": tut-play.md
-  - Howtos:
+  - "Howto Guides":
     - "Howto: Setting Up Audio (Linux)": how-audio.md
-  - Using Anklang:
-    - Anklang Overview: ch-editing.md
-    - User Interface:
+  - "Reference":
+    - "ANKLANG(1) Manual Page": ch-man-pages.md
+    - "User Interface":
       - Clip-List: cliplist.md
       - Piano-Ctrl: piano-ctrl.md
       - Piano-Roll: pianoroll.md
-    - Manual Pages: ch-man-pages.md
-  - Development:
+    - JS Scripting: scripting-docs.md
+    - "Anklang C++ API":
+      - 'C++ Class-Tree':       class-tree.md
+      - 'C++ API Links':        AnklangCxx/links.md
+      - 'Class List':           AnklangCxx/annotated.md
+      - 'Class Members':        AnklangCxx/class_members.md
+      - 'Namespace List':       AnklangCxx/namespaces.md
+      - 'Namespace Members':    AnklangCxx/namespace_members.md
+      - 'Files':                AnklangCxx/files.md
+  - "Design & Development":
     - Development Overview: ch-development.md
     - UI Development:
-      - JS Scripting: scripting-docs.md
       - Web Components: ch-component.md
       - Component API: jsdocs.md
-    - AnklangCxx:
-      - C++ Class-Tree: class-tree.md
-      - 'Links': 'AnklangCxx/links.md'
-      - 'Class List': 'AnklangCxx/annotated.md'
-      - 'Class Members': 'AnklangCxx/class_members.md'
-      - 'Namespace List': 'AnklangCxx/namespaces.md'
-      - 'Namespace Members': 'AnklangCxx/namespace_members.md'
-      - 'Files': 'AnklangCxx/files.md'
-    - Internals:
+    - Implementation Details:
       - Making Releases: ch-releasing.md
       - Interpolation Notes: ch-appendix.md
 

From 8d0b292a13f2a7ce924335be5a15366ad159964d Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 25 Jul 2024 13:56:57 +0200
Subject: [PATCH 14/25] doc/mkdocs.yml: enableMathJAX rendering

* doc/ch-appendix.md: simplify for MathJAX
* doc/javascripts/mathjax.js: detect MathJAX blocks
* doc/Makefile.mk: allow extra Javascript

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk           |   1 +
 doc/ch-appendix.md        | 119 +++++++++++++++++---------------------
 doc/javascript/mathjax.js |  20 +++++++
 doc/mkdocs.yml            |  15 ++++-
 4 files changed, 87 insertions(+), 68 deletions(-)
 create mode 100644 doc/javascript/mathjax.js

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index e9a08255..d42daf84 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -259,6 +259,7 @@ $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
 	$Q rm -rf $>/site/
 	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
+	$Q cp -r doc/javascript $>/mkdocs/
 	$Q ( cd $> && mkdocs build )
 mkdocs:
 	rm -rf $>/mkdocs/
diff --git a/doc/ch-appendix.md b/doc/ch-appendix.md
index 7648c36e..2786100a 100644
--- a/doc/ch-appendix.md
+++ b/doc/ch-appendix.md
@@ -1,124 +1,115 @@
-\appendix
-
 # Appendix
 
-&nbsp;
-
 ## One-dimensional Cubic Interpolation
 
-\def\V#1{V_{#1}}
-
-\def\W#1{W_{#1}}
-
-\def\w#1{w_{#1}}
-
-With four sample values $\V0$, $\V1$, $\V2$ and $\V3$, cubic interpolation approximates
-the curve segment connecting $\V1$ and $\V2$, by using the beginning and ending
+With four sample values $V_0$, $V_1$, $V_2$ and $V_3$, cubic interpolation approximates
+the curve segment connecting $V_1$ and $V_2$, by using the beginning and ending
 slope, the curvature and the rate of curvature change to construct a cubic
 polynomial.
 
 
 The cubic polynomial starts out as:
 
-(@a)	$f(x) = \w3 x^3 + \w2 x^2 + \w1 x + \w0$
+* a)	$f(x) = w_3 x^3 + w_2 x^2 + w_1 x + w_0$
 
 Where $0 <= x <= 1$, specifying the sample value of the curve segment between
-$\V1$ and $\V2$ to obtain.
+$V_1$ and $V_2$ to obtain.
 
-To calculate the coefficients $\w0,…,\w3$, we set out the following conditions:
+To calculate the coefficients $w_0…w_3$, we set out the following conditions:
 
-(@b)	$f(0)  = \V1$
-(@c)	$f(1)  = \V2$
-(@d)	$f'(0) = \V1'$
-(@e)	$f'(1) = \V2'$
+* b)	$f(0)  = V_1$
+* c)	$f(1)  = V_2$
+* d)	$f'(0) = V_1'$
+* e)	$f'(1) = V_2'$
 
-We obtain $\V1'$ and $\V2'$ from the respecting slope triangles:
+We obtain $V_1'$ and $V_2'$ from the respecting slope triangles:
 
-(@f)	$\V1' = \frac {\V2 - \V0} {2}$
-(@g)	$\V2' = \frac {\V3 - \V1} {2}$
+* f)	$V_1' = \frac {V_2 - V_0} {2}$
+* g)	$V_2' = \frac {V_3 - V_1} {2}$
 
-With (@f) →  (@d) and (@g) →  (@e) we get:
+With (f)→(d) and (g)→(e) we get:
 
-(@h)	$f'(0) = \frac {\V2 - \V0} {2}$
-(@i)	$f'(1) = \frac {\V3 - \V1} {2}$
+* h)	$f'(0) = \frac {V_2 - V_0} {2}$
+* i)	$f'(1) = \frac {V_3 - V_1} {2}$
 
 The derivation of $f(x)$ is:
 
-(@j)	$f'(x)  = 3 \w3 x^2 + 2 \w2 x + \w1$
+* j)	$f'(x)  = 3 w_3 x^2 + 2 w_2 x + w_1$
+
+From $x=0$ →(a), i.e. (b), we obtain $w_0$ and from $x=0$ →(j),
+i.e. (h), we obtain $w_1$. With $w_0$ and $w_1$ we can solve the
+linear equation system formed by (c)→(a) and (e)→(j)
+to obtain $w_2$ and $w_3$.
 
-From $x=0$ → (@a), i.e. (@b), we obtain $\w0$ and from $x=0$ →  (@j),
-i.e. (@h), we obtain $\w1$. With $\w0$ and $\w1$ we can solve the
-linear equation system formed by (@c) →  (@a) and (@e) →  (@j)
-to obtain $\w2$ and $\w3$.
+$(c)→(a):	 	w_3 +   w_2 + \frac {V_2 - V_0} {2} + V_1 = V_2$
 
-(@c_a_)	  (@c) →  (@a):	  	$\w3 +   \w2 + \frac {\V2 - \V0} {2} + \V1 = \V2$
-(@e_j_)	  (@e) →  (@j):	  	$3 \w3 + 2 \w2 + \frac {\V2 - \V0} {2}    = \frac {\V3 - \V1} {2}$
+$(e)→(j):	 	3 w_3 + 2 w_2 + \frac {V_2 - V_0} {2}    = \frac {V_3 - V_1} {2}$
 
 With the resulting coefficients:
 
 $$
 \begin{aligned}
-    \w0 &= \V1 &                                        &(initial\:value)           \\
-    \w1 &= \frac{\V2 - \V0} {2} &                       &(initial\:slope)           \\
-    \w2 &= \frac{-\V3 + 4 \V2 - 5 \V1 + 2 \V0} {2} &    &(initial\:curvature)       \\
-    \w3 &= \frac{\V3 - 3 \V2 + 3 \V1 - \V0} {2} &       &(rate\:change\:of\:curvature)
+    w_0 &= V_1 &                                        &(initial\:value)           \\
+    w_1 &= \frac{V_2 - V_0} {2} &                       &(initial\:slope)           \\
+    w_2 &= \frac{-V_3 + 4 V_2 - 5 V_1 + 2 V_0} {2} &    &(initial\:curvature)       \\
+    w_3 &= \frac{V_3 - 3 V_2 + 3 V_1 - V_0} {2} &       &(rate\:change\:of\:curvature)
 \end{aligned}
 $$
 
-Reformulating (@a) to involve just multiplications and additions (eliminating power), we get:
+Reformulating (a) to involve just multiplications and additions (eliminating power), we get:
 
-(@k)	$f(x) = ((\w3 x + \w2) x + \w1) x + \w0$
+* k)	$f(x) = ((w_3 x + w_2) x + w_1) x + w_0$
 
-Based on $\V0,…,\V3$, $\w0,…,\w3$ and (@k), we can now approximate all values of the
-curve segment between $\V1$ and $\V2$.
+Based on $V_0…V_3$, $w_0…w_3$ and (k), we can now approximate all values of the
+curve segment between $V_1$ and $V_2$.
 
 However, for practical resampling applications where only a specific
 precision is required, the number of points we need out of the curve
 segment can be reduced to a finite amount.
 Lets assume we require $n$ equally spread values of the curve segment,
-then we can precalculate $n$ sets of $\W{0,…,3}[i]$, $i=[0,…,n]$, coefficients
+then we can precalculate $n$ sets of $W_{0…3}[i]$, $i=[0…n]$, coefficients
 to speed up the resampling calculation, trading memory for
-computational performance. With $\w{0,…,3}$ in (@a):
+computational performance. With $w_{0…3}$ in (a):
 
 $$
 \begin{alignedat} {2}
-	f(x) \  &= &   \frac{\V3 - 3 \V2 + 3 \V1 - \V0} 2 x^3 \  +	& \\
-		    &  & \frac{-\V3 + 4 \V2 - 5 \V1 + 2 \V0} 2 x^2 \ +	& \\
-		    &  &                     \frac{\V2 - \V0} 2 x \  +	& \\
-		    &  &                                   V1   \ \ 	&
+	f(x) \  &= &   \frac{V_3 - 3 V_2 + 3 V_1 - V_0} 2 x^3 \  +	& \\
+		    &  & \frac{-V_3 + 4 V_2 - 5 V_1 + 2 V_0} 2 x^2 \ +	& \\
+		    &  &                     \frac{V_2 - V_0} 2 x \  +	& \\
+		    &  &                                   V1 \ \ \ \ 	&
 \end{alignedat}
 $$
 
-sorted for $\V0,…,\V4$, we have:
+sorted for $V_0…V_4$, we have:
 
-(@l) $$\begin{aligned}
- f(x) \  = \  & \V3 \  (0.5 x^3 - 0.5 x^2) \  +		& \\
-	          & \V2 \  (-1.5 x^3 + 2 x^2 + 0.5 x) \  +	& \\
-			  & \V1 \  (1.5 x^3 - 2.5 x^2 + 1) \  +	& \\
-			  & \V0 \  (-0.5 x^3 + x^2 - 0.5 x)		&
-\end{aligned}$$
+* l) $\begin{aligned}
+ f(x) \  = \  & V_3 \  (0.5 x^3 - 0.5 x^2) \  +		& \\
+	          & V_2 \  (-1.5 x^3 + 2 x^2 + 0.5 x) \  +	& \\
+			  & V_1 \  (1.5 x^3 - 2.5 x^2 + 1) \  +	& \\
+			  & V_0 \  (-0.5 x^3 + x^2 - 0.5 x)		&
+\end{aligned}$
 
-With (@l) we can solve $f(x)$ for all $x = \frac i n$, where $i = [0, 1, 2, …, n]$ by
+With (l) we can solve $f(x)$ for all $x = \frac i n$, where $i = [0, 1, 2, …, n]$ by
 substituting $g(i) = f(\frac i n)$ with
 
-(@m)	$g(i) = \V3 \W3[i] + \V2 \W2[i] + \V1 \W1[i] + \V0 \W0[i]$
+* m)	$g(i) = V_3 W_3[i] + V_2 W_2[i] + V_1 W_1[i] + V_0 W_0[i]$
 
-and using $n$ precalculated coefficients $\W{0,…,3}$ according to:
+and using $n$ precalculated coefficients $W_{0…3}$ according to:
 
 $$
 \begin{alignedat}{4}
         m      &= \frac i n                                \\
-        \W3[i] &=&  0.5 m^3 & - & 0.5 m^2 &         &      \\
-        \W2[i] &=& -1.5 m^3 & + &   2 m^2 & + 0.5 m &      \\
-        \W1[i] &=&  1.5 m^3 & - & 2.5 m^2 &         & + 1  \\
-        \W0[i] &=& -0.5 m^3 & + &     m^2 & - 0.5 m &
+        W_3[i] &=&  0.5 m^3 & - & 0.5 m^2 &         &      \\
+        W_2[i] &=& -1.5 m^3 & + &   2 m^2 & + 0.5 m &      \\
+        W_1[i] &=&  1.5 m^3 & - & 2.5 m^2 &         & + 1  \\
+        W_0[i] &=& -0.5 m^3 & + &     m^2 & - 0.5 m &
 \end{alignedat}
 $$
 
-We now need to setup $\W{0,…,3}[0,…,n]$ only once, and are then able to
+We now need to setup $W_{0…3}[0…n]$ only once, and are then able to
 obtain up to $n$ approximation values of the curve segment between
-$\V1$ and $\V2$ with four multiplications and three additions using (@m),
-given $\V0,…,\V3$.
+$V_1$ and $V_2$ with four multiplications and three additions using (m),
+given $V_0…V_3$.
 
 
 ## Modifier Keys
@@ -141,7 +132,6 @@ none             →  copy            (else move (else link))
 
 Regarding selections, the following email provides a short summary:
 
-> ~~~
 > From: Tim Janik <timj@gtk.org>
 > To: Hacking Gnomes <Gnome-Hackers@gnome.org>
 > Subject: modifiers for the second selection
@@ -201,4 +191,3 @@ Regarding selections, the following email provides a short summary:
 >
 > ---
 > ciaoTJ
-> ~~~
diff --git a/doc/javascript/mathjax.js b/doc/javascript/mathjax.js
new file mode 100644
index 00000000..cd97bc52
--- /dev/null
+++ b/doc/javascript/mathjax.js
@@ -0,0 +1,20 @@
+
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe (() => { 
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+});
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index 1a2783c3..bcf5e8c4 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -3,9 +3,6 @@ site_url: https://mydomain.org/mysite
 site_dir: site
 docs_dir: mkdocs
 
-# docker run --rm -it -v${PWD}:/docs -p 127.0.0.1:8001:8000 ghcr.io/tim-janik/anklang-ci:mkdocs-latest
-# docker run --rm -it -v${PWD}:/docs --entrypoint '' squidfunk/mkdocs-material sudo chown 1000:1000 -R /docs/.
-
 repo_url: https://github.com/tim-janik/anklang
 repo_name: Anklang.git
 
@@ -30,6 +27,12 @@ plugins:
             FILE_PATTERNS: "*.c .h *.cc *.hh *.js *.md *.dox" # specify file patterns to filter out
             RECURSIVE: True # recursive search in source directories
 
+extra_javascript:
+  - javascript/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+
+
+
 nav:
   - Home: index.md
   - "Get Started: Intro & Tutorials":
@@ -110,6 +113,8 @@ extra:
       link: https://social.tchncs.de/@timj
 
 markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
   - pymdownx.critic
   - pymdownx.caret
   - pymdownx.keys
@@ -119,3 +124,7 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+
+# docker run --rm -it -v${PWD}:/docs -p 127.0.0.1:8001:8000 ghcr.io/tim-janik/anklang-ci:mkdocs-latest
+# docker run --rm -it -v${PWD}:/docs --entrypoint '' squidfunk/mkdocs-material sudo chown 1000:1000 -R /docs/.

From e0dda7e04615a4a7e32f0b825b02f9dcd5980e34 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 25 Jul 2024 16:17:12 +0200
Subject: [PATCH 15/25] doc/mkdocs.yml: trim Doxygen generation of mkdoxy

* doc/Makefile.mk: remove useless listing of anonymous namespaces

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk |  3 +++
 doc/mkdocs.yml  | 37 +++++++++++++++++++++++++++----------
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index d42daf84..27f28681 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -261,6 +261,9 @@ $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
 	$Q cp -r doc/javascript $>/mkdocs/
 	$Q ( cd $> && mkdocs build )
+	$Q # remove useless listing of anonymous namespaces
+	$Q sed 's|<li><strong>namespace</strong> *<a[^>]*><strong>@[0-9]+</strong></a> *</li>||' \
+		-r -i $>/site/AnklangCxx/namespaces.html $>/site/AnklangCxx/annotated.html
 mkdocs:
 	rm -rf $>/mkdocs/
 	$(MAKE) $>/site/search/search_index.js
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index bcf5e8c4..005d835e 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -1,11 +1,9 @@
 site_name: Anklang Documentation
 site_url: https://mydomain.org/mysite
-site_dir: site
-docs_dir: mkdocs
-
 repo_url: https://github.com/tim-janik/anklang
 repo_name: Anklang.git
-
+docs_dir: mkdocs
+site_dir: site
 
 plugins:
   - search
@@ -20,12 +18,31 @@ plugins:
 
   - mkdoxy:
       projects:
-        AnklangCxx: # name of project must be alphanumeric + numbers (without spaces)
-          src-dirs: ../ase/ ../devices/  # path to source code (support multiple paths separated by space) => INPUT
-          full-doc: True # if you want to generate full documentation
-          doxy-cfg: # standard doxygen configuration (key: value)
-            FILE_PATTERNS: "*.c .h *.cc *.hh *.js *.md *.dox" # specify file patterns to filter out
-            RECURSIVE: True # recursive search in source directories
+        AnklangCxx:
+          src-dirs: ../ase/ ../devices/
+          doxy-cfg:
+            FILE_PATTERNS: "*.c .h *.cc *.hh *.js *.md *.dox"
+            INTERNAL_DOCS: YES
+            RECURSIVE: NO
+            EXTRACT_LOCAL_CLASSES: NO
+            HIDE_UNDOC_MEMBERS: YES
+            HIDE_UNDOC_CLASSES: YES
+            HIDE_FRIEND_COMPOUNDS: YES
+            HIDE_COMPOUND_REFERENCE: YES
+            SHOW_INCLUDE_FILES: NO
+            INLINE_INFO: NO
+            SHOW_USED_FILES: NO
+            VERBATIM_HEADERS: NO
+            XML_PROGRAMLISTING: NO
+            COLLABORATION_GRAPH: NO
+            GROUP_GRAPHS: NO
+            INCLUDE_GRAPH: NO
+            INCLUDED_BY_GRAPH: NO
+            GRAPHICAL_HIERARCHY: NO
+            DIRECTORY_GRAPH: NO
+            DOT_IMAGE_FORMAT: svg
+            EXTRACT_ALL: NO
+            EXTRACT_ANON_NSPACES: NO
 
 extra_javascript:
   - javascript/mathjax.js

From ee9217b05a69c635f24095eb3e6b1793e03e2e42 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 02:57:58 +0200
Subject: [PATCH 16/25] doc/Makefile.mk: add comments

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 27f28681..3d876b95 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -258,12 +258,15 @@ $>/site/search/search_index.js: # $>/mkdocs/anklang-cxx.pdf $>/mkdocs/anklang-cx
 $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	@$(QECHO) RUN mkdocs
 	$Q rm -rf $>/site/
+	$Q # prepare mkdocs inputs
 	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
 	$Q cp -r doc/javascript $>/mkdocs/
-	$Q ( cd $> && mkdocs build )
+	$Q # mkdocs build to $>/site/
+	$Q cd $> && mkdocs build
 	$Q # remove useless listing of anonymous namespaces
 	$Q sed 's|<li><strong>namespace</strong> *<a[^>]*><strong>@[0-9]+</strong></a> *</li>||' \
 		-r -i $>/site/AnklangCxx/namespaces.html $>/site/AnklangCxx/annotated.html
+	$Q # TODO: Section on Piano-Ctrl needs SVG tools icons
 mkdocs:
 	rm -rf $>/mkdocs/
 	$(MAKE) $>/site/search/search_index.js

From 0fa406a2bc0060e12d582236447de64643a6663a Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 04:09:01 +0200
Subject: [PATCH 17/25] doc/Makefile.mk: use new tab for external links

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 3d876b95..6a2b8764 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -266,6 +266,9 @@ $>/site/search/search_index.js: doc/mkdocs.yml $(doc/mkdocs.mdlist)	| $>/mkdocs/
 	$Q # remove useless listing of anonymous namespaces
 	$Q sed 's|<li><strong>namespace</strong> *<a[^>]*><strong>@[0-9]+</strong></a> *</li>||' \
 		-r -i $>/site/AnklangCxx/namespaces.html $>/site/AnklangCxx/annotated.html
+	$Q # use new tab for external links
+	$Q sed -r '/http[^ ]*github.io\/anklang/!s|<a (href="https?://[^">]+")>|<a \1 target="_blank">|g' \
+		-i out/site/*.html
 	$Q # TODO: Section on Piano-Ctrl needs SVG tools icons
 mkdocs:
 	rm -rf $>/mkdocs/

From 2116b0023ff7dc434adac9b95b8ae119280f2c06 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 02:57:58 +0200
Subject: [PATCH 18/25] doc/mkdocs.yml: add comment about future feature

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/mkdocs.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index 005d835e..f5af3400 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -8,6 +8,9 @@ site_dir: site
 plugins:
   - search
   - privacy
+    # https://squidfunk.github.io/mkdocs-material/plugins/privacy/?h=blank#config.links_attr_map
+    # links_attr_map:
+    #   target: _blank
   - offline
   - tags
   #- blog

From d4e1306fab74fb87b0994eaf489b81b5446b6a81 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 25 Jul 2024 11:58:31 +0200
Subject: [PATCH 19/25] doc/index.md: merge intro and install info

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/index.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 89 insertions(+), 5 deletions(-)

diff --git a/doc/index.md b/doc/index.md
index 41418535..e4542bac 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,11 +1,95 @@
-**Anklang**
-
-
+Welcome to Anklang, a free and open-source digital audio synthesizer and music creation software.
 
 ## Anklang: Craft Your Audio, Live and Free
 
+Anklang is a music synthesis and composition program designed to help you create and shape your sounds,
+released under the Mozilla Public License 2.0 ([MPL-2.0 summary](https://choosealicense.com/licenses/mpl-2.0/)).
 Join us in collaborating on Anklang, an experimental, digital audio workstation for live music composition and audio synthesis.
 Join the journey, contribute, and help us improve it.
 
-[Quick Start](https://github.com/tim-janik/anklang/releases)
-[Roadmap & Ideas](https://github.com/tim-janik/anklang/issues/52)
+## Getting Started
+
+Getting started with Anklang is easy.
+Begin by downloading the latest version from our GitHub release page.
+You can choose from a variety of binary packages for GNU/Linux, including AppImage and Debian packages.
+
+[Anklang Releases · tim-janik/anklang](https://github.com/tim-janik/anklang/releases/)
+
+If you want to try out the latest features and bug fixes, you can use our nightly release builds.
+Keep in mind that these builds might be less stable than the regular release builds.
+
+### Installing Anklang
+
+#### Using the AppImage Package
+
+1. Download the AppImage package from our GitHub release page.
+2. Once downloaded, open the file manager and navigate to the `Downloads` folder.
+3. Right-click on the AppImage file and select `Permissions` → `Execute` → `[x] Allow executing file as program`.
+4. After that, the AppImage can be started directly from the file manager.
+
+Alternatively, you can use the command line:
+
+```sh
+# Enable execution of the AppImage
+chmod +x ~/Downloads/anklang-[VERSION]-x64.AppImage
+# Run Anklang via self contained AppImage
+~/Downloads/anklang-[VERSION]-x64.AppImage
+```
+
+#### Using the Debian Package
+
+1. Install the Debian package using tools like `gnome-software` or via the command line:
+
+```sh
+# Install Anklang system wide
+sudo apt install Downloads/anklang_[VERSION]_amd64.deb
+# Start via system PATH
+anklang
+```
+
+### First Run and Driver Setup
+
+Once Anklang is started, drivers and other settings can be adjusted in the `Preferences`.
+The `File Menu` in the upper left includes an item to open the `Preferences` dialog.
+
+Depending on your system, a number of PCM and MIDI devices can be selected here.
+The `PulseAudio Sound Server` or `Automatic driver selection` should work on most systems out of the box.
+
+For systems with Jackd installed, the Jackd sound server needs to be running first:
+
+```sh
+# Suspend PulseAudio and run Jackd instead
+# -r avoids realtime mode which requires special rights
+# -d alsa uses the Jackd ALSA backend
+pasuspender -- jackd -r -d alsa
+```
+
+The Jackd server should be running now, so in Anklang the "JACK Audio Device" can be selected.
+
+To verify Anklang does indeed use Jackd, the setup can be inspected as follows:
+
+```sh
+# List active Jack ports
+jack_lsp
+# The list should include 'AnklangSynthEngine'
+
+# Start GUI to control Jackd
+qjackctl
+# Click on the "Graph" button to show connections
+# The graph should include 'AnklangSynthEngine'
+```
+
+### Next Steps
+
+Now that you've installed and run Anklang for the first time, you can explore the various features and tutorials to help you get started with music synthesis and composition.
+
+Refer to the following documentation sections for more information on using Anklang,
+including tutorial material, Howto descriptions, Man pages, API reference, file formats and conventions,
+and development details.
+
+Contribute to Anklang by submitting pull requests or via the
+[Ideas & Roadmap Discussions](https://github.com/tim-janik/anklang/issues/52)
+in the Anklang issue tracker.
+
+
+Happy creating with Anklang!

From c9fbe310ce5d02f03db983914e12f8fcc675c804 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Thu, 25 Jul 2024 11:58:31 +0200
Subject: [PATCH 20/25] doc/*: remove old sections

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/Makefile.mk   |  3 --
 doc/ch-editing.md |  5 ----
 doc/ch-install.md | 75 -----------------------------------------------
 doc/ch-intro.md   | 20 -------------
 doc/mkdocs.yml    |  3 --
 5 files changed, 106 deletions(-)
 delete mode 100644 doc/ch-editing.md
 delete mode 100644 doc/ch-install.md
 delete mode 100644 doc/ch-intro.md

diff --git a/doc/Makefile.mk b/doc/Makefile.mk
index 6a2b8764..a6a5c3d0 100644
--- a/doc/Makefile.mk
+++ b/doc/Makefile.mk
@@ -7,9 +7,6 @@ doc/all:
 
 # == doc/ files ==
 doc/manual-chapters ::= $(strip		\
-	doc/ch-intro.md			\
-	doc/ch-install.md		\
-	doc/ch-editing.md		\
 	$>/doc/b/cliplist.md		\
 	$>/doc/b/pianoroll.md		\
 	$>/doc/b/piano-ctrl.md		\
diff --git a/doc/ch-editing.md b/doc/ch-editing.md
deleted file mode 100644
index 24dd3db8..00000000
--- a/doc/ch-editing.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Using Anklang
-
-Anklang can display and allows editing of MIDI notes, events and tracks.
-
-
diff --git a/doc/ch-install.md b/doc/ch-install.md
deleted file mode 100644
index fe1c374f..00000000
--- a/doc/ch-install.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Program Installation
-
-## Download and Startup
-
-Ankang can be downloaded as binary package for GNU/Linux from
-its Github release page:
-
-https://github.com/tim-janik/anklang/releases/
-
-To test bleeding edge versions, "Nightly" builds are also available,
-but mileage may very with these. In particular stability or file format
-compatibility can be affected in the nightly versions.
-
-The Debian package (`.deb`) can be installed with tools like `gnome-software`
-or via the command line:
-
-```sh
-# Install Anklang system wide
-sudo apt install Downloads/anklang_[VERSION]_amd64.deb
-# Start via system PATH
-anklang
-```
-
-The AppImage package can be executed without an installation step.
-Once downloaded, it needs permissions for execution and can be run
-right away. This is done for instance as follow:
-
-- Once downloaded, open ~/Downloads/ for instance via web browser → 'Show in Folder'
-- Right click on the AppImage to open the file manager context menu
-- Select 'Permission' → 'Execute' → [x] Allow executing file as program
-- After that, the AppImage can be started directly from the file manager
-
-Of course, the same can also be done via the command line:
-
-```sh
-# Enable execution of the AppImage
-chmod +x ~/Downloads/anklang-[VERSION]-x64.AppImage
-# Run Anklang via self contained AppImage
-~/Downloads/anklang-[VERSION]-x64.AppImage
-```
-
-## Driver Setup
-
-Once Anklang is started, drivers and other settings can be adjusted
-in the Preferences. The 'File Menu' in the upper left includes an
-item to open the 'Preferences' dialog.
-
-Depending on the system, a number of PCM and MIDI devices can be selected
-here. The "PulseAudio Sound Server" or "Automatic driver selection" should
-work on most systems out of the box.
-On systems with Jackd installed, the Jackd sound server needs to be
-running first:
-
-```sh
-# Suspend PulseAudio and run Jackd instead
-# -r avoids realtime mode which requires special rights
-# -d alsa uses the Jackd ALSA backend
-pasuspender -- jackd -r -d alsa
-```
-
-The Jackd server should be running now, so in Anklang the
-"JACK Audio Device" can be selected.
-To verify Anklang does indeed use Jackd, the setup can be
-inspected as follows:
-
-```sh
-# List active Jack ports
-jack_lsp
-# The list should include 'AnklangSynthEngine'
-
-# Start GUI to control Jackd
-qjackctl
-# Click on the "Graph" button to show connections
-# The graph should include 'AnklangSynthEngine'
-```
diff --git a/doc/ch-intro.md b/doc/ch-intro.md
deleted file mode 100644
index ab55bf10..00000000
--- a/doc/ch-intro.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title:      The ANKLANG Manual
-author:     The Anklang Project <[anklang.testbit.eu](https://anklang.testbit.eu/)>
-abstract:   Manual about usage, installation, and scripting of the
-            Anklang digital synthesizer and music creation software.
-keywords:   Anklang, DAW, DSP, Audio Synthesis, Linux, ALSA, JavaScript, Scripting
----
-
-# The ANKLANG Manual
-
-This is the Anklang manual, Anklang is a music synthesis and composition program,
-released as Free Software under the
-[MPL-2.0](https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)).
-
-The manual is structured into sections covering tutorial material,
-Howto descriptions, Man pages, file formats and conventions,
-development details with related considerations and an API reference.
-
-It is written in Markdown and contributions are welcome, e.g. as pull requests
-or via the [Anklang issue tracker](https://github.com/tim-janik/anklang/issues/).
diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index f5af3400..d4caa47a 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -56,9 +56,6 @@ extra_javascript:
 nav:
   - Home: index.md
   - "Get Started: Intro & Tutorials":
-    - Introduction: ch-intro.md
-    - Installation: ch-install.md
-    - Anklang Overview: ch-editing.md
     - "Tutorial 1: Starting to Play Notes": tut-play.md
   - "Howto Guides":
     - "Howto: Setting Up Audio (Linux)": how-audio.md

From 7ffa106800a87a705d5dd788cc31132593a44346 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 02:57:58 +0200
Subject: [PATCH 21/25] doc/mkdocs.yml: fix site URL, cleanup, improve nav

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/mkdocs.yml | 36 +++++++++++++++---------------------
 1 file changed, 15 insertions(+), 21 deletions(-)

diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml
index d4caa47a..2933b3cd 100644
--- a/doc/mkdocs.yml
+++ b/doc/mkdocs.yml
@@ -1,9 +1,13 @@
+# This Source Code Form is licensed MPL-2.0: http://mozilla.org/MPL/2.0
+
+# https://www.mkdocs.org/getting-started/
 site_name: Anklang Documentation
-site_url: https://mydomain.org/mysite
+site_url: https://tim-janik.github.io/anklang
 repo_url: https://github.com/tim-janik/anklang
 repo_name: Anklang.git
 docs_dir: mkdocs
 site_dir: site
+copyright: Copyright &copy; 2024 Anklang Project
 
 plugins:
   - search
@@ -13,12 +17,7 @@ plugins:
     #   target: _blank
   - offline
   - tags
-  #- blog
-  #- git-revision-date-localized:
-  #    type: timeago
-  #    fallback_to_build_date: true
-  #    enable_creation_date: true
-
+  # https://mkdoxy.kubaandrysek.cz/
   - mkdoxy:
       projects:
         AnklangCxx:
@@ -46,20 +45,22 @@ plugins:
             DOT_IMAGE_FORMAT: svg
             EXTRACT_ALL: NO
             EXTRACT_ANON_NSPACES: NO
+  #- git-revision-date-localized:
+  #    type: timeago
+  #    fallback_to_build_date: true
+  #    enable_creation_date: true
 
 extra_javascript:
   - javascript/mathjax.js
   - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
 
-
-
 nav:
-  - Home: index.md
-  - "Get Started: Intro & Tutorials":
+  - "About Anklang": index.md
+  - "Introductionary Tutorials":
     - "Tutorial 1: Starting to Play Notes": tut-play.md
   - "Howto Guides":
     - "Howto: Setting Up Audio (Linux)": how-audio.md
-  - "Reference":
+  - "References":
     - "ANKLANG(1) Manual Page": ch-man-pages.md
     - "User Interface":
       - Clip-List: cliplist.md
@@ -83,9 +84,7 @@ nav:
       - Making Releases: ch-releasing.md
       - Interpolation Notes: ch-appendix.md
 
-# TODO: Piano-Ctrl lacks tools icons
-
-
+# https://squidfunk.github.io/mkdocs-material/getting-started/
 theme:
   name: material
   language: 'en'
@@ -101,7 +100,6 @@ theme:
     - navigation.sections
     #- navigation.expand
     - navigation.path
-
   # taken from https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#system-preference
   palette:
     - media: "(prefers-color-scheme)"
@@ -118,17 +116,13 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to dark mode
-
-
-
-copyright: Copyright &copy; 2024 Anklang Project
-
 extra:
   generator: false
   social:
     - icon: fontawesome/brands/mastodon
       link: https://social.tchncs.de/@timj
 
+# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/
 markdown_extensions:
   - pymdownx.arithmatex:
       generic: true

From e0b2c9b6d95376b901c011b17e09b85285ad891e Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 04:16:50 +0200
Subject: [PATCH 22/25] doc/copyright.ini: fix missing licenses

Signed-off-by: Tim Janik <timj@gnu.org>
---
 doc/copyright.ini | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/copyright.ini b/doc/copyright.ini
index 203b2179..85fe3367 100644
--- a/doc/copyright.ini
+++ b/doc/copyright.ini
@@ -33,8 +33,12 @@ files =
 	README.md
 	devices/blepsynth/TODO
 	doc/highlights.theme
+	doc/how-audio.md
+	doc/index.md
+	doc/javascript/mathjax.js
 	doc/jsdocrc.json
 	doc/template.diff
+	doc/tut-play.md
 	images/README.md
 	misc/anklang-mime.xml
 	package.json

From bc9240d816bbe7c0c7eb11dd3ba65a509fa47749 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 27 Jul 2024 04:14:09 +0200
Subject: [PATCH 23/25] .github/workflows/pages.yml: name workflow

Signed-off-by: Tim Janik <timj@gnu.org>
---
 .github/workflows/pages.yml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 249b174f..f937a6d7 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -1,8 +1,10 @@
-# Sample workflow for building and deploying a mdBook site to GitHub Pages
+# This Source Code Form is licensed MPL-2.0: http://mozilla.org/MPL/2.0
+#
+# Workflow for mkdocs building and deploying to GitHub Pages
 #
 # Linting: xclip -sel c <.github/workflows/pages.yml # https://rhysd.github.io/actionlint/
 #
-name: Deploy site to Pages
+name: Deploy mkdocs site to Pages
 
 on:
   # Runs on pushes targeting the default branch

From 3b0e166d3d1cf0383d0400c97dab3c6c2b59576e Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sat, 21 Sep 2024 01:27:48 +0200
Subject: [PATCH 24/25] misc/subdirs.mk: use $O or out/ as builddir if unset

Signed-off-by: Tim Janik <timj@gnu.org>
---
 misc/subdirs.mk | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/misc/subdirs.mk b/misc/subdirs.mk
index 8a951443..4752f015 100644
--- a/misc/subdirs.mk
+++ b/misc/subdirs.mk
@@ -9,8 +9,7 @@ misc/subdirs_mk/subdir_prefix ::= $(patsubst $(misc/subdirs_mk/topdir)/%,%, $(ab
 
 # Read default config, in particular $(builddir)
 -include $(misc/subdirs_mk/topdir)/config-defaults.mk
-builddir ?= $(O)
-builddir ?= out
+builddir ?= $(if $(O),$(O),out)
 
 # Fallback to 'make all' in topdir if MAKECMDGOALS is empty
 MAKECMDGOALS ?= all

From 895a0ae317b86f752894842eb8960f5539fce7b9 Mon Sep 17 00:00:00 2001
From: Tim Janik <timj@gnu.org>
Date: Sun, 4 Aug 2024 01:56:08 +0200
Subject: [PATCH 25/25] .gitignore: add OUTLINE.md

Signed-off-by: Tim Janik <timj@gnu.org>
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index c7a585bc..1a0d225f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@
 /.submodule-stamp
 /.vscode/
 /BACKLOG.md
+/OUTLINE.md
 /TAGS
 /bun.lockb
 /compile_commands.json