write_first_page_first.py

"""Lays a whole novel out, writes it twice — the ordinary way, then first page
first — and publishes the book written first page first, closed by a page stating
how much of each reading software must hold before it can show page one.

The Python twin of the `write_first_page_first` example in Rust. An ordinary PDF
is read from the end: the table saying where every object lives sits after every
object, so reading software has to hold the whole file before it can draw anything at
all. A file written first page first carries the first page, what that page draws
with, and a table stating where every other page begins, all at the head of the
file — so page one appears while the rest is still on its way, and page fifty is
one stretch of bytes to ask for.

The document measured is a novel carried in full, laid out by the same code as
`write_english_book`. It is built once and written both ways, so the two figures
are two spellings of one document, and the file this leaves behind is that same
book: reading software that opens it shows page one while the rest of the novel is still
arriving.

The closing page is added after the two figures are read, so what it states is the
book alone. The words on it are held in `Words`, once per language, and
`HQF_PDF_LANG` picks which set is drawn. The figures are not language: they are read
off the two files.

A second path, if one is given, is where the book is written the ordinary way, so
that the two spellings of one document can be handed to reading software side by side.

Usage: python examples/write_first_page_first.py [out.pdf] [ordinary.pdf]
       HQF_PDF_LANG=fr python examples/write_first_page_first.py
"""

from __future__ import annotations

import sys
from dataclasses import dataclass
from pathlib import Path

import _book
import _language
import _licence
import _out

import hqf_pdf

# Where the committed fonts sit.
FONT_DIR = _out.ROOT / "crates" / "hqf-pdf" / "tests" / "fonts"

# The chapter titles as English sets them.
#
# The file writes them in capitals throughout, which English does not do. That is undone
# here -- nothing else is, and the Rust twin carries the same list, checked letter for
# letter against the file.
TITLES = (
    "Playing Pilgrims",
    "A Merry Christmas",
    "The Laurence Boy",
    "Burdens",
    "Being Neighborly",
    "Beth Finds the Palace Beautiful",
    "Amy’s Valley of Humiliation",
    "Jo Meets Apollyon",
    "Meg Goes to Vanity Fair",
    "The P.C. and P.O.",
    "Experiments",
    "Camp Laurence",
    "Castles in the Air",
    "Secrets",
    "A Telegram",
    "Letters",
    "Little Faithful",
    "Dark Days",
    "Amy’s Will",
    "Confidential",
    "Laurie Makes Mischief, and Jo Makes Peace",
    "Pleasant Meadows",
    "Aunt March Settles the Question",
    "Gossip",
    "The First Wedding",
    "Artistic Attempts",
    "Literary Lessons",
    "Domestic Experiences",
    "Calls",
    "Consequences",
    "Our Foreign Correspondent",
    "Tender Troubles",
    "Jo’s Journal",
    "Friend",
    "Heartache",
    "Beth’s Secret",
    "New Impressions",
    "On the Shelf",
    "Lazy Laurence",
    "The Valley of the Shadow",
    "Learning to Forget",
    "All Alone",
    "Surprises",
    "My Lord and Lady",
    "Daisy and Demi",
    "Under the Umbrella",
    "Harvest Time",
)

# The novel this lays out, carried in full. Its file opens a chapter on a line that
# reads `CHAPTER I.`, and it holds forty-seven of them.
#
# One book is drawn whatever language the closing page is written in: what is being
# shown is the shape of the file, and the longer the book the plainer it shows. The page
# that closes it names the book, so a reader of either language is told what was
# measured.
BOOK = _book.Book(
    title="Little Women",
    author="Louisa May Alcott",
    file="littlewomen.txt",
    mark_before="CHAPTER ",
    mark_after=".",
    chapters=47,
    contents_title="Contents",
    titles=TITLES,
)


