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
| Backend | Inline Rendering | Glossary |
|---|---|---|
| html5 | SVG badge with anchor link | HTML definition list |
| docbook5 | DocBook link + phrase | DocBook glossary |
| pdf (Prawn) | Bold + code styled text | Not supported |
- Since:
- 1.0.0
- See Also:
-
ClassDescriptionThe
[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, asx0, y0, x1, y1, ….An open polyline through its points, asx0, y0, x1, y1, …, round-capped and round-joined.An axis-aligned rectangle from its top-left corner.How a mark's outline is drawn;nullfor 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.ADecisionFigureas one self-contained SVG document: aviewBoxthe figure's size, every mark an element whoseclassis 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 aDecisionFigure, drawn as the liveTornadoChartdraws 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;thresholdis the measure's value there, printed with its unit, for a root flip.The sweep as the tornado reads it.ADecisionFigureas Typst code: oneboxthe figure's size, in points, and inside it every markplaced 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 akind: patternkoncept in presentation form: the referenced component first, then each declared field, labeled 1-indexed (Field 1is the first declared field).One field of akind: patternkoncept: 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 handlesk:ConceptName[]syntax in AsciiDoc documents.AsciidoctorJ block macro processor that splices a koncept's curated, long-formnarrativefield into the document as real AsciiDoc source.AsciidoctorJ block macro processor that renders a "List of Patterns": a flat, numbered index of everykind: patternkoncept 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 akind: patternkoncept'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.