Document the .titleblock template format

sources/titleblock/ is ~8,300 lines and the format was undocumented: title blocks were mentioned in features and user_manual, but nothing said how to author one. Covers the grid model and the part that makes a template fit any paper size -- the three kinds of column length, where an unprefixed value is absolute pixels, t22% is a fraction of the total width and r100% takes the remainder, while rows are always absolute. Also label-vs-value and why only labels are normally translated, the more permissive variable substitution used here (both %{name} and %name, longest key first, but only the braced form is discoverable by the editor), the two logo storage forms and the fact that bitmaps are forced to base64, the four collections including the embedded one that makes a project self-contained, and the cell tag names. Notes F023 inline as a known defect: a logo whose storage attribute is neither xml nor base64 is written back with no image data. EN/FR/DE.
2026-09-20 07:14:13 +02:00 · 2026-09-11 22:06:32 +12:00
parent 53e9b9b4e9
commit 5e19ac2f65
5 changed files with 673 additions and 0 deletions
@@ -26,6 +26,8 @@

 **[Auto-numbering](autonumbering)** — schemes, sequences, freezing

+**[Title block templates](title_blocks)** — the .titleblock format
+
 **[Elements XML](elements_XML)**
 * [attribute](elements_definition_attribute)
 * [uuid](elements_child_uuid)
@@ -62,6 +62,7 @@ Beginnen Sie mit der deutschen Version dieses Wikis:
 | Variables & formulas | ✅ | ✅ | ✅ |
 | Terminal strips | ✅ | ✅ | ✅ |
 | Auto-numbering | ✅ | ✅ | ✅ |
+| Title block templates | ✅ | ✅ | ✅ |

 **Legend:** ✅ Translated | 📋 Planned | ❌ Not yet started

