Gloss is a target-independent inline semantic annotation language for binding meaning and data to spans of free text.
Gloss is designed for authoring, not programming.
It allows writers, designers, and systems to enrich narrative text with
machine-readable semantics without mixing structure, presentation, or behavior
into the text itself.
Gloss answers one question only:
“What does this span of text mean?”
Legacy markup systems—especially HTML and Markdown—collapse multiple concerns into a single syntax:
This makes content:
Gloss solves this by doing one thing only:
Binding semantic meaning to spans of text.
Nothing else.
Gloss is:
Gloss is intentionally small, stable, and boring.
Gloss is not:
Gloss is subordinate and dependent on Paperhat Codex.
Gloss cannot be used independently. It only functions correctly within the Paperhat ecosystem.
Gloss annotations appear inline using curly-brace syntax.
There are exactly two addressing forms.
@){@id}
{@id | label}
Used to reference Entities—Concepts with identity.
Example:
<Book id="book:hobbit" title="The Hobbit" author="J.R.R. Tolkien" />
I love {@book:hobbit}.
I love {@book:hobbit | The Hobbit — Tolkien}.
Entity references express association, not linking.
They MAY participate in:
Linking behavior is decided by Design Policy, not Gloss.
#){#id}
{#id | label}
Used to reference non-Entity Concepts, such as:
Example:
<PrecisionNumber id="pi" value=3.141592653589793p15 />
The value of pi is {#pi}.
These annotations express meaning, not appearance.
Gloss follows a strict lifecycle:
Gloss guarantees:
Errors surface as Help, never as crashes.
When Gloss binds text to Entities:
Gloss does not control emission format or placement.
Gloss is intended to evolve slowly and conservatively.
Gloss exists because:
Meaning is not presentation. Structure is not prose. Identity is not layout.
Gloss keeps those concerns separate—on purpose.
The specification and documentation in this repository are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
This license applies only to the textual and illustrative content. It does not grant rights to names, trademarks, or software implementations.