Document build system

.github/workflows/lit-prog.yaml

@@ -0,0 +1,69 @@
+name: Weave+publish, & tangle onto `master`
+
+on:
+  push:
+    branches: [ "doc" ]
+  workflow_dispatch:
+
+jobs:
+  tangle:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Noweb
+        run: sudo apt install noweb
+      - name: Checkout master branch
+        uses: actions/checkout@v4
+        with:
+          ref: master
+          path: master
+          token: ${{ secrets.PAT }}
+      - name: Tangle
+        run: notangle -RMakefile -t8 Makefile.nw >master/Makefile
+      - name: Push the modified Makefile
+        uses: EndBug/add-and-commit@v9
+        with:
+          cwd: master
+          add: Makefile
+          message: |
+            Update Makefile from `doc` branch
+
+            Built from commit $(git -C .. rev-parse HEAD)
+          default_author: user_info
+          pathspec_error_handling: exitAtEnd
+          push: true
+
+  weave:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Install Noweb
+        run: sudo apt install noweb texlive-latex-extra texlive-lang-english texlive-lang-french texlive-xetex
+      - name: Weave
+        run: |
+          ./weave.sh
+          mkdir _site
+          cp out/build-system.pdf _site
+      - name: Upload generated PDF
+        uses: actions/upload-pages-artifact@v3
+  publish:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: weave
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,2 @@
+/out/
+/Makefile.tex

README.md

@@ -0,0 +1,16 @@
+# gb-starter-kit documentation
+
+This branch of `gb-starter-kit` contains the build system's documentation.
+
+Partly as a fun (for myself) exercise, this was done using [literate programming]; in other words, the build system *itself* is extracted from its own documentation.
+This is why changes intended for the build system on the “official” branch (`master`) should be done here.
+(As a bonus, it should also help ensure that the documentation is never forgotten about!)
+
+The literate programming system in use here is [Noweb] (2.13 on my machine).
+This *does* mean that writing some LaTeX is required; [the LaTeX wikibook] offers introduction, help, and advice.
+
+As soon as changes are pushed to this branch, CI will automatically run `noweave` to update the PDF file published at https://eldred.fr/gb-starter-kit/build-system.pdf, and `notangle` to update the `master` branch.
+
+[literate programming]: https://en.wikipedia.org/wiki/Literate_programming
+[Noweb]: https://github.com/nrnrnr/noweb
+[the LaTeX wikibook]: https://en.wikibooks.org/wiki/LaTeX

build-system.tex

@@ -0,0 +1,35 @@
+
+\documentclass[12pt,a4paper]{article}
+\usepackage[french,english]{babel}
+\usepackage{alertmessage}
+\usepackage{twemojis}
+\usepackage[bottom]{footmisc}
+\usepackage[margin=1in]{geometry}
+\usepackage{noweb}
+\usepackage{pygmentex}
+\usepackage{tcolorbox}
+\usepackage[colorlinks=true,pdftitle=gb-starter-kit]{hyperref}
+
+\def\nwbegincode#1{%
+  \vskip5pt\noindent}
+\def\nwendcode{}
+\let\nwdocspar=\smallbreak
+
+\author{\href{https://eldred.fr}{Eldred \bsc{Habert}}\thanks{Contributions by JL2210, Damian Yerrick, Evie, and Starleaf.}}
+\title{\texttt{gb-starter-kit} build system breakdown}
+
+\begin{document}
+\maketitle
+\renewcommand{\abstractname}{Summary and Intended Audience}
+\begin{abstract}
+	This document is useful for people who wish to understand why gb-starter-kit's Makefile (build script) is written in the way that it is, why and how it does what it does, and perhaps also gain some insight into Makefile good practices.
+
+	It does contain a fairly quick primer on what a Makefile \emph{is}, so it is intended to be suitable to people who have never touched a Makefile before.
+\end{abstract}
+\tableofcontents
+
+\pagebreak
+
+\input{Makefile}
+
+\end{document}

filter.awk

@@ -0,0 +1,28 @@
+#!/usr/bin/awk -f
+BEGIN {
+	in_code = 0
+}
+
+/nwendcode/ {
+	in_code = 0
+	print "\\end{pygmented}"
+}
+
+in_code {
+	gsub(/\\\{/, "{")
+	gsub(/\\\}/, "}")
+	gsub(/\\\\/, "\\")
+	if (/^\\LA/) {
+		$0 = "|" $0 "|"
+	}
+}
+
+/nwbegincode/ {
+	in_code = 1
+	$0 = $0 "\\begin{pygmented}[lang=makefile,boxing method=tcolorbox]"
+	if (/Makefile/) { # `escapeinside` breaks some of the highlighting, for some reason...
+		sub(/\]/, ",escapeinside=||]")
+	}
+}
+
+{ print }

weave.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -euo pipefail
+
+mkdir -p out
+noweave -x -n -t4 Makefile.nw | ./filter.awk >Makefile.tex
+xelatex -synctex=1 -interaction=nonstopmode -output-directory=out build-system.tex
+pygmentex out/build-system.snippets
+xelatex -synctex=1 -interaction=nonstopmode -output-directory=out build-system.tex
+xelatex -synctex=1 -interaction=nonstopmode -output-directory=out build-system.tex