@@ -0,0 +1,225 @@
+# Schriftfeldvorlagen
+
+Das Schriftfeld ist das umrahmte Feld mit den Zeichnungsangaben in der Ecke
+eines Folios. Sein Aufbau steckt nicht fest im Programm — er ist eine
+**Vorlage**, eine `.titleblock`-Datei, die Sie ändern oder selbst schreiben
+können.
+
+QElectroTech liefert zehn Vorlagen mit und bringt einen eigenen Editor dafür
+mit.
+
+Quellen: `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h` und
+`sources/titleblock/` für den Editor.
+
+---
+
+## 1. Eine Vorlage ist ein Raster
+
+Eine Vorlage ist ein Raster aus Zellen. Es gibt drei Zelltypen:
+
+| Typ | Zeigt |
+|---|---|
+| **Feld** | eine Beschriftung und einen Wert, beide dürfen Variablen enthalten |
+| **Logo** | ein in der Vorlagendatei gespeichertes Bild |
+| **Leer** | nichts — die Zelle hält den Platz frei |
+
+Zellen können benachbarte Zeilen und Spalten **überspannen**; eine breite
+Titelzelle oben über einem Stapel kleiner Zellen ist nichts anderes als das.
+
+### Spaltenbreiten haben drei Naturen
+
+Das ist der Teil des Formats, den man verstehen sollte, denn er lässt eine
+Vorlage zu jedem Papierformat passen. Das Attribut `cols` des Rasters ist eine
+Liste von Längen, jede mit ihrem Präfix:
+
+| Geschrieben | Bedeutet |
+|---|---|
+| `120px;` | **absolut** — immer 120 Pixel |
+| `t22%;` | **22 % der gesamten** verfügbaren Breite |
+| `r100%;` | **100 % des Rests**, nachdem absolute und gesamtbezogene Spalten abgezogen sind |
+
+`cols="t22%;r100%;t22%;"` — die mitgelieferte Vorgabe — heißt also: eine Spalte
+mit 22 % der Breite, dann eine, die alles Übrige aufnimmt, dann wieder 22 %. Die
+mittlere Spalte dehnt sich, die äußeren behalten ihre Proportion, unabhängig von
+der Breite des Folios.
+
+**Zeilen sind stets absolut**, als Pixelhöhen angegeben: `rows="25;25;"`. Eine
+relative Zeilenhöhe gibt es nicht.
+
+---
+
+## 2. Beschriftungen, Werte und Übersetzungen
+
+Eine Feldzelle enthält zwei Texte, **beide übersetzbar**:
+
+```xml
+<field row="0" col="0" name="author" align="left" valign="center"
+       displaylabel="true" hadjust="true">
+    <value>
+        <translation lang="en">%author</translation>
+    </value>
+    <label>
+        <translation lang="en">Author</translation>
+        <translation lang="fr">Auteur</translation>
+        <translation lang="de">Autor</translation>
+    </label>
+</field>
+```
+
+- Die **Beschriftung** ist die feste Aufschrift — *Autor* — und wird
+  üblicherweise in alle von der Vorlage unterstützten Sprachen übersetzt.
+- Der **Wert** ist das, was sich je Folio ändert, und enthält gewöhnlich eine
+  Variable. Meist genügt ein einziger Eintrag, da `%author` in jeder Sprache
+  gleich ist.
+- `displaylabel` entscheidet, ob die Aufschrift überhaupt gezeichnet wird. Eine
+  große Titelzelle setzt es meist auf `false`.
+- `name` bezeichnet die Zelle innerhalb der Vorlage. Er wird **nicht**
+  gezeichnet.
+- `hadjust` verkleinert die Schrift, wenn der Text nicht passt, statt ihn
+  überlaufen zu lassen.
+
+---
+
+## 3. Variablen
+
+Schriftfeldzellen haben ihre eigene Ersetzung, und sie ist **großzügiger als
+überall sonst in QET**: Jeder Schlüssel im Kontext des Folios wird ersetzt, in
+beiden Formen. `%{author}` und `%author` wirken gleichermaßen.
+
+Standardschlüssel sind die Felder des Folios: `title`, `author`, `filename`,
+`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`.
+Projekteigenschaften und eigene Foliofelder werden ebenfalls ersetzt — so kann
+eine Vorlage ein Feld tragen, von dem QET nichts weiß.
+
+Zwei Einzelheiten:
+
+- Schlüssel werden **vom längsten zum kürzesten** ersetzt, mit Absicht, damit
+  ein Schlüssel namens `plant` nicht den Anfang von `%plantcode` auffrisst.
+- Nur die geschweifte Form `%{name}` lässt sich **auffinden**: Der Editor baut
+  seine Liste der verwendeten Variablen durch Suche nach `%{…}`; ein nacktes
+  `%name` wird zwar gezeichnet, kann aber von nichts aufgezählt werden.
+  **Bevorzugen Sie die geschweifte Form** in Vorlagen.
+
+Vollständige Referenz: **[Variablen und Formeln](variables)**.
+
+---
+
+## 4. Logos
+
+Logos werden **in** der Vorlagendatei gespeichert; eine Vorlage ist damit in
+sich geschlossen und lässt sich als eine Datei weitergeben.
+
+Das Tag `<logo>` steht für zwei verschiedene Dinge — gut zu wissen, bevor man
+eine Datei von Hand bearbeitet:
+
+```xml
+<logos>
+    <!-- das gespeicherte Bild selbst -->
+    <logo storage="xml" type="svg" name="qelectrotech.svg">
+        <svg …>…</svg>
+    </logo>
+</logos>
+<grid cols="…" rows="…">
+    <!-- eine Zelle, die eines anzeigt -->
+    <logo row="0" col="0" rowspan="1" name="" resource="qelectrotech.svg"/>
+</grid>
+```
+
+In `<logos>` ist es das Bild, in `<grid>` eine Zelle, die ein Bild über
+`resource` bezeichnet.
+
+Zwei Speicherformen:
+
+| `storage` | Für | Wie |
+|---|---|---|
+| `xml` | nur SVG | der `<svg>`-Baum wird direkt als XML eingebettet |
+| `base64` | jedes Rasterbild (und SVG, wenn man darauf besteht) | die Rohbytes, base64-kodiert, als Text |
+
+**Rasterbilder können nur als `base64` gespeichert werden** — QET erzwingt das,
+gleich was man angibt. SVG kann beides, und `xml` ist die vernünftige Wahl: Die
+Datei bleibt vergleichbar und das Logo skalierbar.
+
+Fügt man ein Logo über den Editor hinzu, versucht QET zuerst SVG und fällt dann
+auf Raster zurück; die Speicherform wird also für Sie gewählt.
+
+> **Bekannter Fehler.** Ein `<logo>`, dessen Attribut `storage` weder `xml` noch
+> `base64` ist, verliert beim Speichern seine Bilddaten: Das Element wird mit
+> seinen Attributen und ohne Inhalt geschrieben, stillschweigend. Der Code
+> enthält den Rückfall, der das verhindern würde, benutzt ihn aber nicht. Nur
+> von Hand geschriebene oder erzeugte Dateien können darauf laufen — keine der
+> mitgelieferten Vorlagen. Bleiben Sie bei den beiden gültigen Werten.
+
+---
+
+## 5. Wo Vorlagen liegen
+
+Vier Sammlungen, in QETs eigenem Vokabular:
+
+| Sammlung | Ort | Für |
+|---|---|---|
+| **Gemeinsam** | `titleblocks/` neben dem Programm | die mit QET gelieferten Vorlagen |
+| **Firma** | `<Datenverzeichnis>/titleblocks-company/` | gemeinsame Vorlagen einer Organisation |
+| **Benutzer** | `<Datenverzeichnis>/titleblocks/` | Ihre eigenen |
+| **Eingebettet** | in der `.qet`-Datei | Vorlagen, die ein Projekt mitführt |
+
+Die eingebettete zählt beim Weitergeben: Ein Projekt, das eine von Ihnen
+geschriebene Vorlage nutzt, führt eine Kopie mit und wird daher auch auf einem
+Rechner richtig dargestellt, der Ihre Vorlage nie gesehen hat.
+
+---
+
+## 6. Das Format auf einen Blick
+
+```xml
+<titleblocktemplate name="default">
+    <information></information>
+    <logos/>
+    <grid cols="t22%;r100%;t22%;" rows="25;25;">
+        <field row="0" col="0" name="author" align="left" valign="center"
+               displaylabel="true" hadjust="true">
+            <value><translation lang="en">%author</translation></value>
+            <label><translation lang="de">Autor</translation></label>
+        </field>
+        …
+    </grid>
+</titleblocktemplate>
+```
+
+| Element | Enthält |
+|---|---|
+| `<information>` | freier Text über die Vorlage — Autor, Zweck |
+| `<logos>` | die gespeicherten Bilder |
+| `<grid>` | `cols`, `rows` und die Zellen |
+| `<field>` | eine Feldzelle |
+| `<logo>` (im Raster) | eine Logozelle |
+| `<empty>` | eine leere Zelle |
+
+Der **Tagname einer Zelle ist ihr Typ**: `field`, `logo` oder `empty`.
+Gemeinsame Attribute sind `row`, `col`, `rowspan`, `colspan` und `name`. Ein
+`field` ergänzt `align` (`left`/`center`/`right`), `valign`, `displaylabel`,
+`hadjust` und `fontsize` — Letzteres nur, wenn eine Größe gesetzt wurde; ein
+fehlendes `fontsize` heißt also „Vorgabe“. Eine `logo`-Zelle ergänzt
+`resource`.
+
+---
+
+## 7. Praktische Hinweise
+
+- **Entwerfen Sie für die Dehnung, nicht für eine feste Breite.** Geben Sie den
+  Zellen, die ihre Proportion halten müssen, eine `t…%`-Breite und lassen Sie
+  eine Spalte `r100%` nehmen. Eine nur aus absoluten Breiten gebaute Vorlage
+  sieht auf einem anderen Papierformat falsch aus.
+- **Übersetzen Sie Beschriftungen, nicht Werte.** Ein Wert ist meist eine
+  Variable und in jeder Sprache gleich.
+- **Nutzen Sie `%{geschweifte}` Variablen**, damit der Editor sie auflisten kann.
+- **Halten Sie eine Vorlage in sich geschlossen.** Logos leben in der Datei;
+  verlassen Sie sich nicht auf einen externen Pfad.
+- **Ein eigenes Foliofeld genügt für eine zusätzliche Zeile.** Sie müssen QET
+  nicht ändern, um projektspezifische Angaben zu zeigen: Fügen Sie das Feld dem
+  Folio hinzu und verweisen Sie mit `%{meinfeld}` darauf.
+
+---
+
+Siehe auch: **[Variablen und Formeln](variables)** ·
+**[Automatische Nummerierung](autonumbering)** ·
+[Project XML](project_XML)
@@ -0,0 +1,225 @@
+# Modèles de cartouche
+
+Le cartouche est le panneau encadré d'informations, dans un coin du folio. Sa
+disposition n'est pas figée dans le programme : c'est un **modèle**, un fichier
+`.titleblock`, que vous pouvez modifier ou réécrire.
+
+QElectroTech livre dix modèles et dispose d'un éditeur dédié.
+
+Sources : `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h`, et
+`sources/titleblock/` pour l'éditeur.
+
+---
+
+## 1. Un modèle est une grille
+
+Un modèle est une grille de cellules, de trois types :
+
+| Type | Affiche |
+|---|---|
+| **Champ** | un libellé et une valeur, l'un comme l'autre pouvant contenir des variables |
+| **Logo** | une image stockée dans le fichier modèle |
+| **Vide** | rien — la cellule réserve la place |
+
+Les cellules peuvent **fusionner** lignes et colonnes voisines : une large
+cellule de titre en haut surmontant une pile de petites cellules, ce n'est que
+de la fusion.
+
+### Les largeurs de colonnes ont trois natures
+
+C'est la partie du format qu'il faut comprendre, car c'est elle qui permet à un
+modèle de s'adapter à tout format de papier. L'attribut `cols` de la grille est
+une liste de longueurs, chacune avec son préfixe :
+
+| Écrit | Signifie |
+|---|---|
+| `120px;` | **absolu** — toujours 120 pixels |
+| `t22%;` | **22 % du total** de la largeur disponible |
+| `r100%;` | **100 % du reste**, une fois retirées les colonnes absolues et relatives au total |
+
+Ainsi `cols="t22%;r100%;t22%;"` — le défaut livré — signifie : une colonne de
+22 % de la largeur, puis une colonne qui absorbe tout le reste, puis encore
+22 %. La colonne centrale s'étire et les deux extérieures gardent leurs
+proportions, quelle que soit la largeur du folio.
+
+**Les lignes sont toujours absolues**, données en pixels : `rows="25;25;"`. Il
+n'existe pas de hauteur de ligne relative.
+
+---
+
+## 2. Libellés, valeurs et traductions
+
+Une cellule de champ contient deux textes, **tous deux traduisibles** :
+
+```xml
+<field row="0" col="0" name="author" align="left" valign="center"
+       displaylabel="true" hadjust="true">
+    <value>
+        <translation lang="en">%author</translation>
+    </value>
+    <label>
+        <translation lang="en">Author</translation>
+        <translation lang="fr">Auteur</translation>
+        <translation lang="de">Autor</translation>
+    </label>
+</field>
+```
+
+- Le **libellé** est la légende fixe — *Auteur* — normalement traduite dans
+  toutes les langues que le modèle prend en charge.
+- La **valeur** est ce qui change d'un folio à l'autre, et contient
+  habituellement une variable. Une seule entrée suffit le plus souvent, puisque
+  `%author` est identique dans toutes les langues.
+- `displaylabel` décide si la légende est dessinée. Une grande cellule de titre
+  le met généralement à `false`.
+- `name` identifie la cellule dans le modèle. Il n'est **pas** dessiné.
+- `hadjust` réduit la police quand le texte ne tient pas, au lieu de le laisser
+  déborder.
+
+---
+
+## 3. Variables
+
+Les cellules de cartouche ont leur propre substitution, **plus permissive que
+partout ailleurs dans QET** : toute clé du contexte du folio est remplacée, sous
+les deux formes. `%{author}` et `%author` fonctionnent l'un comme l'autre.
+
+Les clés standard sont les champs du folio : `title`, `author`, `filename`,
+`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`. Les
+propriétés du projet et tout champ de folio personnalisé sont également
+substitués — c'est ainsi qu'un modèle peut porter un champ dont QET ignore tout.
+
+Deux détails :
+
+- Les clés sont substituées **de la plus longue à la plus courte**,
+  délibérément, pour qu'une clé nommée `plant` ne puisse pas manger le début de
+  `%plantcode`.
+- Seule la forme entre accolades `%{nom}` peut être **découverte** : l'éditeur
+  construit sa liste de variables employées en cherchant `%{…}` ; un `%nom` nu
+  s'affiche bien mais rien ne peut l'énumérer. **Préférez la forme entre
+  accolades** dans un modèle.
+
+Référence complète : **[Variables et formules](variables)**.
+
+---
+
+## 4. Logos
+
+Les logos sont stockés **dans** le fichier modèle : un modèle est donc autonome
+et se partage en un seul fichier.
+
+La balise `<logo>` sert à deux choses différentes, ce qu'il vaut mieux savoir
+avant d'éditer un fichier à la main :
+
+```xml
+<logos>
+    <!-- l'image stockée elle-même -->
+    <logo storage="xml" type="svg" name="qelectrotech.svg">
+        <svg …>…</svg>
+    </logo>
+</logos>
+<grid cols="…" rows="…">
+    <!-- une cellule qui en affiche un -->
+    <logo row="0" col="0" rowspan="1" name="" resource="qelectrotech.svg"/>
+</grid>
+```
+
+Dans `<logos>` c'est l'image ; dans `<grid>` c'est une cellule, qui désigne une
+image par `resource`.
+
+Deux formes de stockage :
+
+| `storage` | Pour | Comment |
+|---|---|---|
+| `xml` | SVG uniquement | l'arbre `<svg>` est intégré directement en XML |
+| `base64` | toute image matricielle (et le SVG, si vous y tenez) | les octets bruts, encodés en base64, sous forme de texte |
+
+**Les images matricielles ne peuvent être stockées qu'en `base64`** — QET
+l'impose, quoi que vous demandiez. Le SVG accepte les deux, et `xml` est le
+choix raisonnable : le fichier reste comparable et le logo reste vectoriel.
+
+Quand vous ajoutez un logo depuis l'éditeur, QET essaie d'abord le SVG puis se
+rabat sur le matriciel : la forme de stockage est donc choisie pour vous.
+
+> **Défaut connu.** Un `<logo>` dont l'attribut `storage` n'est ni `xml` ni
+> `base64` perd son image à l'enregistrement : l'élément est écrit avec ses
+> attributs et sans contenu, silencieusement. Le code contient le repli qui
+> l'éviterait mais ne s'en sert pas. Seuls des fichiers écrits à la main ou
+> générés peuvent tomber dessus — aucun modèle livré n'est concerné. Tenez-vous
+> aux deux valeurs valides.
+
+---
+
+## 5. Où vivent les modèles
+
+Quatre collections, dans le vocabulaire de QET :
+
+| Collection | Emplacement | Pour |
+|---|---|---|
+| **Commune** | `titleblocks/` à côté du binaire | les modèles livrés avec QET |
+| **Entreprise** | `<dossier de données>/titleblocks-company/` | les modèles partagés d'une organisation |
+| **Utilisateur** | `<dossier de données>/titleblocks/` | les vôtres |
+| **Intégrée** | à l'intérieur du fichier `.qet` | les modèles portés par un projet |
+
+L'intégrée est celle qui compte pour le partage : un projet utilisant un modèle
+que vous avez écrit en emporte une copie, et s'affiche donc correctement sur une
+machine qui n'a jamais vu votre modèle.
+
+---
+
+## 6. Le format en un coup d'œil
+
+```xml
+<titleblocktemplate name="default">
+    <information></information>
+    <logos/>
+    <grid cols="t22%;r100%;t22%;" rows="25;25;">
+        <field row="0" col="0" name="author" align="left" valign="center"
+               displaylabel="true" hadjust="true">
+            <value><translation lang="en">%author</translation></value>
+            <label><translation lang="fr">Auteur</translation></label>
+        </field>
+        …
+    </grid>
+</titleblocktemplate>
+```
+
+| Élément | Contient |
+|---|---|
+| `<information>` | texte libre sur le modèle — auteur, usage |
+| `<logos>` | les images stockées |
+| `<grid>` | `cols`, `rows`, et les cellules |
+| `<field>` | une cellule de champ |
+| `<logo>` (dans la grille) | une cellule de logo |
+| `<empty>` | une cellule vide |
+
+Le **nom de balise d'une cellule est son type** : `field`, `logo` ou `empty`.
+Les attributs communs sont `row`, `col`, `rowspan`, `colspan` et `name`. Un
+`field` ajoute `align` (`left`/`center`/`right`), `valign`, `displaylabel`,
+`hadjust` et `fontsize` — ce dernier écrit seulement si une taille a été fixée,
+un `fontsize` absent signifiant donc « par défaut ». Une cellule `logo` ajoute
+`resource`.
+
+---
+
+## 7. Notes pratiques
+
+- **Concevez pour l'étirement, non pour une largeur fixe.** Donnez une largeur
+  `t…%` aux cellules qui doivent garder leurs proportions et laissez une colonne
+  prendre `r100%`. Un modèle bâti uniquement sur des largeurs absolues sera mal
+  proportionné sur un autre format de papier.
+- **Traduisez les libellés, pas les valeurs.** Une valeur est le plus souvent une
+  variable, identique dans toutes les langues.
+- **Utilisez les variables `%{entre accolades}`** pour que l'éditeur puisse les
+  lister.
+- **Gardez un modèle autonome.** Les logos vivent dans le fichier ; ne dépendez
+  pas d'un chemin externe.
+- **Un champ de folio personnalisé suffit à ajouter une ligne.** Nul besoin de
+  modifier QET pour afficher une information propre à votre projet : ajoutez le
+  champ au folio et référencez-le par `%{monchamp}`.
+
+---
+
+Voir aussi : **[Variables et formules](variables)** ·
+**[Numérotation automatique](autonumbering)** ·
+[Project XML](project_XML)
@@ -0,0 +1,220 @@
+# Title block templates
+
+The title block is the framed panel of drawing information in the corner of a
+folio. Its layout is not hard-coded — it is a **template**, a `.titleblock`
+file, and you can edit or write your own.
+
+QElectroTech ships ten templates and includes a dedicated editor for them.
+
+Source: `sources/titleblocktemplate.cpp`, `sources/titleblockcell.h`, and
+`sources/titleblock/` for the editor.
+
+---
+
+## 1. A template is a grid
+
+A template is a grid of cells. Each cell is one of three types:
+
+| Type | Shows |
+|---|---|
+| **Text** | a label and a value, either of which may contain variables |
+| **Logo** | an image stored inside the template file |
+| **Empty** | nothing — it reserves space |
+
+Cells can **span** neighbouring rows and columns, so a wide title cell across
+the top and a stack of small cells below is just spanning.
+
+### Column widths use three kinds of length
+
+This is the part of the format worth understanding, because it is what makes a
+template fit any paper size. The grid's `cols` attribute is a list of lengths,
+each with a prefix:
+
+| Written | Means |
+|---|---|
+| `120px;` | **absolute** — always 120 pixels |
+| `t22%;` | **22% of the total** width available |
+| `r100%;` | **100% of the remaining** width, after absolute and total-relative columns are taken out |
+
+So `cols="t22%;r100%;t22%;"` — the shipped default — is: a column of 22% of the
+width, then a column that absorbs everything left over, then another 22%. The
+middle column stretches and the outer two stay proportional, whatever the
+folio's width.
+
+**Rows are always absolute**, given as plain pixel heights: `rows="25;25;"`.
+There is no relative row height.
+
+---
+
+## 2. Labels, values and translations
+
+A text cell holds two pieces of text, and **both are translatable**:
+
+```xml
+<field row="0" col="0" name="author" align="left" valign="center"
+       displaylabel="true" hadjust="true">
+    <value>
+        <translation lang="en">%author</translation>
+    </value>
+    <label>
+        <translation lang="en">Author</translation>
+        <translation lang="fr">Auteur</translation>
+        <translation lang="de">Autor</translation>
+    </label>
+</field>
+```
+
+- The **label** is the fixed caption — *Author* — and is normally translated
+  into every language the template supports.
+- The **value** is what changes per folio, and normally holds a variable. It
+  usually needs only one entry, since `%author` is the same in every language.
+- `displaylabel` decides whether the caption is drawn at all. A big title cell
+  typically sets it `false`.
+- `name` identifies the cell inside the template. It is **not** drawn.
+- `hadjust` shrinks the font when the text does not fit, rather than letting it
+  overflow.
+
+---
+
+## 3. Variables
+
+Title block cells use their own substitution, and it is **more permissive than
+anywhere else in QET**: every key in the folio's context is replaced, in both
+the braced and bare forms. `%{author}` and `%author` both work.
+
+Standard keys are the folio's own fields: `title`, `author`, `filename`,
+`folio`, `plant`, `locmach`, `indexrev`, `date`, `display_folio`. Project
+properties and any custom folio fields are substituted too — which is how a
+template can carry a field QET knows nothing about.
+
+Two details:
+
+- Keys are substituted **longest first**, deliberately, so a key named `plant`
+  cannot eat the front of `%plantcode`.
+- Only the braced form `%{name}` can be **discovered**. The editor builds its
+  list of variables in use by scanning for `%{…}`; a bare `%name` still
+  renders but nothing can enumerate it. **Prefer the braced form** when writing
+  a template.
+
+Full variable reference: **[Variables & formulas](variables)**.
+
+---
+
+## 4. Logos
+
+Logos are stored **inside** the template file, so a template is self-contained
+and can be shared as one file.
+
+The `<logo>` tag is used for two different things, which is worth knowing before
+you hand-edit a file:
+
+```xml
+<logos>
+    <!-- the stored image itself -->
+    <logo storage="xml" type="svg" name="qelectrotech.svg">
+        <svg …>…</svg>
+    </logo>
+</logos>
+<grid cols="…" rows="…">
+    <!-- a cell that displays one -->
+    <logo row="0" col="0" rowspan="1" name="" resource="qelectrotech.svg"/>
+</grid>
+```
+
+Inside `<logos>` it is the image; inside `<grid>` it is a cell, referring to an
+image by `resource`.
+
+Two storage forms:
+
+| `storage` | For | How |
+|---|---|---|
+| `xml` | SVG only | the `<svg>` tree is embedded directly as XML |
+| `base64` | any bitmap (and SVG, if you insist) | the raw bytes, base64 encoded, as text |
+
+**Bitmaps can only be stored as `base64`** — QET forces it regardless of what
+you ask for. SVG can use either, and `xml` is the sensible choice: it keeps the
+file diffable and lets the logo scale.
+
+When you add a logo through the editor, QET tries SVG first and falls back to
+bitmap, so the storage form is chosen for you.
+
+> **Known defect.** A `<logo>` whose `storage` attribute is neither `xml` nor
+> `base64` loses its image data when the template is saved: the element is
+> written with its attributes and no content, silently. The code contains the
+> fallback that would prevent this but does not use it. Only hand-written or
+> generated files can hit this — none of the shipped templates do. Keep
+> `storage` to the two valid values.
+
+---
+
+## 5. Where templates live
+
+Four collections, in QET's own vocabulary:
+
+| Collection | Location | For |
+|---|---|---|
+| **Common** | `titleblocks/` next to the binary | the templates that ship with QET |
+| **Company** | `<data dir>/titleblocks-company/` | an organisation's shared templates |
+| **Custom** | `<data dir>/titleblocks/` | your own |
+| **Embedded** | inside the `.qet` file | templates carried by a project |
+
+Embedded is the one that matters for sharing work: a project that uses a
+template you wrote carries a copy, so it renders correctly on a machine that has
+never seen your template.
+
+---
+
+## 6. The file format at a glance
+
+```xml
+<titleblocktemplate name="default">
+    <information></information>
+    <logos/>
+    <grid cols="t22%;r100%;t22%;" rows="25;25;">
+        <field row="0" col="0" name="author" align="left" valign="center"
+               displaylabel="true" hadjust="true">
+            <value><translation lang="en">%author</translation></value>
+            <label><translation lang="en">Author</translation></label>
+        </field>
+        …
+    </grid>
+</titleblocktemplate>
+```
+
+| Element | Holds |
+|---|---|
+| `<information>` | free text about the template — author, purpose |
+| `<logos>` | the stored images |
+| `<grid>` | `cols`, `rows`, and the cells |
+| `<field>` | a text cell |
+| `<logo>` (in grid) | a logo cell |
+| `<empty>` | an empty cell |
+
+The cell's **tag name is its type**: `field`, `logo` or `empty`. Common
+attributes are `row`, `col`, `rowspan`, `colspan` and `name`. A `field` adds
+`align` (`left`/`center`/`right`), `valign`, `displaylabel`, `hadjust` and
+`fontsize` — the last written only when a size has actually been set, so an
+absent `fontsize` means "default". A `logo` cell adds `resource`.
+
+---
+
+## 7. Practical notes
+
+- **Design against the stretch, not a fixed width.** Give the cells that must
+  keep their proportions a `t…%` width and let one column take `r100%`. A
+  template built from absolute widths only will look wrong on a different paper
+  size.
+- **Translate labels, not values.** A value is usually a variable and the same
+  in every language.
+- **Use `%{braced}` variables** so the editor can list them.
+- **Keep a template self-contained.** Logos live inside the file; do not rely on
+  an external path.
+- **A custom folio field is enough to add a row.** You do not need to modify
+  QET to show project-specific information — add the field to the folio and
+  reference it as `%{yourfield}`.
+
+---
+
+See also: **[Variables & formulas](variables)** ·
+**[Auto-numbering](autonumbering)** ·
+[Project XML](project_XML)