Build a thesis template from your university's rules

# rules.toml: the thesis manual of Example University, invented for this lesson, as rules that a program can check.
# Each rule keeps the sentence of the manual it comes from (manual), the kind of measurement (check) and its numbers.
# spec_check.py reads this file and a PDF and says, rule by rule, what it measured and whether the rule holds.

[[rule]]
id = "paper"
manual = "Print on A4 paper, 210 by 297 mm."
check = "page-size"
width_mm = 210
height_mm = 297

[[rule]]
id = "margin-left"
manual = "Leave at least 35 mm on the left of every page, for the binding."
check = "margin"
side = "left"
min_mm = 35

[[rule]]
id = "margin-right"
manual = "Leave at least 25 mm on the right."
check = "margin"
side = "right"
min_mm = 25

[[rule]]
id = "margin-top"
manual = "Leave at least 25 mm above the text."
check = "margin"
side = "top"
min_mm = 25

[[rule]]
id = "margin-bottom"
manual = "Leave at least 25 mm below the text; the page number goes in this margin."
check = "margin"
side = "bottom"
min_mm = 25

[[rule]]
id = "body-size"
manual = "Set the text in 12 pt type."
check = "body-size"
pt = 12
tolerance_pt = 0.1

[[rule]]
id = "line-spacing"
manual = "Space the lines of the text one and a half times the type size apart: 18 pt from baseline to baseline."
check = "line-pitch"
pt = 18
tolerance_pt = 0.2

[[rule]]
id = "chapter-titles"
manual = "Set chapter titles in bold type of at least 16 pt."
check = "chapter-titles"
min_pt = 16

[[rule]]
id = "page-numbers"
manual = "Number every page but the title page at its foot, centred under the text, 12 to 20 mm above the bottom edge."
check = "page-numbers"
min_mm = 12
max_mm = 20
tolerance_mm = 1

[[rule]]
id = "numbering"
manual = "Number the pages before chapter 1 in lowercase roman, counting the title page, and from chapter 1 on in arabic from 1."
check = "labels"

[[rule]]
id = "front-matter"
manual = "Give the certificate, declaration, acknowledgements, abstract and contents in that order."
check = "order"
titles = ["Certificate", "Declaration", "Acknowledgements", "Abstract", "Contents"]

[[rule]]
id = "chapter-pages"
manual = "Start every chapter on a new page."
check = "chapter-pages"

[[rule]]
id = "citations"
manual = "Cite sources by number in square brackets, as [3], never by author and year."
check = "citations"

"""Checks a thesis PDF against the rules of a manual, written as rules.toml, and prints one line per rule: what it
measured, and PASS or FAIL. Nothing is judged by eye: every number comes from the PDF.

    python3 spec_check.py rules.toml thesis.pdf

The PDF is read with two command-line tools: MuPDF's mutool draw -F stext gives each page's size and every line of
text with its box, its baseline and the size and name of its font, in points (72 to the inch), and qpdf --json gives
the page labels. The title page, the first page, is left out of the margin and page-number checks, since its layout is
the manual's own. A page number is the last line of a page when that line is the page's label. Margins are measured
from the ink of the text, from the first to the last visible character of each line (a PDF may keep a space after the
last word of a line, which is not ink), with 1 mm of tolerance, because glyphs such as a full stop may hang a little
into the margin. A line counts as body text when its type is the size used most in the document, and the spacing of
lines is the most common distance between the baselines of two body lines that follow each other in one paragraph.
"""

import json
import re
import subprocess
import sys
import tomllib
import xml.etree.ElementTree as ET
from collections import Counter

MM = 25.4 / 72  # millimetres per point
MARGIN_TOLERANCE_MM = 1.0
BOLD = re.compile(r"Bold|BX|Black|Heavy|Semibold", re.I)


