A Khosra Demo

Readings from a rain gauge on a roof

Menu

Annotations

Notes on a picture or on lines of code, each pointing at its place: one call, annotated, read three ways.

Contents

The photographs are the NOAA Photo Library’s, in the public domain.

The thing comes first, a picture or a code block. Anything written after it is its caption. Then a list, each item opening with where it points and a colon: on a picture two numbers, percent across and down, as a thumbnail’s point is written; on code a line or lines, 3 or 6-7, as hl= writes them. Nothing else to learn, and no script anywhere on this page: every mark is a link to its note, and pointing at either lights the other.

Notes beside the picture

show=beside is a picture’s way unless it says otherwise. On a wide window the notes stand in the margin, where sidenotes do; narrower, under the picture.

:::annotated
![Two men on a roof, releasing a balloon](rooftop-balloon.jpg)

A balloon test on a Washington roof, about 1930.

- 56 12.5: **The balloon**, filled with hydrogen: an early test of balloons for radiosonde measurements.
- 28.5 38: **Just let go.** His hand is still up, and the balloon only a little above the roof.
- 41 46: **The theodolite**, which follows the balloon as it climbs, until it is too far to see.
- 62.5 55.5: **His colleague**, a clipboard ready.
:::

A balloon test on a Washington roof, about 1930.

  1. 1The balloon, filled with hydrogen: an early test of balloons for radiosonde measurements.
  2. 2Just let go. His hand is still up, and the balloon only a little above the roof.
  3. 3The theodolite, which follows the balloon as it climbs, until it is too far to see.
  4. 4His colleague, a clipboard ready.

Notes under the picture

show=under keeps the picture its full width and the notes after it, in the same numbers.

:::annotated{show=under}
![A weather station in snow](weather-station.jpg)

- 45.5 8: **The mast** over the tower, a vane at its tip.
- 45.5 20: **The tower's railed platform**, the highest place on the building to stand.
- 67 71: **The porches**, two storeys of them, the ground in snow. A postcard, about 1900.
:::
  1. 1The mast over the tower, a vane at its tip.
  2. 2The tower’s railed platform, the highest place on the building to stand.
  3. 3The porches, two storeys of them, the ground in snow. A postcard, about 1900.

A tour of the picture

show=tour reads the notes one at a time, for a picture read in an order — a plan, a machine, a page of a manuscript. The caption comes first, with every mark at rest; Next goes to note 1, its mark lit and the others stepped back. The way on and back stays put from step to step. On the keyboard, the steps are a group the arrow keys walk.

:::annotated{show=tour}
![A woman fills a balloon](filling-a-balloon.jpg)

Filling a pilot balloon from the station's cabinet: four things to look at, in the order the job is done.

- 53 31: **Start with the balloon**: a pilot balloon, being filled.
- 52 51.5: **Then what it is filled from**, a fitting on a small shelf pulled out of the cabinet.
- 62 47: **Then her hand**, at the fitting.
- 30 64: **And the cabinet**, its drawers left open.
:::

Filling a pilot balloon from the station’s cabinet: four things to look at, in the order the job is done.

  1. 1 of 4

    1Start with the balloon: a pilot balloon, being filled.
  2. 2 of 4

    2Then what it is filled from, a fitting on a small shelf pulled out of the cabinet.
  3. 3 of 4

    3Then her hand, at the fitting.
  4. 4 of 4

    4And the cabinet, its drawers left open.

Without a caption a tour opens on note 1.

Notes on code

On code a place is lines. The line numbers show, a noted line’s darker; point at a note and its lines light. The numbers are the marks, and nothing has to be written into the code itself — whatever its language writes comments with. Code’s way is under.

:::annotated
```py
import math

RIM = 22.0  # the tin across, in centimetres

def rainfall(depth_mm, rim_cm=RIM):
    area_tin = math.pi * (rim_cm / 2) ** 2
    area_ref = math.pi * (20.3 / 2) ** 2
    return depth_mm * area_tin / area_ref

print(round(rainfall(2.0), 2))
```

- 3: The tin, not a gauge: its rim is what everything is scaled by.
- 6-7: How much sky the tin catches, and how much a standard gauge's funnel does — 20.3 cm across, the eight-inch gauge.
- 10: Two millimetres in the tin is 2.35 in a real gauge.
:::
 1import math
 2
 3RIM = 22.0  # the tin across, in centimetres
 4
 5def rainfall(depth_mm, rim_cm=RIM):
 6    area_tin = math.pi * (rim_cm / 2) ** 2
 7    area_ref = math.pi * (20.3 / 2) ** 2
 8    return depth_mm * area_tin / area_ref
 9
10print(round(rainfall(2.0), 2))
  1. 3The tin, not a gauge: its rim is what everything is scaled by.
  2. 6-7How much sky the tin catches, and how much a standard gauge’s funnel does — 20.3 cm across, the eight-inch gauge.
  3. 10Two millimetres in the tin is 2.35 in a real gauge.

show=beside sets the same notes in the margin, a commentary beside the listing; here on a shell script, whose comments are not Python’s.

1#!/bin/sh
2set -eu
3for tin in north south; do
4  depth=$(cat "readings/$tin.txt")
5  printf '%s %s\n' "$tin" "$depth"
6done | sort -k2 -n
  1. 2Stop at the first failure, and on any name never set.
  2. 3-6One line per tin, its name and its depth.
  3. 6Wettest last.

A tour of code

show=tour on code walks its notes in order, each step lighting the lines it names.

1const tins = await fetch("/readings.json").then(r => r.json());
2const wettest = tins.reduce((a, b) => (b.depth > a.depth ? b : a));
3document.querySelector("#wettest").textContent = wettest.name;

What the status page does with the night’s readings.

  1. 1 of 3

    1Every tin’s reading, from the file the station writes.
  2. 2 of 3

    2The one with the most in it.
  3. 3 of 3

    3Its name, onto the page.

AI use: The notes on the photographs and the code are an assistant's, written to show the call.

khosra · khata 4d8d4c99 · content f6393d22 · 228 publications, 4256671 bytes · built in 1.460642387s