Template documents
A template document is your own Word or LibreOffice document with blanks that
archec fills from the model. You write the specification, the interface control
document or the test report as your company lays it out: its title page, styles,
headers and tables. Where the model's content goes, you type a placeholder such
as {{ requirement REQ-1 .text }}. archec doc fills the placeholders and
writes a new document.
A first template#
Take a model with two requirements:
requirement REQ-1 "Stop in time" {
text "The car shall stop within 40 m from 50 km/h."
status approved
}
requirement REQ-2 "Warn the driver" {
text "The display shall warn of a brake fault within 100 ms."
status draft
}
In Word, write a spec.docx with these four paragraphs:
Requirements ({{ count requirements }})
{{#each requirements}}
{{ .id }}: {{ .text }} [{{ .status }}]
{{/each}}
Then fill it:
archec doc main.arche --template spec.docx -o spec-filled.docx
✓ spec-filled.docx
spec-filled.docx keeps your styles and says:
Requirements (2)
REQ-1: The car shall stop within 40 m from 50 km/h. [approved]
REQ-2: The display shall warn of a brake fault within 100 ms. [draft]
The two paragraphs that held only {{#each}} and {{/each}} are left out.
A larger example is in the repository:
examples/templates/autonomous-car-spec.docx, for
examples/autonomous-car/main.arche.
Formats#
- The template is a
.docxor.dotx(Word), or an.odtor.ott(LibreOffice). - The result is a document of the same kind:
archec doc main.arche --template report.odt -o report.odt. - Nothing else needs to be installed: no Word, no LibreOffice, no pandoc.
The idea is the same as Capella's M2Doc and OpenMBEE's DocGen, with a smaller language.
Placeholders#
A placeholder is written between {{ and }}. It can go anywhere text goes: a
heading, a paragraph, a table cell. Spaces inside it do not matter.
| Placeholder | What it gives |
|---|---|
{{ requirement REQ-1 .text }} |
a field of one element. The element can be a requirement, system, component, part Car.brakes, message, test-plan, case, hazard… |
{{ requirement REQ-1 }} |
the element's label, or its id when it has no label |
{{ project .version }} |
a field of the project; {{ project }} gives its name |
{{ .text }} |
a field of the element the loop is on. If that element does not have the field, the loops around it are tried. |
{{ count requirements where status=draft }} |
how many elements a selection gives |
{{ diagram Car }} |
the block diagram of a system, as a picture. {{ diagram }} draws the system archec sim runs. |
{{ date }} |
today's date, as 2026-11-10 |
Fields#
A field is any property of the element, by its name: .text, .status,
.priority, .owner, .rationale, .tags, .kind, .layer, .verifies…
- A list gives its values, separated by commas.
- A flag written alone in the model (such as
tbc) givestrue. - A part also has the properties of its definition that it does not set itself.
These fields are computed for you:
| Field | What it is |
|---|---|
.id, .label |
the name, and the label (the name when there is no label) |
.text |
a requirement's text; else its description; else its ears |
.satisfied-by, .verified-by |
what satisfies or verifies a requirement, from the traces |
.path |
where a part is, such as Car.brakes |
.definition |
a part's definition |
.type, .direction, .value |
a port's or variable's type, a port's direction, a constant's value |
.index |
the place in its loop: 1, 2, 3… |
.file, .line |
where the element is written |
Loops#
{{#each requirements}} … {{/each}} repeats what is between the two tags,
once per element. Where you put the tags decides what repeats:
- Both in one paragraph: the text between them repeats.
- In two cells or two rows of one table (or in two paragraphs of one cell):
the table rows repeat, from the row with
{{#each}}to the row with{{/each}}. A requirement table needs one row:{{#each requirements}}{{ .id }}in the first cell and{{ .text }}{{/each}}in the last cell. - In two paragraphs: the paragraphs from the first tag to the last repeat. A paragraph that holds only a tag is left out of the document.
A loop can go over requirements, systems, parts (every part of every
system), components (the definitions), ports, links, messages, types,
constants, test-plans, cases, scenarios, functions, hazards,
safety-goals, threats, deployments, interfaces, variants,
parameters, states, transitions…
Inside a loop, a name that the current element holds goes over that element's own list:
{{#each cases}}in a test plan;{{#each ports}}or{{#each parts}}in a part or a system;{{#each fields}}in a message;{{#each states}}in a part with a state machine.
where#
where keeps only the elements that pass a condition. It filters the same way
a viewpoint does.
| Condition | Holds when |
|---|---|
status=approved |
the field has that value |
tag=safety,asil-d |
the field has one of these values |
status!=draft |
the field has none of these values |
text~brake |
the field contains the text, in any case |
rationale |
the field is written |
view=compute |
the viewpoint compute shows the element (by its kinds, layers, tags, text) |
Join conditions with and when all must hold:
{{#each requirements where tag=safety and status!=draft}}.
Quote a value that has spaces: owner="A. Martin".
if#
{{#if status=approved}}…{{/if}} goes inside a loop. It keeps what is between
the tags only when the element passes the condition. It takes the same
conditions as where. Where you put its tags works as it does for a loop.
Diagrams#
{{ diagram Car }} puts the system's block diagram where the placeholder is.
The diagram shows the parts, their ports and the links. It is laid out as
archec sim --html lays it out, and is six and a half inches wide at most.
- In a
.docx, the diagram is an SVG picture, which Word 2016 and later show. A PNG of the same boxes and lines, without the words, goes beside it for older readers. - In an
.odt, the diagram is an SVG picture, which LibreOffice shows.
When Word cuts a placeholder#
When you type a placeholder in several goes, Word may save it as several pieces of text. This happens when you correct it, make part of it bold, or when the spelling checker marks it. archec reads the pieces of a paragraph as one text. It puts each placeholder back in its first piece, so the placeholder keeps the formatting of that piece.
When something cannot be filled#
archec may fail to fill a placeholder: it cannot read it, the element does not
exist, or a loop has no end tag. The document is still written. Where the value
would be, it says what went wrong, such as [archec: no requirement REQ-9].
archec prints each problem and exits with code 1, so a pipeline sees it:
bad.docx: warning no requirement REQ-9
✓ bad-filled.docx, 1 placeholder problem(s)
Limits#
- A placeholder must be in one paragraph. archec joins the pieces Word splits inside a paragraph, but not across paragraphs.
- A diagram goes in the body of the document, not in a header or a footer.
- In a
.docx, the SVG diagram needs Word 2016 or later. Older readers show the PNG beside it, which has no words.