@dataclass(frozen=True)
class Words:
    """Every word the closing page draws, in one language.

    What is not language stays out of it: the three figures and the page count are
    read off the files themselves.
    """

    # The line across the top of the page.
    title: str
    # What writing a file first page first does, in two paragraphs.
    why: str
    # The heading over the three figures.
    figures: str
    # What was measured, cut where the page count goes in. The name of the book stands
    # in the first half.
    subject_before: str
    subject_after: str
    # The label on what reading software waits for in the ordinary file.
    ordinary: str
    # The label on what it waits for in the file written first page first.
    reordered: str
    # The label on the difference between the two.
    held_back: str
    # What a figure is counted in.
    unit: str
    # The closing note, cut where the share goes into it.
    note_before: str
    note_after: str
    # The line saying what this very file is.
    itself: str

    def subject(self, pages: int) -> str:
        """What was measured, over `pages` pages."""
        return f"{self.subject_before}{pages}{self.subject_after}"

    def note(self, share: int) -> str:
        """The closing note, with the share reading software waits for in it."""
        return f"{self.note_before}{share}{self.note_after}"


# The page in English.
ENGLISH = Words(
    title="What reading software waits for before page one",
    why=(
        "An ordinary PDF is read from the end. The table saying where every "
        "object lives is written after every object, so reading software has to "
        "hold the whole file before it can show a single page — however few of "
        "them it means to look at.\n"
        "Written first page first, the same document carries page one, what "
        "page one draws with, and a table stating where every other page "
        "begins and ends, all at the head of the file. Page one appears while "
        "the rest is still arriving, and page fifty is one stretch of bytes to "
        "ask for rather than a whole document to fetch."
    ),
    figures="The same book, measured twice",
    subject_before=(
        "The book measured here is Little Women, by Louisa May "
        "Alcott, carried in full over "
    ),
    subject_after=(
        " pages, each of them headed, numbered and reached from a "
        "contents a reader can click. This closing page is the only "
        "thing added to it, and the figures below are the book "
        "without it."
    ),
    ordinary="Written the ordinary way",
    reordered="Written first page first",
    held_back="No longer waited for",
    unit="bytes",
    note_before="Reading software given this file shows page one after ",
    note_after=(
        " per cent of it has arrived, and reads the first chapter while "
        "the last one is still on its way. The book is the same one "
        "either way: reading software that knows nothing of any of this opens "
        "the file as it opens every other."
    ),
    itself=(
        "The pages before this one are that book, written first page first. "
        "A reader who has read them has read one of the two documents "
        "being measured."
    ),
)

# The page in French.
FRENCH = Words(
    title="Ce que le logiciel de lecture attend avant la page un",
    why=(
        ("Un PDF ordinaire se lit par la fin. La table qui indique où se trouve chaque"
         " objet est écrite après tous les objets : le logiciel de lecture doit donc "
         "recevoir le fichier entier avant de pouvoir afficher une seule page — même "
         "s’il ne compte en regarder qu’une.\nÉcrit première page en tête, le même "
         "document contient, dès le début du fichier, la page un, ce dont elle a "
         "besoin pour s’afficher, et une table qui indique où commence et où finit "
         "chacune des autres pages. La page un s’affiche pendant que le reste arrive, "
         "et la page cinquante n’est qu’une plage d’octets à demander, et non un "
         "document entier à rapatrier.")
    ),
    figures="Le même livre, mesuré deux fois",
    subject_before=(
        ("Le livre mesuré ici est Little Women, de Louisa May Alcott, reproduit en "
         "entier sur ")
    ),
    subject_after=(
        (" pages, chacune dotée d’un titre courant, numérotée et accessible depuis une"
         " table des matières cliquable. Cette page de fin est le seul ajout, et les "
         "chiffres ci-dessous concernent le livre sans elle.")
    ),
    ordinary="Écrit de la façon habituelle",
    reordered="Écrit première page en tête",
    held_back="Attente supprimée",
    unit="octets",
    note_before="Avec ce fichier, le logiciel de lecture affiche la page un dès que ",
    note_after=(
        (" pour cent du fichier est arrivé, et affiche le premier chapitre pendant que"
         " le dernier est encore en route. Dans les deux cas, le livre est le même : "
         "un logiciel de lecture qui ignore tout cela l’ouvre comme n’importe quel "
         "autre fichier.")
    ),
    itself=(
        ("Les pages qui précèdent celle-ci sont ce livre, écrit première page en tête."
         " Un lecteur qui les a lues a donc lu l’un des deux documents mesurés.")
    ),
)