def roman(number):
    """4 -> 'iv'."""
    out = ""
    for value, letters in [(1000, "m"), (900, "cm"), (500, "d"), (400, "cd"), (100, "c"), (90, "xc"), (50, "l"),
                           (40, "xl"), (10, "x"), (9, "ix"), (5, "v"), (4, "iv"), (1, "i")]:
        while number >= value:
            out, number = out + letters, number - value
    return out


def read_pages(pdf):
    """Every page as {width, height, lines}, each line {text, size, bold, x0, y0, x1, y1, baseline, block}."""
    xml = subprocess.run(["mutool", "draw", "-F", "stext", "-o", "-", pdf], capture_output=True, text=True,
                         check=True).stdout
    pages = []
    for page in ET.fromstring(xml).iter("page"):
        lines = []
        for number, block in enumerate(page.iter("block")):
            for line in block.iter("line"):
                fonts = line.findall("font")
                chars = [char for font in fonts for char in font.findall("char")]
                if not chars or not line.get("text", "").strip():
                    continue
                main = max(fonts, key=lambda font: len(font.findall("char")))
                _, y0, _, y1 = (float(v) for v in line.get("bbox").split())
                # The ink of the line runs from its first to its last visible character; a space that a PDF keeps
                # after the last word is not part of it.
                ink = [char for char in chars if char.get("c", "").strip()]
                corners = [float(v) for v in ink[0].get("quad").split()[0::2] + ink[-1].get("quad").split()[0::2]]
                lines.append({"text": line.get("text").strip(), "size": float(main.get("size")),
                              "bold": bool(BOLD.search(main.get("name", ""))), "x0": min(corners[:4]),
                              "y0": y0, "x1": max(corners[4:]), "y1": y1, "baseline": float(chars[0].get("y")),
                              "block": number})
        pages.append({"width": float(page.get("width")), "height": float(page.get("height")), "lines": lines})
    return pages


def read_labels(pdf, count):
    """The label of every page from the PDF's /PageLabels, or None when it has none."""
    found = json.loads(subprocess.run(["qpdf", "--json", "--json-key=pagelabels", pdf], capture_output=True,
                                      text=True, check=True).stdout)["pagelabels"]
    if not found:
        return None
    styles = {"/D": str, "/r": roman, "/R": lambda n: roman(n).upper()}
    out = []
    for index in range(count):
        start = max((r for r in found if r["index"] <= index), key=lambda r: r["index"])
        label = start["label"]
        number = label.get("/St", 1) + index - start["index"]
        out.append(styles[label["/S"]](number) if "/S" in label else "")
    return out


class Thesis:
    def __init__(self, pdf):
        self.pages = read_pages(pdf)
        self.labels = read_labels(pdf, len(self.pages))
        sizes = Counter()
        for page in self.pages:
            for line in page["lines"]:
                sizes[round(line["size"], 1)] += len(line["text"])
        self.body_size = sizes.most_common(1)[0][0]
        first_lines = [page["lines"][0]["text"] if page["lines"] else "" for page in self.pages]
        self.first_lines = first_lines
        self.chapter_one = next((i for i, line in enumerate(first_lines) if re.fullmatch(r"Chapter 1", line)), None)

    def number_line(self, index):
        """The page number line of page `index`, or None."""
        lines = self.pages[index]["lines"]
        if not lines or self.labels is None:
            return None
        last = max(lines, key=lambda line: line["baseline"])
        return last if last["text"] == self.labels[index] else None

    def text_lines(self, index):
        number = self.number_line(index)
        return [line for line in self.pages[index]["lines"] if line is not number]


def check_page_size(thesis, rule):
    sizes = {(round(p["width"] * MM, 1), round(p["height"] * MM, 1)) for p in thesis.pages}
    ok = all(abs(w - rule["width_mm"]) <= 1 and abs(h - rule["height_mm"]) <= 1 for w, h in sizes)
    return ", ".join(f"{w} × {h} mm" for w, h in sorted(sizes)), ok


