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 dit où vit chaque "
        "objet est écrite après tous les objets : le logiciel de lecture doit "
        "donc tenir le fichier entier avant de pouvoir afficher une seule page "
        "— même s'il n'a l'intention d'en regarder qu'une.\n"
        "Écrit première page en tête, le même document porte la page un, ce "
        "que la page un dessine, et une table qui dit où commence et où finit "
        "chacune des autres pages, le tout au début du fichier. La page un "
        "paraît pendant que le reste arrive, et la page cinquante est une "
        "tranche d'octets à demander plutôt qu'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, porté en entier sur "
    ),
    subject_after=(
        " pages, chacune coiffée, numérotée et atteinte depuis une "
        "table des matières où le lecteur peut cliquer. Cette page "
        "de fin est la seule chose qui lui ait été ajoutée, et les "
        "chiffres ci-dessous sont ceux du livre sans elle."
    ),
    ordinary="Écrit à l'ordinaire",
    reordered="Écrit première page en tête",
    held_back="Plus attendu",
    unit="octets",
    note_before="Sur ce fichier, le logiciel de lecture affiche la page un dès que ",
    note_after=(
        " pour cent est arrivé, et lit le premier chapitre pendant que "
        "le dernier arrive encore. Le livre est le même des deux "
        "côtés : un logiciel de lecture qui ne sait rien de tout cela l'ouvre "
        "comme il ouvre les autres."
    ),
    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."
    ),
)

# 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}

# 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()