Drop answer-letter references from explanations

Update documentation
2026-06-22 11:44:34 +02:00 · 2026-06-22 11:44:10 +02:00
3 changed files with 159 additions and 21 deletions
@@ -163,8 +163,11 @@ decks never collide on import.
 - `EXPLANATIONS.md` — the editorial contract for agents asked to add
  or improve per-question explanations. The schema, the workflows
  ("explain everything unexplained", "improve everything below
-  confidence 7"), and the source/confidence guidance live there.
-  `explanations.json` is an empty `{}` until agents populate it.
+  confidence 7"), the source/confidence guidance, and the **MathJax
+  typesetting rules (§4a) with a verification sweep** live there. The
+  `$...$` typesetting is the most error-prone part of the file — read
+  §4a before touching any formula, and fix every occurrence in both the
+  explanation body and the `Hilfsmittel:` note.
 - Start from `DESIGN.md` — it has the JSON schema, the question/answer
  conventions (answer A is always correct upstream → consumers shuffle
  before display), the LaTeX-in-questions caveat, the exam-structure
@@ -156,13 +156,137 @@ source citation.
  rule of thumb.
 - **Math.** Use inline `$...$`; it's rewritten to MathJax on the
  card, same as for question text. Don't use display math `$$...$$`
-  (the deck has no MathJax support for those).
+  (the deck has no MathJax support for those). Getting the *inside* of
+  `$...$` right is its own discipline — see **§4a Math typesetting**
+  below. This is the single most error-prone part of this file.
 - **Inline emphasis.** `<u>...</u>` is the only HTML you should
  type by hand. Everything else gets HTML-escaped.
 - **No spoilers about other answers.** If a distractor is a common
  trap, naming the trap is fine; quoting the distractor's text is
  noise.

+### 4a. Math typesetting (MathJax) — get this right
+
+Everything between `$...$` is TeX. MathJax renders **bare multi-letter
+runs as a product of italic variables**, so `ohm` shows as *o·h·m*,
+`log10` as *l·o·g·10*, `P_{PEP}` as *P·(P·E·P)*. A whole multi-round
+review on this repo was spent fixing exactly these. The rules below are
+the checklist; wrong → right.
+
+**Units** — never leave a unit as bare letters; wrap in `\text{}` (or use
+the symbol) and put a thin space `\,` after the number:
+
+| Wrong (in `$...$`) | Right |
+|---|---|
+| `0.01 ohm`, `10 kOhm`, `5 MOhm` | `0.01\,\Omega`, `10\,\text{k}\Omega`, `5\,\text{M}\Omega` |
+| `3 microhenry`, `3 uH` | `3\,\mu\text{H}` |
+| `1 uF`, `100 nF`, `47 pF` | `1\,\mu\text{F}`, `100\,\text{nF}`, `47\,\text{pF}` |
+| `5 mA`, `2 mV`, `1 kHz`, `28 MHz` | `5\,\text{mA}`, `2\,\text{mV}`, `1\,\text{kHz}`, `28\,\text{MHz}` |
+| `12 dB`, `8 dBi`, `46.8 bit/s` | `12\,\text{dB}`, `8\,\text{dBi}`, `46.8\,\text{bit/s}` |
+| `5 mm2`, `2.5 A/mm2` | `5\,\text{mm}^2`, `2.5\,\text{A/mm}^2` |
+| `360 degrees`, `45°` | `360^\circ`, `45^\circ` |
+| `20 A`, `12 V`, `100 W`, `5 m`, `50 s` | `20\,\text{A}`, `12\,\text{V}`, `100\,\text{W}`, `5\,\text{m}`, `50\,\text{s}` |
+
+**Operators, functions, Greek, powers:**
+
+| Wrong | Right | Why |
+|---|---|---|
+| `log10(x)` | `\log_{10}(x)` | bare `log` is *l·o·g* |
+| `10^(20/10)` | `10^{20/10}` | `^(` superscripts only the `(`; braces group |
+| `lambda`, `pi`, `tau`, `omega`, `rho`, `mu` | `\lambda`, `\pi`, `\tau`, … | bare = italic letters |
+| `sin`, `cos`, `ln` | `\sin`, `\cos`, `\ln` | |
+| `2 x 3`, `R1 || R2` | `2 \cdot 3`, `R_1 \parallel R_2` | `x`/`||` are not operators |
+| `62.5%` | `62.5\%` | **bare `%` is a TeX comment — it silently eats the rest of the math** |
+| `4,200,000` | `4{,}200{,}000` | bare `,` gets TeX punctuation spacing |
+
+**Subscripts.** Descriptive multi-letter labels/acronyms are roman; a
+single-letter subscript stays italic:
+
+| Wrong | Right |
+|---|---|
+| `P_{EIRP}`, `U_{peak}`, `f_{mod}`, `V_{BE}`, `f_{sum}` | `P_\mathrm{EIRP}`, `U_\mathrm{peak}`, `f_\mathrm{mod}`, `V_\mathrm{BE}`, `f_\mathrm{sum}` |
+| `R1/R2 = R3/R4` | `R_1/R_2 = R_3/R_4` |
+| keep italic: `U_F`, `f_c`, `X_C`, `R_g` | (single letter = variable, leave as-is) |
+
+A standalone acronym used as a variable (e.g. `MUF` on a formula's LHS)
+also goes roman: `\mathrm{MUF}`.
+
+**Dimensional constants keep their unit.** The field-strength constant is
+`30\,\Omega`, so write `\sqrt{30\,\Omega \cdot P_\mathrm{EIRP}}` and
+`(E\cdot d)^2/(30\,\Omega)`, not a bare `30`. Same idea for the dB-level
+exponent: `10^{g/(10\,\text{dB})}` (the `(...)` groups the denominator —
+`10^{g/10\,\text{dB}}` parses as `(g/10)·dB`).
+
+**Unit vs. variable — don't blindly unit-ize a single letter.** `A` is
+amperes in `20 A` but *area* in `N^2 A/l`; `s`/`m` are seconds/metres in
+`50 s` / `5 m` but could be variables elsewhere. The tell: a *free-standing
+number* immediately before the letter (`20 A`) means a unit; an exponent
+base (`N^2 A`) or a symbolic factor (`S \cdot A`) means a variable. When
+unsure, read the sentence.
+
+**What stays prose — do NOT force into `$...$`:**
+
+- Band/wavelength designations: `5/8-wave`, `20/15/10 m trap dipole`,
+  `the 80 m band`.
+- Conceptual word-equations: `1st overtone = 2nd harmonic`,
+  `Region 1 = Europe/Africa`.
+- Units mentioned adjectivally in a sentence: "a 50 ohm antenna",
+  "the 28 V/m limit", "about 11.7 V/m".
+
+But a **worked computation with an `=`** (e.g. `230 V / 20 = 11.5 V`)
+belongs in `$...$`, fully typeset.
+
+### Verifying it — the process lessons
+
+These review rounds kept finding *peers* of an already-fixed defect.
+Avoid the repeat:
+
+1. **Fix the whole record, not a substring.** The same formula usually
+   appears in *both* the explanation body *and* the `Hilfsmittel:` note.
+   Search the entire entry and fix every occurrence.
+2. **Fix the whole class, file-wide — not just the IDs someone listed.**
+   If `P_{EIRP}` is wrong in one card it is wrong in twenty; sweep the
+   whole file for the pattern.
+3. **Verify with a positive sweep, not a blacklist.** A list of
+   known-bad tokens always misses a new category (it missed `degrees`,
+   `bit`, `||`, bare seconds…). Instead: strip `\text{}`/`\mathrm{}` and
+   the known macros, then flag *every remaining* ≥2-letter run inside
+   `$...$` — each survivor must be a deliberate variable product
+   (`LC`, `jX`, `RC`, `di/dt`) or it's a bug.
+4. **Don't claim "0 / exhaustive" unless the check actually covers that
+   category.** Report what you checked, not a blanket adjective.
+
+A ready-made sweep:
+
+```sh
+python3 -c '
+import json, re
+d = json.load(open("explanations.json"))
+span = re.compile(r"\$[^$]*\$")
+def strip(s):
+    s = re.sub(r"\\(?:text|mathrm|operatorname)\{[^{}]*\}", " ", s)
+    return re.sub(r"\\[A-Za-z]+", " ", s)   # drop macros (\sqrt, \pi, \cdot, ...)
+for k, e in d.items():
+    ex = e["explanation"] if isinstance(e, dict) else ""
+    if ex.count("$") % 2 or ex.count("{") != ex.count("}"):
+        print("BALANCE", k)
+    for m in span.finditer(ex):
+        s = m.group(0)
+        if re.search(r"(?<!\\)%", s) or "||" in s or "°" in s \
+           or re.search(r"(?<!\\)\blog10\b|10\^\(", s) \
+           or re.search(r"_\{[A-Za-z][A-Za-z,]*\}", s) \
+           or re.search(r"(?<=\d),(?=\d\d\d)", s):
+            print("ISSUE", k, m.group(0)[:60]); break
+        for tok in re.findall(r"[A-Za-z]{2,}", strip(s)):
+            # whitelist genuine products / kept tokens; investigate the rest
+            if tok not in {"LC","RC","RA","UI","CU","PR","jX","fL","fC","di","dt"}:
+                print("TOKEN?", k, tok, "|", m.group(0)[:60])
+'
+```
+
+Anything it prints is either a real defect or a new legitimate product to
+add to the whitelist — look, don't assume.
+
 ### What "WHY-focused" means in practice

 | Less useful                                  | More useful                                   |
@@ -455,7 +579,18 @@ Before saving, confirm:
 - [ ] `confidence` honestly reflects how well the source supports
      the explanation.
 - [ ] Keys remain in alphabetical order in the file.
- [ ] `python3 -m unittest test_amateurfunk_anki` passes.
+- [ ] **Math typesetting (§4a):** every formula is in `$...$`; units are
+      `\text{}`/symbols with a leading `\,`; no bare `log10`, `10^(`,
+      Greek words, `%`, `||`, multi-letter `_{...}` subscripts, or raw
+      thousands commas; dimensional constants keep their unit. Fix every
+      occurrence in **both** the body and the `Hilfsmittel:` note.
+- [ ] The §4a verification sweep prints nothing unexpected (run it after
+      any batch of math edits — don't trust a per-ID fix to have caught
+      the peers).
+- [ ] `python3 -m unittest test_amateurfunk_anki` passes. (The full deck
+      suite is `test_amateurfunk_fetch test_amateurfunk_anki
+      test_amateurfunk_shorthand test_amateurfunk_technical` — 95 tests;
+      the two-module subset that validates explanation schema is 65.)

 ---

@@ -5346,8 +5346,8 @@
    "confidence": 8
  },
  "EA104": {
-    "revision": 3,
-    "explanation": "Magnetic field strength $H$ is given in amperes per metre (A/m). The straight-wire case shows why: $H = I/(2\\pi r)$ is a current (amperes) spread over a circumference (metres). Keep $H$ (field strength, A/m) distinct from flux density $B$ (tesla); option D, H/m, is the unit of permeability instead.",
+    "revision": 4,
+    "explanation": "Magnetic field strength $H$ is given in amperes per metre (A/m). The straight-wire case shows why: $H = I/(2\\pi r)$ is a current (amperes) spread over a circumference (metres). Keep $H$ (field strength, A/m) distinct from flux density $B$ (tesla); H/m is the unit of permeability instead.",
    "source": "https://50ohm.de/NEA_h_feld.html#EA104",
    "confidence": 8
  },
@@ -5370,8 +5370,8 @@
    "confidence": 8
  },
  "EA108": {
-    "revision": 4,
-    "explanation": "Micro ($\\mu$) means $10^{-6}$. Expressing $0.00042$ A in microamperes shifts the decimal six places: $0.00042$ A $= 420 \\cdot 10^{-6}$ A $= 420\\ \\mu$A. Option D, $42 \\cdot 10^{-6}$ A, is ten times too small. <u>Hilfsmittel:</u> use the Zehnerpotenzen/SI-Präfix table (S.11): micro = $10^{-6}$.",
+    "revision": 5,
+    "explanation": "Micro ($\\mu$) means $10^{-6}$. Expressing $0.00042$ A in microamperes shifts the decimal six places: $0.00042$ A $= 420 \\cdot 10^{-6}$ A $= 420\\ \\mu$A. The value $42 \\cdot 10^{-6}$ A is ten times too small. <u>Hilfsmittel:</u> use the Zehnerpotenzen/SI-Präfix table (S.11): micro = $10^{-6}$.",
    "source": "https://50ohm.de/NEA_zehnerpotenzen.html#EA108",
    "confidence": 8
  },