def check_margin(thesis, rule):
    side = rule["side"]
    values = []
    for index in range(1, len(thesis.pages)):
        page, lines = thesis.pages[index], thesis.text_lines(index)
        if not lines:
            continue
        values.append({"left": min(l["x0"] for l in lines), "right": page["width"] - max(l["x1"] for l in lines),
                       "top": min(l["y0"] for l in lines), "bottom": page["height"] - max(l["y1"] for l in lines)}[side])
    least = min(values) * MM
    return f"{least:.1f} mm at the least", least >= rule["min_mm"] - MARGIN_TOLERANCE_MM


def check_body_size(thesis, rule):
    return f"{thesis.body_size:g} pt", abs(thesis.body_size - rule["pt"]) <= rule["tolerance_pt"]


def check_line_pitch(thesis, rule):
    gaps = Counter()
    for page in thesis.pages:
        body = [l for l in page["lines"] if abs(l["size"] - thesis.body_size) < 0.05]
        for before, after in zip(body, body[1:]):
            if before["block"] == after["block"]:
                gaps[round(after["baseline"] - before["baseline"], 1)] += 1
    if not gaps:
        return "no two body lines in a row", False
    pitch = gaps.most_common(1)[0][0]
    return f"{pitch:g} pt between baselines", abs(pitch - rule["pt"]) <= rule["tolerance_pt"]


def check_chapter_titles(thesis, rule):
    titles = []
    for index, page in enumerate(thesis.pages[1:], 1):
        lines = thesis.text_lines(index)
        if not lines or lines[0]["size"] <= thesis.body_size:
            continue
        opening = [lines[0]] + ([lines[1]] if re.fullmatch(r"Chapter \d+", lines[0]["text"]) and len(lines) > 1 else [])
        titles.extend(opening)
    if not titles:
        return "no chapter titles found", False
    smallest = min(t["size"] for t in titles)
    bold = sum(t["bold"] for t in titles)
    return f"{len(titles)} title lines, {bold} bold, {smallest:.1f} pt at the least", bold == len(titles) and \
        smallest >= rule["min_pt"]


def check_page_numbers(thesis, rule):
    found, good = 0, 0
    lefts = [min(l["x0"] for l in thesis.text_lines(i)) for i in range(1, len(thesis.pages)) if thesis.text_lines(i)]
    rights = [max(l["x1"] for l in thesis.text_lines(i)) for i in range(1, len(thesis.pages)) if thesis.text_lines(i)]
    middle = (min(lefts) + max(rights)) / 2
    heights = []
    for index in range(1, len(thesis.pages)):
        line = thesis.number_line(index)
        if line is None:
            continue
        found += 1
        above = (thesis.pages[index]["height"] - line["baseline"]) * MM
        centred = abs((line["x0"] + line["x1"]) / 2 - middle) * MM <= rule["tolerance_mm"]
        heights.append(above)
        good += centred and rule["min_mm"] <= above <= rule["max_mm"]
    pages = len(thesis.pages) - 1
    if not heights:
        return f"0 of {pages} pages numbered", False
    return f"{found} of {pages} numbered, {good} in place, {min(heights):.1f} to {max(heights):.1f} mm up", \
        found == good == pages


def check_labels(thesis, rule):
    if thesis.labels is None:
        return "no page labels", False
    if thesis.chapter_one is None:
        return "no page starts with Chapter 1", False
    expected = [roman(n) for n in range(1, thesis.chapter_one + 1)]
    expected += [str(n) for n in range(1, len(thesis.pages) - thesis.chapter_one + 1)]
    for index, (label, want) in enumerate(zip(thesis.labels, expected), 1):
        if label != want:
            return f"page {index} is {label or '(empty)'}, not {want}", False
    return f"{thesis.labels[0]} to {thesis.labels[thesis.chapter_one - 1]}, then 1 to {thesis.labels[-1]}", True


