glossarist 2.13.9 → 2.13.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e42372897ecf000813b37db02afdc6461039b9ee4618182515793d548bd9951
-  data.tar.gz: 33f5ba8dfb1b35782fc3711aa9ec7a0f1f675c55a0876c830975d4ca14770761
+  metadata.gz: 16c44282632761dbbfeb3b63ff619b519648f0af7306ee5aa85fba1606244bd6
+  data.tar.gz: 37e8af5033c014195228ba11f50528b7aca8c06424533196ea0c318d5f78c7f0
 SHA512:
-  metadata.gz: 02d246dd723fd2f2834c54ac2e3d8f4a38251e543d7b677ed0ada8cd11af05cddfd41999f6772bbf8235ba486af8d76a603585185f4fd8475bcfaac22ce72a59
-  data.tar.gz: d1f34a759e7505afee75884ca7d5cbaa0b02f547ce8f1464317e00fc31fb011b4cd9820faa4a13d9eaa3e87c5daae74d93236cf940759d8b0cd7367996c00f78
+  metadata.gz: 8dadb718f3a39e49167eb1d8aa8eeada22f826c049be68dcfe151cd0980edb0e80006a51b21f64912dcc9e9d4ef21ff47618002b6d7d1496b88669cb39932620
+  data.tar.gz: 29f66da8f1f743c7f5424e966bf4b19a94e83264146d9c3156243f0f0a39e728874fcc4cbf6f2a2d8c77bd4799406083162d27b5f675dd1fe0aa88246091222d

data/PROMPT-NOW.md