# The page in Dutch.
DUTCH = Words(
    title="Waar leessoftware op wacht vóór pagina één",
    why=(
        "Een gewone pdf wordt vanaf het einde gelezen. De tabel die zegt waar elk "
        "object staat, wordt na alle objecten geschreven, dus leessoftware moet het "
        "hele bestand hebben voordat ze één pagina kan tonen, hoe weinig ze er ook "
        "wil zien.\nWordt de eerste pagina eerst geschreven, dan staan pagina één, "
        "alles waarmee pagina één getekend wordt en een tabel die zegt waar elke "
        "andere pagina begint en eindigt, allemaal aan het begin van het bestand. "
        "Pagina één verschijnt terwijl de rest nog binnenkomt, en pagina vijftig is "
        "één reeks bytes om op te vragen in plaats van een heel document om op te "
        "halen."
    ),
    figures="Hetzelfde boek, twee keer gemeten",
    subject_before=(
        "Het hier gemeten boek is Little Women (Onder moeders vleugels) van Louisa "
        "May Alcott, volledig, op"
    ),
    subject_after=(
        " pagina’s, elk met een kop, genummerd en bereikbaar via een klikbare "
        "inhoudsopgave. Deze slotpagina is het enige wat is toegevoegd, en de cijfers "
        "hieronder gelden voor het boek zonder deze pagina."
    ),
    ordinary="Op de gewone manier geschreven",
    reordered="Met pagina één voorop geschreven",
    held_back="Niet meer op gewacht",
    unit="bytes",
    note_before="Leessoftware die dit bestand krijgt, toont pagina één zodra",
    note_after=(
        " procent ervan binnen is, en leest het eerste hoofdstuk terwijl het laatste "
        "nog onderweg is. Het boek is in beide gevallen hetzelfde: leessoftware die "
        "hier niets van weet, opent het bestand zoals elk ander."
    ),
    itself=(
        "De pagina’s vóór deze zijn dat boek, met de eerste pagina eerst geschreven. "
        "Wie ze gelezen heeft, heeft een van de twee gemeten documenten gelezen."
    ),
)

# The page in Portuguese.
PORTUGUESE = Words(
    title="O que um leitor de PDF espera antes da página 1",
    why=(
        "Um PDF normal lê-se a partir do fim. A tabela que diz onde vive cada objeto "
        "é escrita depois de todos os objetos, por isso o programa de leitura tem de "
        "ter o ficheiro inteiro antes de mostrar uma só página, por poucas que queira "
        "ver.\nEscrito com a primeira página primeiro, o mesmo documento leva a "
        "página um, aquilo com que ela se desenha e uma tabela que diz onde começa e "
        "acaba cada uma das outras páginas, tudo no início do ficheiro. A página um "
        "aparece enquanto o resto ainda chega, e a página cinquenta é um troço de "
        "bytes a pedir e não um documento inteiro a descarregar."
    ),
    figures="O mesmo livro, medido duas vezes",
    subject_before=(
        "O livro medido aqui é Little Women (Mulherzinhas), de Louisa May Alcott, "
        "completo em"
    ),
    subject_after=(
        " páginas, cada uma com cabeçalho, numerada e acessível a partir de um índice "
        "clicável. Esta página final é a única coisa acrescentada, e os números "
        "abaixo são o livro sem ela."
    ),
    ordinary="Escrito da forma normal",
    reordered="Escrito com a página um à frente",
    held_back="Já não se espera",
    unit="bytes",
    note_before="Um programa de leitura mostra a página um deste ficheiro quando chegaram",
    note_after=(
        " por cento dele, e lê o primeiro capítulo enquanto o último ainda vem a "
        "caminho. O livro é o mesmo nos dois casos: um programa de leitura que não "
        "sabe nada disto abre o ficheiro como qualquer outro."
    ),
    itself=(
        "As páginas antes desta são esse livro, escrito com a primeira página "
        "primeiro. Quem as leu, leu um dos dois documentos medidos."
    ),
)