def check_order(thesis, rule):
    places = []
    for title in rule["titles"]:
        if title not in thesis.first_lines:
            return f"{title} missing", False
        places.append(thesis.first_lines.index(title))
    return f"{len(places)} parts on pages {', '.join(str(p + 1) for p in places)}", places == sorted(places)


def check_chapter_pages(thesis, rule):
    openings = [(i, line) for i, page in enumerate(thesis.pages) for line in page["lines"]
                if re.fullmatch(r"Chapter \d+", line["text"])]
    first = sum(line is thesis.pages[i]["lines"][0] for i, line in openings)
    return f"{first} of {len(openings)} chapters open a page", bool(openings) and first == len(openings)


def check_citations(thesis, rule):
    start = thesis.chapter_one or 0
    text = " ".join(line["text"] for page in thesis.pages[start:] for line in page["lines"])
    numbered = len(re.findall(r"\[\d+(?:[,–-] ?\d+)*\]", text))
    named = len(re.findall(r"\([A-Z][a-z]+(?: and [A-Z][a-z]+| et al\.)?,? \d{4}[a-z]?\)", text))
    return f"{numbered} numbered, {named} by author and year", numbered > 0 and named == 0


CHECKS = {"page-size": check_page_size, "margin": check_margin, "body-size": check_body_size,
          "line-pitch": check_line_pitch, "chapter-titles": check_chapter_titles, "page-numbers": check_page_numbers,
          "labels": check_labels, "order": check_order, "chapter-pages": check_chapter_pages,
          "citations": check_citations}


def main(rules_file, pdf):
    with open(rules_file, "rb") as handle:
        rules = tomllib.load(handle)["rule"]
    thesis = Thesis(pdf)
    passed = 0
    print(f"{'rule':<15}{'measured':<52}result")
    for rule in rules:
        measured, ok = CHECKS[rule["check"]](thesis, rule)
        passed += ok
        print(f"{rule['id']:<15}{measured:<52}{'PASS' if ok else 'FAIL'}")
    print(f"{len(rules)} rules: {passed} pass, {len(rules) - passed} fail")


if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])

from session import files, run

# The test before the template: plain.tex, the thesis on the report class's own settings, built and checked against
# rules.toml with spec_check.py.
files("rules.toml", "spec_check.py", "latex/plain.tex=plain.tex", "latex/chapters.tex=chapters.tex")
run(r"""
latexmk -pdf -interaction=nonstopmode -silent plain.tex > /dev/null 2>&1
python3 spec_check.py rules.toml plain.pdf
""")

$ latexmk -pdf -interaction=nonstopmode -silent plain.tex > /dev/null 2>&1
$ python3 spec_check.py rules.toml plain.pdf
rule           measured                                            result
paper          215.9 × 279.4 mm                                    FAIL
margin-left    47.2 mm at the least                                PASS
margin-right   47.4 mm at the least                                PASS
margin-top     45.1 mm at the least                                PASS
margin-bottom  42.4 mm at the least                                PASS
body-size      10 pt                                               FAIL
line-spacing   12 pt between baselines                             FAIL
chapter-titles 10 title lines, 10 bold, 20.7 pt at the least       PASS
page-numbers   9 of 9 numbered, 0 in place, 31.5 to 31.5 mm up     FAIL
numbering      page 1 is 1, not i                                  FAIL
front-matter   5 parts on pages 2, 3, 4, 5, 6                      PASS
chapter-pages  2 of 2 chapters open a page                         PASS
citations      4 numbered, 0 by author and year                    PASS
13 rules: 8 pass, 5 fail

from session import files, run

# The class at work: thesis.tex, built with exu-thesis.cls and checked against the same rules.
files("rules.toml", "spec_check.py", "latex/exu-thesis.cls=exu-thesis.cls", "latex/thesis.tex=thesis.tex",
      "latex/chapters.tex=chapters.tex")
