Document the terminal name check (PR #1159); drop merged #1152 notices

aligning_items.md

@@ -59,12 +59,6 @@ what happened:
 
 ### Which items move, and to which grid
 
-> **Status: pending.** The shape changes in this section describe
-> [PR #1152](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1152),
-> not yet merged. Until it lands, shapes are left out: a selection of
-> shapes only greys the commands out, and a shape outside a group is not
-> moved. This notice will come out once it merges.
-
 | Item | Snaps to |
 |---|---|
 | Symbols | the folio grid, by the symbol's origin point: exactly where dragging it would have dropped it |
@@ -97,13 +91,6 @@ Items already on the grid stay exactly where they are.
 
 ## Align
 
-> **Status: pending.** The shape changes in this section, and "a single
-> group counts as one item", describe
-> [PR #1152](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1152),
-> not yet merged. Until it lands, shapes are left out: a selection of
-> shapes only greys the commands out, and a shape outside a group is not
-> moved. This notice will come out once it merges.
-
 ### Using it
 
 1. Select **two or more** items: symbols, pictures, free texts, shapes or groups.

api_reference.md

@@ -213,6 +213,21 @@ It reports each file as OK, WARN (loads but suspicious — for instance zero
 terminals) or FAIL (unparseable, wrong root tag, missing bounding box), and
 exits non-zero on any failure. Put it in CI if you generate `.elmt` files.
 
+> **Status: pending.** The terminal-name checks in this paragraph describe
+> [PR #1159](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1159),
+> not yet merged. This notice will come out once it merges.
+
+It also checks terminal names, with the same rule the element editor applies
+on save (see **[Using the element editor](element_editor)** §5): two terminals
+of one element sharing a name is a **FAIL**, and terminals without a name are
+a **WARN** (folio reports, conductor definitions and thumbnails excepted).
+The element editor's setting to turn the check off does not apply here.
+
+```text
+FAIL  my_elements/shelly_pro_2pm.elmt  (repeated terminal names: N ×3)
+WARN  my_elements/90-10-0111.elmt  (2 of 2 terminals have no name)
+```
+
 ### Rules of thumb
 
 - **Close the project in QET before rewriting its file.** QET holds its own

element_editor.md

@@ -62,6 +62,9 @@ Terminal *type* and *function* (generic, fuse, diode, ground…) are set
 afterward in the terminal's own properties, not while placing it — see
 **[Linking elements](element_linking)** §4.
 
+Give every terminal a **name** in its properties too, and never the same name
+twice in one symbol — see §5, *Terminal names*.
+
 ---
 
 ## 3. Width, height and hotspot are computed, not typed
@@ -118,6 +121,58 @@ An element with zero terminals still saves — you'll just get a dialog telling
 you it can't be wired to anything, which is sometimes exactly what you want
 (a thumbnail, a text block, a title-block decoration).
 
+### Terminal names
+
+> **Status: pending.** Everything in this subsection describes
+> [PR #1159](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1159),
+> not yet merged. Nothing here works until that lands — check the PR before
+> trying any of this against your own build. This notice will come out once
+> it merges.
+
+Every terminal of a symbol should have a name, and no two terminals of the
+same symbol may share one. The wiring list (what connects to what) names each
+end of a wire as *symbol label : terminal name*, so two terminals both called
+`N` on `-K1` give two different wires the same address, `-K1:N`, and nobody
+wiring the panel can tell them apart. IEC 61666 §4.1 states the rule: *"Each
+terminal shall be unambiguously identified with respect to the object
+itself."*
+
+| Condition | Severity |
+|---|---|
+| Two or more terminals share a name | **error** — the save is blocked, and the terminals involved are selected so you can find them |
+| One or more terminals have no name | **warning** — the save goes ahead. Folio reports, conductor definitions and thumbnails are not checked |
+
+![The error dialog when saving a Shelly Pro 2PM with three terminals named N: "Plusieurs bornes portent le même nom : N ×3", with the fix "Donner un nom unique à chaque borne, par exemple N.1 et N.2"](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/element-editor-duplicate-terminal-names.png)
+
+How names are compared:
+
+- Spaces at the start and end are ignored: `PE` and ` PE ` are the same name.
+- Case counts: `n` and `N` are different names.
+- Unnamed terminals are counted as unnamed, never as duplicates of each other.
+
+**Real devices sometimes print the same marking twice.** Some Shelly relays
+have two terminals marked N or two marked L, bridged inside the device. The marking on the device is still not enough
+for the drawing: IEC 61666 §4.2 says that when the manufacturer's marking is
+insufficient to tell terminals apart, you assign your own designations and
+explain them. Give each one a distinct name that keeps the printed marking,
+for example `N.1` and `N.2`.
+
+![The warning dialog for a feed-through terminal whose two terminals have no name: "2 borne(s) sans nom"](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/element-editor-unnamed-terminals.png)
+
+#### Turning the check off
+
+*Configuration → Configurer QElectroTech → Général → Editor →*
+**Vérifier les noms des bornes à l'enregistrement** (*Check terminal names
+when saving*). It is on by default. Unticked, neither the error nor the
+warning appears and every symbol saves as before.
+
+![The Editor tab of the configuration dialog, with the "Vérifier les noms des bornes à l'enregistrement" checkbox ticked](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/settings-check-terminal-names.png)
+
+The setting belongs to your QElectroTech installation, not to the symbol or
+the project. The command-line check (`--check-elements`, see
+**[Automating QElectroTech](api_reference)**) ignores it and always checks
+names.
+
 ---
 
 ## 6. The panels around the canvas