Documentation

Status: Current.

Allors Documents renders OpenDocument texts from templates. A template is written in LibreOffice Writer with tags in placeholder fields and in the descriptions of pictures, bound to a model and rendered to a document. The documentation serves three audiences. Template authors write templates in Writer. Developers render documents from their models and validate templates. Maintainers change the library.

README.md introduces the packages. The writing guide defines the rules for these pages; Terminology records the agreed names. These pages are for humans. Agents use the same technical content, following the instructions in AGENTS.md.

For template authors

The following pages are written for template authors. Developers read them too.

Page	Kind	Status	Content
Write a template	How-to guide	Current	Building a template in Writer step by step: tags in placeholder fields, repeated table rows, conditions, pictures, document settings, maps, and how to save and check the result.
Tags	Reference	Current	The tag language: bindings, loops, conditions with their else branches, and where a tag may sit and how the template renders.
Formatting	Reference	Current	How values print: the attributes of a tag, the document settings of a template, the cultures and patterns, and the layers that combine them.
Pictures	Reference	Current	Binding a picture frame through its description: the picture tag, the empty and fit attributes, the formats the library knows and how pictures are stored.
Maps	Reference	Current	Translating values into the template’s own words with a map table and the map attribute.
Findings	Reference	Current	What Validate and Render report: every kind of finding with its severity, its meaning and where it comes from.

For developers

Page	Kind	Status	Content
Render your first document	Tutorial	Current	A small invoice template rendered from a plain class, the finding that says what the model could not give, formatting for an installation and a validation without data.
Validate templates	How-to guide	Current	Check a template against the shape of its model without rendering it, when it is saved and in a test over every template.
Resolve your own model	How-to guide	Current	Implement the shape and the resolver that let templates read your own objects, and the rules the base resolver carries.
Renderers and picture processing	How-to guide	Planned	Renderers that transform one value by name, such as upper-case text or a barcode, and a picture processor that prepares pictures for their frames: the agreed design for version 4.0.
API	Reference	Current	The packages, the template class with Inspect, Validate and Render, the render settings and result, and flat documents.
Design	Explanation	Current	Why the tag language is small: Parr’s rules for model-view separation, the roles of model, view, controller and renderer, the steps past StringTemplate, what the library refuses and why a render never throws.

For everyone

Page	Kind	Status	Content
Terminology	Reference	Current	Agreed names for templates, tags, models and findings, with links to their definitions.

For maintainers

The pages under internals/ describe how the library is built, documented and released. An application must not rely on them: they can change with any version.

Page	Kind	Status	Content
Architecture	Explanation	Current	How a template becomes a document: the parts, the program built once per template, the renderer that walks it per render, pictures and output, and how Inspect and Validate share the same reading of a template.
Releasing	How-to guide	Current	Build, test and pack with Task, how the version is stamped, and how a tag publishes the packages.
Writing documentation	How-to guide	Current	Audience, Diátaxis, status, Oxford English, stable terminology, visual explanations and review.
Documentation website	Decision record	Current	Agreed website design, its adoption from the Allors3 documentation project, implementation subtasks, validation and publication.

The writing guide defines page kinds and statuses. Audience, kind and status describe different things: who a page serves, what it helps them do and whether it describes current behaviour.