# The page in Italian.
ITALIAN = Words(
    title="Cosa aspetta un lettore PDF prima della pagina 1",
    why=(
        "Un PDF normale si legge dalla fine. La tabella che dice dove vive ogni "
        "oggetto è scritta dopo tutti gli oggetti, così il programma di lettura deve "
        "avere l’intero file prima di mostrare una sola pagina, per quanto poche ne "
        "voglia guardare.\nScritto con la prima pagina in testa, lo stesso documento "
        "porta la pagina uno, ciò con cui essa si disegna e una tabella che dice dove "
        "inizia e finisce ogni altra pagina, tutto all’inizio del file. La pagina uno "
        "appare mentre il resto sta ancora arrivando, e la pagina cinquanta è un "
        "tratto di byte da chiedere e non un documento intero da scaricare."
    ),
    figures="Lo stesso libro, misurato due volte",
    subject_before=(
        "Il libro misurato qui è Little Women (Piccole donne), di Louisa May Alcott, "
        "completo su"
    ),
    subject_after=(
        " pagine, ciascuna con intestazione, numerata e raggiungibile da un indice "
        "cliccabile. Questa pagina finale è l’unica aggiunta, e le cifre qui sotto "
        "sono il libro senza di essa."
    ),
    ordinary="Scritto nel modo normale",
    reordered="Scritto con la prima pagina in testa",
    held_back="Non più atteso",
    unit="byte",
    note_before="Un programma di lettura mostra la pagina uno di questo file quando ne è arrivato il",
    note_after=(
        " per cento, e legge il primo capitolo mentre l’ultimo è ancora in viaggio. "
        "Il libro è lo stesso nei due casi: un programma di lettura che non sa nulla "
        "di tutto questo apre il file come ogni altro."
    ),
    itself=(
        "Le pagine prima di questa sono quel libro, scritto con la prima pagina in "
        "testa. Chi le ha lette ha letto uno dei due documenti misurati."
    ),
)

# The page in Spanish.
SPANISH = Words(
    title="Qué espera un lector de PDF antes de la página 1",
    why=(
        "Un PDF normal se lee desde el final. La tabla que dice dónde está cada "
        "objeto se escribe después de todos los objetos, así que el programa de "
        "lectura tiene que tener el archivo entero antes de mostrar una sola página, "
        "por pocas que quiera mirar.\nEscrito con la primera página primero, el mismo "
        "documento lleva la página uno, lo que ella usa para dibujarse y una tabla "
        "que dice dónde empieza y acaba cada una de las demás páginas, todo al "
        "principio del archivo. La página uno aparece mientras llega el resto, y la "
        "página cincuenta es un tramo de bytes que pedir y no un documento entero que "
        "descargar."
    ),
    figures="El mismo libro, medido dos veces",
    subject_before=(
        "El libro medido aquí es Little Women (Mujercitas), de Louisa May Alcott, "
        "completo en "
    ),
    subject_after=(
        " páginas, cada una con cabecera, numerada y accesible desde un índice en el "
        "que se puede hacer clic. Esta página final es lo único añadido, y las cifras "
        "de abajo son el libro sin ella."
    ),
    ordinary="Escrito de la forma normal",
    reordered="Escrito con la primera página primero",
    held_back="Ya no se espera",
    unit="bytes",
    note_before="Un programa de lectura muestra la página uno de este archivo cuando ha llegado el ",
    note_after=(
        " por ciento, y lee el primer capítulo mientras el último aún está en camino. "
        "El libro es el mismo en los dos casos: un programa de lectura que no sabe "
        "nada de esto abre el archivo como cualquier otro."
    ),
    itself=(
        "Las páginas anteriores son ese libro, escrito con la primera página primero. "
        "Quien las haya leído ha leído uno de los dos documentos medidos."
    ),
)

