pytex-preprocessor 1.0.6__tar.gz → 1.2.0__tar.gz

{pytex_preprocessor-1.0.6 → pytex_preprocessor-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytex-preprocessor
-Version: 1.0.6
+Version: 1.2.0
 Summary: Type-safe LaTeX document generation with Python
 Author-email: Frederik Beimgraben <frederik@beimgraben.net>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -692,62 +692,66 @@ Dynamic: license-file
 
 # PyTeX
 
-Type-safe LaTeX document generation with Python. Build a document as a tree of
-typed `TeX` nodes and render it to a `.tex` file, or drop inline Python
-expressions into an existing `.tex` source and have them evaluated at render
-time. Requires Python 3.13+.
+PyTeX builds a LaTeX document from Python, and a type checker can check the
+Python code. You build the document as a node tree of typed `TeX` nodes. Then
+you render it to a rendered `.tex` file. You can also put inline Python
+expressions into an existing `.tex` source. PyTeX evaluates them when it
+renders the file. PyTeX needs Python 3.13 or later.
 
-A `TeX` node is an immutable dataclass with a `.rendered` property. The public
-API mirrors LaTeX control sequences as PascalCase factories (`Section`,
-`Bold`, `Frac`, `Title`, ...), so a document reads like the LaTeX it produces
-while staying checkable by a type checker. Nodes track their package
-requirements, so the preamble is assembled automatically from what the body
-uses.
+A `TeX` node is a dataclass with a `.rendered` property. Most node types are
+immutable. The types `Document`, `Raw` and `IncludeImage` stay mutable. The
+public API mirrors the LaTeX control sequences as PascalCase factories
+(`Section`, `Bold`, `Frac`, `Title`, ...), so a document reads like the LaTeX
+it renders. A node requires a package, so PyTeX assembles the preamble from
+the package requirements that the body uses.
 
 ## Install
 
 ### Prebuilt binary
 
-Each release attaches standalone `pytex` binaries (Linux/macOS/Windows) — no
-Python or `pip` needed. Download one from the
+Each release attaches a standalone `pytex` binary for Linux, macOS and Windows.
+The binary needs neither Python nor `pip`. Download one from the
 [Releases](https://github.com/frederikbeimgraben/PyTeX-Preprocessor/releases)
-page, make it executable, and run it. The binary bundles its own interpreter
-plus common data packages (numpy, pandas, openpyxl/calamine for spreadsheets,
-Pillow, PyYAML), so documents can `import` those without installing anything;
-see [`packaging/`](packaging/). It is built on Python 3.14, so documents may use
-`tex(t"...")` even on machines without 3.14. (`--build` still needs `tectonic`,
-which pytex downloads on first use.)
+page, make it executable, and run it.
+
+The binary holds its own interpreter and common data packages. Those packages
+are numpy, pandas, openpyxl and calamine for spreadsheets, Pillow, and PyYAML.
+A document can `import` those without an install (see
+[`packaging/`](packaging/)). PyTeX builds the binary on Python 3.14, so a
+document can use `tex(t"...")` on a machine without Python 3.14. A build with
+`--build` still needs the tectonic binary, which PyTeX downloads on first use.
 
 ### From PyPI
 
-To use the `pytex` command anywhere, install it as an isolated tool with
+To get the `pytex` command everywhere, install it as an isolated tool with
 [pipx](https://pipx.pypa.io/):
 
 ```sh
 pipx install pytex-preprocessor
 ```
 
-It is also available via plain `pip install pytex-preprocessor`.
+A plain `pip install pytex-preprocessor` also works.
 
-For development, work in a virtualenv with an editable install instead:
+For development, work in a virtualenv and make an editable install instead:
 
 ```sh
 python -m venv venv && . venv/bin/activate
 pip install -e .            # add [dev] for pytest, ruff, basedpyright
 ```
 
-External tools, each needed only for the matching feature:
+PyTeX uses these external tools. Each tool serves one feature:
 
-- `tectonic` — compile to PDF (`--build`). If not on `PATH`, the build
-  downloads a self-contained binary into a temp folder and reuses it.
-- `inkscape` — `SVG` image conversion.
-- `makeindex` (from a TeX distribution, e.g. TeX Live) — resolve
-  glossaries/acronyms.
+- `tectonic` — compiles the rendered `.tex` file to PDF (`--build`). If the
+  tectonic binary is not on `PATH`, PyTeX downloads a self-contained binary
+  into `$XDG_CACHE_HOME/pytex` or `~/.cache/pytex` and reuses it.
+- `inkscape` — converts an `SVG` image to PDF.
+- `makeindex` (from a TeX distribution, for example TeX Live) — resolves the
+  `glossaries` entries and the acronyms.
 
 ## Quick start
 
-A `.tex.py` file is plain Python exposing a module-level `__pytex__` that holds
-a `TeX` node:
+A `.tex.py` file is plain Python that defines the `__pytex__` node at module
+level. That node holds a `TeX` node:
 
 ```py
 from pytex.commands.builtin import Bold, Emph, Section, Title, MakeTitle
@@ -772,14 +776,15 @@ pytex example.tex.py          # render -> build/example.out.tex
 pytex example.tex.py --build  # render + compile -> build/example.out.pdf
 ```
 
-Bare strings are coerced to text nodes and LaTeX-escaped.
+PyTeX coerces a bare string to a text node and escapes it for LaTeX.
 
 ### Template strings (Python 3.14+)
 
 On Python 3.14, `pytex.tex` accepts a [PEP 750](https://peps.python.org/pep-0750/)
-template string and builds a `TeX` tree from it. Static parts are literal LaTeX;
-interpolations are LaTeX-escaped when they are plain values and spliced as-is
-when they are `TeX` nodes (nested template strings and lists are handled too):
+template string and builds a node tree from it. The static parts stay literal
+LaTeX. For an interpolation, `tex` escapes a plain value for LaTeX, and puts a
+`TeX` node into the node tree without a change. It handles a nested template
+string, a list and a tuple the same way:
 
 ```py
 from pytex import tex
@@ -788,22 +793,23 @@ name = "Q&A: 50%"
 body = tex(t"{Bold('Heading')} — {name}")   # node spliced; name -> "Q\&A: 50\%"
 ```
 
-`tex` is only exported on 3.14+; the rest of the library runs on 3.13.
+PyTeX exports `tex` only on Python 3.14 and later. The rest of the library runs
+on Python 3.13.
 
 ## The `pytex` command
 
-The input file is dispatched by extension:
+PyTeX dispatches the input file by its extension:
 
 | Extension | Handling |
 | --- | --- |
-| `.py` | imported as a module; its `__pytex__` node is rendered. Convention: name it `<doc>.tex.py`. |
-| `.tex` | wrapped in `IncludeTeX`; inline `\iffalse{pytex(...)}\fi` markers are evaluated, then rendered. Convention: `<doc>.py.tex`. |
-| `.md` / `.markdown` | converted to nodes and wrapped in a document according to `--variant` (see below). Without `--variant` the style is auto-detected. |
+| `.py` | PyTeX imports the file as a module and renders its `__pytex__` node. By convention, name the file `<doc>.tex.py`. |
+| `.tex` | PyTeX wraps the file in `IncludeTeX`, evaluates each inline `pytex(...)` marker, then renders the file. By convention, name the file `<doc>.py.tex`. |
+| `.md` / `.markdown` | The Markdown converter turns the file into nodes. PyTeX wraps them in a document that `--variant` picks (see below). Without `--variant`, PyTeX detects the variant. |
 
-### Inline replacements in `.tex`
+### Inline `pytex(...)` markers in `.tex`
 
-Any registered factory is in scope inside a marker. The `\iffalse ... \fi` pair
-is a LaTeX no-op, so the source still compiles as-is without PyTeX:
+Every registered factory is in scope inside a marker. The `\iffalse ... \fi`
+pair is a LaTeX no-op, so LaTeX still compiles the source without PyTeX:
 
 ```tex
 Today is \iffalse{pytex(Today())}\fi.
@@ -815,73 +821,76 @@ Plain Python works too: $3^2 = \iffalse{pytex(3 ** 2)}\fi$.
 
 | Flag | Default | Meaning |
 | --- | --- | --- |
-| `-o`, `--output` | `<build-dir>/<input>.out.tex` | rendered LaTeX output path |
-| `-b`, `--build` | off | compile the rendered `.tex` to PDF with tectonic |
-| `--build-dir DIR` | `build` | directory for artifacts and tectonic output |
-| `--no-shell-escape` | shell-escape on | disable shell-escape |
-| `-t`, `--tree` | off | also print the input's `TeX`-node tree (`tree`-style) before rendering/building |
-| `-f`, `--force` | off | skip the optimize + analysis pass and build even if problems are found |
-| `--variant STYLE` | auto-detect | Markdown output style (`plain`, `report`, `report-makers`, `protocol-asta`, `protocol-stupa`) |
-| `--config JSON` | none | JSON object of document-class params, merged over the frontmatter |
-| `--untrusted` | off (trusted) | render foreign input through the trust policy (see [Security](#security-and-trust)) |
-| `--trust-level LEVEL` | `trusted` | `trusted`, `sandboxed`, or `untrusted` (see [Security](#security-and-trust)) |
-
-Shell-escape is on by default because inline images decode their base64
-payloads at compile time. The build runs tectonic, then `makeindex` (for
-`glossaries`/acronyms), then reruns tectonic when an index changed.
+| `-o`, `--output` | `<build-dir>/<input>.out.tex` | path of the rendered `.tex` file |
+| `-b`, `--build` | off | compile the rendered `.tex` file to PDF with the tectonic binary |
+| `--build-dir DIR` | `build` | build directory for the artifacts and the tectonic output |
+| `--no-shell-escape` | shell-escape on | turn shell-escape off |
+| `-t`, `--tree` | off | also print the node tree of the input file in `tree` style before the render |
+| `-f`, `--force` | off | skip the optimize pass and the analysis pass, and build even when PyTeX finds a problem |
+| `--variant STYLE` | auto-detect | variant for a Markdown input file (`plain`, `report`, `report-makers`, `protocol`, `protocol-asta`, `protocol-stupa`) |
+| `--config JSON` | none | JSON object of document-class parameters. `--config` overrides the frontmatter. |
+| `--untrusted` | off (trusted) | render input from a source you do not trust through the trust policy (see [Security](#security-and-trust)) |
+| `--trust-level LEVEL` | `trusted` | the trust level: `trusted`, `sandboxed`, or `untrusted` (see [Security](#security-and-trust)) |
+
+Shell-escape is on by default, because an inline image decodes its base64
+data during the compile pass. The build runs the tectonic binary, then the
+makeindex step for `glossaries` and the acronyms. When the makeindex step
+rebuilds an index, the build runs one more compile pass.
 
 ### Security and trust
 
-By default the CLI runs in a **trusted** context: it imports and executes `.py`
-inputs, evaluates `.tex` `pytex(...)` replacements and Markdown `eval`
-comments, and enables shell-escape. That is code execution by design — it is
-how PyTeX documents work — and is safe **only for documents you wrote
-yourself**. Do not run the default CLI on a file from a source you do not
-trust.
-
-To render input from a foreign or untrusted source, pass `--untrusted` (or
-`--trust-level {sandboxed,untrusted}`). These route the build through the
-`pytex_api` trust policy, which:
-
-- refuses `.py` / `.tex.py` inputs (no Python execution),
-- leaves `.tex` `pytex(...)` markers and Markdown `eval` comments inert,
-- forces shell-escape **off** and rejects code-/file-surface packages
-  (`minted`, `shellesc`, `pythontex`, …) and anything off the package
-  allowlist,
-- applies CPU/memory/output resource limits, and
-- for `sandboxed`, additionally requires the Podman OS sandbox for PDF builds.
-
-`--untrusted` is shorthand for `--trust-level untrusted`. The two flags are
-mutually exclusive; `trusted` is the default, so existing invocations are
-unchanged.
-
-Output is minimal and color-tagged (`==>`, `note:`, `warning:`, `error:`),
-following tectonic's style; on failure it points at the likely cause and the
-log file. Set `NO_COLOR` to disable color.
-
-### Pre-flight optimize + analysis
-
-Before rendering, the builder runs two render-equivalent passes over the node
-tree. First `Optimize` tidies the tree (flatten nested `Concat`s, drop empty
-nodes, turn whole-`Raw` LaTeX constructs into native nodes) without changing
-the output (it also expands inline `pytex(...)` markers and turns `Raw`
-comments and math — `\[...\]`, `\(...\)`, `$...$` — into native nodes). Then
-`pytex_analyze` checks for problems that LaTeX would only surface later (or
-silently):
-
-- references (`\ref`, `\cref`, `\autoref`, ...) to a label that is never
-  defined,
-- labels defined more than once,
-- `\includegraphics` paths that do not exist on disk.
-
-Missing-image issues are errors and abort the build; the rest are warnings.
-Pass `-f`/`--force` to skip both passes and build regardless.
+By default the `pytex` command runs at trust level `trusted`. At that level
+PyTeX imports and executes a `.py` input file. It evaluates each inline
+`pytex(...)` marker of a `.tex` input file and each Markdown `eval` comment. It
+also turns shell-escape on. This is code execution by design, because that is
+how a PyTeX document works. **Use the default only on a document you wrote
+yourself.**
+
+If the input file comes from a source you do not trust, pass `--untrusted` (or
+`--trust-level {sandboxed,untrusted}`). Both options route the build through
+the `pytex_api` trust policy. The trust policy:
+
+- refuses a `.py` or `.tex.py` input file, so PyTeX executes no Python,
+- leaves each inline `pytex(...)` marker and each Markdown `eval` comment
+  inert,
+- forces shell-escape **off**, and rejects a package that opens a
+  code-execution surface (`minted`, `shellesc`, `pythontex`, …) and every
+  package off the package allowlist,
+- applies the CPU, memory and output limits, and
+- needs the Podman sandbox for a PDF build at both trust levels. The level
+  `sandboxed` has a wider package allowlist than `untrusted`.
+
+`--untrusted` is shorthand for `--trust-level untrusted`. The two options are
+mutually exclusive. The default trust level is `trusted`, so an existing
+command line does not change.
+
+The `pytex` command prints short, color-tagged output (`==>`, `note:`,
+`warning:`, `error:`) in the style of tectonic. On a failure it names the
+likely cause and the log file. Set `NO_COLOR` to turn color off.
+
+### The optimize pass and the analysis pass
+
+Before PyTeX renders the node tree, it runs the optimize pass and then the
+analysis pass. The optimize pass tidies the node tree. It flattens a nested
+`Concat`, drops an empty node, and turns a whole-`Raw` LaTeX construct into a
+native node. It also expands each inline `pytex(...)` marker, and turns a `Raw`
+comment and `Raw` math (`\[...\]`, `\(...\)`, `$...$`) into a native node. The
+optimize pass is render-equivalent. The analysis pass then runs static checks
+for problems that LaTeX reports late or not at all:
+
+- a reference (`\ref`, `\cref`, `\autoref`, ...) to a label that no node
+  defines,
+- a label that more than one node defines,
+- an `\includegraphics` path that does not exist on disk.
+
+A missing image is an error and stops the build. Every other issue is a
+warning. To skip both passes and build anyway, pass `-f` or `--force`.
 
 ### Inspecting the node tree
 
-`--tree` prints the parsed `TeX`-node tree (then renders/builds as usual),
-useful for debugging how an input maps to nodes. Nodes that require a package
-are tagged with it (`[+package]`):
+`--tree` prints the node tree of the input file, then renders or builds as
+usual. Use it to see how PyTeX maps an input file to nodes. A node that
+requires a package carries a tag with the package name (`[+package]`):
 
 ```
 $ pytex example.tex.py --tree
@@ -897,22 +906,24 @@ Document (article)
 
 ## Packages
 
-`pytex` is the core; the rest are optional and build on it.
+`pytex` is the core package. Every other package is optional and builds on
+`pytex`.
 
 | Package | Provides |
 | --- | --- |
-| `pytex` | core node model, `Document`, math, tables, graphics, and factories for the common LaTeX packages (biblatex, cleveref, glossaries, hyperref, listings, ...). |
-| `pytex_koma` | KOMA-Script classes and commands (`Addchap`, `Minisec`, `KOMAoptions`, ...). |
+| `pytex` | the core node model, `Document`, math, tables, graphics, and the factories for the common LaTeX packages (biblatex, cleveref, glossaries, hyperref, listings, ...). |
+| `pytex_koma` | the KOMA-Script classes and commands (`Addchap`, `Minisec`, `KOMAoptions`, ...). |
 | `pytex_tikz` | TikZ pictures and primitives (`TikzPicture`, `Draw`, `Node`, `Circle`, ...). |
-| `pytex_components` | reusable, template-agnostic widgets: colored callout boxes (`ColoredBox` + presets), a voting tally, draft watermark, word-count and smart-pagebreak macros, a clickable author-year citation, German cleveref labels. |
-| `pytex_markdown` | Markdown -> native `TeX` conversion (see below), including `pytex_markdown.protocol` (STUPA/AStA meeting minutes) and `pytex_markdown.frontmatter` (YAML frontmatter parsing). |
-| `pytex_analyze` | static checks over the node tree (dangling refs, duplicate labels, missing images), plus `Optimize` to simplify a tree render-equivalently. |
-| `pytex_hsrtreport` | HSRT report document class, title pages, logos, and HSRT colors/fonts/glossary helpers. Builds on `pytex_components` (and re-exports it for compatibility). |
-| `pytex_protocol` | deprecated alias for `pytex_markdown.protocol` (kept as a re-export shim). |
+| `pytex_components` | the components that any document can use: colored boxes (`ColoredBox` and the presets), a voting tally, a draft watermark, word-count and smart-pagebreak macros, a clickable author-year citation, and German cleveref labels. |
+| `pytex_markdown` | the Markdown converter, which turns Markdown into native `TeX` nodes (see below). It holds `pytex_markdown.protocol` for a StuPa or AStA meeting protocol, and `pytex_markdown.frontmatter` for the YAML frontmatter. |
+| `pytex_analyze` | the analysis pass, which runs static checks over the node tree for a dangling reference, a duplicate label and a missing image. It also holds `Optimize`, the render-equivalent optimize pass. |
+| `pytex_hsrtreport` | the HSRT report document class, the title pages, the logos, and the HSRT color, font and glossary helpers. It builds on `pytex_components` and re-exports it, so an older import keeps working. |
+| `pytex_protocol` | the deprecated alias for `pytex_markdown.protocol`. It stays as a re-export shim. |
 
 ## Markdown
 
-`pytex_markdown` converts Markdown to native `TeX` nodes (via `marko`):
+The Markdown converter in `pytex_markdown` turns Markdown into native `TeX`
+nodes. It parses the source with `marko`:
 
 ```py
 from pytex_markdown import Markdown, IncludeMarkdown
@@ -921,83 +932,88 @@ body = Markdown("# Title\n\nText with **bold**, `code`, [a link](https://x).")
 body = IncludeMarkdown("notes.md", base_level=-1)   # base_level=-1: # -> \chapter
 ```
 
-Headings, emphasis, inline/fenced code, lists, links, images, GFM tables, block
-quotes and thematic breaks map to the standard pytex library; text is
-LaTeX-escaped. Some extras on top of plain Markdown:
+A heading, emphasis, inline code and fenced code map to the core `pytex`
+library. A list, a link, an image, a GFM table, a block quote and a thematic
+break map to it too. The Markdown converter escapes the text for LaTeX. It adds
+these extras to plain Markdown:
 
-- **GitHub-style callouts** become colored boxes (from `pytex_components`):
+- **GitHub-style callouts** become colored boxes from `pytex_components`:
   ```md
   > [!NOTE]      -> InfoBox        > [!IMPORTANT] -> ImportantBox
   > [!TIP]       -> SuccessBox     > [!WARNING]   -> WarningBox
   ```
-- **Citations** in Pandoc syntax: `[@key]` / `[@key, p. 5]` -> `\autocite`,
-  `[@a; @b]` -> a combined cite, and a narrative `@key` -> `\textcite`.
-- **Bibliography** from frontmatter — `bibliography:` is either inline BibTeX (a
-  `|` block scalar) or a path to a `.bib` file; reports print a numbered
-  `\printbibliography`.
-- ASCII **math arrows** (`->`, `=>`, `<->`, ...) become inline math arrows, the
-  **euro sign** `€` becomes a font-independent `\euro{}`, and tables get a bit of
-  vertical breathing room.
-
-Both factories are registered, so they work in `\iffalse{pytex(...)}\fi`
-replacements in `.tex` sources too.
+- **Citations** in Pandoc syntax. `[@key]` and `[@key, p. 5]` -> `\autocite`,
+  `[@a; @b]` -> one combined cite, and a narrative `@key` -> `\textcite`.
+- **Bibliography** from the frontmatter. The key `bibliography:` holds either
+  inline BibTeX (a `|` block scalar) or a path to a `.bib` file. A report
+  variant prints a numbered `\printbibliography`.
+- An ASCII **math arrow** (`->`, `=>`, `<->`, ...) becomes an inline math
+  arrow. The **euro sign** `€` becomes a font-independent `\euro{}`. A table
+  gets more vertical space.
+
+PyTeX registers both factories, so they also work in an inline `pytex(...)`
+marker in a `.tex` input file.
 
 ### Output variants
 
-When the `pytex` command renders a `.md` file it wraps the converted nodes in a
-document chosen by `--variant`:
+When the `pytex` command renders a `.md` file, it wraps the converted nodes in
+a document that `--variant` picks:
 
 | Variant | Document |
 | --- | --- |
-| `plain` | a bare `Document` (default class `article`); `#` -> `\section`. |
-| `report` | an HSRT report with title page and table of contents; `#` -> `\chapter`. |
-| `report-makers` | a `report` branded with the MAKERS logo (title page + footer). |
-| `protocol-asta` | an AStA meeting protocol (HSRT report, AStA logos). |
-| `protocol-stupa` | a StuPa meeting protocol (HSRT report, StuPa logos). |
+| `plain` | a bare `Document`. The default document class is `article`, and `#` -> `\section`. |
+| `report` | an HSRT report with a title page and a table of contents. `#` -> `\chapter`. |
+| `report-makers` | a `report` with the MAKERS logo on the title page and in the footer. |
+| `protocol` | a meeting protocol with no corporate design of its own. The caller names the logos with `logos` and `footer_logos`. |
+| `protocol-asta` | an AStA meeting protocol. It is an HSRT report with the AStA logos. |
+| `protocol-stupa` | a StuPa meeting protocol. It is an HSRT report with the StuPa logos. |
 
-Without `--variant`, protocol frontmatter (`gremium:` or `typ: protokoll`) picks
-a protocol style and everything else falls back to `plain`.
+Without `--variant`, PyTeX detects the variant. Meeting-protocol frontmatter
+(`gremium:` or `typ: protokoll`) picks a protocol variant. Every other input
+file gets `plain`.
 
-Document-class parameters come from the YAML frontmatter and from `--config`
-(a JSON object that overrides the frontmatter), e.g.:
+Document-class parameters come from the YAML frontmatter and from `--config`, a
+JSON object. `--config` overrides the frontmatter. For example:
 
 ```sh
 pytex notes.md --variant plain --config '{"documentclass": "scrartcl", "classoptions": ["11pt", "twocolumn"]}'
 ```
 
 `classoptions` accepts a list (`"twocolumn"`, `"DIV=12"`) or a `{key: value}`
-object. For styles with a title page (`report`), the title is taken from
-`title:`/`--config` if given, otherwise from the first `#` heading (which is then
-not also rendered as a chapter).
-
-The report styles read further frontmatter keys: `author`, `abstract`,
-`keywords`, title-page `datalines` (a list of `"Label: value"` entries),
-`bibliography` (see [Markdown](#markdown)), `logos` (title-page logos — vendored
-names like `INF`/`MAKERS` and/or paths to custom image files), and the labels
-`abstract_heading` / `keywords_heading` to rename the default "Abstract" /
-"Keywords" sections.
+object. A variant with a title page, such as `report`, takes the title from
+`title:` or from `--config`. If neither one gives a title, the variant takes
+the first `#` heading, and then does not also render it as a chapter.
+
+The report variants read more frontmatter keys. These are `author`, `abstract`,
+`keywords`, the title-page `datalines` (a list of `"Label: value"` entries), and
+`bibliography` (see [Markdown](#markdown)). The key `logos` names the title-page
+logos, and the key `footer_logos` the logos of the page footer. Each one takes
+a vendored name such as `INF` or `MAKERS`, a path to a custom image file, or
+both. Without these keys, the variant supplies its own logos. The keys `abstract_heading` and `keywords_heading` rename
+the default "Abstract" and "Keywords" sections.
 
 ## Converting LaTeX to PyTeX
 
-`pytex-tex2py` turns an existing `.tex` file into an equivalent `.tex.py`
-source. It reads the file, runs `Optimize` over it (expanding inline
-`pytex(...)` markers and recognising comments and math), and serialises the
-result to Python that rebuilds the same tree:
+`pytex-tex2py` turns an existing `.tex` file into an equivalent `.tex.py` file.
+It reads the file and runs the optimize pass over it. The optimize pass expands
+each inline `pytex(...)` marker and recognizes comments and math.
+`pytex-tex2py` then serializes the result to Python that rebuilds the same node
+tree:
 
 ```sh
 pytex-tex2py paper.tex            # -> paper.tex.py
 pytex-tex2py paper.tex -o out.py
 ```
 
-Rendering the generated `.tex.py` reproduces the original output byte-for-byte;
-nodes the serialiser does not special-case fall back to a literal `Raw`, so the
-conversion always round-trips.
+The rendered `.tex` file of the new `.tex.py` file matches the original byte
+for byte. A node that the serializer does not handle falls back to a literal
+`Raw`, so the conversion always round-trips.
 
 ## Examples
 
-See `examples/` for one minimal input per kind (`.tex.py`, `.py.tex`, `.md`,
-mixed, and a full HSRT report). Run from the repository root so relative paths
-resolve:
+The `examples/` directory holds one minimal input file per kind: `.tex.py`,
+`.py.tex`, `.md`, a mixed file, and a full HSRT report. Run the commands from
+the repository root, so the relative paths resolve:
 
 ```sh
 pytex examples/document.tex.py --build
@@ -1007,24 +1023,27 @@ pytex examples/notes.md --build
 
 ## Stability
 
-From 1.0 the project follows [Semantic Versioning](https://semver.org). The
-public API is what each package exports through its top-level `__all__`:
-everything reachable as `from pytex import X` (and the same for `pytex_koma`,
-`pytex_tikz`, `pytex_components`, `pytex_markdown`, `pytex_analyze`,
-`pytex_hsrtreport`). Breaking those names needs a major version bump.
-
-Also part of the contract: the registry keys exposed to `\iffalse{pytex(...)}\fi`
-markers — they are the factory names, so renaming a registered factory is a
-breaking change (which is why the `\fill` length is `Fill_len`, leaving the bare
-`Fill` key to the TikZ path command).
-
-Internal and not covered by the guarantee: any name with a leading underscore,
-modules whose name starts with an underscore (e.g. `pytex_api._policy`,
-`pytex_api._compile`), and anything not listed in a package's `__all__`. Import
-those at your own risk.
-
-Deprecated shims (`pytex_protocol`, the `pytex.commands.lengths.Fill` alias) keep
-working with a `DeprecationWarning` and may be removed in the next major release.
+From 1.0 on, PyTeX follows [Semantic Versioning](https://semver.org). The
+public API is what each package exports through its top-level `__all__`. That
+is every name you can reach as `from pytex import X`, and the same for
+`pytex_koma`, `pytex_tikz`, `pytex_components`, `pytex_markdown`,
+`pytex_analyze` and `pytex_hsrtreport`. A change that breaks one of those names
+needs a major version bump.
+
+The contract also covers the registry keys that an inline `pytex(...)` marker
+can use. A registry key is the name of a factory, so a rename of a registered
+factory is a breaking change. For that reason the `\fill` length is `Fill_len`,
+which leaves the bare `Fill` registry key to the TikZ path command.
+
+Some parts are internal, and the guarantee does not cover them. A name with a
+leading underscore is internal. A module whose name starts with an underscore
+is internal, for example `pytex_api._policy` and `pytex_api._compile`. A name
+that a package does not list in its `__all__` is also internal. Import those at
+your own risk.
+
+The deprecated shims `pytex_protocol` and the `pytex.commands.lengths.Fill`
+alias keep working and raise a `DeprecationWarning`. PyTeX may remove them in
+the next major release.
 
 ## License