@@ -0,0 +1,227 @@
+# PROMPT-NOW: parseMention extension + legacy <<>> deprecation + terminology alignment + raw-HTML validation
+
+> **Context:** concept-browser is implementing a strict DATA/DEPLOYMENT boundary for inline content. This requires all Glossarist libraries (JS, Ruby, and the concept-model schema) to parse the same unified `{{kind:target}}` syntax and align terminology. The JS library changes are tracked in a parallel PROMPT-NOW.md; this prompt mirrors them for the Ruby library. Self-contained.
+
+## Background: the principle
+
+**Dataset authors** write `{{kind:target}}` mentions in concept text. They don't know where their dataset will be deployed.
+
+**Concept-browser** resolves every mention at runtime via `ReferenceResolver`. For this to work, `parse_mention` must produce a canonical `{kind, target, label}` shape for every mention kind — identical to the JS library's output.
+
+The current parser recognizes `cite:`, `urn:`, `fig:`/`figure:`, `table:`/`tbl:`, `formula:`/`eq:`, and bare designation/numeric. Three new kinds are needed: `link`, `image`, `bib`.
+
+---
+
+## P1: parse_mention extension — `link`, `image`, `bib` kinds
+
+### New kinds to parse
+
+```ruby
+Glossarist.parse_mention("{{link:https://example.com/page}}")
+# => { kind: 'link-ref', uri: 'https://example.com/page', label: nil }
+
+Glossarist.parse_mention("{{link:https://example.com, click here}}")
+# => { kind: 'link-ref', uri: 'https://example.com', label: 'click here' }
+
+Glossarist.parse_mention("{{image:diagram.png}}")
+# => { kind: 'image-ref', src: 'diagram.png', alt: nil }
+
+Glossarist.parse_mention("{{image:diagram.png, The diagram}}")
+# => { kind: 'image-ref', src: 'diagram.png', alt: 'The diagram' }
+
+Glossarist.parse_mention("{{bib:ref_1}}")
+# => { kind: 'bib-ref', id: 'ref_1', label: nil }
+
+Glossarist.parse_mention("{{bib:ref_1, ISO 704}}")
+# => { kind: 'bib-ref', id: 'ref_1', label: 'ISO 704' }
+```
+
+### Design notes
+
+- `link` uses `uri` (not `id`) because the target is a URL, not a dataset-local handle. The URL is canonical — external to all datasets, deployment-independent.
+- `image` uses `src` (not `uri`) and `alt` (not `label`) because it's an embed, not a link. The `alt` field is the accessibility text.
+- `bib` uses `id` because it references a dataset-local bibliography entry. This is the case-3-only path — the author explicitly wants a flat bibliographic record, not a concept resolution.
+
+The parsed shapes MUST match the JS library's output exactly (same keys, same values) so concept-browser can consume either library's output interchangeably.
+
+---
+
+## P2: Legacy `<<target, caption>>` deprecation
+
+### The problem
+
+The AsciiDoc xref syntax `<<target, caption>>` has been overloaded for:
+1. **Non-concept entity xrefs** (legitimate AsciiDoc use — should map to `{{fig/table/formula:target, caption}}`)
+2. **Bibliography lookups** (wrong — bypasses the resolution cascade)
+3. **Concept citations** (wrong — should use `{{cite:target, caption}}`)
+
+### Proposed change
+
+When the parser encounters `<<target, caption>>`:
+
+1. **Emit a deprecation warning** via Ruby's `Warning` module:
+
+```ruby
+Warning.warn("[glossarist] <<#{target}, #{caption}>> is deprecated. " \
+             "Use {{fig/table/formula:#{target}, #{caption}}} for non-concept entities, " \
+             "or {{cite:#{target}, #{caption}}} for concept citations.")
+```
+
+2. **Re-parse** based on what `target` resolves to:
+   - If `target` matches a figure/table/formula entity in the dataset → treat as `{{kind:target, caption}}`
+   - Otherwise → treat as `{{cite:target, caption}}` (let concept-browser's resolution cascade handle it)
+
+3. **Do NOT** treat as a bibliography lookup. Bibliography is reached only via `{{bib:id}}` (explicit) or via the resolution cascade's case-3 fallback (implicit).
+
+### RuboCop cop (optional)
+
+Consider a custom RuboCop cop that flags `<<...,...>>` in concept text fixtures:
+
+```ruby
+# .rubocop.yml
+require: glossarist/rubocop
+
+Glossarist/NoLegacyXrefSyntax:
+  Enabled: true
+  Description: 'Use {{kind:target}} instead of <<target, caption>>'
+```
+
+---
+
+## P3: Terminology alignment
+
+### The rename
+
+Rename `NonVerbalEntity` → `NonConceptEntity` in Ruby model classes (where referring to Figure/Table/Formula). The terminology fix:
+
+- **Non-verbal** refers to the modality of expression (non-verbal designation: symbol, formula expression). Properties OF concepts.
+- **Non-concept** refers to entities that are NOT concepts at all (Figure, Table, Formula). Standalone dataset entities.
+
+### Proposed change
+
+```ruby
+# BEFORE
+module Glossarist
+  class NonVerbalEntity < GlossaristModel; end      # ambiguous
+  class SharedNonVerbalEntity < NonVerbalEntity; end
+  class NonVerbRep < GlossaristModel; end            # concept-local designation
+end
+
+# AFTER
+module Glossarist
+  class NonConceptEntity < GlossaristModel; end      # clear — NOT a concept
+  class NonVerbRep < GlossaristModel; end            # unchanged — IS a designation
+
+  # Deprecated alias for backward compat
+  # @deprecated Use NonConceptEntity instead.
+  NonVerbalEntity = NonConceptEntity
+  SharedNonVerbalEntity = NonConceptEntity
+end
+```
+
+Keep `NonVerbRep` unchanged — it IS a non-verbal representation (a designation of a concept).
+
+Provide deprecated aliases for one release cycle.
+
+---
+
+## P4: Raw-HTML validation
+
+### The problem
+
+Concept text sometimes contains raw HTML instead of typed mention syntax:
+
+```yaml
+# BAD — raw HTML in YAML
+definition:
+  - content: See <a href="http://std.iec.ch/...">IEV</a> for details.
+```
+
+This bypasses the renderer, is brittle, has no accessibility contract, and can embed deployment-specific URLs.
+
+### Proposed change
+
+Add a validator:
+
+```ruby
+module Glossarist
+  module Validators
+    class NoRawHtml
+      def self.call(text)
+        issues = []
+
+        # <a href="URL">label</a> → {{link:URL, label}}
+        text.scan(/<a\s+href="([^"]+)"[^>]*>([^<]*)<\/a>/i) do |url, label|
+          issues << {
+            severity: 'warning',
+            match: "<a href=\"#{url}\">#{label}</a>",
+            suggestion: label && !label.empty? ? "{{link:#{url}, #{label}}}" : "{{link:#{url}}}",
+            message: 'Use {{link:}} instead of raw <a> tags',
+          }
+        end
+
+        # <img src="SRC" alt="ALT"> → {{image:SRC, ALT}}
+        text.scan(/<img\s+src="([^"]+)"(?:\s+alt="([^"]*)")?[^>]*>/i) do |src, alt|
+          suggestion = alt ? "{{image:#{src}, #{alt}}}" : "{{image:#{src}}}"
+          issues << {
+            severity: 'warning',
+            match: "<img src=\"#{src}\"#{" alt=\"#{alt}\"" if alt}>",
+            suggestion: suggestion,
+            message: 'Use {{image:}} instead of raw <img> tags',
+          }
+        end
+
+        issues
+      end
+    end
+  end
+end
+```
+
+Replacement suggestions:
+
+| Raw HTML | Suggested replacement |
+|---|---|
+| `<a href="URL">label</a>` | `{{link:URL, label}}` |
+| `<a href="URL">URL</a>` | `{{link:URL}}` |
+| `<img src="SRC">` | `{{image:SRC}}` |
+| `<img src="SRC" alt="ALT">` | `{{image:SRC, ALT}}` |
+| `<iframe src="URL">` | `{{link:URL}}` (iframes not supported as embeds) |
+
+The validator is opt-in — concept-browser (or the data pipeline) can call it during data loading to warn dataset authors.
+
+---
+
+## Summary
+
+| Change | Impact |
+|---|---|
+| P1: parse_mention extension | New parsed shapes for `link`, `image`, `bib` (must match JS output exactly) |
+| P2: Legacy `<<>>` deprecation | Warning + re-parse; optional RuboCop cop |
+| P3: Terminology rename | `NonVerbalEntity` → `NonConceptEntity` (with deprecated alias) |
+| P4: Raw-HTML validator | New `Glossarist::Validators::NoRawHtml` class |
+
+## Coordination
+
+- **concept-model** needs schema changes for the new kinds and terminology (parallel PROMPT-NOW.md).
+- **glossarist-js** needs the same parser extension (parallel PROMPT-NOW.md).
+- **concept-browser** wires the resolvers once both libraries ship the new parse output.
+- A **shared contract test fixture** (a concept with every kind of mention) should be consumed by all implementations to prevent syntax drift. The fixture lives in concept-model; both libraries import it.
+
+## Cross-library contract
+
+The parsed output from `parse_mention` MUST be identical between the Ruby and JS libraries:
+
+```ruby
+# Ruby
+Glossarist.parse_mention("{{link:https://example.com, click here}}")
+# => { kind: 'link-ref', uri: 'https://example.com', label: 'click here' }
+```
+
+```ts
+// JS
+parseMention("{{link:https://example.com, click here}}")
+// => { kind: 'link-ref', uri: 'https://example.com', label: 'click here' }
+```
+
+Same keys. Same values. Same symbol-as-string for `kind`. This allows concept-browser to consume either library's output without translation.

data/lib/glossarist/figure.rb

@@ -13,7 +13,7 @@ module Glossarist
   # subfigures.
   #
   # Caption, description, and alt are localized (hash keyed by ISO 639 code).
-  class Figure < SharedNonVerbalEntity
+  class Figure < SharedNonConceptEntity
     attribute :images, FigureImage, collection: true
     attribute :subfigures, Figure, collection: true
 

data/lib/glossarist/formula.rb

@@ -7,7 +7,7 @@ module Glossarist
   # shared across concepts. The mathematical expression is stored in a
   # notation format (LaTeX, MathML, AsciiMath). Caption, description, and
   # alt are localized for accessibility.
-  class Formula < SharedNonVerbalEntity
+  class Formula < SharedNonConceptEntity
     attribute :expression, :hash
     attribute :notation, :string
 

data/lib/glossarist/mention_parser.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Reference kinds produced by parse_mention for the unified
+  # {{kind:target}} / {{kind:target, label}} mention syntax.
+  #
+  # The shape produced for each kind is the cross-library contract —
+  # glossarist-js produces the same keys, same values, so concept-browser
+  # can consume either library's output interchangeably without translation.
+  module MentionKinds
+    # {{link:URL}} or {{link:URL, label}} — external URL link.
+    # `uri` is canonical (deployment-independent); `label` is the display
+    # text (nil means render the URL itself).
+    LINK_REF = "link-ref"
+
+    # {{image:src}} or {{image:src, alt}} — embedded image.
+    # `src` is the image source; `alt` is accessibility text (nil means
+    # no a11y label). Distinct from link-ref because it's an embed, not
+    # a navigation link.
+    IMAGE_REF = "image-ref"
+
+    # {{bib:id}} or {{bib:id, label}} — dataset-local bibliography entry.
+    # `id` references an entry in the dataset's bibliography.yaml. This is
+    # the case-3-only path — the author explicitly wants a flat
+    # bibliographic record, not a concept resolution.
+    BIB_REF = "bib-ref"
+
+    # {{cite:id}} or {{cite:id, label}} — concept citation.
+    CITE_REF = "cite-ref"
+
+    # {{fig:id}} / {{figure:id}} — non-concept figure entity xref.
+    FIG_REF = "fig-ref"
+
+    # {{table:id}} / {{tbl:id}} — non-concept table entity xref.
+    TABLE_REF = "table-ref"
+
+    # {{formula:id}} / {{eq:id}} — non-concept formula entity xref.
+    FORMULA_REF = "formula-ref"
+
+    # {{123}} or {{123, label}} — local concept by numeric id.
+    LOCAL_CONCEPT_REF = "local-concept-ref"
+
+    # {{designation}} — concept by designation text.
+    DESIGNATION_REF = "designation-ref"
+
+    # {{urn:...}} — URN reference.
+    URN_REF = "urn-ref"
+  end
+
+  # Parsed mention result — a plain Hash with symbol keys. Built by
+  # Glossarist.parse_mention. The shape per kind is documented on
+  # MentionKinds constants above.
+  #
+  # Examples:
+  #
+  #   Glossarist.parse_mention("{{link:https://example.com, click here}}")
+  #   # => { kind: "link-ref", uri: "https://example.com", label: "click here" }
+  #
+  #   Glossarist.parse_mention("{{image:diagram.png, The diagram}}")
+  #   # => { kind: "image-ref", src: "diagram.png", alt: "The diagram" }
+  #
+  #   Glossarist.parse_mention("{{bib:ref_1, ISO 704}}")
+  #   # => { kind: "bib-ref", id: "ref_1", label: "ISO 704" }
+  module MentionParser
+    module_function
+
+    # Parse a single {{...}} mention into a canonical Hash.
+    #
+    # Returns nil if the input is not a valid mention string.
+    # Raises ArgumentError if the mention is malformed (e.g., unknown
+    # kind prefix).
+    def parse_mention(text)
+      return nil unless text.is_a?(String)
+
+      match = text.match(/\A\s*\{\{([^}]+)\}\}\s*\z/)
+      return nil unless match
+
+      content = match[1].strip
+      parse_content(content)
+    end
+
+    # Parse the inside of a {{...}} mention (without the braces).
+    def parse_content(content)
+      content = content.to_s.strip
+      return nil if content.empty?
+
+      identifier, label = split_identifier_and_label(content)
+      dispatch_by_identifier(identifier, label)
+    end
+
+    def split_identifier_and_label(content)
+      return [content, nil] unless content.include?(",")
+
+      parts = content.split(",", 2)
+      [parts[0].strip, parts[1].to_s.strip]
+    end
+    private_class_method :split_identifier_and_label
+
+    def dispatch_by_identifier(identifier, label)
+      case identifier
+      when /\Alink:/i   then parse_link(identifier, label)
+      when /\Aimage:/i  then parse_image(identifier, label)
+      when /\Abib:/i    then parse_bib(identifier, label)
+      when /\Acite:/i   then parse_cite(identifier, label)
+      when /\A(fig|figure):/i  then parse_entity(identifier, label, MentionKinds::FIG_REF, "fig:")
+      when /\A(table|tbl):/i   then parse_entity(identifier, label, MentionKinds::TABLE_REF, "table:")
+      when /\A(formula|eq):/i  then parse_entity(identifier, label, MentionKinds::FORMULA_REF, "formula:")
+      when /\Aurn:/i    then parse_urn(identifier, label)
+      when /\A\d[\d.-]*\z/     then parse_local_concept(identifier, label)
+      else parse_designation(identifier, label)
+      end
+    end
+    private_class_method :dispatch_by_identifier
+
+    def strip_label(label)
+      label.nil? || label.empty? ? nil : label
+    end
+    private_class_method :strip_label
+
+    def parse_link(identifier, label)
+      uri = identifier.sub(/\Alink:/i, "").strip
+      { kind: MentionKinds::LINK_REF, uri: uri, label: strip_label(label) }
+    end
+    private_class_method :parse_link
+
+    def parse_image(identifier, label)
+      src = identifier.sub(/\Aimage:/i, "").strip
+      { kind: MentionKinds::IMAGE_REF, src: src, alt: strip_label(label) }
+    end
+    private_class_method :parse_image
+
+    def parse_bib(identifier, label)
+      id = identifier.sub(/\Abib:/i, "").strip
+      { kind: MentionKinds::BIB_REF, id: id, label: strip_label(label) }
+    end
+    private_class_method :parse_bib
+
+    def parse_cite(identifier, label)
+      id = strip_quote_wrapping(identifier.sub(/\Acite:/i, "").strip)
+      { kind: MentionKinds::CITE_REF, id: id, label: strip_label(label) }
+    end
+    private_class_method :parse_cite
+
+    def parse_entity(identifier, label, kind, prefix)
+      id = identifier.sub(/\A(?:fig|figure|table|tbl|formula|eq):/i, "").strip
+      { kind: kind, id: id, label: strip_label(label) }
+    end
+    private_class_method :parse_entity
+
+    def parse_urn(identifier, label)
+      { kind: MentionKinds::URN_REF, urn: identifier, label: strip_label(label) }
+    end
+    private_class_method :parse_urn
+
+    def parse_local_concept(identifier, label)
+      { kind: MentionKinds::LOCAL_CONCEPT_REF, id: identifier, label: strip_label(label) }
+    end
+    private_class_method :parse_local_concept
+
+    def parse_designation(identifier, label)
+      { kind: MentionKinds::DESIGNATION_REF, designation: label || identifier }
+    end
+    private_class_method :parse_designation
+
+    # cite: identifiers may be wrapped in double quotes; the wrapping
+    # is removed and the doubled "“”" inside unescaped.
+    def strip_quote_wrapping(s)
+      return s unless s.start_with?('"') && s.end_with?('"') && s.length >= 2
+
+      s[1..-2].gsub('""', '"')
+    end
+    private_class_method :strip_quote_wrapping
+  end
+end