# The page in German.
GERMAN = Words(
    title="Worauf eine Lesesoftware vor Seite eins wartet",
    why=(
        "Ein gewöhnliches PDF wird vom Ende her gelesen. Die Tabelle, die sagt, wo "
        "jedes Objekt liegt, steht hinter allen Objekten, also muss eine Lesesoftware "
        "die ganze Datei haben, bevor sie eine einzige Seite zeigen kann — wie wenige "
        "Seiten man auch ansehen will.\nMit der ersten Seite zuerst geschrieben, "
        "trägt dasselbe Dokument Seite eins, was Seite eins zur Anzeige braucht, und "
        "eine Tabelle, die sagt, wo jede andere Seite beginnt und endet, alles am "
        "Anfang der Datei. Seite eins erscheint, während der Rest noch eintrifft, und "
        "Seite fünfzig ist ein Byte-Bereich, den man anfordert, statt eines ganzen "
        "Dokuments, das man holen muss."
    ),
    figures="Dasselbe Buch, zweimal gemessen",
    subject_before=(
        "Das hier gemessene Buch ist Little Women von Louisa May Alcott, vollständig "
        "auf "
    ),
    subject_after=(
        " Seiten, jede mit Kopfzeile und Nummer und über ein anklickbares "
        "Inhaltsverzeichnis erreichbar. Diese Schlussseite ist das Einzige, was "
        "hinzugefügt wurde, und die Zahlen unten gelten für das Buch ohne sie."
    ),
    ordinary="Gewöhnlich geschrieben",
    reordered="Erste Seite zuerst",
    held_back="Nicht mehr abzuwarten",
    unit="Bytes",
    note_before="Eine Lesesoftware, die diese Datei erhält, zeigt Seite eins, sobald ",
    note_after=(
        " Prozent davon eingetroffen sind, und liest das erste Kapitel, während das "
        "letzte noch unterwegs ist. Das Buch ist in beiden Fällen dasselbe: Eine "
        "Lesesoftware, die von alldem nichts weiß, öffnet die Datei wie jede andere."
    ),
    itself=(
        "Die Seiten vor dieser sind dieses Buch, mit der ersten Seite zuerst "
        "geschrieben. Wer sie gelesen hat, hat eines der beiden gemessenen Dokumente "
        "gelesen."
    ),
)

# Every language the example is written in. A language is added by writing its own set
# of words and naming it here.
WORDS = {_language.ENGLISH: ENGLISH, _language.FRENCH: FRENCH, _language.GERMAN: GERMAN, _language.SPANISH: SPANISH, _language.ITALIAN: ITALIAN, _language.PORTUGUESE: PORTUGUESE, _language.DUTCH: DUTCH}

# The left edge of everything on the page.
X = 60.0

# The width every block is broken to.
ROOM = 475.0

# How far apart two lines of a block sit, which is also the least room a block leaves
# between its last line and whatever stands under it.
BLOCK_LEADING = 14.0

# The baseline the title sits on.
TITLE_TOP = 780.0

# The top of the block that says what writing a file first page first does.
WHY_TOP = 748.0

# The top of the line naming what was measured.
SUBJECT_TOP = 606.0

# The top of the heading over the three figures.
FIGURES_TOP = 520.0

# The top of the first of the three figures.
FIRST_FIGURE_TOP = 494.0

# How far apart two figures sit.
FIGURE_DROP = 20.0

# Where the number of a figure begins, its label sitting at X.
NUMBER_X = X + 190.0

# The top of the closing note.
NOTE_TOP = 406.0

# The top of the line saying what this file is.
ITSELF_TOP = 320.0


def laid_out(font: hqf_pdf.Font) -> tuple[hqf_pdf.Document, hqf_pdf.FontHandle]:
    """The book, laid out whole, and the handle its text is drawn through."""
    document = hqf_pdf.Document()
    document.set_license(_licence.licensed())
    handle = document.add_font(font)

    text = BOOK.path().read_text(encoding="utf-8")
    _book.lay_out(document, handle, BOOK, text)
    return document, handle


def waited_for(data: bytes) -> int:
    """How many bytes of `data` reading software holds before it can draw page one.

    A file written first page first says so itself: the `/E` entry of its parameter
    dictionary is the offset of the end of the first page, and everything before it
    is what reading software needs. A file written the ordinary way states no such thing, and
    the answer for it is the whole file.
    """
    head = data[: min(1024, len(data))]
    at = head.find(b"/E ")
    if at < 0:
        return len(data)
    at += 3
    while head[at : at + 1] == b" ":
        at += 1
    value = 0
    while head[at : at + 1].isdigit():
        value = value * 10 + int(head[at : at + 1])
        at += 1
    return value