@@ -5424,8 +5424,8 @@
    "confidence": 8
  },
  "EA201": {
-    "revision": 3,
-    "explanation": "Binary needs only two symbols, 0 and 1, which map directly onto two robust electrical states — a switching element such as a transistor is simply off or on (low or high voltage). Multi-level analog states (option C) are far harder to keep reliable across temperature and noise, so digital logic builds everything from clean two-state switching.",
+    "revision": 4,
+    "explanation": "Binary needs only two symbols, 0 and 1, which map directly onto two robust electrical states — a switching element such as a transistor is simply off or on (low or high voltage). Representing intermediate values between 0 and 1 with multi-level analog states is far harder to keep reliable across temperature and noise, so digital logic builds everything from clean two-state switching.",
    "source": "https://50ohm.de/NEA_binaer.html#EA201",
    "confidence": 8
  },
@@ -5718,8 +5718,8 @@
    "confidence": 8
  },
  "EB504": {
-    "revision": 4,
-    "explanation": "Start from $P = U \\cdot I$ and substitute Ohm's law $I = U/R$ to eliminate the unknown current: $P = U^2/R$. Solving for the voltage gives $U = \\sqrt{P \\cdot R}$. (Option C, $\\sqrt{P/R}$, actually gives the current, not the voltage.) <u>Hilfsmittel:</u> combine $P = U\\cdot I$ with $I = U/R$ to get $P = U^2/R$, hence $U = \\sqrt{P\\cdot R}$ (Leistung, S.12).",
+    "revision": 5,
+    "explanation": "Start from $P = U \\cdot I$ and substitute Ohm's law $I = U/R$ to eliminate the unknown current: $P = U^2/R$. Solving for the voltage gives $U = \\sqrt{P \\cdot R}$. The expression $\\sqrt{P/R}$ instead gives the current, not the voltage. <u>Hilfsmittel:</u> combine $P = U\\cdot I$ with $I = U/R$ to get $P = U^2/R$, hence $U = \\sqrt{P\\cdot R}$ (Leistung, S.12).",
    "source": "https://50ohm.de/NEA_leistung_2.html#EB504",
    "confidence": 8
  },
