diff --git a/DOCS/DEPENDENCIES.md b/DOCS/DEPENDENCIES.md
index 69d7dda..35a7962 100644
--- a/DOCS/DEPENDENCIES.md
+++ b/DOCS/DEPENDENCIES.md
@@ -45,11 +45,11 @@ category: documentation
| select | dropdown |
| input | form |
| item | list |
-| year-start | timeline |
-| year-end | timeline |
+| year-start | timeline or series |
+| year-end | timeline or series |
| month | calendar |
| year | calendar |
-| date | event |
+| date | event, metadata, or episode |
| image | media |
| audio | media |
| video | media |
@@ -88,13 +88,13 @@ category: documentation
| style | ebook |
| javascript | ebook |
| script | ebook |
-| title | metadata |
+| title | metadata or any creative-work record |
| subtitle | metadata |
-| author | metadata |
+| author | metadata or book |
| language | metadata |
-| description| metadata |
-| date | metadata or event |
-| publisher | metadata |
+| description| metadata or any creative-work record |
+| date | metadata, event, or episode |
+| publisher | metadata, book, or game |
| rights | metadata |
| image | cover, content, media, or section |
| caption | cover or media |
@@ -102,6 +102,23 @@ category: documentation
| paragraph | content or section |
| | |
+## CREATIVE-WORK RECORDS
+
+`film`, `song`, `album`, `book`, `series`, `episode`, `game`, and `podcast` require exactly one nonempty `title`. They have no required parent. Each record accepts optional `description`, `release-year`, and repeated `genre`, plus the following fields:
+
+| Record | Additional children |
+| --- | --- |
+| film | director |
+| song | artist, album (text field) |
+| album | artist |
+| book | author, publisher |
+| series | creator, start-year, end-year |
+| episode | season-number, episode-number, date |
+| game | creator, publisher |
+| podcast | creator |
+
+Fields contain nonempty text only. Credits and genres may repeat; other fields may occur once. Years use four digits, series end-year cannot precede start-year, season-number is nonnegative, and episode-number is positive. Consecutive work records become siblings; close `/song` explicitly before a standalone album record. See [SPEC](SPEC.md#19-creative-work-records).
+
## CONTEXTUAL VALIDATION
- event ---> **AS A CHILD OF** ---> timeline ---> **MUST HAVE** date **BETWEEN** start-year AND end-year
@@ -140,7 +157,7 @@ category: documentation
## PAIRS & SETS ---> CANNOT EXIST OUTSIDE OF
- after **AND** before ---> **CANNOT EXIST OUTSIDE OF** ---> comparison
-- start-year **AND** end-year ---> **CANNOT EXIST OUTSIDE OF** timeline
+- start-year **AND** end-year ---> **CANNOT EXIST OUTSIDE OF** timeline or series
- image, audio, **AND** video **CANNOT EXIST OUTSIDE OF** media
---
diff --git a/DOCS/README.md b/DOCS/README.md
index 0e8142c..8f09962 100644
--- a/DOCS/README.md
+++ b/DOCS/README.md
@@ -25,7 +25,7 @@ Source documents stay readable as plain text while compiling into a structured d
| File | Purpose |
| ---- | ------- |
| **[SPEC.md](SPEC.md)** | Full language specification (v0.1): syntax, principles, validation rules, and schema definitions. |
-| **[TAGS.md](TAGS.md)** | Official tag registry with examples. Currently lists **48 official tags** (argument, calendar, claim, comparison, document, form, media, timeline, and others). |
+| **[TAGS.md](TAGS.md)** | Official tag registry with examples. Currently lists **95 official tags** (argument, calendar, claim, comparison, document, form, media, timeline, and others). |
| **[SHORTHAND.md](SHORTHAND.md)** | Shorthand alias rules and the official shorthand table (`arg`, `comp`, `grp`, `img`, `evi`, etc.). |
| **[DEPENDENCIES.md](DEPENDENCIES.md)** | Parent/child relationships, required children, and nesting rules — including **group** (shared trait values) and **comparison** schemas. |
| **[SYNONYMS.md](SYNONYMS.md)** | Conceptual synonym mappings (e.g. section ↔ chapter, claim ↔ statement). |
@@ -215,6 +215,27 @@ media
* `media` requires at least one of `image`, `audio`, or `video`
* `caption` belongs under `media` or `cover`
+## Creative-work records
+
+Describe films, songs, albums, books, series, episodes, games, and podcasts with named fields:
+
+```mml
+film
+title
+The Menu
+director
+Mark Mylod
+release-year
+2022
+genre
+dark-comedy
+genre
+horror
+/film
+```
+
+Each record requires a `title`. Other fields are optional; repeat genres and credits for multiple values. Consecutive entries become siblings automatically. `book` describes a work, while `ebook` contains the actual book content. See [creative-work records](SPEC.md#19-creative-work-records) for the fields and validation rules. The parser demo includes a **Load Film Example** button.
+
## Ebook
Format-independent book schema (implemented in `export/src/ebook-schema.js`):
@@ -310,13 +331,13 @@ Do you have a more advanced tag idea? **[SUBMIT A SCHEMA](https://github.com/mon
---
## Community
-- Please read our [Code of Conduct](./CODE_OF_CONDUCT.md) before
+- Please read our [Code of Conduct](https://github.com/monapdx/Modular-Markup-Language/blob/main/CODE_OF_CONDUCT.md) before
participating.
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to report bugs,
+- See [CONTRIBUTING.md](https://github.com/monapdx/Modular-Markup-Language/blob/main/CONTRIBUTING.md) for how to report bugs,
propose tags/schemas, set up your dev environment, and submit pull
requests.
- All pull requests use the template in
- [.github/PULL_REQUEST_TEMPLATE.md](./.github/PULL_REQUEST_TEMPLATE.md)
+ [.github/PULL_REQUEST_TEMPLATE.md](https://github.com/monapdx/Modular-Markup-Language/blob/main/.github/ISSUE_TEMPLATE/PULL_REQUEST_TEMPLATE.md)
automatically.
---
diff --git a/DOCS/SCHEMA-INDEX.md b/DOCS/SCHEMA-INDEX.md
new file mode 100644
index 0000000..ee0cd20
--- /dev/null
+++ b/DOCS/SCHEMA-INDEX.md
@@ -0,0 +1,112 @@
+# Generated grammar index
+
+Generated from grammar.js. Parent rules describe parser boundaries; consult SPEC.md and validator.js for complete validation and attributes.
+
+## Schema implementations
+
+- [crossword-schema.js](../export/src/crossword-schema.js) — exports: CROSSWORD_ROOT_CHILDREN, CROSSWORD_DIRECTION_CHILDREN, splitCrosswordList, readCrossword, crosswordEntries, validateCrossword
+- [ebook-schema.js](../export/src/ebook-schema.js) — exports: EBOOK_ROOT_CHILDREN, EBOOK_REQUIRED_CHILDREN, METADATA_FIELDS, COVER_CHILDREN, CONTENT_CHILDREN, EBOOK_OUTPUT_FORMATS, EBOOK_MODES, EBOOK_ALLOWED_PARENTS, getEbookAllowedParents
+- [survey-schema.js](../export/src/survey-schema.js) — exports: SURVEY_QUESTION_TYPES, surveyQuestions, validateSurvey
+- [work-schema.js](../export/src/work-schema.js) — exports: WORK_FIELDS, WORK_TYPES, WORK_FIELD_PARENTS, validateWork
+
+## Tags
+
+| Tag | Required parent candidates | Aliases |
+| --- | --- | --- |
+| across | crossword-grid | — |
+| across-clues | crossword-grid | — |
+| after | No parent requirement | — |
+| album | No parent requirement | — |
+| antonym | word | ant |
+| argument | No parent requirement | arg |
+| artist | song, album | — |
+| audio | No parent requirement | mp3, wav |
+| author | metadata, book | — |
+| before | No parent requirement | — |
+| blockquote | No parent requirement | quote |
+| book | No parent requirement | — |
+| button | No parent requirement | — |
+| calendar | No parent requirement | cal |
+| canvas | No parent requirement | — |
+| cell | No parent requirement | — |
+| claim | No parent requirement | — |
+| column | No parent requirement | col |
+| comparison | No parent requirement | comp |
+| condition | scenario | cond, conditions |
+| content | ebook | — |
+| cover | ebook | — |
+| creator | series, game, podcast | — |
+| crossword-grid | No parent requirement | — |
+| date | event, metadata, episode | — |
+| definition | word | def |
+| description | metadata, film, song, album, book, series, episode, game, podcast | — |
+| director | film | — |
+| document | No parent requirement | doc |
+| down | crossword-grid | — |
+| down-clues | crossword-grid | — |
+| dropdown | No parent requirement | drop |
+| ebook | No parent requirement | — |
+| end-year | timeline, series | year-end |
+| entity | group, comparison | — |
+| episode | No parent requirement | — |
+| episode-number | episode | — |
+| event | No parent requirement | — |
+| evidence | claim, argument | evi |
+| fieldset | No parent requirement | set |
+| film | No parent requirement | — |
+| first-letters | across, down | — |
+| footnote | No parent requirement | foot, fnote |
+| form | No parent requirement | — |
+| game | No parent requirement | — |
+| genre | film, song, album, book, series, episode, game, podcast | — |
+| glossary | No parent requirement | glo |
+| group | No parent requirement | grp |
+| heading | content, section | h |
+| image | cover, content, media, section | img, jpg, png, svg, gif |
+| input | No parent requirement | — |
+| item | No parent requirement | — |
+| javascript | ebook | js |
+| language | metadata | — |
+| legend | No parent requirement | — |
+| link | No parent requirement | — |
+| list | No parent requirement | — |
+| media | No parent requirement | — |
+| metadata | ebook | — |
+| month | calendar | year-month |
+| option | question, dropdown | — |
+| origin | word | ori |
+| paragraph | content, section | p |
+| podcast | No parent requirement | — |
+| prompt | question | — |
+| publisher | metadata, book, game | — |
+| question | survey | — |
+| release-year | film, song, album, book, series, episode, game, podcast | — |
+| rights | metadata | — |
+| row | No parent requirement | — |
+| scenario | No parent requirement | scene |
+| script | ebook | — |
+| season-number | episode | — |
+| section | No parent requirement | sect |
+| selection | No parent requirement | — |
+| series | No parent requirement | — |
+| song | No parent requirement | — |
+| start-year | timeline, series | year-start |
+| style | ebook | — |
+| subtitle | metadata | — |
+| survey | No parent requirement | — |
+| synonym | word | syn |
+| table | No parent requirement | — |
+| text | No parent requirement | — |
+| textarea | No parent requirement | para |
+| timeline | No parent requirement | — |
+| title | metadata, film, song, album, book, series, episode, game, podcast | — |
+| toc | ebook | — |
+| trait | entity | — |
+| unique | entity | — |
+| usage | word | usag |
+| video | No parent requirement | mp4 |
+| word | glossary, across, down | — |
+| word-lengths | across, down | — |
+| year | calendar | — |
+
+See [SPEC.md](SPEC.md) for authored schema examples and attributes.
diff --git a/DOCS/SPEC.md b/DOCS/SPEC.md
index e3f1846..ba18bf5 100644
--- a/DOCS/SPEC.md
+++ b/DOCS/SPEC.md
@@ -1029,7 +1029,101 @@ The compiler produces an HTML form with controls named by question ID. If `actio
---
-# 19. Future Considerations
+# 19. Creative-Work Records
+
+Use `film`, `song`, `album`, `book`, `series`, `episode`, `game`, and `podcast` to describe works. These are records about works; `ebook` continues to structure actual book content for export.
+
+Every record requires exactly one nonempty `title`. Other fields are optional and hold nonempty text, without nested elements. Fields may use a value on the following line or a quoted inline value. Use quoted inline values when a value itself is a reserved tag name.
+
+```mml
+film
+title
+The Menu
+director
+Mark Mylod
+release-year
+2022
+genre
+dark-comedy
+genre
+horror
+/film
+```
+
+All types accept `title`, `description`, `release-year`, and repeated `genre` fields, plus these fields:
+
+| Record | Additional fields |
+| --- | --- |
+| `film` | `director` |
+| `song` | `artist`, `album` |
+| `album` | `artist` |
+| `book` | `author`, `publisher` |
+| `series` | `creator`, `start-year`, `end-year` |
+| `episode` | `season-number`, `episode-number`, `date` |
+| `game` | `creator`, `publisher` |
+| `podcast` | `creator` |
+
+Repeat `genre` and credit fields (`director`, `artist`, `author`, `creator`, `publisher`) to express multiple values. All other fields accept at most one value. `release-year`, `start-year`, and `end-year` use exactly four digits. A series may omit its end year while ongoing; when both years exist, the end cannot precede the start. `season-number` is a nonnegative integer (0 can represent specials); `episode-number` is a positive integer. Episode `date` holds nonempty date text, as in the existing date field; no additional date-format validation is imposed.
+
+Consecutive work records become siblings automatically. Closers are optional; `/film` may directly follow the last field's value. Explicit field closers such as `/genre` also work.
+
+```mml
+book
+title "Example Book"
+author "First Author"
+author "Second Author"
+publisher "Example Publisher"
+release-year "2022"
+series
+title "Example Series"
+creator "Example Creator"
+start-year "2020"
+episode
+title "Pilot"
+season-number "1"
+episode-number "1"
+date "2020-01-01"
+```
+
+Within a song, `album` is the album's name as a text field. Elsewhere, `album` is a record with its own title and artist. Close `/song` explicitly to start a separate album record immediately after a song:
+
+```mml
+song
+title "Example Song"
+artist "Example Artist"
+album "Example Album"
+release-year "2022"
+/song
+album
+title "Example Album"
+artist "Example Artist"
+```
+
+A missing title, an empty field, an unsupported field, or an invalid numeric value is invalid:
+
+```mml-invalid
+film
+title "The Menu"
+release-year "twenty twenty-two"
+```
+
+The compiler preserves record and field names in its semantic output, with escaped text values (as with ebook metadata):
+
+```html
+
+ The Menu
+ Mark Mylod
+ 2022
+ dark-comedy
+ horror
+
+```
+
+Existing ebook metadata, event dates, and timeline rules retain their original contexts. Work records have no required parent and can be grouped in a document, section, or list item; they cannot appear in containers whose schema disallows them, such as ebook content.
+
+---
+
+# 20. Future Considerations
Potential future areas include:
@@ -1044,7 +1138,7 @@ Potential future areas include:
---
-# 20. Guiding Principle
+# 21. Guiding Principle
> A document should remain understandable as plain text while remaining unambiguously parseable as structured semantic data.
diff --git a/DOCS/TAGS.md b/DOCS/TAGS.md
index 644a4c9..353e2c2 100644
--- a/DOCS/TAGS.md
+++ b/DOCS/TAGS.md
@@ -150,7 +150,7 @@ Comma-separated answer lengths.
### across-clues / down-clues
Clues in the same order as the corresponding directional words.
-See the [crossword schema](/DOCS/SPEC.md#16-crossword-grid-schema) for an example and validation rules.
+See the [crossword schema](/DOCS/SPEC.md#17-crossword-grid-schema) for an example and validation rules.
## Ebook
@@ -196,7 +196,34 @@ A possible answer for a single-choice or multiple-choice question; also used by
See the [survey schema](/DOCS/SPEC.md#18-survey-schema) for types, validation, and a complete example.
-## CURRENT TOTAL: 80 OFFICIAL TAGS
+## Creative-work records
+
+### film / song / album / book / series / episode / game / podcast
+Records describing creative works. Each requires exactly one nonempty `title`; all accept optional `description`, `release-year`, and repeated `genre` fields. `book` describes a work; `ebook` contains its actual content for export. In a song, `album` is a scalar album-name field; elsewhere it is a record.
+
+### director
+Film director credit. Repeat for multiple directors.
+
+### artist
+Song or album artist credit. Repeat for multiple artists.
+
+### creator
+Series, game, or podcast creator credit. Repeat for multiple creators.
+
+### release-year
+Four-digit release/publication year of any creative-work record.
+
+### genre
+A genre label on any creative-work record. Repeat for multiple genres; labels such as `dark-comedy` remain plain text.
+
+### season-number / episode-number
+Episode numbering. Season numbers are nonnegative (0 for specials); episode numbers are positive integers.
+
+The existing `title` and `description` fields also belong directly under any work record; `author` belongs under `book`, and `publisher` under `book` or `game`. `start-year` and `end-year` also belong under `series`; `date` also belongs under `episode`.
+
+See the [creative-work schema](SPEC.md#19-creative-work-records) for field rules and complete examples.
+
+## CURRENT TOTAL: 95 OFFICIAL TAGS
---
## CONTRIBUTE
diff --git a/export/DOCS/DEPENDENCIES.html b/export/DOCS/DEPENDENCIES.html
index aad5942..4d21185 100644
--- a/export/DOCS/DEPENDENCIES.html
+++ b/export/DOCS/DEPENDENCIES.html
@@ -1,25 +1,5 @@
-
-
-
-
-
- DEPENDENCIES
-
-
-
-
-
-
- title
- DEPENDENCIES
-
-
- category
- documentation
-
-
-
-
PARENT TAGS
+
+DEPENDENCIES — MML
PARENT TAGS
@@ -28,8 +8,7 @@
PARENT TAGS
CONTAINER
-
-
+
document
no
yes
@@ -124,9 +103,48 @@
PARENT TAGS
yes
yes
-
-
-
CHILD TAGS
+
+
group
+
no
+
yes
+
+
+
glossary
+
no
+
yes
+
+
+
ebook
+
no
+
yes
+
+
+
survey
+
no
+
yes
+
+
+
question
+
no
+
yes
+
+
+
metadata
+
no
+
yes
+
+
+
cover
+
no
+
yes
+
+
+
content
+
no
+
yes
+
+
+
CHILD TAGS
@@ -134,10 +152,9 @@
CHILD TAGS
CHILD OF
-
-
+
option
-
dropdown
+
dropdown or choice question
select
@@ -153,11 +170,11 @@
CHILD TAGS
year-start
-
timeline
+
timeline or series
year-end
-
timeline
+
timeline or series
month
@@ -169,7 +186,7 @@
CHILD TAGS
date
-
event
+
event, metadata, or episode
image
@@ -256,15 +273,177 @@
CHILD TAGS
text
+
trait
+
entity
+
+
+
word
+
glossary
+
+
+
definition
+
word
+
+
+
synonym
+
word
+
+
+
antonym
+
word
+
+
+
origin
+
word
+
+
+
usage
+
word
+
+
+
question
+
survey
+
+
+
prompt
+
question
+
+
+
option
+
question (choice types)
+
+
+
metadata
+
ebook
+
+
+
cover
+
ebook
+
+
+
toc
+
ebook
+
+
+
content
+
ebook
+
+
+
style
+
ebook
+
+
+
javascript
+
ebook
+
+
+
script
+
ebook
+
+
+
title
+
metadata or any creative-work record
+
+
+
subtitle
+
metadata
+
+
+
author
+
metadata or book
+
+
+
language
+
metadata
+
+
+
description
+
metadata or any creative-work record
+
+
+
date
+
metadata, event, or episode
+
+
+
publisher
+
metadata, book, or game
+
+
+
rights
+
metadata
+
+
+
image
+
cover, content, media, or section
+
+
+
caption
+
cover or media
+
+
+
heading
+
content or section
+
+
+
paragraph
+
content or section
+
+
-
-
+
+
CREATIVE-WORK RECORDS
+
film, song, album, book, series, episode, game, and podcast require exactly one nonempty title. They have no required parent. Each record accepts optional description, release-year, and repeated genre, plus the following fields:
+
+
+
+
Record
+
Additional children
+
+
+
+
film
+
director
+
+
+
song
+
artist, album (text field)
+
+
+
album
+
artist
+
+
+
book
+
author, publisher
+
+
+
series
+
creator, start-year, end-year
+
+
+
episode
+
season-number, episode-number, date
+
+
+
game
+
creator, publisher
+
+
+
podcast
+
creator
+
+
+
Fields contain nonempty text only. Credits and genres may repeat; other fields may occur once. Years use four digits, series end-year cannot precede start-year, season-number is nonnegative, and episode-number is positive. Consecutive work records become siblings; close /song explicitly before a standalone album record. See SPEC.
+
CONTEXTUAL VALIDATION
+
+
event ---> AS A CHILD OF ---> timeline ---> MUST HAVE date BETWEEN start-year AND end-year
+
+
-
REQUIRES
+
REQUIRES
-
claim <--- REQUIRES <--- evidence
calendar ---> REQUIRES ---> month AND year
event ---> REQUIRES ---> date
@@ -275,23 +454,33 @@
REQUIRES
option ---> REQUIRES ---> dropdown
select ---> REQUIRES ---> dropdown
list ---> REQUIRES ---> item
+
group ---> REQUIRES ---> TWO OR MORE ENTITIES
+
glossary ---> REQUIRES ---> word
+
word ---> REQUIRES ---> definition when inside glossary
+
ebook ---> REQUIRES ---> content
+
survey ---> REQUIRES ---> one or more questions
+
question ---> REQUIRES ---> prompt; choice questions require two or more options
+
synonym ---> REQUIRES ---> word
+
antonym ---> REQUIRES ---> word
+
origin ---> REQUIRES ---> word
+
usage ---> REQUIRES ---> word
-
-
AS A CHILD OF ---> IS ONLY VALID ---> WHEN MULTIPLES EXIST
+
AS A CHILD OF ---> IS ONLY VALID ---> WHEN MULTIPLES EXIST
entity ---> AS A CHILD OF ---> comparison ---> IS ONLY VALID ---> WHEN TWO OR MORE EXIST AS CHILDREN
scenario ---> AS A CHILD OF ---> comparison ---> IS ONLY VALID ---> WHEN TWO OR MORE EXIST AS CHILDREN
+
entity ---> AS A CHILD OF ---> group ---> IS ONLY VALID ---> WHEN AT LEAST TWO EXIST
-
PAIRS & SETS ---> CANNOT EXIST OUTSIDE OF
+
PAIRS & SETS ---> CANNOT EXIST OUTSIDE OF
after AND before ---> CANNOT EXIST OUTSIDE OF ---> comparison
-
start-year AND end-year ---> CANNOT EXIST OUTSIDE OF timeline
+
start-year AND end-year ---> CANNOT EXIST OUTSIDE OF timeline or series
image, audio, AND video CANNOT EXIST OUTSIDE OF media
-
CANNOT EXIST OUTSIDE OF
+
CANNOT EXIST OUTSIDE OF
row ---> CANNOT EXIST OUTSIDE OF ---> table
column ---> CANNOT EXIST OUTSIDE OF ---> table
@@ -300,16 +489,20 @@
CANNOT EXIST OUTSIDE OF
legend ---> CANNOT EXIST OUTSIDE OF ---> fieldset
dropdown ---> CANNOT EXIST OUTSIDE OF ---> form
section ---> CANNOT EXIST OUTSIDE OF ---> document
A meaning-first markup language that remains readable as plain text.
-
Modular Markup (MML) is an experimental semantic markup language designed around a simple idea:
+
Modular Markup (MML) is a semantic markup language designed around a simple idea:
Documents should describe meaning, not formatting.
Unlike Markdown, which relies on symbolic shortcuts, or HTML, which mixes semantic and presentational concerns, MML focuses on explicit semantic structures that are understandable to both humans and machines.
-
The source document should remain readable as plain text while compiling into a fully structured document tree.
+
Source documents stay readable as plain text while compiling into a structured document tree.
Official tag registry with examples. Currently lists 95 official tags (argument, calendar, claim, comparison, document, form, media, timeline, and others).
Anything that is not recognized as valid markup is treated as text.
-
claim
-
-Arguments are not always unhealthy.
-
-
+
Closing tags
+
Closing tags (/claim) are optional and never required. The parser infers structure from the next tag or content line and the compiler emits closers in output.
+
Inline quoted values
+
Some elements accept a value on the same line:
+
title "Proof I Was Here"
+heading level="1" "Chapter One"
+image "cover.jpg"
-
The word "Arguments" is content, not a tag.
+
Text content
+
Anything that is not valid markup is treated as text. Blank lines inside content are ignored. Consecutive untagged lines merge into one text node.
At least two entities must share a common trait value (text inside trait)
+
Differs from comparison, which uses named schemas instead of shared traits
+
+
Media
media
-├── image
-├── video
-├── audio
-├── caption
-└── source
+├── image | audio | video
+└── caption
+
+
+
media requires at least one of image, audio, or video
+
caption belongs under media or cover
+
+
Creative-work records
+
Describe films, songs, albums, books, series, episodes, games, and podcasts with named fields:
+
film
+title
+The Menu
+director
+Mark Mylod
+release-year
+2022
+genre
+dark-comedy
+genre
+horror
+/film
+
+
Each record requires a title. Other fields are optional; repeat genres and credits for multiple values. Consecutive entries become siblings automatically. book describes a work, while ebook contains the actual book content. See creative-work records for the fields and validation rules. The parser demo includes a Load Film Example button.
+
Ebook
+
Format-independent book schema (implemented in export/src/ebook-schema.js):
media requires at least one image, audio, or video
-
caption typically belongs to media
+
+
content is required
+
toc is a declaration tag — the compiler auto-generates a table of contents from heading tags inside content
+
style and javascript are optional HTML/web exporter tags; plain-text export ignores them
-
Design Principles
-
Text Wins
-
If something is not valid markup, it is text.
-
The parser should never aggressively reinterpret ordinary writing as structure.
+
Design principles
+
Text wins
+
If something is not valid markup, it is text. The parser does not reinterpret ordinary writing as structure.
+
Singular elements
+
Element names are singular (claim, event, entity — not claims, events, entities).
+
Semantic necessity
+
A tag should represent a meaningful concept that cannot already be expressed with existing tags.
+
Shorthand and synonyms
+
Use SHORTHAND.md for accepted abbreviations and SYNONYMS.md for conceptual alternates. Only shorthand entries registered in the parser are recognized as tags.
-
Singular Elements
-
Element names are singular.
-
Valid:
-
claim
-event
-entity
-image
-
-
Invalid:
-
claims
-events
-entities
-images
+
Project status
+
Working parser, validator, and compiler live in export/src/:
+
+
grammar.js — tag registry, aliases, attribute parsing, inline-value matching
+
parser.js — opening-tag-only parsing with implicit close
+
validator.js — semantic validation for all registered schemas
ebook.js / ebook-schema.js — ebook TOC generation and schema constants
+
+
Run tests from the repo root:
+
npm test
+
The language and documentation are still evolving. Official tags are listed in TAGS.md; newer parser features (such as ebook tags) may land in code before the tag list is updated.
-
Semantic Necessity
-
A tag should only exist if it represents a meaningful concept that cannot already be expressed using existing tags.
An ebook is a structured book with optional front matter and a required content section. Like other MML, each opening tag occupies one line. Authors can put a quoted value on a tag line or put the value on the following line; closing tags are optional in the current parser.
+
ebook output="html" mode="static"
+metadata
+title "A Small Book"
+author "Ashly Lorenzana"
+language "en"
+toc
+content
+heading level="1" "First Chapter"
+paragraph "The opening paragraph."
+heading level="2" "A Smaller Section"
+paragraph "Another paragraph."
+
Heading text, optionally with level="1" through level="6" and id
+
+
+
paragraph
+
content or section
+
Body paragraph
+
+
+
style
+
ebook
+
Optional CSS for styled or interactive HTML mode
+
+
+
javascript or script
+
ebook
+
Optional JavaScript for interactive HTML mode
+
+
+
content is the only required child. A toc is generated from the headings in document order; heading levels determine nesting. Missing heading IDs are assigned from their text. min-depth and max-depth control which levels appear in the TOC. The output attribute accepts html, plain-text, pdf, or epub; the current compiler produces HTML or plain-text only. The mode attribute accepts static, styled, or interactive. The compiler includes style in styled and interactive HTML and includes javascript/script in interactive HTML. Plain-text output omits cover, CSS, and JavaScript.
+
The parser also accepts p as shorthand for paragraph, h for heading, and js for javascript. In an ebook, title and other metadata fields belong under metadata; image may appear under cover or content (and in its established media contexts).
+
+
17. Crossword Grid Schema
+
A crossword-grid describes a rectangular crossword with two directional word lists. Each tag occupies its own line; the following line contains its value. Closing tags are optional in the current parser.
+
crossword-grid
+7 x 7
+across
+word
+STARS, ASH
+first-letters
+(1,1), (3,1)
+word-lengths
+5, 3
+down
+word
+SEA
+first-letters
+(1,1)
+word-lengths
+3
+across-clues
+Night lights, Fire remains
+down-clues
+Large body of salt water
+
+
The dimension line is columns x rows. Coordinates in first-letters are (row,column), beginning at 1. The first item in each directional list belongs to the first word, the second to the second word, and so on. across-clues and down-clues follow their respective word order. An empty direction still includes its three empty list tags and its empty clue tag.
+
+
+
+
Tag
+
Parent
+
Value
+
+
+
+
crossword-grid
+
document
+
Dimensions followed by the directional and clue tags
+
+
+
across, down
+
crossword-grid
+
One word, first-letters, and word-lengths tag each
+
+
+
word
+
across or down
+
Comma-separated answers using A–Z letters
+
+
+
first-letters
+
across or down
+
Comma-separated starting squares (row,column)
+
+
+
word-lengths
+
across or down
+
Comma-separated positive lengths
+
+
+
across-clues, down-clues
+
crossword-grid
+
Comma-separated clues
+
+
+
A clue containing a comma must be enclosed in double quotes; double quotes inside a quoted clue are doubled. Coordinate commas inside parentheses do not separate list entries. The parser requires the four corresponding lists to have equal item counts, each length to match its answer, all words to fit inside the grid, and letters at crossings to agree. The same starting square may be shared by one across and one down word. Unused squares are black in the compiled HTML solution. Numbers are assigned to distinct starting squares in row-major order and shared by across and down words beginning in the same square.
+
The word tag also remains available under glossary. Only glossary words require a definition child.
+
+
18. Survey Schema
+
A survey groups questions and describes how each answer is collected. One tag appears per line. Values may follow their tag on the next line or appear as quoted inline values.
+
survey title="Tool Preferences"
+question id="workplace" type="single-choice" required="true"
+prompt "Where do you work most often?"
+option "Home"
+option "Office"
+question id="apps" type="multiple-choice"
+prompt "Which tools do you use?"
+option "Obsidian"
+option "VS Code"
+question id="usefulness" type="rating" min="1" max="5"
+prompt "How useful are they?"
+question id="notes" type="long-text"
+prompt "Anything else you want to tell us?"
+
+
+
+
+
Tag
+
Parent
+
Meaning
+
+
+
+
survey
+
document
+
Survey root; optional title and action attributes
+
+
+
question
+
survey
+
One answerable question; type is required, id and required are optional
+
+
+
prompt
+
question
+
Required, nonempty question wording
+
+
+
option
+
choice question
+
One possible answer; the existing option tag also works under dropdown
+
+
+
Supported question types are single-choice (radio buttons), multiple-choice (checkboxes), rating (numbered radio buttons), text (short input), and long-text (textarea). A choice question needs at least two distinct, nonempty option values. Other types do not take options. A rating question needs integer min and max attributes between 0 and 10, with max greater than min. required accepts true or false. Each question ID must be unique and start with a letter; an omitted ID is generated from its position.
+
The compiler produces an HTML form with controls named by question ID. If action is supplied on survey, the form uses that URL with method="post"; the schema does not provide response storage. required maps to native HTML validation for radio and text answers; for multiple-choice it is represented on the fieldset for semantics, because HTML cannot require at least one checkbox in a group without additional behavior. Branching and scoring are outside this initial schema.
+
+
19. Creative-Work Records
+
Use film, song, album, book, series, episode, game, and podcast to describe works. These are records about works; ebook continues to structure actual book content for export.
+
Every record requires exactly one nonempty title. Other fields are optional and hold nonempty text, without nested elements. Fields may use a value on the following line or a quoted inline value. Use quoted inline values when a value itself is a reserved tag name.
+
film
+title
+The Menu
+director
+Mark Mylod
+release-year
+2022
+genre
+dark-comedy
+genre
+horror
+/film
+
+
All types accept title, description, release-year, and repeated genre fields, plus these fields:
+
+
+
+
Record
+
Additional fields
+
+
+
+
film
+
director
+
+
+
song
+
artist, album
+
+
+
album
+
artist
+
+
+
book
+
author, publisher
+
+
+
series
+
creator, start-year, end-year
+
+
+
episode
+
season-number, episode-number, date
+
+
+
game
+
creator, publisher
+
+
+
podcast
+
creator
+
+
+
Repeat genre and credit fields (director, artist, author, creator, publisher) to express multiple values. All other fields accept at most one value. release-year, start-year, and end-year use exactly four digits. A series may omit its end year while ongoing; when both years exist, the end cannot precede the start. season-number is a nonnegative integer (0 can represent specials); episode-number is a positive integer. Episode date holds nonempty date text, as in the existing date field; no additional date-format validation is imposed.
+
Consecutive work records become siblings automatically. Closers are optional; /film may directly follow the last field's value. Explicit field closers such as /genre also work.
Within a song, album is the album's name as a text field. Elsewhere, album is a record with its own title and artist. Close /song explicitly to start a separate album record immediately after a song:
Existing ebook metadata, event dates, and timeline rules retain their original contexts. Work records have no required parent and can be grouped in a document, section, or list item; they cannot appear in containers whose schema disallows them, such as ebook content.
+
+
20. Future Considerations
Potential future areas include:
-
-
Compiler targets
-
Rich editor support
-
Semantic repair actions
-
Schema extensions
-
Accessibility metadata
-
Knowledge graph generation
-
PDF and eBook compilation
-
AI-native document representations
-
-
-
15. Guiding Principle
+
+
Compiler targets
+
Rich editor support
+
Semantic repair actions
+
Schema extensions
+
Accessibility metadata
+
Knowledge graph generation
+
PDF and EPUB generation
+
AI-native document representations
+
+
+
21. Guiding Principle
A document should remain understandable as plain text while remaining unambiguously parseable as structured semantic data.
-
-
15.1 SUPPORT
-
Check out the README if you're not sure where to start.
Table of contents generated from headings in content.
+
content
+
The required body of an ebook.
+
heading / paragraph
+
Headings (with optional level and id) and body paragraphs within ebook content or sections.
+
title / subtitle / author / language / description / publisher / rights
+
Fields within ebook metadata; date also works there.
+
javascript
+
Interactive ebook script; script also works.
+
See the ebook schema for an example and output behavior.
+
Survey
+
survey
+
A set of questions; optional title and form action attributes.
+
question
+
An answerable survey question with a type attribute and optional id and required attributes.
+
prompt
+
The wording of a survey question.
+
option
+
A possible answer for a single-choice or multiple-choice question; also used by dropdowns.
+
See the survey schema for types, validation, and a complete example.
+
Creative-work records
+
film / song / album / book / series / episode / game / podcast
+
Records describing creative works. Each requires exactly one nonempty title; all accept optional description, release-year, and repeated genre fields. book describes a work; ebook contains its actual content for export. In a song, album is a scalar album-name field; elsewhere it is a record.
+
director
+
Film director credit. Repeat for multiple directors.
+
artist
+
Song or album artist credit. Repeat for multiple artists.
+
creator
+
Series, game, or podcast creator credit. Repeat for multiple creators.
+
release-year
+
Four-digit release/publication year of any creative-work record.
+
genre
+
A genre label on any creative-work record. Repeat for multiple genres; labels such as dark-comedy remain plain text.
+
season-number / episode-number
+
Episode numbering. Season numbers are nonnegative (0 for specials); episode numbers are positive integers.
+
The existing title and description fields also belong directly under any work record; author belongs under book, and publisher under book or game. start-year and end-year also belong under series; date also belongs under episode.