data/lib/glossarist/{non_verbal_entity.rb → non_concept_entity.rb}

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
 module Glossarist
-  # Shared payload for every non-verbal representation, whether it lives
-  # inline on a concept (NonVerbRep) or as a dataset-shared file
-  # (Figure / Table / Formula).
+  # Shared payload for every non-concept entity — entities that are NOT
+  # concepts at all (Figure, Table, Formula), as opposed to non-verbal
+  # designations OF concepts (NonVerbRep).
   #
-  # The four attributes here are the common a11y + provenance payload every
-  # non-verbal entity carries, regardless of content type or scope:
+  # Terminology alignment (PROMPT-NOW P3):
+  #   - Non-verbal refers to the modality of expression (non-verbal
+  #     designation: symbol, formula expression). PROPERTIES OF concepts.
+  #   - Non-concept refers to entities that are NOT concepts at all
+  #     (Figure, Table, Formula). STANDALONE dataset entities.
+  #
+  # The four attributes here are the common a11y + provenance payload
+  # every non-concept entity carries, regardless of content type:
   #
   # - +caption+: localized short title (a11y / indexing).
   # - +description+: localized long description (a11y screen readers).
   # - +alt+: localized alternative text (a11y short screen-reader label).
   # - +sources+: bibliographic sources for the representation.
   #