def counted(value: int) -> str:
    """A count of bytes, its thousands held apart by a space."""
    digits = str(value)
    grouped = ""
    for index, digit in enumerate(digits):
        if index > 0 and (len(digits) - index) % 3 == 0:
            grouped += " "
        grouped += digit
    return grouped


def share_waited_for(ordinary: int, reordered: int) -> int:
    """The share of a file reading software holds before page one appears, in whole per cent.

    Whole numbers throughout: a share written as a fraction would be spelled by
    whatever language drew it, and the two twins must write the same bytes.
    """
    if ordinary == 0:
        return 0
    return reordered * 100 // ordinary


def report(
    handle: hqf_pdf.FontHandle,
    words: Words,
    pages: int,
    ordinary: int,
    reordered: int,
) -> hqf_pdf.Content:
    """The page that closes the book and reports the two figures."""
    content = hqf_pdf.Content()

    title = hqf_pdf.TextFlow(handle, 18.0)
    title.draw(content, title.break_lines(words.title, ROOM), X, TITLE_TOP, ROOM)

    why = hqf_pdf.TextFlow(handle, 10.0, leading=BLOCK_LEADING)
    why.draw(content, why.break_lines(words.why, ROOM), X, WHY_TOP, ROOM)

    subject = hqf_pdf.TextFlow(handle, 10.0, leading=BLOCK_LEADING)
    subject.draw(
        content, subject.break_lines(words.subject(pages), ROOM), X, SUBJECT_TOP, ROOM
    )

    heading = hqf_pdf.TextFlow(handle, 11.0)
    heading.draw(content, heading.break_lines(words.figures, ROOM), X, FIGURES_TOP, ROOM)

    rows = (
        (words.ordinary, ordinary),
        (words.reordered, reordered),
        (words.held_back, ordinary - reordered),
    )
    for index, (label, figure) in enumerate(rows):
        top = FIRST_FIGURE_TOP - FIGURE_DROP * float(index)
        line = hqf_pdf.TextFlow(handle, 10.0)
        line.draw(content, line.break_lines(label, ROOM), X, top, ROOM)

        stated = f"{counted(figure)} {words.unit}"
        number = hqf_pdf.TextFlow(handle, 10.0)
        number.draw(content, number.break_lines(stated, ROOM), NUMBER_X, top, ROOM)

    note = words.note(share_waited_for(ordinary, reordered))
    closing = hqf_pdf.TextFlow(handle, 10.0, leading=BLOCK_LEADING)
    closing.draw(content, closing.break_lines(note, ROOM), X, NOTE_TOP, ROOM)

    itself = hqf_pdf.TextFlow(handle, 10.0, leading=BLOCK_LEADING)
    itself.draw(content, itself.break_lines(words.itself, ROOM), X, ITSELF_TOP, ROOM)
    return content


def main() -> None:
    language = _language.from_environment()
    words = _language.words_of(WORDS, language)

    out = _out.output_path(
        Path(_language.file_name("first_page_first.pdf", language)).stem
    )

    font = hqf_pdf.Font.from_path(FONT_DIR / "DejaVuSans.ttf")

    # One book, written twice: the two figures are two spellings of it, not two
    # documents that happen to hold the same thing.
    document, handle = laid_out(font)
    the_ordinary_way = document.to_bytes()
    document.set_linearized(True)
    reordered = document.to_bytes()

    ordinary = waited_for(the_ordinary_way)
    first_page = waited_for(reordered)
    pages = document.page_count

    if len(sys.argv) > 2:
        beside = Path(sys.argv[2])
        beside.parent.mkdir(parents=True, exist_ok=True)
        beside.write_bytes(the_ordinary_way)
        print(f"wrote {beside}: {len(the_ordinary_way)} bytes")

    page = hqf_pdf.Page.a4()
    page.set_content(report(handle, words, pages, ordinary, first_page))
    document.add_page(page)

    data = document.to_bytes()
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_bytes(data)
    print(f"wrote {out}: {len(data)} bytes")


if __name__ == "__main__":
    main()