The Dam typrography

This document showcases the Dam's typographic features available to documentation writers. Some of the choices are laconically explained. This document also serves as an integration test for the export mechanism.

1. Basics

The documentation is written in org-mode, exported as HTML. An #+INCLUDE directive at the top sets the HTML export options and inlines a CSS.

2. Lean HTML

2.1. Single TCP roundtrip

Pages under 15kb load in a single typical TCP round trip (10 packets)11: see https://endtimes.dev/why-your-website-should-be-under-14kb-in-size/, and https://news.ycombinator.com/item?id=32587740 . But TLS will cost two roundtrips before data is exchanged.

2.2. Critical rendering path

The CSS is inlined to avoid having to fetch it before rendering22: https://web.dev/articles/critical-rendering-path .

2.3. Images

should have their size specified, so that rendering can happen before the image is loaded.

listen-git.svg
Figure 1: The p9ufs 9P server has read-only access to the global /srv/git directory, and is owned by the git user (user listen wouldn't be able to read /srv/git). This access is transferred, via the /run/9p/git socket and a 9P FUSE mount, to the namespace of the git service script, itself owned by listen. The git service script is itself never started, instead the /srv/tcp9418.namespace sets up a loopack network interface, starts the git daemon, and hijacks the usual procedure by launching socat, instead of relinquishing control to listen. This allows the incoming data to be redirected to the container's port 9418 instead of /srv/tcp9418's standard streams.

3. Misc.

3.1. Side notes

Sometimes we33: I mean I use44: Some say "abuse". footnotes55: Actually side-notes .

3.2. Citations

I refer to the work of Piketty and Zucman (2015) or to their paper directly (Piketty and Zucman 2015).

This is the real documentation https://blog.tecosaur.com/tmio/2021-07-31-citations.html

A full reference can be insterted with (Pike, Rob, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom. 1993. “The Use of Name Spaces in Plan 9.” Acm Sigops Operating Systems Review 27 (2): 72–76.)

3.3. Links

See section 3.2.

4. Blocks

4.1. quote

Use the force, harry

– Gandalf

4.2. src

In scheme

(define (hello who)
  (format #t (string-append "Hello " who)))

In bash

#!/bin/bash
set -euo pipefail
echo $toto

Inline

git clone git@the-dam.org listen

5. Bibliography

Pike, Rob, Dave Presotto, Ken Thompson, Howard Trickey, and Phil Winterbottom. 1993. “The Use of Name Spaces in Plan 9.” Acm Sigops Operating Systems Review 27 (2): 72–76.
Piketty, Thomas, and Gabriel Zucman. 2015. “Wealth and Inheritance in the Long Run.” In Handbook of Income Distribution, 2:1303–68. Elsevier.