-  # Identity (+id+, +identifier+) belongs on subclasses that have it; see
-  # SharedNonVerbalEntity for the dataset-shared variant.
-  class NonVerbalEntity < Lutaml::Model::Serializable
+  # Identity (+id+, +identifier+) belongs on subclasses that have it;
+  # see SharedNonConceptEntity for the dataset-shared variant.
+  class NonConceptEntity < Lutaml::Model::Serializable
     attribute :caption, :hash
     attribute :description, :hash
     attribute :alt, :hash
@@ -42,4 +48,7 @@ module Glossarist
       from_yaml(File.read(path, encoding: "utf-8"))
     end
   end
+
+  # @deprecated Use NonConceptEntity instead. Kept for one release
+  #   cycle to ease migration of downstream callers.
 end

data/lib/glossarist/non_verb_rep.rb

@@ -4,17 +4,26 @@ module Glossarist
   # A concept-local non-verbal representation (ISO 10241-1 §6.5).
   #
   # NonVerbRep is the inline form attached directly to a concept's data.
-  # The dataset-shared form is Figure / Table / Formula. The two share the
-  # same a11y + provenance payload via NonVerbalEntity; NonVerbRep differs
-  # only in that it has no dataset-wide identity (no +id+, no +identifier+)
-  # — its identity is its position inside the parent concept.
+  # The dataset-shared form is Figure / Table / Formula. The two share
+  # the same a11y + provenance payload via NonConceptEntity; NonVerbRep
+  # differs only in that it has no dataset-wide identity (no +id+, no
+  # +identifier+) — its identity is its position inside the parent
+  # concept.
+  #
+  # Note on terminology (PROMPT-NOW P3):
+  #   NonVerbRep IS a non-verbal representation — it's a designation
+  #   (a way of expressing a concept, distinct from verbal designation
+  #   like terms). It is NOT a non-concept entity (which is a Figure /
+  #   Table / Formula standalone). Both happen to inherit from
+  #   NonConceptEntity for the shared a11y + provenance payload; the
+  #   name NonVerbRep preserves the modality distinction.
   #
   # +type+ discriminates the kind of non-verbal content: "image", "table",
   # or "formula". When +type+ is "image", +images+ carries one or more
   # FigureImage variants (responsive, format fallback, dark/light). The
   # caption/description/alt fields are localized (hash keyed by ISO 639
   # code) for accessibility.
