GlossaristGlossarist

Inline Mentions

Inline references in concept text (definitions, notes, examples) use a unified mention syntax: {{kind:target}}. Every mention carries an explicit kind prefix — the renderer always knows what type of thing it is resolving.

One rule to remember: every mention is {{kind:target}}. The kind says what type of thing you’re referencing. The target is the canonical identifier (never a local alias, never bare text). If in doubt, qualify with the dataset name: DATASET:ID.

Kind reference

KindSyntaxExampleResolves to
concept{{concept:DATASET:ID}}{{concept:IEV:702-02-07}}A concept (link, no source metadata)
cite{{cite:DATASET:ID}}{{cite:IEV:702-02-07, IEV 702-02-07}}A concept cited as a source (carries ConceptSource metadata if matched)
fig{{fig:ID}}{{fig:diagram_3, Figure 3: Signal flow}}A figure entity in the same dataset
table{{table:ID}}{{table:units}}A table entity
formula{{formula:ID}}{{formula:ohm_law}}A formula entity
bib{{bib:ID}}{{bib:ref_1, ISO 704:2022}}A bibliography entry (no underlying concept)
link{{link:URL}}{{link:https://example.com, Example Site}}An external URL (https:// or http:// only)
image{{image:path}}{{image:figures/wave.svg, Sine wave}}An inline image (path or URL)

Every mention requires a kind. Bare {{designation}} or {{112-01-10}} are rejected at parse time.

Target types

The target (everything after kind: and before the optional , label) is parsed into a structured shape:

Target textParsed asStructured shape
urn:iec:std:iec:60050:702-02-07URN{ type: "urn", urn: "urn:iec:std:iec:60050:702-02-07" }
IEV:702-02-07Dataset-qualified{ type: "dataset_qualified", dataset: "IEV", id: "702-02-07" }
ISO:10241-1:2011Dataset-qualified (last colon splits){ type: "dataset_qualified", dataset: "ISO", id: "10241-1:2011" }
diagram_3Plain entity ID{ type: "entity_id", id: "diagram_3" }
https://example.comURL{ type: "url", url: "https://example.com" }
figures/img.svgFile path{ type: "path", path: "figures/img.svg" }

For DATASET:ID, the parser splits on the last colon — everything before is the dataset name, everything after is the entity ID. This handles dataset names with internal colons like ISO:10241-1:2011.

Per-kind target validation

Each kind accepts only certain target types. Invalid combinations throw InvalidMentionError at parse time:

KindAcceptsRejects
conceptDATASET:ID, URNbare ID, URL, path
citeDATASET:ID, URNbare ID, URL, path
figplain ID, URNDATASET:ID (use URN for cross-dataset)
tableplain ID, URNDATASET:ID
formulaplain ID, URNDATASET:ID
bibplain ID onlyURN, DATASET:ID, URL
linkhttps:// or http:// URLbare text, path, DATASET:ID
imagepath or URLDATASET:ID, URN

Resolution

Mentions resolve in two phases: parse (pure, no I/O) produces segments; resolve looks each mention up against the loaded dataset.

concept:DATASET:ID / concept:URN

Looks up the concept in the vocabulary store. If found, renders as an inline link. If not found, renders as plain text with a dashed underline and tooltip — authoring errors are visible, not silent.

cite:DATASET:ID / cite:URN

Resolves the concept (same as concept: above). If the surrounding concept has a ConceptSource whose origin.ref matches { source: dataset, id: entity_id }, the citation carries the source metadata (type, status, modification). If no source matches, the citation still resolves as a plain concept link — no pre-declaration required.

sources:
  - type: authoritative
    origin:
      ref: { source: IEV, id: "702-02-07" }

notes:
  - content: "See {{cite:IEV:702-02-07, IEV 702-02-07}} for the definition of signal."

fig / table / formula / bib

Look up the entity by plain ID in the same dataset. Cross-dataset URN lookups for non-concept entities are planned for a future phase.

Always resolve — the URL or path is the canonical target. The renderer handles missing image files.

Data / Deployment Boundary

Mention syntax is deployment-agnostic. The dataset author writes {{cite:IEV:702-02-07}} regardless of where the dataset will be deployed.

The deployment (via site-config.yml) determines how each DATASET:ID or URN target resolves at render time:

  1. Is the target in a co-deployed dataset? → internal link to the local concept page
  2. Is the target in the routing table? → external link via the deployment’s uriPatterns
  3. Does the source have a canonical link? → flat self-contained bib record
  4. No match → plain text with dashed-underline indicator

The same YAML renders differently in different deployments. The data never changes — only the routing does.

URN variant (cross-dataset universal)

When you know the canonical URN but not the dataset-qualified ID, use the URN form with concept: or cite::

{{concept:urn:iec:std:iec:60050:702-02-07}}
{{cite:urn:iso:std:iso:704:2022, ISO 704:2022}}

The deployment’s uriPatterns in site-config.yml routes the URN to the canonical source.

Common errors and fixes

ErrorCauseFix
missing kind prefixWrote {{measurement unit}} or {{112-01-10}}Add kind: {{concept:VIM:112-01-10}}
must be DATASET:ID or URN; got bare IDWrote {{cite:sourceId1}} (local alias)Use canonical: {{cite:IEV:702-02-07}}
concept target must be DATASET:ID or URNWrote {{concept:112-01-10}}Add dataset: {{concept:VIM:112-01-10}}
link target must be https:// or http://Wrote {{link:/internal/page}}Use full URL: {{link:https://...}}
bib entries do not have URNsWrote {{bib:urn:...}}Use plain ID: {{bib:ref_1}}
unknown kind 'ref'Wrote {{ref:IEV:702-02-07}}Use cite or concept
Raw HTML rejectedWrote <a href="..."> or <img src="...">Use {{link:...}} or {{image:...}}
Deprecated syntaxWrote <<target, caption>>Use {{fig:target, caption}}

Deprecated: <<ref,title>>

The AsciiDoc xref syntax <<ref,title>> is deprecated. It emits a console warning and renders as plain text. Migrate to the unified syntax:

  • <<fig_3, Figure 3>> → {{fig:fig_3, Figure 3}}
  • <<845-01-01, 845-01-01>> → {{cite:IEV:845-01-01, 845-01-01}}
  • <<ref_1, ISO 704>> → {{bib:ref_1, ISO 704}}
Edit this page