@@ -6006,8 +6006,8 @@
    "confidence": 8
  },
  "EC503": {
-    "revision": 3,
-    "explanation": "Forward threshold (Schwellspannung) depends on the semiconductor: germanium conducts from about $0.2$-$0.4$ V, silicon from about $0.6$-$0.8$ V. The lower germanium drop is why crystal/detector receivers favour Ge or Schottky diodes for weak signals. Option B simply swaps the two materials.",
+    "revision": 4,
+    "explanation": "Forward threshold (Schwellspannung) depends on the semiconductor: germanium conducts from about $0.2$-$0.4$ V, silicon from about $0.6$-$0.8$ V. The lower germanium drop is why crystal/detector receivers favour Ge or Schottky diodes for weak signals. Assigning $0.6$-$0.8$ V to germanium and $0.2$-$0.4$ V to silicon simply swaps the two materials.",
    "source": "https://50ohm.de/NEA_diode_1.html#EC503",
    "confidence": 8
  },
@@ -6114,8 +6114,8 @@
    "confidence": 8
  },
  "EC521": {
-    "revision": 4,
-    "explanation": "With no load, the series resistor carries only the Zener current and must drop the supply down to the Zener voltage: $13.8\\ \\text{V} - 5\\ \\text{V} = 8.8$ V across it at $30$ mA. So $R = 8.8\\ \\text{V} / 0.030\\ \\text{A} \\approx 293\\ \\Omega$. (Option B's milliohm value would short the supply — a sanity-check fail.) <u>Hilfsmittel:</u> apply $R = U/I$ (Ohmsches Gesetz, S.11) to the resistor's drop and Zener current.",
+    "revision": 5,
+    "explanation": "With no load, the series resistor carries only the Zener current and must drop the supply down to the Zener voltage: $13.8\\ \\text{V} - 5\\ \\text{V} = 8.8$ V across it at $30$ mA. So $R = 8.8\\ \\text{V} / 0.030\\ \\text{A} \\approx 293\\ \\Omega$. A value of about $3.41\\,\\text{m}\\Omega$ would short the supply — a sanity-check fail. <u>Hilfsmittel:</u> apply $R = U/I$ (Ohmsches Gesetz, S.11) to the resistor's drop and Zener current.",
    "source": "https://50ohm.de/NEA_diode_1.html#EC521",
    "confidence": 8
  },