-  class NonVerbRep < NonVerbalEntity
+  class NonVerbRep < NonConceptEntity
     attribute :type, :string
     attribute :images, FigureImage, collection: true, initialize_empty: true
 

data/lib/glossarist/reference_extractor.rb

@@ -223,8 +223,56 @@ module Glossarist
       concept_refs + asset_refs
     end
 
-    def resolve_asciidoc_xref(target)
-      BibliographicReference.new(anchor: target.strip)
+    # AsciiDoc cross-reference: <<target>> or <<target, caption>>
+    #
+    # PROMPT-NOW P2: the `<<...,...>>` syntax has been overloaded for
+    # three different uses, only one of which is legitimate (non-concept
+    # entity xrefs). The other two (bibliography lookup, concept
+    # citation) bypass the unified resolution cascade.
+    #
+    # Behavior on encounter:
+    #   1. Emit a deprecation warning via Ruby's Warning module.
+    #   2. Re-parse to a typed reference based on the target's shape:
+    #      - explicit fig:/table:/formula: prefix → typed entity xref
+    #      - numeric id → local ConceptReference (legacy cite)
+    #      - anything else → ConceptReference (let the resolver handle it)
+    #   3. Do NOT treat as a bibliography lookup. Bibliography is reached
+    #      only via the new {{bib:id}} mention kind.
+    def resolve_asciidoc_xref(target, caption = nil)
+      target = target.to_s.strip
+      caption = caption.to_s.strip unless caption.nil?
+      warn_deprecated_xref(target, caption)
+
+      case target
+      when /\Afig(?:ure)?:/i   then resolve_non_verbal_mention("fig:", target, caption, FigureReference)
+      when /\Atable:/i          then resolve_non_verbal_mention("table:", target, caption, TableReference)
+      when /\Atbl:/i            then resolve_non_verbal_mention("tbl:", target, caption, TableReference)
+      when /\Aformula:/i        then resolve_non_verbal_mention("formula:", target, caption, FormulaReference)
+      when /\Aeq:/i             then resolve_non_verbal_mention("eq:", target, caption, FormulaReference)
+      when /\A\d[\d.-]*\z/      then resolve_local(caption || target, target)
+      else resolve_designation(target, caption)
+      end
+    end
+
+    def warn_deprecated_xref(target, caption)
+      return unless Warning.respond_to?(:warn)
+
+      suffix = ", #{caption}" if caption && !caption.empty?
+      Warning.warn(
+        "[glossarist] <<#{target}#{suffix}>> is deprecated. " \
+        "Use {{fig/table/formula:#{target}#{suffix}}} for non-concept entities, " \
+        "or {{cite:#{target}#{suffix}}} for concept citations.\n",
+      )
+    end
+
+    # {{bib:id}} → BibliographicReference. This is the explicit
+    # bibliography-lookup path (PROMPT-NOW P2). Replaces the old
+    # <<anchor>> bibliography shortcut which is now deprecated.
+    def resolve_bib_key(identifier, display)
+      cleaned = identifier.delete_prefix("bib:").strip
+      return nil if cleaned.empty?
+
+      BibliographicReference.new(anchor: cleaned)
     end
 
     def resolve_image_ref(path)
