Guides pratiques › Remplir des documents modèles

Guides pratiques

Documents modèles

Un document modèle est votre propre document Word ou LibreOffice, avec des champs à remplir qu'archec complète à partir du modèle. Vous rédigez la spécification, le document de contrôle d'interface ou le rapport de test selon la présentation de votre entreprise : page de titre, styles, en-têtes et tableaux. Là où doit aller le contenu du modèle, vous tapez un champ tel que {{ requirement REQ-1 .text }}. archec doc remplit les champs et écrit un nouveau document.

Un premier modèle#

Prenons un modèle avec deux exigences :

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
}

Dans Word, écrivez un fichier spec.docx avec ces quatre paragraphes :

Requirements ({{ count requirements }})
{{#each requirements}}
{{ .id }}: {{ .text }} [{{ .status }}]
{{/each}}

Puis remplissez-le :

archec doc main.arche --template spec.docx -o spec-filled.docx
✓ spec-filled.docx

spec-filled.docx garde vos styles et contient :

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]

Les deux paragraphes qui ne contenaient que {{#each}} et {{/each}} ont disparu.

Un exemple plus complet se trouve dans le dépôt : examples/templates/autonomous-car-spec.docx, pour examples/autonomous-car/main.arche.

Formats#

  • Le modèle est un .docx ou un .dotx (Word), ou un .odt ou un .ott (LibreOffice).
  • Le résultat est un document du même type : archec doc main.arche --template report.odt -o report.odt.
  • Rien d'autre à installer : ni Word, ni LibreOffice, ni pandoc.

L'idée est la même que celle de M2Doc pour Capella et de DocGen pour OpenMBEE, avec un langage plus réduit.

Champs#

Un champ s'écrit entre {{ et }}. Il peut se placer partout où va du texte : un titre, un paragraphe, une cellule de tableau. Les espaces à l'intérieur ne comptent pas.

Champ Ce qu'il donne
{{ requirement REQ-1 .text }} une propriété d'un élément. L'élément peut être un requirement, system, component, part Car.brakes, message, test-plan, case, hazard…
{{ requirement REQ-1 }} le libellé de l'élément, ou son id s'il n'a pas de libellé
{{ project .version }} une propriété du projet ; {{ project }} donne son nom
{{ .text }} une propriété de l'élément parcouru par la boucle. Si cet élément ne l'a pas, on essaie les boucles qui l'entourent.
{{ count requirements where status=draft }} le nombre d'éléments d'une sélection
{{ diagram Car }} le schéma de blocs d'un système, sous forme d'image. {{ diagram }} dessine le système qu'exécute archec sim.
{{ date }} la date du jour, au format 2026-11-10

Propriétés#

Une propriété est n'importe quelle propriété de l'élément, désignée par son nom : .text, .status, .priority, .owner, .rationale, .tags, .kind, .layer, .verifies…

  • Une liste donne ses valeurs, séparées par des virgules.
  • Un indicateur écrit seul dans le modèle (comme tbc) donne true.
  • Une part a aussi les propriétés de sa définition qu'elle ne fixe pas elle-même.

Ces propriétés sont calculées pour vous :

Propriété Ce que c'est
.id, .label le nom, et le libellé (le nom s'il n'y a pas de libellé)
.text le text d'une exigence ; à défaut sa description ; à défaut son ears
.satisfied-by, .verified-by ce qui satisfait ou vérifie une exigence, d'après les traces
.path l'emplacement d'une part, par exemple Car.brakes
.definition la définition d'une part
.type, .direction, .value le type d'un port ou d'une variable, le sens d'un port, la valeur d'une constante
.index le rang dans sa boucle : 1, 2, 3…
.file, .line l'endroit où l'élément est écrit

Boucles#

{{#each requirements}} … {{/each}} répète ce qui se trouve entre les deux balises, une fois par élément. L'emplacement des balises décide de ce qui se répète :

  • Toutes deux dans un même paragraphe : le texte entre elles se répète.
  • Dans deux cellules ou deux lignes d'un même tableau (ou dans deux paragraphes d'une même cellule) : les lignes du tableau se répètent, de la ligne qui contient {{#each}} à celle qui contient {{/each}}. Un tableau d'exigences n'a besoin que d'une ligne : {{#each requirements}}{{ .id }} dans la première cellule et {{ .text }}{{/each}} dans la dernière.
  • Dans deux paragraphes : les paragraphes de la première balise à la dernière se répètent. Un paragraphe qui ne contient qu'une balise disparaît du document.

Une boucle peut parcourir requirements, systems, parts (toutes les parts de tous les systèmes), components (les définitions), ports, links, messages, types, constants, test-plans, cases, scenarios, functions, hazards, safety-goals, threats, deployments, interfaces, variants, parameters, states, transitions…

Dans une boucle, un nom que porte l'élément courant parcourt la liste propre à cet élément :

  • {{#each cases}} dans un plan de test ;
  • {{#each ports}} ou {{#each parts}} dans une part ou un système ;
  • {{#each fields}} dans un message ;
  • {{#each states}} dans une part dotée d'une machine à états.

where#

where ne garde que les éléments qui remplissent une condition. Le filtrage est le même que celui d'un viewpoint.

Condition Vraie quand
status=approved la propriété a cette valeur
tag=safety,asil-d la propriété a l'une de ces valeurs
status!=draft la propriété n'a aucune de ces valeurs
text~brake la propriété contient le texte, sans tenir compte de la casse
rationale la propriété est renseignée
view=compute le viewpoint compute montre l'élément (selon ses kinds, layers, tags, texte)

Reliez les conditions par and quand toutes doivent être vraies : {{#each requirements where tag=safety and status!=draft}}. Mettez entre guillemets une valeur qui contient des espaces : owner="A. Martin".

if#

{{#if status=approved}}…{{/if}} se place dans une boucle. Il ne garde ce qui se trouve entre les balises que si l'élément remplit la condition. Il accepte les mêmes conditions que where. L'emplacement de ses balises fonctionne comme pour une boucle.

Schémas#

{{ diagram Car }} place le schéma de blocs du système à l'endroit du champ. Le schéma montre les parts, leurs ports et les liens. Sa mise en page est celle de archec sim --html, et il fait au plus six pouces et demi de large.

  • Dans un .docx, le schéma est une image SVG, qu'affichent Word 2016 et les versions suivantes. Un PNG des mêmes boîtes et traits, sans le texte, l'accompagne pour les lecteurs plus anciens.
  • Dans un .odt, le schéma est une image SVG, que LibreOffice affiche.

Quand Word coupe un champ#

Si vous tapez un champ en plusieurs fois, Word peut l'enregistrer en plusieurs morceaux de texte. Cela arrive quand vous le corrigez, quand vous en mettez une partie en gras ou quand le correcteur orthographique le souligne. archec lit les morceaux d'un paragraphe comme un seul texte. Il remet chaque champ dans son premier morceau : le champ garde donc la mise en forme de ce morceau.

Quand un champ ne peut pas être rempli#

Il arrive qu'archec ne puisse pas remplir un champ : il ne sait pas le lire, l'élément n'existe pas, ou une boucle n'a pas de balise de fin. Le document est tout de même écrit. À la place de la valeur, il indique le problème, par exemple [archec: no requirement REQ-9]. archec affiche chaque problème et se termine avec le code 1, pour qu'un pipeline le voie :

bad.docx: warning no requirement REQ-9
✓ bad-filled.docx, 1 placeholder problem(s)

Limites#

  • Un champ doit tenir dans un seul paragraphe. archec recolle les morceaux que Word découpe à l'intérieur d'un paragraphe, mais pas d'un paragraphe à l'autre.
  • Un schéma se place dans le corps du document, pas dans un en-tête ni dans un pied de page.
  • Dans un .docx, le schéma SVG demande Word 2016 ou une version plus récente. Les lecteurs plus anciens affichent le PNG qui l'accompagne, sans texte.