run(r"""
latexmk -pdf -interaction=nonstopmode -silent thesis.tex > /dev/null 2>&1
python3 spec_check.py rules.toml thesis.pdf
""")

$ latexmk -pdf -interaction=nonstopmode -silent thesis.tex > /dev/null 2>&1
$ python3 spec_check.py rules.toml thesis.pdf
rule           measured                                            result
paper          210.0 × 297.0 mm                                    PASS
margin-left    35.0 mm at the least                                PASS
margin-right   25.0 mm at the least                                PASS
margin-top     26.3 mm at the least                                PASS
margin-bottom  25.0 mm at the least                                PASS
body-size      12 pt                                               PASS
line-spacing   17.9 pt between baselines                           PASS
chapter-titles 10 title lines, 10 bold, 24.8 pt at the least       PASS
page-numbers   9 of 9 numbered, 9 in place, 14.5 to 14.5 mm up     PASS
numbering      i to vi, then 1 to 4                                PASS
front-matter   5 parts on pages 2, 3, 4, 5, 6                      PASS
chapter-pages  2 of 2 chapters open a page                         PASS
citations      4 numbered, 0 by author and year                    PASS
13 rules: 13 pass, 0 fail

from session import files, run

# The template at work: typst/thesis.typ compiled with the first version of the exu-thesis template, then with the
# second, and each PDF checked against the same rules.
files("rules.toml", "spec_check.py", "typst/first/exu-thesis.typ=first/exu-thesis.typ",
      "typst/exu-thesis.typ=exu-thesis.typ", "typst/thesis.typ=thesis.typ", "typst/refs.bib=refs.bib")
run(r"""
sed 's#"exu-thesis.typ"#"first/exu-thesis.typ"#' thesis.typ > first.typ
typst compile first.typ
python3 spec_check.py rules.toml first.pdf
typst compile thesis.typ
python3 spec_check.py rules.toml thesis.pdf
""")

$ sed 's#"exu-thesis.typ"#"first/exu-thesis.typ"#' thesis.typ > first.typ
$ typst compile first.typ
$ python3 spec_check.py rules.toml first.pdf
rule           measured                                            result
paper          210.0 × 297.0 mm                                    PASS
margin-left    35.0 mm at the least                                PASS
margin-right   24.2 mm at the least                                PASS
margin-top     25.4 mm at the least                                PASS
margin-bottom  27.7 mm at the least                                PASS
body-size      12 pt                                               PASS
line-spacing   18 pt between baselines                             PASS
chapter-titles 10 title lines, 10 bold, 20.0 pt at the least       PASS
page-numbers   9 of 9 numbered, 9 in place, 13.3 to 13.3 mm up     PASS
numbering      page 1 is (empty), not i                            FAIL
front-matter   5 parts on pages 2, 3, 4, 5, 6                      PASS
chapter-pages  2 of 2 chapters open a page                         PASS
citations      4 numbered, 0 by author and year                    PASS
13 rules: 12 pass, 1 fail
$ typst compile thesis.typ
$ python3 spec_check.py rules.toml thesis.pdf
rule           measured                                            result
paper          210.0 × 297.0 mm                                    PASS
margin-left    35.0 mm at the least                                PASS
margin-right   25.0 mm at the least                                PASS
margin-top     25.4 mm at the least                                PASS
margin-bottom  27.7 mm at the least                                PASS
body-size      12 pt                                               PASS
line-spacing   18 pt between baselines                             PASS
chapter-titles 10 title lines, 10 bold, 20.0 pt at the least       PASS
page-numbers   9 of 9 numbered, 9 in place, 13.3 to 13.3 mm up     PASS
numbering      i to vi, then 1 to 4                                PASS
front-matter   5 parts on pages 2, 3, 4, 5, 6                      PASS
chapter-pages  2 of 2 chapters open a page                         PASS
citations      4 numbered, 0 by author and year                    PASS
13 rules: 13 pass, 0 fail