@@ -292,10 +340,13 @@ module Glossarist
     ) { |ext, content| ext.resolve_mention(content) }
 
     # AsciiDoc cross-references: <<anchor>> or <<anchor,display text>>
+    # Captures both target and caption so resolve_asciidoc_xref can
+    # re-dispatch (PROMPT-NOW P2 — <<>> is deprecated, re-parse to
+    # the right kind based on target).
     register_pattern(
       name: :asciidoc_xref,
-      regex: /<<([^,>\n]+?)(?:,[^>\n]*)?>>/,
-    ) { |ext, target| ext.resolve_asciidoc_xref(target) }
+      regex: /<<([^,>\n]+?)(?:,([^>\n]*))?>>/,
+    ) { |ext, target, caption| ext.resolve_asciidoc_xref(target, caption) }
 
     # Image references: image::path[] or image:path[]
     register_pattern(
@@ -307,6 +358,10 @@ module Glossarist
       ext.resolve_cite_key(identifier, display)
     end
 
+    register_identifier_resolver("bib:") do |ext, identifier, display|
+      ext.resolve_bib_key(identifier, display)
+    end
+
     register_identifier_resolver("fig:") do |ext, identifier, display|
       ext.resolve_non_verbal_mention("fig:", identifier, display, FigureReference)
     end

data/lib/glossarist/{shared_non_verbal_entity.rb → shared_non_concept_entity.rb}

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module Glossarist
-  # Dataset-shared non-verbal entity — a NonVerbalEntity with a stable
+  # Dataset-shared non-concept entity — a NonConceptEntity with a stable
   # identity. Figure, Table, and Formula inherit from this; NonVerbRep
-  # (concept-local, positional) inherits from NonVerbalEntity directly.
+  # (concept-local, positional) inherits from NonConceptEntity directly.
   #
   # The +id+ is the stable identifier used for cross-referencing
   # (e.g. +figures/fig_A.23.yaml+ → +id: fig_A.23+). The +identifier+ is
   # the human-readable label (e.g. +"A.23"+) used for display and AsciiDoc
   # xref targets like +<<fig_A.23>>+.
-  class SharedNonVerbalEntity < NonVerbalEntity
+  class SharedNonConceptEntity < NonConceptEntity
     attribute :id, :string
     attribute :identifier, :string
 
@@ -26,4 +26,7 @@ module Glossarist
       [id].compact
     end
   end
+
+  # @deprecated Use SharedNonConceptEntity instead. Kept for one
+  #   release cycle to ease migration.
 end

data/lib/glossarist/table.rb

@@ -7,7 +7,7 @@ module Glossarist
   # across concepts. The content is stored as structured data (rows/columns)
   # or as a markup string (HTML, Markdown, AsciiDoc). Caption, description,
   # and alt are localized for accessibility.
-  class Table < SharedNonVerbalEntity
+  class Table < SharedNonConceptEntity
     attribute :content, :hash
     attribute :format, :string
 

data/lib/glossarist/validators/no_raw_html.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validators
+    # Flags raw HTML in concept text that should be expressed as typed
+    # mention syntax instead. Raw HTML bypasses the renderer, is
+    # brittle, has no accessibility contract, and can embed
+    # deployment-specific URLs.
+    #
+    # Suggested replacements:
+    #
+    #   <a href="URL">label</a>  → {{link:URL, label}}
+    #   <a href="URL">URL</a>    → {{link:URL}}
+    #   <img src="SRC">          → {{image:SRC}}
+    #   <img src="SRC" alt="ALT">→ {{image:SRC, ALT}}
+    #   <iframe src="URL">       → {{link:URL}}
+    #
+    # Usage:
+    #   issues = Glossarist::Validators::NoRawHtml.call(concept_text)
+    #   issues.each { |i| warn i[:message] }
+    class NoRawHtml
+      # Patterns are intentionally conservative — only tags that have
+      # a direct typed-mention replacement. Other HTML tags (<b>, <i>,
+      # <sup>, etc.) are left to the renderer's HTML sanitiser.
+      LINK_PATTERN = /<a\s+href="([^"]+)"[^>]*>([^<]*)<\/a>/i.freeze
+      IMAGE_PATTERN = /<img\s+src="([^"]+)"(?:\s+alt="([^"]*)")?[^>]*>/i.freeze
+      IFRAME_PATTERN = /<iframe\s+src="([^"]+)"[^>]*>/i.freeze
+
+      class << self
+        # @param text [String] the concept text to check
+        # @return [Array<Hash>] issues with severity, match, suggestion, message
+        def call(text)
+          return [] unless text.is_a?(String)
+
+          [].tap do |issues|
+            scan_links(text, issues)
+            scan_images(text, issues)
+            scan_iframes(text, issues)
+          end
+        end
+
+        private
+
+        def scan_links(text, issues)
+          text.scan(LINK_PATTERN) do |url, label|
+            suggestion = label && !label.strip.empty? ?
+              "{{link:#{url}, #{label.strip}}}" :
+              "{{link:#{url}}}"
+            issues << {
+              severity: "warning",
+              match: %(<a href="#{url}">#{label}</a>),
+              suggestion: suggestion,
+              message: "Use {{link:#{url}}} instead of raw <a> tags",
+            }
+          end
+        end
+
+        def scan_images(text, issues)
+          text.scan(IMAGE_PATTERN) do |src, alt|
+            suggestion = alt && !alt.strip.empty? ?
+              "{{image:#{src}, #{alt.strip}}}" :
+              "{{image:#{src}}}"
+            issues << {
+              severity: "warning",
+              match: %(<img src="#{src}"#{" alt=\"#{alt}\"" if alt}>),
+              suggestion: suggestion,
+              message: "Use {{image:#{src}}} instead of raw <img> tags",
+            }
+          end
+        end
+
+        def scan_iframes(text, issues)
+          text.scan(IFRAME_PATTERN).each do |match|
+            url = match.is_a?(Array) ? match[0] : match
+            issues << {
+              severity: "warning",
+              match: %(<iframe src="#{url}">),
+              suggestion: "{{link:#{url}}}",
+              message: "iframes are not supported as embeds; use {{link:}} instead",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validators.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Namespace for standalone validators (not Validation::Rule classes).
+  # These are opt-in utilities that consumers call explicitly — they
+  # are not auto-registered into the Validation::Rules pipeline.
+  module Validators
+    autoload :NoRawHtml, "glossarist/validators/no_raw_html"
+  end
+end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.13.9"
+  VERSION = "2.13.10"
 end

data/lib/glossarist.rb

@@ -40,8 +40,8 @@ module Glossarist
   autoload :ConceptEnricher, "glossarist/concept_enricher"
   autoload :Config,                   "glossarist/config"
   autoload :LocalizedString,          "glossarist/localized_string"
-  autoload :NonVerbalEntity,          "glossarist/non_verbal_entity"
-  autoload :SharedNonVerbalEntity,    "glossarist/shared_non_verbal_entity"
+  autoload :NonConceptEntity,         "glossarist/non_concept_entity"
+  autoload :SharedNonConceptEntity,   "glossarist/shared_non_concept_entity"
   autoload :NonVerbalReference,       "glossarist/non_verbal_reference"
   autoload :Figure,                   "glossarist/figure"
   autoload :FigureImage,              "glossarist/figure_image"
@@ -65,6 +65,8 @@ module Glossarist
   autoload :ManagedConcept,           "glossarist/managed_concept"
   autoload :ManagedConceptCollection, "glossarist/managed_concept_collection"
   autoload :ManagedConceptData,       "glossarist/managed_concept_data"
+  autoload :MentionParser,            "glossarist/mention_parser"
+  autoload :MentionKinds,             "glossarist/mention_parser"
   autoload :NonVerbRep,               "glossarist/non_verb_rep"
   autoload :Pronunciation,            "glossarist/pronunciation"
   autoload :RelatedConcept,           "glossarist/related_concept"
@@ -86,10 +88,35 @@ module Glossarist
   autoload :GlossaryDefinition,       "glossarist/glossary_definition"
   autoload :GlossaryStore,            "glossarist/glossary_store"
   autoload :Tasks,                    "glossarist/tasks"
+  autoload :Validators,               "glossarist/validators"
 
   LANG_CODES = %w[eng ara deu fra spa ita jpn kor pol por srp swe zho rus fin
                   dan nld msa nob nno].freeze
 
+  # @deprecated Use NonConceptEntity. Removed in next minor release.
+  def self.const_missing(name)
+    case name
+    when :NonVerbalEntity
+      warn "[glossarist] Glossarist::NonVerbalEntity is deprecated; " \
+           "use Glossarist::NonConceptEntity instead."
+      NonConceptEntity
+    when :SharedNonVerbalEntity
+      warn "[glossarist] Glossarist::SharedNonVerbalEntity is deprecated; " \
+           "use Glossarist::SharedNonConceptEntity instead."
+      SharedNonConceptEntity
+    else
+      super
+    end
+  end
+
+  # Parse a single {{...}} mention into a canonical Hash. Defined here
+  # (rather than via autoload) so calling Glossarist.parse_mention(str)
+  # triggers the MentionParser autoload chain transparently — method
+  # calls do not fire autoloads on their own.
+  def self.parse_mention(text)
+    MentionParser.parse_mention(text)
+  end
+
   SCHEMA_VERSION = "3"
   V3_SCHEMA_VERSION = "3"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.9
+  version: 2.13.10
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -195,6 +195,7 @@ files:
 - CLAUDE.md
 - Gemfile
 - LICENSE.txt
+- PROMPT-NOW.md
 - README.adoc
 - Rakefile
 - config.yml
@@ -291,8 +292,9 @@ files:
 - lib/glossarist/managed_concept.rb
 - lib/glossarist/managed_concept_collection.rb
 - lib/glossarist/managed_concept_data.rb
+- lib/glossarist/mention_parser.rb
+- lib/glossarist/non_concept_entity.rb
 - lib/glossarist/non_verb_rep.rb
-- lib/glossarist/non_verbal_entity.rb
 - lib/glossarist/non_verbal_reference.rb
 - lib/glossarist/pronunciation.rb
 - lib/glossarist/rdf.rb
@@ -352,7 +354,7 @@ files:
 - lib/glossarist/schema_migration/v0_to_v1.rb
 - lib/glossarist/schema_migration/v2_to_v3.rb
 - lib/glossarist/section.rb
-- lib/glossarist/shared_non_verbal_entity.rb
+- lib/glossarist/shared_non_concept_entity.rb
 - lib/glossarist/sts.rb
 - lib/glossarist/sts/extracted_designation.rb
 - lib/glossarist/sts/extracted_lang_set.rb
@@ -480,6 +482,8 @@ files:
 - lib/glossarist/validation/shacl_validator.rb
 - lib/glossarist/validation/validation_issue.rb
 - lib/glossarist/validation_result.rb
+- lib/glossarist/validators.rb
+- lib/glossarist/validators/no_raw_html.rb
 - lib/glossarist/version.rb
 - memory/project-status.md
 - relaton-bib-2.0.0.gem