Table of Contents

And a script to maintain the readme:
  - updating the ToC
  - updating links relative to the branch name

Makefile

@@ -35,3 +35,7 @@ endef
 shell:
 	$(docker/build)
 	docker run -it -v $$PWD:$$PWD -w $$PWD --privileged $$($(docker/build) -q)
+
+.PHONY: README.md
+README.md:
+	./scripts/update-readme.sh

README.md

@@ -15,6 +15,46 @@ session and **without any JTAG probe**.
 This repository contains the freemium distribution of [Alpha] for any
 version of the Raspberry Pi.
 
+<!-- Table of Contents -->
+
+Table of Contents
+=================
+
+   * [Alpha](#alpha)
+   * [Table of Contents](#table-of-contents)
+   * [Use Cases](#use-cases)
+      * [Bare Metal Programming](#bare-metal-programming)
+         * [Benchmarking](#benchmarking)
+         * [Writing drivers](#writing-drivers)
+         * [High performance](#high-performance)
+         * [Learning by doing](#learning-by-doing)
+      * [Operating System Debugging](#operating-system-debugging)
+      * [Multi-core Debugging](#multi-core-debugging)
+   * [A convenient programming environment](#a-convenient-programming-environment)
+      * [A bare metal C library](#a-bare-metal-c-library)
+         * [List of delegated syscalls](#list-of-delegated-syscalls)
+         * [List of implemented syscalls](#list-of-implemented-syscalls)
+         * [A stack](#a-stack)
+      * [An address space](#an-address-space)
+      * [An extended GDB server](#an-extended-gdb-server)
+         * [Exiting GDB resets the SoC](#exiting-gdb-resets-the-soc)
+         * [Stopping the execution](#stopping-the-execution)
+         * [Alpha-specific commands](#alpha-specific-commands)
+   * [Installation](#installation)
+      * [Alpha](#alpha-1)
+      * [Wiring](#wiring)
+   * [Examples](#examples)
+      * [Hello World](#hello-world)
+         * [Compiling](#compiling)
+         * [Running](#running)
+      * [Raytracer](#raytracer)
+         * [Compiling](#compiling-1)
+         * [Running](#running-1)
+   * [Support](#support)
+   * [Licensing](#licensing)
+
+Generated by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
+<!-- !Table of Contents -->
 
 # Use Cases
 

scripts/update-readme.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# immediately exit on any unhandled error
+set -e
+
+# current working directory
+cwd=${0%/*}
+
+
+#
+# script entry function
+#
+cmd() {
+  gawk -i inplace \
+    'BEGIN { toc = 0; }
+    /<!-- Table of Contents -->/ {
+      toc = 1;
+      print;
+      system("gh-md-toc README.md");
+    }
+    /<!-- !Table of Contents -->/ { toc = 0; }
+    toc == 0 { print; }' \
+    README.md
+
+  sed -i \
+      -e 's/Created by \[gh-md-toc\]/Generated by [gh-md-toc]/g' \
+      -e "s#\(https://cdn.rawgit.com/farjump/raspberry-pi/\)feature-readme-get-started/#\1$(git rev-parse --abbrev-ref HEAD)/#g" \
+      README.md
+
+  return 0
+}
+
+cmd $@

sdk/Dockerfile

@@ -20,13 +20,19 @@ RUN apt-get update && apt-get install --no-install-recommends -y \
   curl \
   make \
   libncurses5 \
+  gawk \
+  git \
   ca-certificates
 
 # Official distribution of the ARM Toolchain
 COPY ./scripts/ /tmp/scripts/
 RUN /tmp/scripts/install-toolchain.sh --prefix=/opt/arm-none-eabi
 ENV PATH="/opt/arm-none-eabi/bin:$PATH"
 
+# Helper script to generate the markdown Table of Content
+RUN curl -sSL https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc > /usr/local/bin/gh-md-toc \
+    && chmod +x /usr/local/bin/gh-md-toc
+
 # Create a non-root user with the same uid as on the host to allow proper file
 # permissions created inside the container. Since it is not root, allow calling
 # sudo without password when required.