tokenfabrikker/rapport/lag_vedlegg_endringer.py
Kjell Tore Guttormsen f271f11715
docs(rapport): appendices with the parameters and the change list, the reference list, and the two-page summary
Appendix B, appendix C and the reference list are generated from the frozen
parameter file, the pre-registration and the source bank. Citations link to
their item in the list. The two-page summary states only what the summary in
the report states. Draft PDFs of the report and the summary are in pdf/.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:24:36 +01:00

503 lines
20 KiB
Python

# ruff: noqa: INP001
r"""Write appendix C of the report: the list «Endringer» of the pre-registration, word for word.
Reads ``FORHANDSREGISTRERING.md`` from the heading ``## Endringer`` to the end of the file and
writes ``rapport/generert/vedlegg-endringer.tex``: a lead-in line (the number of dated entries and
the SHA-256 of the file it was read from) and the list itself in ``\small``. Only the layout
changes: the date of an entry is set in bold, inline code in ``\texttt`` with break points,
``**bold**`` in ``\textbf`` and ``*italic*`` in ``\emph``. The words, numbers and punctuation are
those of the source, in the same order.
The converter knows exactly the Markdown the section uses, read by its indentation:
* an entry: ``- YYYY-MM-DD: text`` at the margin, continued on lines indented by two spaces;
* a numbered point inside an entry: `` N. text`` (indented by two), continued on lines indented
to the text of the point; the numbers of one list run on without a gap;
* a new paragraph of the entry: a line indented by two after a numbered list or after a blank
line;
* inline: code spans, ``**bold**`` and ``*italic*`` (properly nested, closed in the paragraph),
the backslash escape of CommonMark, and a fixed table of characters.
Anything else stops the script with the line number, and nothing is written: another heading,
a block quote, a table row, a code fence, a bullet inside an entry, a numbered point inside a
point, a blank line inside a point, trailing whitespace, a tab, a link or HTML (``[``, ``]``,
``<``), an underscore or tilde that could be emphasis or strike-through, and every character
not in the table.
Standard library only. The output depends only on the input file: same input, same bytes.
Run from anywhere: ``python3 rapport/lag_vedlegg_endringer.py``.
"""
from __future__ import annotations
import hashlib
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path
ROT = Path(__file__).resolve().parent.parent
KILDE = ROT / "FORHANDSREGISTRERING.md"
UT = ROT / "rapport" / "generert" / "vedlegg-endringer.tex"
OVERSKRIFT = "## Endringer"
INNRYKK = 2
OPPDELING = 8 # a long hex string (a checksum, a commit) can break after every eighth character
ENTRY = re.compile(r"^- (\d{4}-\d{2}-\d{2}): (\S.*)$")
PUNKT = re.compile(r"^ (\d+)\. (\S.*)$")
LISTEMERKE = re.compile(r"^(?:[-*+] |\d+[.)] )")
BLOKKMERKE = re.compile(r"^(?:#|>|\||```|~~~)")
HEKS = re.compile(r"[0-9a-f]{16,}")
# ASCII punctuation that is typeset as it stands. A character that forms a ligature with the next
# one under T1 (-- , ,, '' !` ?`) gets an empty group after it when such a pair occurs.
VANLIG = frozenset(".,;:()/-+='!?@")
LIGATUR = {"-": "-", ",": ",", "'": "'", "!": "`", "?": "`"}
# ASCII characters that are special to LaTeX and have a plain meaning in the Markdown read here.
SPESIELL = {
"%": r"\%",
"&": r"\&",
"#": r"\#",
"$": r"\$",
"{": r"\{",
"}": r"\}",
"^": r"\textasciicircum{}",
"|": r"\textbar{}",
">": r"\textgreater{}",
'"': r"\textquotedbl{}",
}
# Characters that inputenc (utf8) and T1 set directly, by code point so that the table is ASCII.
DIREKTE = frozenset(
{
0x00E6, # latin small letter ae
0x00F8, # latin small letter o with stroke
0x00E5, # latin small letter a with ring above
0x00C6, # latin capital letter ae
0x00D8, # latin capital letter o with stroke
0x00C5, # latin capital letter a with ring above
0x00E9, # latin small letter e with acute
0x00E8, # latin small letter e with grave
0x00EA, # latin small letter e with circumflex
0x00E4, # latin small letter a with diaeresis
0x00F6, # latin small letter o with diaeresis
0x00FC, # latin small letter u with diaeresis
0x00C4, # latin capital letter a with diaeresis
0x00D6, # latin capital letter o with diaeresis
0x00DC, # latin capital letter u with diaeresis
0x00AB, # left-pointing double angle quotation mark (T1 has the glyph)
0x00BB, # right-pointing double angle quotation mark
}
)
# Every other non-ASCII character the converter accepts, by code point, and how it is set under
# pdflatex with inputenc utf8 and T1.
UNICODE = {
# Punctuation and symbols.
0x2013: r"\textendash{}", # en dash
0x2014: r"\textemdash{}", # em dash
0x2026: r"\textellipsis{}", # horizontal ellipsis
0x201C: r"\textquotedblleft{}", # left double quotation mark
0x201D: r"\textquotedblright{}", # right double quotation mark
0x2018: r"\textquoteleft{}", # left single quotation mark
0x2019: r"\textquoteright{}", # right single quotation mark
0x201E: r"\quotedblbase{}", # double low-9 quotation mark
0x00A0: "~", # no-break space
0x00B7: r"\textperiodcentered{}", # middle dot
0x00D7: r"\texttimes{}", # multiplication sign
0x2212: r"\textminus{}", # minus sign
0x2032: r"\ensuremath{{}^{\prime}}", # prime
0x2192: r"\textrightarrow{}", # rightwards arrow
0x2265: r"\ensuremath{\geq}", # greater-than or equal to
0x2264: r"\ensuremath{\leq}", # less-than or equal to
0x2248: r"\ensuremath{\approx}", # almost equal to
0x00B1: r"\textpm{}", # plus-minus sign
0x00B0: r"\textdegree{}", # degree sign
0x00BD: r"\textonehalf{}", # vulgar fraction one half
0x00BC: r"\textonequarter{}", # vulgar fraction one quarter
0x00B9: r"\textonesuperior{}", # superscript one
0x00B2: r"\texttwosuperior{}", # superscript two
0x00B3: r"\textthreesuperior{}", # superscript three
0x00A7: r"\S{}", # section sign
0x20AC: r"\texteuro{}", # euro sign
# Greek letters as they stand in the specification.
0x03B1: r"\ensuremath{\alpha}", # greek small letter alpha
0x03B2: r"\ensuremath{\beta}", # greek small letter beta
0x03B3: r"\ensuremath{\gamma}", # greek small letter gamma
0x03B4: r"\ensuremath{\delta}", # greek small letter delta
0x03B5: r"\ensuremath{\varepsilon}", # greek small letter epsilon
0x03B7: r"\ensuremath{\eta}", # greek small letter eta
0x03B8: r"\ensuremath{\theta}", # greek small letter theta
0x03BA: r"\ensuremath{\kappa}", # greek small letter kappa
0x03BB: r"\ensuremath{\lambda}", # greek small letter lamda
0x03BC: r"\ensuremath{\mu}", # greek small letter mu
0x03C0: r"\ensuremath{\pi}", # greek small letter pi
0x03C1: r"\ensuremath{\rho}", # greek small letter rho
0x03C3: r"\ensuremath{\sigma}", # greek small letter sigma
0x03C4: r"\ensuremath{\tau}", # greek small letter tau
0x03C6: r"\ensuremath{\varphi}", # greek small letter phi
0x03C7: r"\ensuremath{\chi}", # greek small letter chi
0x03C8: r"\ensuremath{\psi}", # greek small letter psi
0x03C9: r"\ensuremath{\omega}", # greek small letter omega
0x0394: r"\ensuremath{\Delta}", # greek capital letter delta
0x03A3: r"\ensuremath{\Sigma}", # greek capital letter sigma
0x03A9: r"\ensuremath{\Omega}", # greek capital letter omega
}
# Characters that may follow a backslash as a CommonMark escape.
ASCII_TEGN = frozenset("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~")
# Characters that mean something in Markdown, set as themselves (after a backslash, in code).
BOKSTAVELIG = {
"\\": r"\textbackslash{}",
"~": r"\textasciitilde{}",
"_": r"\_",
"<": r"\textless{}",
"[": "[",
"]": "]",
"*": "*",
"`": r"\textasciigrave{}",
}
# Characters after which a code span may break.
KODEBRUDD = {
"/": r"/\allowbreak{}",
".": r".\allowbreak{}",
"-": r"-{}\allowbreak{}",
"_": r"\_\allowbreak{}",
}
class EndringerError(Exception):
"""The input does not have the expected form."""
@dataclass
class Avsnitt:
"""A paragraph of an entry: its source lines without indentation, and the first line number."""
linjer: list[str]
nr: int
@dataclass
class Punkt:
"""A numbered point: its number, source lines without indentation, first line number."""
nummer: int
linjer: list[str]
nr: int
@dataclass
class Liste:
"""A numbered list inside an entry."""
punkter: list[Punkt] = field(default_factory=list)
@dataclass
class Oppforing:
"""A dated entry: the date and its blocks in order."""
dato: str
blokker: list[Avsnitt | Liste]
def feil(nr: int, hva: str, linje: str) -> EndringerError:
"""An error that names the line of the pre-registration it stands on."""
return EndringerError(f"FORHANDSREGISTRERING.md:{nr}: {hva}: {linje!r}")
def sjekk_innhold(innhold: str, nr: int, linje: str) -> None:
"""Stop on a block construct the converter does not know, at the start of a line's text."""
if BLOKKMERKE.match(innhold):
msg = "heading, block quote, table row or code fence"
raise feil(nr, msg, linje)
if LISTEMERKE.match(innhold):
msg = "list marker where only text is expected"
raise feil(nr, msg, linje)
def les_seksjon(tekst: str) -> tuple[list[tuple[int, str]], int]:
"""Return the lines after the heading with their numbers, and the heading's line number."""
linjer = tekst.split("\n")
treff = [i for i, linje in enumerate(linjer) if linje == OVERSKRIFT]
if len(treff) != 1:
msg = f"the heading {OVERSKRIFT!r} stands {len(treff)} times, not once"
raise EndringerError(msg)
start = treff[0]
resten = linjer[start + 1 :]
if resten and resten[-1] == "":
resten = resten[:-1] # the newline that ends the file
else:
msg = "the file does not end with a newline"
raise EndringerError(msg)
return [(start + 2 + i, linje) for i, linje in enumerate(resten)], start + 1
def les_oppforinger(linjer: list[tuple[int, str]]) -> list[Oppforing]: # noqa: C901, PLR0912, PLR0915
"""Read the entries by the indentation of their lines."""
oppforinger: list[Oppforing] = []
tom_foran = True # a blank line (or the heading) stands before this line
for nr, linje in linjer:
if "\t" in linje or "\r" in linje:
raise feil(nr, "tab or carriage return", linje)
if linje != linje.rstrip(" "):
raise feil(nr, "trailing whitespace (a hard line break in Markdown)", linje)
if not linje:
if not oppforinger and not tom_foran:
raise feil(nr, "blank line before the first entry", linje)
tom_foran = True
continue
if linje.startswith("- "):
m = ENTRY.match(linje)
if not m:
raise feil(nr, "an entry does not start with a date and a colon", linje)
sjekk_innhold(m.group(2), nr, linje)
oppforinger.append(Oppforing(m.group(1), [Avsnitt([m.group(2)], nr)]))
tom_foran = False
continue
if not oppforinger:
raise feil(nr, "text before the first entry", linje)
blokker = oppforinger[-1].blokker
siste = blokker[-1]
m = PUNKT.match(linje)
if m:
nummer = int(m.group(1))
sjekk_innhold(m.group(2), nr, linje)
punkt = Punkt(nummer, [m.group(2)], nr)
if isinstance(siste, Liste):
if tom_foran:
raise feil(nr, "blank line inside a numbered list", linje)
if nummer != siste.punkter[-1].nummer + 1:
raise feil(nr, "the numbers of a list do not run on", linje)
siste.punkter.append(punkt)
else:
blokker.append(Liste([punkt]))
tom_foran = False
continue
innrykk = len(linje) - len(linje.lstrip(" "))
innhold = linje[innrykk:]
sjekk_innhold(innhold, nr, linje)
if innrykk == INNRYKK:
if isinstance(siste, Avsnitt) and not tom_foran:
siste.linjer.append(innhold)
else:
blokker.append(Avsnitt([innhold], nr))
elif isinstance(siste, Liste) and not tom_foran:
punkt = siste.punkter[-1]
if innrykk != INNRYKK + len(f"{punkt.nummer}. "):
raise feil(nr, "indentation that continues neither the entry nor the point", linje)
punkt.linjer.append(innhold)
else:
raise feil(nr, "indentation the converter does not know", linje)
tom_foran = False
if not oppforinger:
msg = "the section has no entries"
raise EndringerError(msg)
return oppforinger
def ukjent(nr: int, hva: str) -> EndringerError:
"""An error in a paragraph that starts on line ``nr`` of the pre-registration."""
return EndringerError(f"FORHANDSREGISTRERING.md:{nr}: {hva}")
def tegn(c: str, neste: str, nr: int) -> str:
"""One character of running text in LaTeX (not one of the Markdown characters)."""
if c.isascii() and (c.isalnum() or c in " \n"):
return c
if c in VANLIG:
return c + "{}" if LIGATUR.get(c) == neste else c
if c in SPESIELL:
return SPESIELL[c]
if ord(c) in DIREKTE:
return c
if ord(c) in UNICODE:
return UNICODE[ord(c)]
msg = f"a character the converter does not know: {c!r} (U+{ord(c):04X})"
raise ukjent(nr, msg)
def bokstavelig(c: str, nr: int) -> str:
"""A character that means something in Markdown, set as the character itself."""
if c in BOKSTAVELIG:
return BOKSTAVELIG[c]
return tegn(c, "", nr)
def kode(innhold: str, nr: int) -> str:
r"""A code span in \texttt, with break points after / . _ - and inside long hex strings."""
if not innhold or innhold != innhold.strip(" ") or "\n" in innhold:
msg = "a code span that is empty, padded or broken over lines"
raise ukjent(nr, msg)
ut: list[str] = []
pos = 0
for m in HEKS.finditer(innhold):
ut.extend(kodetegn(c, nr) for c in innhold[pos : m.start()])
heks = m.group(0)
ut.append(
r"\allowbreak{}".join(heks[k : k + OPPDELING] for k in range(0, len(heks), OPPDELING))
)
pos = m.end()
ut.extend(kodetegn(c, nr) for c in innhold[pos:])
return r"\texttt{" + "".join(ut) + "}"
def kodetegn(c: str, nr: int) -> str:
"""One character of a code span."""
if c.isascii() and c.isalnum():
return c
if c in KODEBRUDD:
return KODEBRUDD[c]
return bokstavelig(c, nr)
def kodespenn(tekst: str, i: int, nr: int) -> tuple[str, int]:
"""The code span that opens at ``i``, and the position after it."""
slutt = tekst.find("`", i + 1)
if slutt < 0 or tekst.startswith("``", i):
msg = "an unclosed or double code span"
raise ukjent(nr, msg)
return kode(tekst[i + 1 : slutt], nr), slutt + 1
def stjerne(tekst: str, i: int, apne: list[str], nr: int) -> tuple[str, int]:
"""Open or close the emphasis at ``i``; return its LaTeX and the position after the marker."""
if tekst.startswith("***", i):
msg = "three asterisks in a row"
raise ukjent(nr, msg)
merke = "**" if tekst.startswith("**", i) else "*"
foran = tekst[i - 1] if i > 0 else " "
etter = tekst[i + len(merke)] if i + len(merke) < len(tekst) else " "
if apne and apne[-1] == merke and not foran.isspace():
apne.pop()
return "}", i + len(merke)
if merke not in apne and not etter.isspace():
apne.append(merke)
return (r"\textbf{" if merke == "**" else r"\emph{"), i + len(merke)
msg = "an asterisk that neither opens nor closes emphasis"
raise ukjent(nr, msg)
def vanlig(tekst: str, i: int, nr: int) -> str:
"""One character of running text that is not a code span, an asterisk or a backslash."""
c = tekst[i]
neste = tekst[i + 1] if i + 1 < len(tekst) else ""
if c == "_":
if not (i > 0 and tekst[i - 1].isalnum() and neste.isalnum()):
msg = "an underscore that could be emphasis"
raise ukjent(nr, msg)
return r"\_"
if c == "~":
if neste == "~" or (i > 0 and tekst[i - 1] == "~"):
msg = "a double tilde (strike-through)"
raise ukjent(nr, msg)
return r"\textasciitilde{}"
if c in "<[]":
msg = f"a link or HTML ({c!r})"
raise ukjent(nr, msg)
if c == " " and neste == "%":
return "~" # no line break between a number and its per cent sign
return tegn(c, neste, nr)
def inline(tekst: str, nr: int) -> str:
"""Convert the inline Markdown of one paragraph (lines joined by newlines) to LaTeX."""
ut: list[str] = []
apne: list[str] = []
i = 0
while i < len(tekst):
c = tekst[i]
if c == "`":
bit, i = kodespenn(tekst, i, nr)
elif c == "*":
bit, i = stjerne(tekst, i, apne, nr)
elif c == "\\":
neste = tekst[i + 1] if i + 1 < len(tekst) else ""
if neste not in ASCII_TEGN:
msg = "a backslash that is not a Markdown escape"
raise ukjent(nr, msg)
bit, i = bokstavelig(neste, nr), i + 2
else:
bit, i = vanlig(tekst, i, nr), i + 1
ut.append(bit)
if apne:
msg = f"emphasis not closed in the paragraph: {apne}"
raise ukjent(nr, msg)
return "".join(ut)
def lag_liste(liste: Liste) -> list[str]:
"""The LaTeX of a numbered list inside an entry."""
forste = liste.punkter[0].nummer
storste = liste.punkter[-1].nummer
ut = [
(
rf"\begin{{enumerate}}[label=\arabic*.,start={forste},widest={storste},leftmargin=*,"
r"topsep=0.3ex,itemsep=0.15ex,parsep=0pt]"
)
]
ut += [r"\item " + inline("\n".join(p.linjer), p.nr) for p in liste.punkter]
ut.append(r"\end{enumerate}")
return ut
def lag(tekst: str, sjekksum: str) -> tuple[str, int]:
"""Return the LaTeX of the appendix and the number of dated entries."""
linjer, _ = les_seksjon(tekst)
oppforinger = les_oppforinger(linjer)
antall = len(oppforinger)
sum_tex = kode(sjekksum, 0)
innledning = (
r"\noindent Lista under gjengir avsnittet «Endringer» i \fil{FORHANDSREGISTRERING.md}"
rf" ordrett og i sin helhet: {antall} daterte punkter, i den rekkefølgen de står der."
r" Bare oppsettet er endret: datoen i hvert punkt står med fet skrift, og filnavn og"
r" sjekksummer med skrivemaskinskrift. Lista er laget av"
r" \fil{rapport/lag_vedlegg_endringer.py} fra fila med SHA-256 " + sum_tex + "."
)
ut = [
"% Laget av rapport/lag_vedlegg_endringer.py fra FORHANDSREGISTRERING.md.",
"% Rettes ikke for hånd: kjør skriptet på nytt.",
innledning,
"",
r"{\small",
(
r"\begin{itemize}[leftmargin=1.1em,label=\textbullet,topsep=1ex,itemsep=0.7ex,"
r"parsep=0.5ex,listparindent=0pt]"
),
]
for opp in oppforinger:
for i, blokk in enumerate(opp.blokker):
if isinstance(blokk, Liste):
ut += lag_liste(blokk)
continue
avsnitt = inline("\n".join(blokk.linjer), blokk.nr)
if i == 0:
ut.append(rf"\item \textbf{{{opp.dato}:}} " + avsnitt)
else:
ut += ["", avsnitt]
ut += [r"\end{itemize}", "}", ""]
return "\n".join(ut), antall
def main() -> int:
"""Write the appendix; return 0, or 1 with a message on error."""
try:
data = KILDE.read_bytes()
tekst, antall = lag(data.decode("utf-8"), hashlib.sha256(data).hexdigest())
UT.parent.mkdir(exist_ok=True)
except (EndringerError, OSError, UnicodeDecodeError) as e:
sys.stderr.write(f"lag_vedlegg_endringer: {e}\n")
return 1
UT.write_text(tekst, encoding="utf-8", newline="\n")
sys.stdout.write(f"lag_vedlegg_endringer: skrev {UT.relative_to(ROT)} ({antall} punkter)\n")
return 0
if __name__ == "__main__":
sys.exit(main())