Choose the paper: a size and orientation for an export, themes that declare what they support, and both renderers honouring it

tiagoagueda commented

2026-10-01 07:02:08 +00:00

Owner

Every document Postulo draws is A4 portrait. The templates plugin is asked that a template be either "fluid", printing well "in all common formats and orientations", or restricted, "for example, export only to portrait A4 paper size" (postulo/postulo-templates#9). Today nobody can choose a paper, a theme cannot say what it supports, and one renderer would ignore it anyway.

What exists today

PAGE_FORMAT = "A4" and PAGE_MARGIN = "18mm" are constants (src/postulo/documents/pdf.py).
WeasyPrint honours the @page rule a template writes. Every one in the repository says size: A4: the six built-in theme files and the report.
Chromium is called as page.pdf(format=PAGE_FORMAT, margin=…) with no orientation and without the option that prefers the page's own size, so a template's @page size is ignored there (read from the code and the renderer's documented default; not tried).
DOCX is A4, hard-coded (src/postulo/documents/docx.py).
No setting for a paper size or orientation exists per document, per person or per instance.
Theme has four fields: name, label, templates, provider. Nothing declares a format.
The render tests draw only the built-in themes, and measure overflow on A4 only (tests/test_pdf_render.py).

Proposal

A vocabulary of formats: a paper size and an orientation.
Where it is chosen: a default for the instance, a person's own, and a choice at the moment of export for the things printed wide.
A theme declares what it supports, per kind: every format (fluid) or the ones it names (restricted). The picker offers only the themes that support the paper chosen, and says in words why another is not offered.
The template is told the paper, so a fluid theme can adapt, and the page rule follows the choice.
Both renderers honour it: Chromium is given the chosen size and orientation in place of the constant.
The DOCX export follows the chosen size.
The render tests draw each theme on each format it declares.

Decisions

Which formats. Recommended: A4 and US Letter, portrait and landscape. More when asked for.
Who writes the page rule. Recommended: Postulo, from the choice, so a theme cannot disagree with what the person picked. Alternative: each theme writes its own from the paper it is told.
A theme that declares nothing. Recommended: read as A4 portrait only, which is true of every theme written so far.
A default from the region. Recommended: the instance default set by its administrator, not guessed from a language.

Needed by

postulo/postulo-templates#9, and the wide documents of #341 and #342.

Done when

A person chooses US Letter in landscape for an export, and the PDF from either renderer is that size.
A theme restricted to A4 portrait is not offered for it, and the picker says why.
A fluid built-in theme passes the render test on every format.
New names on postulo.plugins.api get their line in the wiki's Writing a plugin (tests/test_wiki_surface.py) and a test in tests/test_plugin_surface.py; new pages join the page-coverage walk (tests/test_page_coverage.py) and the isolation sweep (tests/security/test_isolation_sweep.py); new strings go in the working catalogues (English, French, and European and Brazilian Portuguese as drafts).

From the list of template improvements of 2026-09-30.

Every document Postulo draws is A4 portrait. The templates plugin is asked that a template be either "fluid", printing well "in all common formats and orientations", or restricted, "for example, export only to portrait A4 paper size" (postulo/postulo-templates#9). Today nobody can choose a paper, a theme cannot say what it supports, and one renderer would ignore it anyway. ## What exists today - `PAGE_FORMAT = "A4"` and `PAGE_MARGIN = "18mm"` are constants (`src/postulo/documents/pdf.py`). - **WeasyPrint** honours the `@page` rule a template writes. Every one in the repository says `size: A4`: the six built-in theme files and the report. - **Chromium** is called as `page.pdf(format=PAGE_FORMAT, margin=…)` with no orientation and without the option that prefers the page's own size, so a template's `@page` size is ignored there (read from the code and the renderer's documented default; not tried). - **DOCX** is A4, hard-coded (`src/postulo/documents/docx.py`). - **No setting** for a paper size or orientation exists per document, per person or per instance. - **`Theme`** has four fields: `name`, `label`, `templates`, `provider`. Nothing declares a format. - **The render tests** draw only the built-in themes, and measure overflow on A4 only (`tests/test_pdf_render.py`). ## Proposal 1. **A vocabulary of formats**: a paper size and an orientation. 2. **Where it is chosen**: a default for the instance, a person's own, and a choice at the moment of export for the things printed wide. 3. **A theme declares what it supports**, per kind: every format (fluid) or the ones it names (restricted). The picker offers only the themes that support the paper chosen, and says in words why another is not offered. 4. **The template is told the paper**, so a fluid theme can adapt, and the page rule follows the choice. 5. **Both renderers honour it**: Chromium is given the chosen size and orientation in place of the constant. 6. **The DOCX export** follows the chosen size. 7. **The render tests** draw each theme on each format it declares. ## Decisions - **Which formats.** Recommended: A4 and US Letter, portrait and landscape. More when asked for. - **Who writes the page rule.** Recommended: Postulo, from the choice, so a theme cannot disagree with what the person picked. Alternative: each theme writes its own from the paper it is told. - **A theme that declares nothing.** Recommended: read as A4 portrait only, which is true of every theme written so far. - **A default from the region.** Recommended: the instance default set by its administrator, not guessed from a language. ## Needed by postulo/postulo-templates#9, and the wide documents of #341 and #342. ## Done when - A person chooses US Letter in landscape for an export, and the PDF from either renderer is that size. - A theme restricted to A4 portrait is not offered for it, and the picker says why. - A fluid built-in theme passes the render test on every format. - New names on `postulo.plugins.api` get their line in the wiki's *Writing a plugin* (`tests/test_wiki_surface.py`) and a test in `tests/test_plugin_surface.py`; new pages join the page-coverage walk (`tests/test_page_coverage.py`) and the isolation sweep (`tests/security/test_isolation_sweep.py`); new strings go in the working catalogues (English, French, and European and Brazilian Portuguese as drafts). From the list of template improvements of 2026-09-30.

tiagoagueda added the

enhancement

interface

labels

2026-10-01 07:02:08 +00:00

tiagoagueda referenced this issue

2026-10-16 15:46:42 +00:00

Documents: one previewer for every file — PDFs drawn with a vendored pdf.js, thumbnails, pictures and text inline, as paperless-ngx does #942

tiagoagueda added this to the 0.5.0 milestone

2026-10-25 17:04:12 +00:00

tiagoagueda referenced this issue from a commit

2026-10-29 10:32:20 +00:00