Annotations
Notes on a picture or on lines of code, each pointing at its place: one call, annotated, read three ways.
Contents
Annotations
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

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.
- 1The balloon, filled with hydrogen: an early test of balloons for radiosonde measurements.
- 2Just let go. His hand is still up, and the balloon only a little above the roof.
- 3The theodolite, which follows the balloon as it climbs, until it is too far to see.
- 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}

- 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.
:::
- 1The mast over the tower, a vane at its tip.
- 2The tower’s railed platform, the highest place on the building to stand.
- 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}

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 of 4
1Start with the balloon: a pilot balloon, being filled.2 of 4
2Then what it is filled from, a fitting on a small shelf pulled out of the cabinet.3 of 4
3Then her hand, at the fitting.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))
- 3The tin, not a gauge: its rim is what everything is scaled by.
- 6-7How much sky the tin catches, and how much a standard gauge’s funnel does — 20.3 cm across, the eight-inch gauge.
- 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
- 2Stop at the first failure, and on any name never set.
- 3-6One line per tin, its name and its depth.
- 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 of 3
1Every tin’s reading, from the file the station writes.2 of 3
2The one with the most in it.3 of 3
3Its name, onto the page.
Subscribe
Readings go up when the gauge has been read, not on a schedule: most weeks twice, every day in the monsoon. However you follow, nothing about you is kept here.
- In a feed reader
- Atom · JSON Feed. Each section has a feed of its own, at its address followed by feed.xml.
- In the fediverse
- Search for https://adventure.x.bdeshi.space/ in Mastodon or any other fediverse app, and follow it.
- From your own site
- Follow https://adventure.x.bdeshi.space/ in an IndieWeb reader. A reply, like or repost from your own site reaches the post here by webmention.
Annotations
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

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.
- The balloon, filled with hydrogen: an early test of balloons for radiosonde measurements.
- Just let go. His hand is still up, and the balloon only a little above the roof.
- The theodolite, which follows the balloon as it climbs, until it is too far to see.
- His 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}

- 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.
:::

- The mast over the tower, a vane at its tip.
- The tower’s railed platform, the highest place on the building to stand.
- The 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}

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.
- Start with the balloon: a pilot balloon, being filled.
- Then what it is filled from, a fitting on a small shelf pulled out of the cabinet.
- Then her hand, at the fitting.
- And 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))
- 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.
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
- 2 Stop at the first failure, and on any name never set.
- 3-6 One line per tin, its name and its depth.
- 6 Wettest 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 Every tin’s reading, from the file the station writes.
- 2 The one with the most in it.
- 3 Its name, onto the page.
Readings go up when the gauge has been read, not on a schedule: most weeks twice, every day in the monsoon. However you follow, nothing about you is kept here.
- In a feed reader
- Atom · JSON Feed. Each section has a feed of its own, at its address followed by feed.xml.
- In the fediverse
- Search for https://adventure.x.bdeshi.space/ in Mastodon or any other fediverse app, and follow it.
- From your own site
- Follow https://adventure.x.bdeshi.space/ in an IndieWeb reader. A reply, like or repost from your own site reaches the post here by webmention.