@@ -7224,8 +7224,8 @@
    "confidence": 8
  },
  "EG305": {
-    "revision": 3,
-    "explanation": "Open parallel-wire line (Hühnerleiter/Paralleldraht) runs mostly through air rather than a lossy solid dielectric, so it has markedly lower loss than coax and withstands high voltages well — ideal for feeding a high-SWR multiband antenna. Its drawback is that it radiates if unbalanced, the opposite of the shielding option B claims.",
+    "revision": 4,
+    "explanation": "Open parallel-wire line (Hühnerleiter/Paralleldraht) runs mostly through air rather than a lossy solid dielectric, so it has markedly lower loss than coax and withstands high voltages well — ideal for feeding a high-SWR multiband antenna. Its drawback is that it radiates if unbalanced; the absence of shielding does not itself prevent common-mode currents.",
    "source": "https://50ohm.de/NEA_uebertragungsleitungen_2.html#EG305",
    "confidence": 8
  },
@@ -7350,8 +7350,8 @@
    "confidence": 9
  },
  "EG502": {
-    "revision": 6,
-    "explanation": "Build EIRP in two steps. First get the real power at the antenna by subtracting feed-line losses from the transmitter output, $P_{\\text{Sender}} - P_{\\text{Verluste}}$; then <u>multiply</u> by the antenna gain factor $G$. Adding gain (options C/D) is the classic error — power and a linear gain factor multiply, not add (you would only add if everything were in dB). <u>Hilfsmittel:</u> subtract feed-line loss, then multiply by the gain factor: the sheet gives $P_\\mathrm{ERP} = P_S\\cdot 10^{(g_d-a)/(10\\,\\text{dB})}$ and $P_\\mathrm{EIRP} = P_\\mathrm{ERP}\\cdot 1{,}64$ (S.15).",
+    "revision": 7,
+    "explanation": "Build EIRP in two steps. First get the real power at the antenna by subtracting feed-line losses from the transmitter output, $P_{\\text{Sender}} - P_{\\text{Verluste}}$; then <u>multiply</u> by the antenna gain factor $G$. Adding antenna gain to power instead of multiplying by the linear gain factor is the classic error (you would only add if everything were in dB). <u>Hilfsmittel:</u> subtract feed-line loss, then multiply by the gain factor: the sheet gives $P_\\mathrm{ERP} = P_S\\cdot 10^{(g_d-a)/(10\\,\\text{dB})}$ and $P_\\mathrm{EIRP} = P_\\mathrm{ERP}\\cdot 1{,}64$ (S.15).",
    "source": "https://50ohm.de/NEA_aequivalente_isotrope_strahlungsleistung_eirp_2.html#EG502",
    "confidence": 8
  },
@@ -10499,4 +10499,4 @@
    "source": "https://50ohm.de/NEA_antennen_baurecht_haftung.html#VE707",
    "confidence": 8
  }
-}
+}
Author	SHA1	Message	Date
imple	4a14bbb989	Drop answer-letter references from explanations	2026-06-22 11:44:34 +02:00
imple	989d6d6888	Update documentation	2026-06-22 11:44:10 +02:00