# Open Processing Model (opm)

> Convert TEI, Docbook or JATS XML to HTML, PDF, EPUB, Word or Markdown, or publish it as a static website. A Python tool for digital editions, driven by TEI ODD.

`opm` is a Python command-line tool and library that converts TEI XML (and
DocBook or JATS) into HTML, PDF (via Typst or CSS for print), EPUB, Word,
Markdown or JSON, and splits documents into static websites. Rendering rules
are written in a TEI ODD file following the TEI Processing Model; `opm`
compiles the ODD into a Python module on demand. ODDs are compatible with
TEI Publisher.

Key facts for agents:

- Install with `pip install open-processing-model` (Python 3.12+). The command is `opm`.
- `opm init` scaffolds a project: `opm.toml` (settings), `odd/custom.odd`
  (rendering rules, inheriting `teipublisher.odd`), `templates/`, `data/`.
- `opm transform FILE -t TYPE -o OUT` converts one file; TYPE is one of web,
  print, epub, markdown, docx, typst, json. `-o out.pdf` with `-t typst` compiles a PDF.
- `opm chunk FILE_OR_DIR --force` splits documents into pages for a static site;
  `opm serve` previews it.
- There is no separate compile step: change the ODD and rerun.
- Change rendering in the ODD first (elementSpec/model/@behaviour/outputRendition),
  then in templates; Python XPath extensions are a last resort.

The complete prose documentation in one file: https://opm.e-editiones.org/llms-full.txt

## Home

- [Home](https://opm.e-editiones.org/index.md): opm converts TEI, JATS, Docbook or other XML languages to HTML, PDF, EPUB, Word and Markdown, or publishes it as a static website, using TEI ODD.

## Getting Started

- [Installation](https://opm.e-editiones.org/getting-started/installation.md): The minimum supported Python version is 3.12.
- [Quickstart](https://opm.e-editiones.org/getting-started/quickstart.md): This walkthrough scaffolds a local project, transforms a sample document, and builds a chunked static site.

## Tutorials

- [Convert XML to HTML](https://opm.e-editiones.org/tutorials/tei-to-html.md): A step-by-step tutorial for turning an XML document — TEI, DocBook or JATS — into a web page with opm, and for changing how it looks.
- [Publish a website](https://opm.e-editiones.org/tutorials/tei-website.md): A step-by-step tutorial for turning one or more XML documents — TEI, DocBook or JATS — into a static website with opm, without a database or server software.
- [Create a PDF](https://opm.e-editiones.org/tutorials/tei-to-pdf.md): A step-by-step tutorial for creating a print-ready PDF from an XML document — TEI, DocBook or JATS — with opm, using Typst or CSS for print.
- [EPUB and Word](https://opm.e-editiones.org/tutorials/tei-to-epub-word.md): A step-by-step tutorial for converting an XML document — TEI, DocBook or JATS — into an EPUB e-book, a Word document or Markdown with opm.

## Guide

- [ODD files](https://opm.e-editiones.org/guide/odd-files.md): An ODD (One Document Does it all) file is a TEI XML document which includes *processing model* instructions.
- [Output formats](https://opm.e-editiones.org/guide/output-formats.md): `opm` can transform XML to a number of output formats.
- [Chunking](https://opm.e-editiones.org/guide/chunking.md): Large documents are awkward to serve as one giant HTML page.
- [Search indexing](https://opm.e-editiones.org/guide/search-indexing.md): A published edition is only as findable as its index.
- [Integration with TEI Publisher](https://opm.e-editiones.org/guide/tei-publisher.md): TEI Publisher normally turns XML into HTML at the moment a reader opens a page.
- [Templates & CSS](https://opm.e-editiones.org/guide/templates-and-css.md): The transform turns your XML into HTML, but that alone is not yet a web page anyone would want to read: a page also needs a title, stylesheets, perhaps a menu bar or a table of contents.
- [Assets](https://opm.e-editiones.org/guide/assets.md): A web page rarely consists of HTML alone.
- [ODD coverage](https://opm.e-editiones.org/guide/coverage.md): `opm odd coverage` is a useful debugging tool.
- [ODD documentation](https://opm.e-editiones.org/guide/odd-documentation.md): While OPM obviously focuses on the processing model parts of the ODD, the specification was initially created for a different purpose: to formally describe a TEI customization, i.e.
- [XPath extensions](https://opm.e-editiones.org/guide/xpath-extensions.md): ODD predicates and parameters are XPath 3.1 expressions.
- [Footnotes](https://opm.e-editiones.org/guide/footnotes.md): For most output formats, footnotes are handled by the target: Typst, EPUB, Word, and print CSS each place notes themselves.
- [Configuration (opm.toml)](https://opm.e-editiones.org/guide/configuration.md): Place an `opm.toml` file in the project root to set defaults for all CLI commands.

## CLI Reference

- [CLI Reference](https://opm.e-editiones.org/cli.md): The `opm` command is a Typer application.

## Optional

- [Overview](https://opm.e-editiones.org/api/index.md): `opm` can be driven entirely from the command line, and every command is a thin wrapper over a public Python API.
- [Project](https://opm.e-editiones.org/api/project.md): `opm.Project` provides a high-level API into opm.
- [transform](https://opm.e-editiones.org/api/transform.md): The high-level transform API.
- [chunking](https://opm.e-editiones.org/api/chunking.md): Split a large document into smaller pages or JSON data files for static site generators and web components.
- [indexing](https://opm.e-editiones.org/api/indexing.md): Roll the `json` output mode's records up into embedding-sized units for a search index or vector store.
- [coverage](https://opm.e-editiones.org/api/coverage.md): Read an ODD's own decisions back against the ODD source: which models fired, which can never fire, and which elements produced no output at all.
- [spec_index](https://opm.e-editiones.org/api/spec-index.md): Graph of ODD specification elements: elements, classes, macros, datatypes, processing models, and the direct facts about them — memberships and content-model references — indexed for lookup.
- [odd_schema](https://opm.e-editiones.org/api/odd-schema.md): Load an ODD and compile it by following `schemaSpec/@source` (schema specs and processing models).
- [odd_relax](https://opm.e-editiones.org/api/odd-relax.md): Write the RELAX NG schema for a compiled ODD (the result of `compiled_odd`), as the TEI Stylesheets' odd2relax does: `opm odd compile --format rng`.
- [document_site](https://opm.e-editiones.org/api/document-site.md): Build a static HTML documentation site from a compiled ODD or Guidelines document.
- [config](https://opm.e-editiones.org/api/config.md): Loading and representation of `opm.toml`.
- [odd_compiler](https://opm.e-editiones.org/api/odd-compiler.md): Compile an ODD file into a transform module.
- [output functions](https://opm.e-editiones.org/api/output-functions.md): `ProcessingModelFunctions` is the abstract base every output format implements.
- [output modes](https://opm.e-editiones.org/api/output-modes.md): Everything that differs between output modes, in one table.
- [typst_compile](https://opm.e-editiones.org/api/typst-compile.md): Compile Typst output to PDF with the `typst` command.
- [runtime](https://opm.e-editiones.org/api/runtime.md): The tree-walking engine that drives a transform: `apply()` / `apply_children()` route each element through the generated `_dispatch` router.
- [License](https://opm.e-editiones.org/license.md): The AGPL is the strongest of the common copyleft licences: it reaches not only software you distribute, but software you *operate* — a web service built on `opm` owes its source to the people using…