Package network.ike.docs.koncept


package network.ike.docs.koncept
Koncept AsciiDoc Extension — inline markup for clinical knowledge concepts.

Overview

This package provides an AsciidoctorJ extension that introduces the k:ConceptName[] inline macro for referencing clinical and knowledge-engineering concepts in AsciiDoc documents. Each reference renders as a clickable SVG badge and is automatically collected into a "Referenced Koncepts" glossary appended to the document.

Extension Architecture

The extension consists of three cooperating components:

KonceptInlineMacro
Processes k:Name[] syntax during document conversion. Renders backend-appropriate markup (SVG for HTML, styled phrase for DocBook, bold text for Prawn PDF) and registers each reference in a document-scoped registry.
KonceptGlossaryProcessor
Postprocessor that consumes the registry after conversion, resolves definitions from a KonceptDefinitionSource, and appends a structured glossary and colophon to the output.
KonceptExtensionRegistry
SPI entry point that auto-registers the inline macro with AsciidoctorJ. The glossary postprocessor is registered separately per-execution to avoid Prawn PDF backend incompatibility.

Koncept Definitions

Definitions are sourced via the KonceptDefinitionSource strategy interface. The default implementation, YamlKonceptDefinitionSource, loads from YAML files. Each definition includes:

  • Natural language definition text
  • Description logic axiom using Unicode DL notation (≡, ⊓, ∃, ∀, ⊑, etc.)
  • Optional SNOMED CT concept identifier (SCTID)
  • Optional OWL IRI

Usage

In AsciiDoc source:

The patient presented with k:HeartFailure[] and k:AorticStenosis[].
A label override: k:HeartFailure[Congestive Heart Failure].

In a YAML definitions file (koncepts.yml):

HeartFailure:
  label: Heart Failure
  definition: >
    A clinical syndrome characterized by the heart's inability
    to pump sufficient blood to meet metabolic demands.
  axiom: "≡ ClinicalSyndrome ⊓ ∃hasPathology.(InsufficientCardiacOutput)"
  sctid: "84114007"

Backend Support

