Merge branch 'mkdocs-build'

* Branch commit log:
  .gitignore: add OUTLINE.md
  misc/subdirs.mk: use $O or out/ as builddir if unset
  .github/workflows/pages.yml: name workflow
  doc/copyright.ini: fix missing licenses
  doc/mkdocs.yml: fix site URL, cleanup, improve nav
  doc/*: remove old sections
  doc/index.md: merge intro and install info
  doc/mkdocs.yml: add comment about future feature
  doc/Makefile.mk: use new tab for external links
  doc/Makefile.mk: add comments
  doc/mkdocs.yml: trim Doxygen generation of mkdoxy
	* doc/Makefile.mk: remove useless listing of anonymous namespaces
  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
  doc/mkdocs.yml: use new nav structure
  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
  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
  doc/mkdocs.yml: enable markdown_extensions
  doc/index.md: add mkdocs front page
	* doc/Makefile.mk: add index.md to docs
	* doc/mkdocs.yml: add index.md to nav
  .github/workflows/pages.yml: build docu with mkdocs and deploy pages
  doc/Makefile.mk: extend mkdocs, add pdf
  doc/Makefile.mk: add mkdocs rule
  doc/mkdocs.yml: build modernized docs with mkdocs, mkdoxy
  misc/Dockerfile.jammy: update build dependencies, add mkdocs
  ui/eslintrc.js: allow attrs w/o newlines
  package.json: update Vue, Electron, Lit and development dependencies
  package.json: add moxygen

Signed-off-by: Tim Janik <[email protected]>

Author: tim-janik

.github/workflows/pages.yml

@@ -0,0 +1,61 @@
+# 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 mkdocs 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

.gitignore

@@ -4,6 +4,7 @@
 /.submodule-stamp
 /.vscode/
 /BACKLOG.md
+/OUTLINE.md
 /TAGS
 /bun.lockb
 /compile_commands.json

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		\
@@ -250,3 +247,76 @@ 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) 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
+	$Q rm -rf $>/site/
+	$Q # prepare mkdocs inputs
+	$Q cp $< $>/mkdocs.yml && cp $(doc/mkdocs.mdlist) $>/mkdocs/
+	$Q cp -r doc/javascript $>/mkdocs/
+	$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 # 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/
+	$(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_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
+	LATEX_CMD_NAME         = xelatex
+	COMPACT_LATEX          = YES
+	LATEX_HIDE_INDICES     = YES
+endef
+export doc_doxygen_xmlcfg
+$>/doxygen/latex/refman.tex: doc/Makefile.mk
+	@$(QECHO) RUN doxygen
+	$Q cat > $>/Doxyfile  <<<$$doc_doxygen_xmlcfg
+	$Q rm -rf $>/doxygen/ && doxygen $>/Doxyfile
+$>/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
+

doc/ch-appendix.md

@@ -1,124 +1,115 @@
-\appendix
-
 # Appendix
 
- 
-
 ## 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 <[email protected]>
 > To: Hacking Gnomes <[email protected]>
 > Subject: modifiers for the second selection
@@ -201,4 +191,3 @@ Regarding selections, the following email provides a short summary:
 >
 > ---
 > ciaoTJ
-> ~~~