How-to guides › Fill document templates

How-to guides

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 .docx or .dotx (Word), or an .odt or .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) gives true.
  • 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.