Rendering behavior by AsciiDoc backend
BackendInline RenderingGlossary
html5SVG badge with anchor linkHTML definition list
docbook5DocBook link + phraseDocBook glossary
pdf (Prawn)Bold + code styled textNot supported
Since:
1.0.0
See Also:
  • Class
    Description
    The [anf] block in the documentation build (dev-anf-adoc-representation): the static projection of the ANF statement card the assistant surface draws for the same block.
    The [calculate] block in the documentation build (dev-calculator-blocks): the record that binds a document's values to a calculator the document defines.
    The [calculator] block in the documentation build (dev-calculator-blocks): the method, rendered as what it is and what binds to it, a table of the inputs with the semantic each expects, the domain the equation is valid over, and what the evaluator does when nothing binds.
    The [complex-concept] block in the documentation build: the static projection of the complex concept editor the assistant surface draws for the same block (dev-decision-point-knowledge).
    A definition source that chains multiple sources in priority order.
    A decision-tree figure as marks on a page: rectangles, circles, polygons, polylines and text, each at a place in the figure's own units, each with its paint and a role naming what it stands for.
    A circle about its centre.
    One mark of the figure.
    A closed polygon through its points, as x0, y0, x1, y1, ….
    An open polyline through its points, as x0, y0, x1, y1, …, round-capped and round-joined.
    An axis-aligned rectangle from its top-left corner.
    How a mark's outline is drawn; null for no outline.
    A run of text whose top-left corner is at (x, top): the writers set the baseline from the size, so a label sits where the builder put its box.
    A DecisionFigure as one self-contained SVG document: a viewBox the figure's size, every mark an element whose class is the mark's role, text in the sans face the width estimate is of.
    What a figure builder knows about text without a font engine: an estimate of a run's width from the average widths of a Helvetica-like sans face, in em per character, so the geometry a layout computes from label widths is the same on every machine and in every medium, and the figure's palette and number formats, which the live JavaFX surface shares.
    What a swept quantity is: a share of those at a node, money, or anything else with a unit of its own.
    A tornado diagram of a decision tree's one-way sensitivity as a DecisionFigure, drawn as the live TornadoChart draws it: one bar per swept measure, longest first, on one axis.
    One measure's bar.
    What the root chose along a stretch of a bar, against what it chose at the base.
    How an amount on the axis is printed.
    A stretch of a bar between two cuts, by where each cut falls on the axis.
    A flip, by where it falls on the axis; threshold is the measure's value there, printed with its unit, for a root flip.
    The sweep as the tornado reads it.
    A DecisionFigure as Typst code: one box the figure's size, in points, and inside it every mark placed at its coordinates, so the print pipeline draws the figure natively, with the document's own text, and never through an embedded image.
    The [decision-tree] block in the documentation build (dev-decision-tree-blocks): the static projection of the block the assistant surface renders live.
    AsciidoctorJ postprocessor that removes empty paragraph blocks from the generated HTML.
    Tags level-1 special sections so the print stylesheets can route them to front- or back-matter page schemes instead of the chapter scheme.
    The [graphlet-model] block in the documentation build (dev-decision-point-knowledge, settled 2026-11-06): the model of a decision as one versioned property graph, the tree's structure and its parameters together, in the decision tree's grammar (DecisionTreeSource) plus parameters that read the document's ANF statements by name and hold the value the tree runs at.
    Renders the Komet identicon for a koncept as a PNG.
    AsciidoctorJ block macro that renders the anatomy of a Koncept Badge as a real, captioned figure: the referenced koncept's badge — kind sigil, identicon, name — drawn large, with a muted part label beneath each part.
    Immutable definition of a Koncept, including natural language definition, description logic axiom, and optional terminology identifiers.
    Builder for constructing KonceptDefinition instances from parsed YAML or programmatic sources.
    One Model Feature of a kind: pattern koncept in presentation form: the referenced component first, then each declared field, labeled 1-indexed (Field 1 is the first declared field).
    One field of a kind: pattern koncept: its own meaning, purpose, and data-type koncept identifiers, in the pattern's own declared field order.
    A comment's text immediately before it was retired, and the time of that retirement.
    Strategy interface for resolving Koncept definitions.
    Tracks references to a single Koncept within a document.
    SPI entry point for automatic registration of Koncept extensions with AsciidoctorJ.
    AsciidoctorJ postprocessor that generates a "Referenced Koncepts" glossary section and a colophon at the end of the document.
    Builds a real, TOC-visible AST section for the comprehensive (koncept-glossary-all) glossary mode (IKE-Network/ike-issues#877).
    AsciidoctorJ block macro that renders a koncept's identicon as a real, captioned figure — for prose that talks about identicons (a "How to Read This Guide" front matter) and needs to show one at figure size, not badge size.
    AsciidoctorJ inline macro processor that handles k:ConceptName[] syntax in AsciiDoc documents.
    AsciidoctorJ block macro processor that splices a koncept's curated, long-form narrative field into the document as real AsciiDoc source.
    AsciidoctorJ block macro processor that renders a "List of Patterns": a flat, numbered index of every kind: pattern koncept in the definition source, alphabetical by label, each entry a plain link to that pattern's own entry in the Koncept Glossary — no columns, no icons, styled the same as the document's own table of contents (ul.sectlevel1) rather than as a data table.
    AsciidoctorJ block macro processor that renders a kind: pattern koncept's shape as a real, captioned AsciiDoc table — one Model Feature (the referenced component, then each declared field in order) per three-row group (IKE-Network/ike-issues#883).
    AsciidoctorJ inline macro that renders a component-kind sigil on its own — the mark a Koncept Badge carries for its kind, without any badge around it — so prose that talks about the sigil scheme (a "How to Read This Guide" front matter, a tutorial) can show the real marks instead of describing them.
    Generates inline SVG badge markup for Koncept references.
    AsciidoctorJ block processor that renders a [koncept-tree] delimited block as an indented list of Koncept chips — the print/HTML/e-mail projection of the live tree Komet draws in the assistant surface (IKE-Network/ike-issues#827, the static counterpart of #805).
    Derives the Tinkar PublicId UUID for a SNOMED CT concept from its SCTID.
    The [tornado] block in the documentation build (dev-decision-point-knowledge, settled 2026-11-06): a rendering of a graphlet model that holds no structure and no number, only how the model is viewed.
    Loads Koncept definitions from a YAML file.