From 36e866cb05f58b434b3d3610c00c038f57fc2817 Mon Sep 17 00:00:00 2001 From: Ashly Date: Sat, 31 Oct 2026 22:35:20 -0700 Subject: [PATCH 1/2] feat(schema): add creative-work records and descriptive fields --- DOCS/DEPENDENCIES.md | 35 +- DOCS/README.md | 29 +- DOCS/SCHEMA-INDEX.md | 112 ++ DOCS/SPEC.md | 98 +- DOCS/TAGS.md | 31 +- export/DOCS/DEPENDENCIES.html | 299 ++++- export/DOCS/README.html | 413 +++--- export/DOCS/SCHEMA-INDEX.html | 497 +++++++ export/DOCS/SPEC.html | 905 ++++++++++--- export/DOCS/TAGS.html | 229 ++-- export/FILES/index.html | 39 + export/src/compiler.js | 13 + export/src/grammar.js | 17 + export/src/index.js | 1 + export/src/parser.js | 25 + export/src/validator.js | 26 +- export/src/work-schema.js | 71 + tests/run-tests.js | 2306 ++++++++++++++++++--------------- 18 files changed, 3544 insertions(+), 1602 deletions(-) create mode 100644 DOCS/SCHEMA-INDEX.md create mode 100644 export/DOCS/SCHEMA-INDEX.html create mode 100644 export/src/work-schema.js 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 - - - -
- - -

PARENT TAGS

+ +DEPENDENCIES — MML

PARENT TAGS

@@ -28,8 +8,7 @@

PARENT TAGS

- - + @@ -124,9 +103,48 @@

PARENT TAGS

- -
CONTAINER
document no yes 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

- - + - + @@ -153,11 +170,11 @@

CHILD TAGS

- + - + @@ -169,7 +186,7 @@

CHILD TAGS

- + @@ -256,15 +273,177 @@

CHILD TAGS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - -
CHILD OF
optiondropdowndropdown or choice question
select
year-starttimelinetimeline or series
year-endtimelinetimeline or series
month
dateeventevent, metadata, or episode
image text
traitentity
wordglossary
definitionword
synonymword
antonymword
originword
usageword
questionsurvey
promptquestion
optionquestion (choice types)
metadataebook
coverebook
tocebook
contentebook
styleebook
javascriptebook
scriptebook
titlemetadata or any creative-work record
subtitlemetadata
authormetadata or book
languagemetadata
descriptionmetadata or any creative-work record
datemetadata, event, or episode
publishermetadata, book, or game
rightsmetadata
imagecover, content, media, or section
captioncover or media
headingcontent or section
paragraphcontent 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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RecordAdditional children
filmdirector
songartist, album (text field)
albumartist
bookauthor, publisher
seriescreator, start-year, end-year
episodeseason-number, episode-number, date
gamecreator, publisher
podcastcreator
+

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
  • +
  • trait ---> CANNOT EXIST OUTSIDE OF ---> entity
  • +
  • synonym ---> CANNOT EXIST OUTSIDE OF ---> word
  • +
  • antonym ---> CANNOT EXIST OUTSIDE OF ---> word
  • +
  • word ---> CANNOT EXIST OUTSIDE OF ---> glossary
  • +
  • definition ---> CANNOT EXIST OUTSIDE OF ---> word
  • +
  • origin ---> CANNOT EXIST OUTSIDE OF ---> word
  • +
  • usage ---> CANNOT EXIST OUTSIDE OF ---> word

-

TAGS

-

Here is the list of TAGS.

-

Looking for the SHORTHAND version?

-

Check out a list of PROPOSED TAGS.

-

Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

-

Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

-

#TAgs #parent #child #GRAMMAr #SEMANTIc #MARKUp #DATA-STRUCTURe #LISTs #rules #dependencies

- -
- - +

TAGS

+

Here is the list of TAGS.

+

Looking for the SHORTHAND version?

+

Check out a list of PROPOSED TAGS.

+

Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

+

Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

+

#tags #parent #child #grammar #semantic #markup #data-structure #lists #rules #dependencies

+
diff --git a/export/DOCS/README.html b/export/DOCS/README.html index 7bcb3f9..c2f7c1a 100644 --- a/export/DOCS/README.html +++ b/export/DOCS/README.html @@ -1,237 +1,294 @@ - - - - - - README - - - -
- - -

Modular Markup (MML)

+ +README — MML

Modular Markup (MML)

+

SUGGEST A TAG PROPOSE A SCHEMA

+

TAGS SPECIFICATIONS DEPENDENCIES

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.


-

Goals

-
    -
  • Human-readable source documents
  • -
  • Explicit semantic structure
  • -
  • Strong parent-child validation
  • -
  • Meaning-first document modeling
  • -
  • Plain text as the authoring format
  • -
  • Automatic structure generation
  • -
  • Compiler-friendly AST representation
  • -
  • Extensible semantic schemas
  • +

    Documentation in this folder

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FilePurpose
    SPEC.mdFull language specification (v0.1): syntax, principles, validation rules, and schema definitions.
    TAGS.mdOfficial tag registry with examples. Currently lists 95 official tags (argument, calendar, claim, comparison, document, form, media, timeline, and others).
    SHORTHAND.mdShorthand alias rules and the official shorthand table (arg, comp, grp, img, evi, etc.).
    DEPENDENCIES.mdParent/child relationships, required children, and nesting rules — including group (shared trait values) and comparison schemas.
    SYNONYMS.mdConceptual synonym mappings (e.g. section ↔ chapter, claim ↔ statement).
    PROPOSED.mdTags and schemas under consideration (node, cluster, identity, profile, education, and others).
    TAG PROPOSAL EVALUATION.mdChecklist for reviewing individual tag proposals.
    SCHEMA PROPOSAL EVALUATION.mdChecklist for reviewing multi-tag schema proposals.
    LINKS.mdQuick links to the repo, issue templates, parser demo, and other docs.
    SCRATCHPAD.mdEmpty notes scratchpad (category: notes). A browser-based editor lives in export-blank/DOCS/SCRATCHPAD.html.
    +
    +

    Goals

    +
      +
    • Human-readable source documents
    • +
    • Explicit semantic structure
    • +
    • Strong parent-child validation
    • +
    • Meaning-first document modeling
    • +
    • Plain text as the authoring format
    • +
    • Automatic structure generation (TOC, text nodes, implicit close)
    • +
    • Compiler-friendly AST representation
    • +
    • Extensible semantic schemas
    - -

    Core Philosophy

    -

    MML is built around semantic objects rather than formatting instructions.

    -

    For example:

    +
    +

    Quick example

    +

    Source (opening-tag-only authoring — closing tags are optional):

    argument
     claim
    +Markdown introduces an unnecessary abstraction layer.
     evidence
    -timeline
    -event
    -comparison
    -entity
    -image
    -caption
    +The final rendered output is already HTML.
     
    -

    represent meaningful concepts.

    -

    By contrast, generic containers such as:

    -
    <div>
    -<span>
    +

    Compiled output:

    +
    <argument>
    +  <claim>
    +    <text>Markdown introduces an unnecessary abstraction layer.</text>
    +    <evidence>
    +      <text>The final rendered output is already HTML.</text>
    +    </evidence>
    +  </claim>
    +</argument>
     
    -

    have no direct equivalent in MML.

    -

    Every element should represent something recognizable and meaningful.

    +

    Try this in the parser demo.


    -

    Syntax

    -

    Opening Tags

    -

    Opening tags are written as plain keywords.

    -
    claim
    -
    +

    Syntax (current parser)

    +

    Opening tags

    +

    One tag per line. Attributes use double-quoted values:

    section title="Background"
    +ebook output="html" mode="interactive"
     
    - -
    -

    Text Content

    -

    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.

    +

    See SPEC.md for the full grammar.


    -

    Validation

    +

    Validation

    MML validates semantic structure, not just syntax.

    -

    Example:

    +

    Invalid:

    evidence
     The final output is already HTML.
    -
    -
    -

    Produces:

    -
    Error:
    -evidence requires parent claim.
     
    +

    Error: evidence requires parent claim or argument

    Valid:

    argument
    -
     claim
    -
     evidence
     The final output is already HTML.
    -
    -
    -
    -

    Automatic Text Nodes

    -

    Plain text is automatically wrapped in text nodes.

    -

    Source:

    -
    claim
    -Markdown is unnecessary.
    -
    -
    -

    Internal representation:

    -
    <claim>
    -  <text>Markdown is unnecessary.</text>
    -</claim>
     
    -

    Authors rarely need to write explicit text tags.

    +

    Parent/child requirements, required children, and schema rules are summarized in DEPENDENCIES.md.


    -

    Semantic Schemas

    -

    Argument

    +

    Semantic schemas

    +

    Schemas implemented in the parser and validator include:

    +

    Argument

    argument
     └── claim
         └── evidence
     
    -

    Rules:

    -
      -
    • argument requires at least one claim
    • -
    • claim may exist standalone
    • -
    • evidence requires parent claim
    • +
        +
      • argument requires at least one claim
      • +
      • claim may exist standalone
      • +
      • evidence requires parent claim or argument
      -
      -

      Timeline

      +

      Timeline

      timeline
      -├── year-start
      +├── start-year
       ├── event
      -└── year-end
      +│   └── date
      +└── end-year
       
      -

      Rules:

      -
        -
      • timeline requires year-start
      • -
      • timeline requires year-end
      • -
      • event requires date
      • +
          +
        • timeline requires start-year and end-year
        • +
        • Event dates must fall within the timeline year range
        • +
        • Legacy aliases: year-start, year-end, spaced forms like end year
        -
        -

        Calendar

        +

        Calendar

        calendar
        -├── year-month
        +├── year
        +├── month
         └── event
        +    └── date
         
        -

        Rules:

        -
          -
        • calendar requires year-month
        • -
        • event requires date
        • +
            +
          • Requires year and/or month
          • +
          • Compiles to an HTML month table with highlighted event days
          • +
          • Event day numbers are validated against the calendar month
          -
          -

          Comparison

          -

          Before / After

          -
          comparison
          -├── before
          -└── after
          -
          -

          Entity Comparison

          -
          comparison
          -├── entity
          -│   └── unique
          +

          Comparison

          +

          Named schemas (see DEPENDENCIES.md):

          +
            +
          • Before / after — before + after
          • +
          • Entity — two or more entity children, each with unique, optionally shared
          • +
          • Scenario — two or more scenario children, each with condition
          • +
          +

          Group

          +
          group
           ├── entity
          -│   └── unique
          -└── shared
          -
          -

          Scenario Comparison

          -
          comparison
          -├── scenario
          -│   └── conditions
          -└── scenario
          -    └── conditions
          +│   └── trait
          +└── entity
          +    └── trait
           
          -
          -

          Media

          +
            +
          • Requires at least two entity children
          • +
          • 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):

          +
          ebook
          +├── metadata (title, author, language, …)
          +├── cover (image, caption)
          +├── toc
          +├── content (heading, section, paragraph, …)
          +├── style
          +└── javascript
           
          -

          Rules:

          -
            -
          • 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
            • +
            • compiler.js — HTML compilation (calendar tables, ebook export, heading IDs, TOC)
            • +
            • 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.

            +

            Contribute

            +

            Have an issue? Get in touch.

            +

            Have an idea for a tag? Submit a tag — review against TAG PROPOSAL EVALUATION.md.

            +

            Have a multi-tag schema idea? Submit a schema — review against SCHEMA PROPOSAL EVALUATION.md.


            -

            Project Status

            -

            Early specification and parser prototype.

            +

            Where to go next

            +

            The language is actively evolving and many schemas, validation rules, and compilation targets remain under discussion.


            -

            CONTRIBUTE

            +

            CONTRIBUTE

            Have an issue? GET IN TOUCH.

            Have an idea for a tag we should add? SUBMIT A TAG here.

            Do you have a more advanced tag idea? SUBMIT A SCHEMA instead!


            -

            SUPPORT

            -

            You can read the full SPEC here.

            +

            Community

            + +
            +

            SUPPORT

            +

            You can read the full SPEC here.

            Try the PARSER.


            -

            TAGS

            -

            Here is the list of TAGS.

            -

            Looking for the SHORTHAND version?

            -

            Check out a list of PROPOSED TAGS.

            -

            Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

            -

            Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

            -

            #readme #markup #grammar #syntax #semantic #data-structure #schemas #official #tags

            - -
- - +

TAGS

+

Here is the list of TAGS.

+

Looking for the SHORTHAND version?

+

Check out a list of PROPOSED TAGS.

+

Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

+

Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

+

#readme #markup #grammar #syntax #semantic #data-structure #schemas #official #tags #documentation

+
diff --git a/export/DOCS/SCHEMA-INDEX.html b/export/DOCS/SCHEMA-INDEX.html new file mode 100644 index 0000000..904c20f --- /dev/null +++ b/export/DOCS/SCHEMA-INDEX.html @@ -0,0 +1,497 @@ + +SCHEMA-INDEX — MML

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 — exports: CROSSWORD_ROOT_CHILDREN, CROSSWORD_DIRECTION_CHILDREN, splitCrosswordList, readCrossword, crosswordEntries, validateCrossword
  • +
  • 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 — exports: SURVEY_QUESTION_TYPES, surveyQuestions, validateSurvey
  • +
  • work-schema.js — exports: WORK_FIELDS, WORK_TYPES, WORK_FIELD_PARENTS, validateWork
  • +
+

Tags

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagRequired parent candidatesAliases
acrosscrossword-grid—
across-cluescrossword-grid—
afterNo parent requirement—
albumNo parent requirement—
antonymwordant
argumentNo parent requirementarg
artistsong, album—
audioNo parent requirementmp3, wav
authormetadata, book—
beforeNo parent requirement—
blockquoteNo parent requirementquote
bookNo parent requirement—
buttonNo parent requirement—
calendarNo parent requirementcal
canvasNo parent requirement—
cellNo parent requirement—
claimNo parent requirement—
columnNo parent requirementcol
comparisonNo parent requirementcomp
conditionscenariocond, conditions
contentebook—
coverebook—
creatorseries, game, podcast—
crossword-gridNo parent requirement—
dateevent, metadata, episode—
definitionworddef
descriptionmetadata, film, song, album, book, series, episode, game, podcast—
directorfilm—
documentNo parent requirementdoc
downcrossword-grid—
down-cluescrossword-grid—
dropdownNo parent requirementdrop
ebookNo parent requirement—
end-yeartimeline, seriesyear-end
entitygroup, comparison—
episodeNo parent requirement—
episode-numberepisode—
eventNo parent requirement—
evidenceclaim, argumentevi
fieldsetNo parent requirementset
filmNo parent requirement—
first-lettersacross, down—
footnoteNo parent requirementfoot, fnote
formNo parent requirement—
gameNo parent requirement—
genrefilm, song, album, book, series, episode, game, podcast—
glossaryNo parent requirementglo
groupNo parent requirementgrp
headingcontent, sectionh
imagecover, content, media, sectionimg, jpg, png, svg, gif
inputNo parent requirement—
itemNo parent requirement—
javascriptebookjs
languagemetadata—
legendNo parent requirement—
linkNo parent requirement—
listNo parent requirement—
mediaNo parent requirement—
metadataebook—
monthcalendaryear-month
optionquestion, dropdown—
originwordori
paragraphcontent, sectionp
podcastNo parent requirement—
promptquestion—
publishermetadata, book, game—
questionsurvey—
release-yearfilm, song, album, book, series, episode, game, podcast—
rightsmetadata—
rowNo parent requirement—
scenarioNo parent requirementscene
scriptebook—
season-numberepisode—
sectionNo parent requirementsect
selectionNo parent requirement—
seriesNo parent requirement—
songNo parent requirement—
start-yeartimeline, seriesyear-start
styleebook—
subtitlemetadata—
surveyNo parent requirement—
synonymwordsyn
tableNo parent requirement—
textNo parent requirement—
textareaNo parent requirementpara
timelineNo parent requirement—
titlemetadata, film, song, album, book, series, episode, game, podcast—
tocebook—
traitentity—
uniqueentity—
usagewordusag
videoNo parent requirementmp4
wordglossary, across, down—
word-lengthsacross, down—
yearcalendar—
+

See SPEC.md for authored schema examples and attributes.

+
diff --git a/export/DOCS/SPEC.html b/export/DOCS/SPEC.html index 81c1100..7851b6a 100644 --- a/export/DOCS/SPEC.html +++ b/export/DOCS/SPEC.html @@ -1,29 +1,5 @@ - - - - - - -SPEC - - - -
- -

1. Introduction

+ +SPEC — MML

1. Introduction

Modular Markup Language (MML) is a semantic document language designed around a simple principle:

Documents should describe meaning rather than formatting.

@@ -31,20 +7,20 @@

1. Introduction

MML is intended to remain readable as plain text while providing enough structure for parsing, validation, compilation, and semantic analysis.

Unlike Markdown, MML does not rely on symbolic formatting conventions.

Unlike HTML, MML prioritizes semantic relationships and parent-child validation over presentation.

-
-

2. Design Goals

+
+

2. Design Goals

MML is designed to be:

-
    -
  • Human-readable
  • -
  • Machine-parseable
  • -
  • Semantically meaningful
  • -
  • Validation-friendly
  • -
  • Extensible
  • -
  • Plain-text authorable
  • -
-
-

3. Core Principles

-

3.1 Meaning First

+
    +
  • Human-readable
  • +
  • Machine-parseable
  • +
  • Semantically meaningful
  • +
  • Validation-friendly
  • +
  • Extensible
  • +
  • Plain-text authorable
  • +
+
+

3. Core Principles

+

3.1 Meaning First

Elements should represent meaningful concepts rather than visual presentation.

Preferred:

argument
@@ -62,28 +38,36 @@ 

3.1 Meaning First

wrapper container
-
-

3.2 Text Wins

+
+

3.2 Text Wins

If content is not valid markup, it is treated as text.

The parser should never aggressively reinterpret ordinary writing as structure.

-
-

3.3 Explicit Structure

+
+

3.3 Explicit Structure

All elements must be explicitly opened and closed.

-
-

3.4 Semantic Validation

+
+

3.4 Semantic Validation

MML validates semantic relationships, not merely syntax.

-
-

4. Syntax

-

4.1 Opening Tags

+
+

4. Syntax

+

4.1 Opening Tags

Opening tags consist of a valid element name.

Example:

claim
 

Attributes may be included:

-
section title="Background"
+
section title="Background"
+
+
+

4.2 Closing Tags

+

Closing tags begin with a forward slash.

+

Example:

+
/claim
+
+
/argument
 
-
-

4.2 Element Names

+
+

4.3 Element Names

All element names are singular.

Valid:

claim
@@ -97,54 +81,89 @@ 

4.2 Element Names

entities images
-
-

4.3 Attributes

+
+

4.4 Attributes

Attributes may only appear on opening tag lines.

Example:

-
section title="Introduction"
+
section title="Introduction"
 

Attributes are parsed only when attached to a valid opening tag.

Example:

section
 
-title="Introduction"
+title="Introduction"
+
+/section
 

In this example:

-
title="Introduction"
+
title="Introduction"
 

is plain text.

-
-

5. Text Handling

-

5.1 Automatic Text Nodes

+
+

5. Text Handling

+

5.1 Automatic Text Nodes

Plain text is automatically wrapped in text elements.

Source:

claim
 Markdown introduces an unnecessary abstraction layer.
+/claim
 

Internal Representation:

<claim>
   <text>Markdown introduces an unnecessary abstraction layer.</text>
+</claim>
 

Authors are not expected to manually create text elements in most situations.

-
-

5.2 Reserved Words

+
+

5.2 Reserved Words

Reserved words only act as markup when they appear in tag position.

Example:

claim
 Arguments are not always unhealthy.
+/claim
 
-

The word "Arguments" is text content.

-
-

6. Parsing Rules

-

6.1 Opening Tag Recognition

+

The word "Arguments" is text content.

+
+

6. Parsing Rules

+

6.1 Opening Tag Recognition

A line is interpreted as an opening tag when:

-
    -
  • It begins with a valid element name.
  • -
  • Any supplied attributes are valid.
  • +
      +
    • It begins with a valid element name.
    • +
    • Any supplied attributes are valid.
    -
    -

    7. Validation Rules

    -

    7.1 Parent Validation

    +
    +

    6.2 Closing Tag Recognition

    +

    A line is interpreted as a closing tag when:

    +
    /element-name
    +
    +

    matches a currently open element.

    +
    +

    6.3 Closing Validation

    +

    Elements must close in stack order.

    +

    Valid:

    +
    argument
    +
    +claim
    +Text.
    +/claim
    +
    +/argument
    +
    +

    Invalid:

    +
    argument
    +
    +claim
    +Text.
    +
    +/argument
    +
    +

    Error:

    +
    Cannot close argument while claim is still open.
    +Expected /claim.
    +
    +
    +

    7. Validation Rules

    +

    7.1 Parent Validation

    Elements may define required parents.

    Example:

    evidence
    @@ -153,42 +172,43 @@ 

    7.1 Parent Validation

    claim
     

    parent.

    -
    -

    7.2 Missing Parent Errors

    +
    +

    7.2 Missing Parent Errors

    Example:

    evidence
     Some evidence.
    +/evidence
     

    Produces:

    Error:
     evidence requires parent claim.
     

    The parser should provide structured repair information whenever possible.

    -
    -

    8. Element Definitions

    -

    8.1 Argument System

    -

    argument

    +
    +

    8. Element Definitions

    +

    8.1 Argument System

    +

    argument

    Purpose:

    -
      -
    • Represents a collection of claims.
    • +
        +
      • Represents a collection of claims.

      Rules:

      -
        -
      • Requires at least one claim.
      • +
          +
        • Requires at least one claim.

        Allowed Children:

        claim
         
        -
        -

        claim

        +
        +

        claim

        Purpose:

        -
          -
        • Represents a semantic assertion.
        • +
            +
          • Represents a semantic assertion.

          Rules:

          -
            -
          • May exist independently.
          • -
          • May exist within argument.
          • +
              +
            • May exist independently.
            • +
            • May exist within argument.

            Allowed Children:

            text
            @@ -196,27 +216,125 @@ 

            claim

            quote source
            -
            -

            evidence

            +
            +

            evidence

            Purpose:

            -
              -
            • Supports a claim.
            • +
                +
              • Supports a claim.

              Rules:

              -
                -
              • Requires parent claim.
              • +
                  +
                • Requires parent claim.

                Allowed Children:

                text
                 quote
                 source
                 
                -
                -

                9. Timeline System

                -

                timeline

                +
                +

                8.2 Glossary System

                +

                glossary

                +

                Purpose:

                +
                  +
                • Represents a collection of word entries.
                • +
                +

                Rules:

                +
                  +
                • Requires at least one word.
                • +
                +

                Allowed Children:

                +
                word
                +
                +
                +

                word

                +

                Purpose:

                +
                  +
                • Represents a glossary entry for a term.
                • +
                +

                Rules:

                +
                  +
                • Requires parent glossary.
                • +
                • Requires definition.
                • +
                +

                Allowed Children:

                +
                text
                +definition
                +synonym
                +antonym
                +origin
                +usage
                +
                +
                +

                definition

                +

                Purpose:

                +
                  +
                • States the meaning of a word.
                • +
                +

                Rules:

                +
                  +
                • Requires parent word.
                • +
                +

                Allowed Children:

                +
                text
                +
                +
                +

                synonym

                +

                Purpose:

                +
                  +
                • Names a related or equivalent term.
                • +
                +

                Rules:

                +
                  +
                • Requires parent word.
                • +
                +

                Allowed Children:

                +
                text
                +
                +
                +

                antonym

                +

                Purpose:

                +
                  +
                • Names an opposite term.
                • +
                +

                Rules:

                +
                  +
                • Requires parent word.
                • +
                +

                Allowed Children:

                +
                text
                +
                +
                +

                origin

                +

                Purpose:

                +
                  +
                • Records etymology or historical source of a word.
                • +
                +

                Rules:

                +
                  +
                • Requires parent word.
                • +
                +

                Allowed Children:

                +
                text
                +
                +
                +

                usage

                +

                Purpose:

                +
                  +
                • Shows how a word is used in context.
                • +
                +

                Rules:

                +
                  +
                • Requires parent word.
                • +
                +

                Allowed Children:

                +
                text
                +
                +
                +

                9. Timeline System

                +

                timeline

                Purpose:

                -
                  -
                • Represents a chronological range.
                • +
                    +
                  • Represents a chronological range.

                  Required Children:

                  year-start
                  @@ -226,30 +344,30 @@ 

                  timeline

                  event
                   

                  A timeline containing only year-start and year-end is valid.

                  -
                  -

                  year-start

                  +
                  +

                  year-start

                  Rules:

                  -
                    -
                  • Requires parent timeline.
                  • +
                      +
                    • Requires parent timeline.
                    -
                    -

                    year-end

                    +
                    +

                    year-end

                    Rules:

                    -
                      -
                    • Requires parent timeline.
                    • +
                        +
                      • Requires parent timeline.
                      -
                      -

                      event

                      +
                      +

                      event

                      Purpose:

                      -
                        -
                      • Represents a time-bound occurrence.
                      • +
                          +
                        • Represents a time-bound occurrence.

                        Rules:

                        -
                          -
                        • Requires date.
                        • -
                        • May exist independently.
                        • -
                        • May exist within timeline.
                        • -
                        • May exist within calendar.
                        • +
                            +
                          • Requires date.
                          • +
                          • May exist independently.
                          • +
                          • May exist within timeline.
                          • +
                          • May exist within calendar.

                          Allowed Children:

                          date
                          @@ -260,18 +378,18 @@ 

                          event

                          note link
                          -
                          -

                          date

                          +
                          +

                          date

                          Rules:

                          -
                            -
                          • Requires parent event.
                          • +
                              +
                            • Requires parent event.
                            -
                            -

                            10. Calendar System

                            -

                            calendar

                            +
                            +

                            10. Calendar System

                            +

                            calendar

                            Purpose:

                            -
                              -
                            • Represents a calendar period.
                            • +
                                +
                              • Represents a calendar period.

                              Required Children:

                              year-month
                              @@ -280,17 +398,17 @@ 

                              calendar

                              event
                               

                              A calendar containing only year-month is valid.

                              -
                              -

                              year-month

                              +
                              +

                              year-month

                              Rules:

                              -
                                -
                              • Requires parent calendar.
                              • +
                                  +
                                • Requires parent calendar.
                                -
                                -

                                11. Comparison System

                                +
                                +

                                11. Comparison System

                                MML supports multiple comparison schemas.

                                -
                                -

                                11.1 Before / After Schema

                                +
                                +

                                11.1 Before / After Schema

                                Required Children:

                                before
                                 after
                                @@ -300,12 +418,16 @@ 

                                11.1 Before / After Schema

                                before Old design. +/before after New design. +/after + +/comparison
                                -
                                -

                                11.2 Entity Schema

                                +
                                +

                                11.2 Entity Comparison Schema

                                Required:

                                entity
                                 entity
                                @@ -313,30 +435,30 @@ 

                                11.2 Entity Schema

                                Optional:

                                shared
                                 
                                -
                                -

                                entity

                                +
                                +

                                entity

                                Rules:

                                -
                                  -
                                • Requires parent comparison.
                                • +
                                    +
                                  • Requires parent comparison.

                                  Allowed Children:

                                  unique
                                   text
                                   
                                  -
                                  -

                                  unique

                                  +
                                  +

                                  unique

                                  Rules:

                                  -
                                    -
                                  • Requires parent entity.
                                  • +
                                      +
                                    • Requires parent entity.
                                    -
                                    -

                                    shared

                                    +
                                    +

                                    shared

                                    Rules:

                                    -
                                      -
                                    • Requires parent comparison.
                                    • +
                                        +
                                      • Requires parent comparison.
                                      -
                                      -

                                      11.3 Scenario Schema

                                      +
                                      +

                                      11.3 Scenario Comparison Schema

                                      Required:

                                      scenario
                                       scenario
                                      @@ -344,33 +466,33 @@ 

                                      11.3 Scenario Schema

                                      Each scenario should contain:

                                      conditions
                                       
                                      -
                                      -

                                      scenario

                                      +
                                      +

                                      scenario

                                      Rules:

                                      -
                                        -
                                      • Requires parent comparison.
                                      • +
                                          +
                                        • Requires parent comparison.

                                        Allowed Children:

                                        conditions
                                         text
                                         note
                                         
                                        -
                                        -

                                        conditions

                                        +
                                        +

                                        conditions

                                        Rules:

                                        -
                                          -
                                        • Requires parent scenario.
                                        • +
                                            +
                                          • Requires parent scenario.
                                          -
                                          -

                                          12. Media System

                                          -

                                          media

                                          +
                                          +

                                          12. Media System

                                          +

                                          media

                                          Purpose:

                                          -
                                            -
                                          • Groups related media assets.
                                          • +
                                              +
                                            • Groups related media assets.

                                            Required Children:

                                            -
                                              -
                                            • At least one of:
                                            • +
                                                +
                                              • At least one of:
                                              image
                                               audio
                                              @@ -380,75 +502,432 @@ 

                                              media

                                              caption
                                               source
                                               
                                              -
                                              -

                                              image

                                              -
                                                -
                                              • Represents an image.
                                              • +
                                                +

                                                image

                                                +
                                                  +
                                                • Represents an image.
                                                -
                                                -

                                                audio

                                                -
                                                  -
                                                • Represents audio content.
                                                • +
                                                  +

                                                  audio

                                                  +
                                                    +
                                                  • Represents audio content.
                                                  -
                                                  -

                                                  video

                                                  -
                                                    -
                                                  • Represents video content.
                                                  • +
                                                    +

                                                    video

                                                    +
                                                      +
                                                    • Represents video content.
                                                    -
                                                    -

                                                    caption

                                                    +
                                                    +

                                                    caption

                                                    Purpose:

                                                    -
                                                      -
                                                    • Describes associated media.
                                                    • +
                                                        +
                                                      • Describes associated media.

                                                      Preferred Parent:

                                                      media
                                                       
                                                      -
                                                      -

                                                      13. Structural Elements

                                                      -

                                                      section

                                                      +
                                                      +

                                                      13. Structural Elements

                                                      +

                                                      section

                                                      Purpose:

                                                      -
                                                        -
                                                      • Represents a logical document section.
                                                      • +
                                                          +
                                                        • Represents a logical document section.

                                                        Attributes:

                                                        title
                                                         

                                                        Example:

                                                        -
                                                        section title="Background"
                                                        +
                                                        section title="Background"
                                                         

                                                        The title attribute functions as the section heading.

                                                        -
                                                        -

                                                        subhead

                                                        +
                                                        +

                                                        subhead

                                                        Purpose:

                                                        -
                                                          -
                                                        • Represents a heading within a section.
                                                        • +
                                                            +
                                                          • Represents a heading within a section.
                                                          -
                                                          -

                                                          14. Future Considerations

                                                          +
                                                          +

                                                          14. Runtime Elements

                                                          +
                                                          script
                                                          +style
                                                          +canvas
                                                          +
                                                          +

                                                          These elements provide runtime functionality and presentation support.

                                                          +
                                                          +

                                                          15. Reserved Elements v0.1

                                                          +
                                                          document
                                                          +section
                                                          +subhead
                                                          +
                                                          +text
                                                          +blockquote
                                                          +source
                                                          +
                                                          +link
                                                          +a
                                                          +
                                                          +argument
                                                          +claim
                                                          +evidence
                                                          +
                                                          +glossary
                                                          +word
                                                          +definition
                                                          +synonym
                                                          +antonym
                                                          +origin
                                                          +usage
                                                          +
                                                          +timeline
                                                          +calendar
                                                          +event
                                                          +date
                                                          +year-start
                                                          +year-end
                                                          +year-month
                                                          +
                                                          +comparison
                                                          +before
                                                          +after
                                                          +entity
                                                          +unique
                                                          +shared
                                                          +scenario
                                                          +conditions
                                                          +
                                                          +media
                                                          +image
                                                          +audio
                                                          +video
                                                          +caption
                                                          +
                                                          +table
                                                          +row
                                                          +column
                                                          +cell
                                                          +
                                                          +form
                                                          +fieldset
                                                          +input
                                                          +select
                                                          +option
                                                          +button
                                                          +
                                                          +canvas
                                                          +script
                                                          +style
                                                          +
                                                          +
                                                          +

                                                          16. Ebook Schema

                                                          +

                                                          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."
                                                          +
                                                          + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
                                                          TagParentMeaning
                                                          ebookdocumentBook root; accepts output and mode attributes
                                                          metadataebookOptional bibliographic fields: title, subtitle, author, language, description, date, publisher, rights
                                                          coverebookOptional image and caption
                                                          tocebookOptional generated table of contents; accepts min-depth and max-depth
                                                          contentebookRequired body; may contain heading, section, paragraph, text, image, caption, quote, blockquote, list, item, table, row, cell, column, media, audio, video, link, and footnote
                                                          headingcontent or sectionHeading text, optionally with level="1" through level="6" and id
                                                          paragraphcontent or sectionBody paragraph
                                                          styleebookOptional CSS for styled or interactive HTML mode
                                                          javascript or scriptebookOptional 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.

                                                          + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
                                                          TagParentValue
                                                          crossword-griddocumentDimensions followed by the directional and clue tags
                                                          across, downcrossword-gridOne word, first-letters, and word-lengths tag each
                                                          wordacross or downComma-separated answers using A–Z letters
                                                          first-lettersacross or downComma-separated starting squares (row,column)
                                                          word-lengthsacross or downComma-separated positive lengths
                                                          across-clues, down-cluescrossword-gridComma-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?"
                                                          +
                                                          + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
                                                          TagParentMeaning
                                                          surveydocumentSurvey root; optional title and action attributes
                                                          questionsurveyOne answerable question; type is required, id and required are optional
                                                          promptquestionRequired, nonempty question wording
                                                          optionchoice questionOne 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:

                                                          + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
                                                          RecordAdditional fields
                                                          filmdirector
                                                          songartist, album
                                                          albumartist
                                                          bookauthor, publisher
                                                          seriescreator, start-year, end-year
                                                          episodeseason-number, episode-number, date
                                                          gamecreator, publisher
                                                          podcastcreator
                                                          +

                                                          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.

                                                          +
                                                          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:

                                                          +
                                                          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:

                                                          +
                                                          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):

                                                          +
                                                          <film>
                                                          +  <title>The Menu</title>
                                                          +  <director>Mark Mylod</director>
                                                          +  <release-year>2022</release-year>
                                                          +  <genre>dark-comedy</genre>
                                                          +  <genre>horror</genre>
                                                          +</film>
                                                          +
                                                          +

                                                          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.

                                                          -

                                                          You can read the full SPEC here.

                                                          +
                                                          +

                                                          SUPPORT

                                                          +

                                                          Check out the README if you're not sure where to start.

                                                          +

                                                          You can read the full SPEC here.

                                                          Try the PARSER.

                                                          -

                                                          You can find the full list of TAGS here.

                                                          -

                                                          #specification #draft #syntax #markup #semantic #grammar #language

                                                          -
- - +

You can find the full list of TAGS here.

+

#specification #draft #syntax #markup #semantic #grammar #language

+
+
diff --git a/export/DOCS/TAGS.html b/export/DOCS/TAGS.html index bef4a34..e90ffac 100644 --- a/export/DOCS/TAGS.html +++ b/export/DOCS/TAGS.html @@ -1,55 +1,42 @@ - - - - - - TAGS - - - -
- - -

1. argument

-

2. calendar

-

3. month

-

4. year

-

5. canvas

-

6. claim

-

7. evidence

-

8. comparison

-

9. after

-

10. before

-

11. condition

-

12. document

-

13. quote

-

14. footnote

-

15. link

-

16. list

-

17. item

- -

18. section

-

19. text

-

20. entity

-

21. unique

-

22. shared

+ +TAGS — MML

1. argument

+

Remote work improves productivity.

+

2. calendar

+

3. month

+

4. year

+

5. canvas

+

6. claim

+

Remote workers spend less time commuting.

+

7. evidence

+

Employees avoid daily commuting.

+

8. comparison

+

Remote work is more flexible than office work.

+

9. after

+

10. before

+

11. group

+

trait

+

12. condition

+

13. document

+

13. quote

+

14. footnote

+ +

16. list

+
17. item
 
-

23. event

-

24. date

-

25. form

+

18. section

+

19. text

+

20. entity

+
21. unique
+22. shared
+
+

23. event

+

Product launched in 2025.

+

24. date

+

25. form

form action="GET"
 form action="POST"
 
-

26. button

+

26. button

button type="add"
 button type="copy"
 button type="delete"
@@ -58,14 +45,14 @@ 

26. button

button type="reset" button type="submit"
-

27. dropdown

-

28. option

-

29. select

- -

30. fieldset

-

legend

- -

31. input

+

27. dropdown

+
28. option
+29. select
+
+

30. fieldset

+
legend
+
+

31. input

input type="checkbox"
 input type="date"
 input type="radio"
@@ -74,36 +61,112 @@ 

31. input

input type="time" input type="upload"
-

32. textarea

-

33. media

-

34. audio

-

35. image

-

36. video

-

37. scenario

-

38. script

-

39. style

-

40. table

-

41. cell

-

42. column

-

43. row

-

44. timeline

-

45. end-year

-

46. start-year

- - -

CONTRIBUTE

+

32. textarea

+

33. media

+

https://example.com/image.png

+

34. audio

+

35. image

+

36. video

+

37. scenario

+

38. script

+

39. style

+

40. table

+

41. cell

+

42. column

+

43. row

+

44. timeline

+

2024: Company adopts remote-first policy.

+

45. end-year

+

46. start-year

+

47. glossary

+

48. word

+

markup

+

49. definition

+

A system of tags that structure meaning.

+

50. synonym

+

tagging

+

51. antonym

+

plaintext

+

52. origin

+

From Middle English marken, "to note or record."

+

53. usage

+

Authors use markup to describe documents without prescribing presentation.

+

Crossword grid

+

crossword-grid

+

A rectangular crossword; its value is columns x rows.

+

across / down

+

Directional groups containing word, first-letters, and word-lengths.

+

word

+

Comma-separated crossword answers when nested under across or down (also used for glossary entries).

+

first-letters

+

Comma-separated starting (row,column) grid squares.

+

word-lengths

+

Comma-separated answer lengths.

+

across-clues / down-clues

+

Clues in the same order as the corresponding directional words.

+

See the crossword schema for an example and validation rules.

+

Ebook

+

ebook

+

Book root with a required content section. output selects HTML or plain-text compilation; mode controls optional style and script inclusion.

+

metadata

+

Bibliographic fields: title, subtitle, author, language, description, date, publisher, rights.

+

cover

+

Optional image and caption.

+

toc

+

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.

+

See the creative-work schema for field rules and complete examples.

+

CURRENT TOTAL: 95 OFFICIAL TAGS

+
+

CONTRIBUTE

Have an issue? GET IN TOUCH.

Have an idea for a tag we should add? SUBMIT A TAG here.

Do you have a more advanced tag idea? SUBMIT A SCHEMA instead!

- -

SUPPORT

+
+

SUPPORT

Please consider STARRING the GITHUB REPO!

-

Check out the README if you're not sure where to start.

-

You can read the full SPEC here.

+

Check out the README if you're not sure where to start.

+

You can read the full SPEC here.

Try the PARSER!


- - -
- - +

TAGS

+

Check out a list of PROPOSED TAGS.

+

Looking for the SHORTHAND version?

+

Curious about how the tags can be used together? Find out here ---> DEPENDENCIES.

+

Did you know that you can use the tag CHAPTER instead of SECTION, if you want? SYNONYMS make it fine to replace one with the other!

+

#tags #semantic #markup #official #current #data-structure #lists

+
diff --git a/export/FILES/index.html b/export/FILES/index.html index b883e1f..349fb1a 100644 --- a/export/FILES/index.html +++ b/export/FILES/index.html @@ -142,6 +142,27 @@ #preview-output .mml-survey input[type="text"], #preview-output .mml-survey textarea { display: block; width: 100%; box-sizing: border-box; padding: .5rem; } #preview-output .mml-survey textarea { min-height: 6rem; } + #preview-output :is(film, song, album, book, series, episode, game, podcast) { + display: block; margin: 1rem 0; padding: 1rem; + border: 3px solid var(--black); box-shadow: 4px 4px 0 var(--purple); + } + #preview-output :is(film, song, album, book, series, episode, game, podcast) > * { display: block; margin: .35rem 0; } + #preview-output :is(film, song, album, book, series, episode, game, podcast) > title { font-size: 1.3rem; font-weight: bold; } + #preview-output song > album { padding: 0; border: 0; box-shadow: none; } + #preview-output director::before { content: "Director: "; font-weight: bold; } + #preview-output artist::before { content: "Artist: "; font-weight: bold; } + #preview-output creator::before { content: "Creator: "; font-weight: bold; } + #preview-output book > author::before { content: "Author: "; font-weight: bold; } + #preview-output :is(book, game) > publisher::before { content: "Publisher: "; font-weight: bold; } + #preview-output song > album::before { content: "Album: "; font-weight: bold; } + #preview-output release-year::before { content: "Released: "; font-weight: bold; } + #preview-output genre::before { content: "Genre: "; font-weight: bold; } + #preview-output series > start-year::before { content: "Started: "; font-weight: bold; } + #preview-output series > end-year::before { content: "Ended: "; font-weight: bold; } + #preview-output season-number::before { content: "Season: "; font-weight: bold; } + #preview-output episode-number::before { content: "Episode: "; font-weight: bold; } + #preview-output episode > date::before { content: "Date: "; font-weight: bold; } + #preview-output ebook { display: block; max-width: 48rem; margin: 0 auto; padding: 1.5rem; background: #fff; color: #222; font-family: Georgia, serif; } #preview-output ebook metadata { display: block; margin-bottom: 1.5rem; } #preview-output ebook metadata title { display: block; font-size: 1.8rem; font-weight: bold; } @@ -236,6 +257,7 @@

Semantic Markup Parser

+ @@ -349,6 +371,19 @@

Semantic Markup Parser

question id="notes" type="long-text" prompt "Anything else you want to tell us?"`; + const FILM_EXAMPLE = `film +title +The Menu +director +Mark Mylod +release-year +2022 +genre +dark-comedy +genre +horror +/film`; + sourceEl.value = EXAMPLE; function updatePreview(html, valid) { @@ -408,6 +443,10 @@

Semantic Markup Parser

sourceEl.value = EBOOK_EXAMPLE; run(); }); + document.getElementById("film-btn").addEventListener("click", () => { + sourceEl.value = FILM_EXAMPLE; + run(); + }); document.getElementById("survey-btn").addEventListener("click", () => { sourceEl.value = SURVEY_EXAMPLE; run(); diff --git a/export/src/compiler.js b/export/src/compiler.js index ff01fdd..4dedd19 100644 --- a/export/src/compiler.js +++ b/export/src/compiler.js @@ -1,3 +1,4 @@ +import { WORK_TYPES } from "./work-schema.js"; import { surveyQuestions } from "./survey-schema.js"; import { readCrossword, crosswordEntries } from "./crossword-schema.js"; /** @@ -299,6 +300,18 @@ function compileNode(node, depth, options = {}) { /** @type {string[]} */ const lines = []; + // Like ebook metadata, scalar fields compile directly to text. In particular, + // HTML title is a raw-text element and must not contain literal markup. + if (WORK_TYPES.includes(node.name)) { + lines.push(`${indent}<${node.name}${formatAttributes(node.attributes)}>`); + for (const child of node.children) { + if (child.type !== "element") continue; + lines.push(`${indent} <${child.name}${formatAttributes(child.attributes)}>${escapeText(textContent(child))}`); + } + lines.push(`${indent}`); + return lines.join("\n"); + } + if (node.name === "survey") return compileSurvey(node, depth); if (node.name === "crossword-grid") { diff --git a/export/src/grammar.js b/export/src/grammar.js index 6224fd4..c541ce5 100644 --- a/export/src/grammar.js +++ b/export/src/grammar.js @@ -1,3 +1,5 @@ +import { WORK_TYPES, WORK_FIELD_PARENTS } from "./work-schema.js"; + /** * Modular Markup Language — Grammar (v0.1) * @@ -26,6 +28,14 @@ /** @readonly — canonical names from DOCS/TAGS.md */ export const CANONICAL_ELEMENTS = new Set([ + ...WORK_TYPES, + "director", + "artist", + "creator", + "release-year", + "genre", + "season-number", + "episode-number", "argument", "calendar", "survey", @@ -242,6 +252,13 @@ export const REQUIRED_PARENTS = { paragraph: ["content", "section"], }; +// Extend existing ebook/timeline fields rather than replacing their parent rules. +for (const [field, parents] of Object.entries(WORK_FIELD_PARENTS)) { + // album can also be an independent record with its own title and artist. + if (WORK_TYPES.includes(field)) continue; + REQUIRED_PARENTS[field] = [...(REQUIRED_PARENTS[field] ?? []), ...parents]; +} + const ELEMENT_NAME_PATTERN = /^[a-z][a-z0-9-]*$/; const ATTR_PAIR_PATTERN = /([a-z][a-z0-9-]*)="([^"]*)"/y; diff --git a/export/src/index.js b/export/src/index.js index f276088..8b08656 100644 --- a/export/src/index.js +++ b/export/src/index.js @@ -1,3 +1,4 @@ +export { WORK_TYPES, WORK_FIELDS, WORK_FIELD_PARENTS, validateWork } from "./work-schema.js"; export { CANONICAL_ELEMENTS, ELEMENT_ALIASES, diff --git a/export/src/parser.js b/export/src/parser.js index 033e15b..e70ad90 100644 --- a/export/src/parser.js +++ b/export/src/parser.js @@ -1,3 +1,4 @@ +import { WORK_TYPES, WORK_FIELDS } from "./work-schema.js"; import { matchOpeningTag, matchClosingTag, @@ -68,6 +69,21 @@ function createText(value, line) { function closeBeforeOpening(stack, newTagName, lastContentTarget) { if (stack.length <= 1) return; + // An album inside a song is a scalar field, not an album record. + if (stack.at(-1)?.name === "album" && stack.at(-2)?.name === "song") stack.pop(); + + // Different work types are sibling entries. The sole field/type overlap is + // song -> album; close /song explicitly when starting a separate album record. + if (WORK_TYPES.includes(newTagName)) { + let workIndex = -1; + for (let i = stack.length - 1; i > 0; i--) { + if (WORK_TYPES.includes(stack[i].name)) { workIndex = i; break; } + } + if (workIndex > 0 && !WORK_FIELDS[stack[workIndex].name].includes(newTagName)) { + stack.length = workIndex; + } + } + const requiredParents = getRequiredParents(newTagName); let top = stack[stack.length - 1]; @@ -170,6 +186,15 @@ export function parse(source) { continue; } + // A container closer may finish its final scalar field, so /film works + // immediately after a genre value without requiring /genre first. + if (WORK_TYPES.includes(closing.name) && stack.length > 2 && + stack.at(-2).name === closing.name && + WORK_FIELDS[closing.name].includes(stack.at(-1).name) && + stack.at(-1).children.every(child => child.type === "text")) { + stack.pop(); + } + const current = stack[stack.length - 1]; if (current.name !== closing.name) { errors.push({ diff --git a/export/src/validator.js b/export/src/validator.js index 10a2e3c..77992d7 100644 --- a/export/src/validator.js +++ b/export/src/validator.js @@ -1,3 +1,4 @@ +import { WORK_TYPES, WORK_FIELD_PARENTS, validateWork } from "./work-schema.js"; import { validateSurvey } from "./survey-schema.js"; import { validateCrossword } from "./crossword-schema.js"; /** @@ -213,6 +214,21 @@ function walkNode(node, parent, errors) { function validateElement(node, parent, errors) { const parentName = parent?.name ?? null; + if (WORK_TYPES.includes(node.name) && !(node.name === "album" && parentName === "song")) { + errors.push(...validateWork(node)); + } + + // Shared fields retain their established ebook, event, and timeline behavior. + const workOnlyFields = ["director", "artist", "creator", "release-year", "genre", "season-number", "episode-number"]; + if (workOnlyFields.includes(node.name) && !WORK_FIELD_PARENTS[node.name].includes(parentName)) { + const parents = WORK_FIELD_PARENTS[node.name]; + errors.push({ + code: "MISSING_REQUIRED_PARENT", element: node.name, line: node.line, + requiredParent: parents.join(" or "), suggestedParentChain: [parents[0]], + message: `${node.name} requires parent ${parents.join(" or ")}`, + }); + } + switch (node.name) { case "evidence": if (parentName !== "claim" && parentName !== "argument") { @@ -229,14 +245,14 @@ function validateElement(node, parent, errors) { case "start-year": case "end-year": - if (parentName !== "timeline") { + if (parentName !== "timeline" && parentName !== "series") { errors.push({ code: "MISSING_REQUIRED_PARENT", element: node.name, - requiredParent: "timeline", + requiredParent: "timeline or series", suggestedParentChain: ["timeline"], line: node.line, - message: `${node.name} requires parent timeline`, + message: `${node.name} requires parent timeline or series`, }); } break; @@ -256,14 +272,14 @@ function validateElement(node, parent, errors) { break; case "date": - if (parentName !== "event" && parentName !== "metadata") { + if (parentName !== "event" && parentName !== "metadata" && parentName !== "episode") { errors.push({ code: "MISSING_REQUIRED_PARENT", element: "date", requiredParent: "event", suggestedParentChain: ["event"], line: node.line, - message: "date requires parent event or metadata", + message: "date requires parent event, metadata, or episode", }); } break; diff --git a/export/src/work-schema.js b/export/src/work-schema.js new file mode 100644 index 0000000..01b208d --- /dev/null +++ b/export/src/work-schema.js @@ -0,0 +1,71 @@ +/** Descriptive records for creative works, separate from ebook content/export. */ +const COMMON_FIELDS = ["title", "description", "release-year", "genre"]; + +export const WORK_FIELDS = { + film: [...COMMON_FIELDS, "director"], + song: [...COMMON_FIELDS, "artist", "album"], + album: [...COMMON_FIELDS, "artist"], + book: [...COMMON_FIELDS, "author", "publisher"], + series: [...COMMON_FIELDS, "creator", "start-year", "end-year"], + episode: [...COMMON_FIELDS, "season-number", "episode-number", "date"], + game: [...COMMON_FIELDS, "creator", "publisher"], + podcast: [...COMMON_FIELDS, "creator"], +}; + +export const WORK_TYPES = Object.keys(WORK_FIELDS); + +/** Used by parser boundaries as well as validation to keep field rules in sync. */ +export const WORK_FIELD_PARENTS = {}; +for (const [type, fields] of Object.entries(WORK_FIELDS)) { + for (const field of fields) (WORK_FIELD_PARENTS[field] ??= []).push(type); +} + +const SINGLE_FIELDS = new Set([ + "title", "description", "release-year", "start-year", "end-year", + "season-number", "episode-number", "date", "album", +]); + +export function validateWork(node) { + const errors = []; + const add = (code, message, target = node) => errors.push({ + code, message, element: target.name, line: target.line, + }); + const elements = node.children.filter(child => child.type === "element"); + const values = {}; + for (const child of node.children) { + if (child.type === "text") { + add("INVALID_WORK_CHILD", `${node.name} uses named fields; put its name inside title`); + continue; + } + if (!WORK_FIELDS[node.name].includes(child.name)) { + add("INVALID_WORK_CHILD", `${child.name} is not allowed inside ${node.name}`, child); + continue; + } + const value = child.children.filter(item => item.type === "text").map(item => item.value.trim()).join("\n"); + if (!value || child.children.some(item => item.type === "element")) { + add("INVALID_WORK_FIELD", `${child.name} requires a nonempty text value, without child elements`, child); + } + (values[child.name] ??= []).push(value); + if (["release-year", "start-year", "end-year"].includes(child.name) && !/^\d{4}$/.test(value)) { + add("INVALID_WORK_YEAR", `${child.name} must be a four-digit year`, child); + } + if (["season-number", "episode-number"].includes(child.name) && + (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || + Number(value) < (child.name === "season-number" ? 0 : 1))) { + add("INVALID_WORK_NUMBER", `${child.name} must be ${child.name === "season-number" ? "a nonnegative" : "a positive"} integer`, child); + } + } + if (!elements.some(child => child.name === "title")) { + add("MISSING_REQUIRED_CHILD", `${node.name} requires title`); + } + for (const [name, entries] of Object.entries(values)) { + if (SINGLE_FIELDS.has(name) && entries.length > 1) { + add("DUPLICATE_WORK_FIELD", `${node.name} allows only one ${name}`); + } + } + const start = values["start-year"]?.[0], end = values["end-year"]?.[0]; + if (/^\d{4}$/.test(start ?? "") && /^\d{4}$/.test(end ?? "") && Number(start) > Number(end)) { + add("INVALID_WORK_RANGE", "series start-year must not be after end-year"); + } + return errors; +} diff --git a/tests/run-tests.js b/tests/run-tests.js index cd4fffd..72b2939 100644 --- a/tests/run-tests.js +++ b/tests/run-tests.js @@ -1,1037 +1,1037 @@ -import { parse } from "../export/src/parser.js"; -import { validate, validateAll } from "../export/src/validator.js"; -import { compile } from "../export/src/compiler.js"; -import { processSource } from "../export/src/index.js"; -import { - generateEbookToc, - prepareEbookHeadings, - collectHeadings, -} from "../export/src/ebook.js"; - -/** @typedef {{ name: string, fn: () => void }} TestCase */ - -/** @type {TestCase[]} */ -const tests = []; - -function test(name, fn) { - tests.push({ name, fn }); -} - -function assertEqual(actual, expected, message = "") { - const a = JSON.stringify(actual); - const e = JSON.stringify(expected); - if (a !== e) { - throw new Error(`${message}\nExpected: ${e}\nActual: ${a}`); - } -} - -function assertTrue(value, message = "") { - if (!value) throw new Error(message || "Expected true"); -} - -function assertFalse(value, message = "") { - if (value) throw new Error(message || "Expected false"); -} - -function assertIncludes(haystack, needle, message = "") { - if (!haystack.includes(needle)) { - throw new Error(`${message}\nExpected to include: ${needle}\nIn: ${haystack}`); - } -} - -function assertMatch(value, pattern, message = "") { - if (!pattern.test(value)) { - throw new Error(`${message}\nExpected ${value} to match ${pattern}`); - } -} - -function findElement(ast, name) { - if (!ast) return null; - if (ast.type === "element" && ast.name === name) return ast; - if (ast.type !== "element") return null; - for (const child of ast.children) { - const found = findElement(child, name); - if (found) return found; - } - return null; -} - -// --- Test cases --- - -test("opening-tag-only argument / claim / evidence (user example)", () => { - const source = `argument -claim -Dogs are better companions. -evidence -Loki.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertTrue(validation.valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, "Dogs are better companions."); - assertIncludes(html, ""); - assertIncludes(html, "Loki."); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); -}); - -test("valid argument / claim / evidence", () => { - const source = `argument -claim -Markdown introduces an unnecessary abstraction layer. -evidence -The final rendered output is already HTML.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertTrue(validation.valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, "Markdown introduces an unnecessary abstraction layer."); - assertIncludes(html, ""); - assertIncludes(html, "The final rendered output is already HTML."); -}); - -test("evidence without claim", () => { - const source = `evidence -The final output is HTML.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "MISSING_REQUIRED_PARENT"); - assertEqual(validation.errors[0].element, "evidence"); - assertEqual(validation.errors[0].requiredParent, "claim"); - assertEqual(validation.errors[0].suggestedParentChain, ["argument", "claim"]); -}); - -test("valid glossary / word / definition", () => { - const source = `glossary -word -markup -definition -A system of tags that structure meaning. -synonym -tagging -antonym -plaintext -origin -From Middle English marken. -usage -Authors use markup to describe documents. -word -schema -definition -A structured set of related tags.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertTrue(validation.valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, "A system of tags that structure meaning."); - assertIncludes(html, "A structured set of related tags."); - assertIncludes(html, ""); -}); - -test("word without glossary", () => { - const source = `word -markup -definition -A system of tags.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "MISSING_REQUIRED_PARENT"); - assertEqual(validation.errors[0].element, "word"); - assertEqual(validation.errors[0].requiredParent, "glossary"); -}); - -test("glossary without word", () => { - const source = `glossary -Empty glossary.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "MISSING_REQUIRED_CHILD"); - assertEqual(validation.errors[0].element, "glossary"); - assertEqual(validation.errors[0].requiredChild, "word"); -}); - -test("word without definition", () => { - const source = `glossary -word -markup -synonym -tagging`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertTrue( - validation.errors.some( - (e) => e.code === "MISSING_REQUIRED_CHILD" && e.element === "word" && e.requiredChild === "definition" - ) - ); -}); - -test("definition without word", () => { - const source = `definition -A system of tags.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "MISSING_REQUIRED_PARENT"); - assertEqual(validation.errors[0].element, "definition"); - assertEqual(validation.errors[0].requiredParent, "word"); - assertEqual(validation.errors[0].suggestedParentChain, ["glossary", "word"]); -}); - -test("glossary shorthand aliases", () => { - const source = `glo -word -markup -def -A system of tags. -syn -tagging -ant -plaintext -ori -Middle English. -usag -Used in documents.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertTrue(validation.valid); - - assertTrue(findElement(ast, "glossary") != null); - assertTrue(findElement(ast, "definition") != null); - assertTrue(findElement(ast, "synonym") != null); - assertTrue(findElement(ast, "antonym") != null); - assertTrue(findElement(ast, "origin") != null); - assertTrue(findElement(ast, "usage") != null); -}); - -test("closing tags are optional not required", () => { - const withoutClosers = `argument -claim -Dogs are better companions. -evidence -Loki.`; - - const withClosers = `argument -claim -Dogs are better companions. -/claim -evidence -Loki.`; - - const withoutResult = parse(withoutClosers); - const withResult = parse(withClosers); - assertEqual(withoutResult.errors, []); - assertEqual(withResult.errors, []); - assertTrue(validate(withoutResult.ast).valid); - assertTrue(validate(withResult.ast).valid); -}); - -test("mismatched optional closing tag", () => { - const source = `argument -claim -Text. -/argument`; - - const { errors } = parse(source); - const mismatch = errors.find((e) => e.code === "MISMATCHED_CLOSE"); - assertTrue(mismatch != null, "Expected MISMATCHED_CLOSE error"); -}); - -test("standalone claim", () => { - const source = `claim -Markdown is unnecessary.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const claim = findElement(ast, "claim"); - assertTrue(claim != null); - assertEqual(claim.children[0], { - type: "text", - value: "Markdown is unnecessary.", - line: 2, - }); -}); - -test("timeline with year-start and year-end only", () => { - const source = `timeline -year-start -2020 -year-end -2024`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("timeline with events", () => { - const source = `timeline -year-start -2020 -event -date -2021-06-01 -Launch day. -year-end -2024`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("timeline with spaced end year alias", () => { - const source = `timeline -start-year -2000 -event -date -09-14-2001 -end year -2015`; - - const result = processSource(source); - assertTrue(result.valid); - assertIncludes(result.html, ""); - assertIncludes(result.html, "2015"); -}); - -test("timeline event date outside range", () => { - const source = `timeline -year-start -2000 -event -date -09-14-1945 -year-end -2015`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "TIMELINE_EVENT_OUT_OF_RANGE"); - assertIncludes(validation.errors[0].message, "1945"); - assertIncludes(validation.errors[0].message, "2000"); - assertIncludes(validation.errors[0].message, "2015"); -}); - -test("calendar with year-month", () => { - const source = `calendar - year-month - 2024-03`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("calendar compiles to month table with highlighted event day", () => { - const source = `calendar -year -2018 -month -8 -event -date -22`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, ''); - assertIncludes(html, ""); - assertIncludes(html, 'class="mml-event-day"'); - assertIncludes(html, ">22"); -}); - -test("calendar event day outside month range", () => { - const source = `calendar -year -2018 -month -2 -event -date -30`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "CALENDAR_EVENT_OUT_OF_RANGE"); -}); - -test("comparison before/after schema", () => { - const source = `comparison - before - Old approach. - after - New approach.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("comparison entity / shared / unique schema", () => { - const source = `comparison -entity -unique -Alpha only. -entity -unique -Beta only. -shared -Common ground.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("comparison scenario / condition schema", () => { - const source = `comparison - scenario - condition - If A happens. - scenario - condition - If B happens.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("valid group entity trait example from GIF", () => { - const source = `group -entity -trait -human -trait -male -entity -trait -human -trait -female`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, ""); - assertIncludes(html, "human"); - assertIncludes(html, "male"); - assertIncludes(html, "female"); - assertIncludes(html, ""); -}); - -test("invalid group with only one entity", () => { - const source = `group -entity -trait -human -trait -male`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "INVALID_GROUP_SCHEMA"); - assertIncludes(validation.errors[0].message, "at least two entity children"); -}); - -test("invalid group without shared trait value", () => { - const source = `group -entity -trait -human -trait -male -entity -trait -canine -trait -female`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "INVALID_GROUP_SCHEMA"); - assertIncludes(validation.errors[0].message, "sharing a common trait value"); -}); - -test("trait without entity parent", () => { - const source = `trait -human`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertEqual(validation.errors[0].code, "MISSING_REQUIRED_PARENT"); - assertEqual(validation.errors[0].element, "trait"); -}); - -test("group shorthand alias grp", () => { - const source = `grp -entity -trait -human -entity -trait -human`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - assertTrue(findElement(ast, "group") != null); -}); - -test("media with image and caption", () => { - const source = `media - image - /photo.png - caption - A sample photo.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); -}); - -test("reserved words used as normal text", () => { - const source = `claim -Arguments aren't always unhealthy.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const claim = findElement(ast, "claim"); - assertIncludes(claim.children[0].value, "Arguments aren't always unhealthy."); -}); - -test("section title attribute", () => { - const source = `section title="Background" -Some content.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const section = findElement(ast, "section"); - assertEqual(section.attributes.title, "Background"); - - const html = compile(ast); - assertIncludes(html, '
'); - assertIncludes(html, "Background"); -}); - -test("title attribute line is plain text inside section", () => { - const source = `section -title="Background"`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const section = findElement(ast, "section"); - assertEqual(Object.keys(section.attributes).length, 0); - assertEqual(section.children[0].value, 'title="Background"'); -}); - -test("malformed attribute line is text not tag", () => { - const source = `section -section title=Background`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const section = findElement(ast, "section"); - assertEqual(section.children[0].value, "section title=Background"); -}); - -test("non-reserved word line is text", () => { - const source = `claim -hello`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const claim = findElement(ast, "claim"); - assertEqual(claim.children[0].value, "hello"); -}); - -test("processSource returns empty html when invalid", () => { - const result = processSource(`evidence -x`); - assertFalse(result.valid); - assertEqual(result.html, ""); - assertMatch(result.validationErrors[0].message, /requires parent claim/); -}); - -test("legacy year-start alias normalizes to start-year", () => { - const source = `timeline - year-start - 2020 - year-end - 2024`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - assertTrue(findElement(ast, "start-year") != null); - assertTrue(findElement(ast, "end-year") != null); -}); - -test("legacy year-month alias normalizes to month", () => { - const source = `calendar - year-month - 2024-03`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - assertTrue(findElement(ast, "month") != null); -}); - -test("shorthand tags from SHORTHAND.md", () => { - const source = `arg - claim - evi - Supported.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(findElement(ast, "argument") != null); - assertTrue(findElement(ast, "claim") != null); - assertTrue(findElement(ast, "evidence") != null); -}); - -test("form elements from TAGS.md", () => { - const source = `form action="POST" - fieldset - legend - Name - input type="text" - dropdown - option - A - selection - A - button type="submit" - Submit - para - Notes here.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(findElement(ast, "form") != null); - assertTrue(findElement(ast, "fieldset") != null); - assertTrue(findElement(ast, "dropdown") != null); - assertTrue(findElement(ast, "textarea") != null); -}); - -test("document structure elements from TAGS.md", () => { - const source = `document - section title="Intro" - text - Hello. - list - item - One - footnote - See also.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(findElement(ast, "list") != null); - assertTrue(findElement(ast, "item") != null); - assertTrue(findElement(ast, "footnote") != null); -}); - -test("table elements from TAGS.md", () => { - const source = `table - row - cell - A1 - column - B`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(findElement(ast, "table") != null); - assertTrue(findElement(ast, "row") != null); - assertTrue(findElement(ast, "cell") != null); - assertTrue(findElement(ast, "column") != null); -}); - -test("media shorthand image alias", () => { - const source = `media - img - /photo.png`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - assertTrue(findElement(ast, "image") != null); -}); - -test("implicit close at EOF leaves no unclosed errors", () => { - const source = `argument - claim - Nested content.`; - - const { errors } = parse(source); - assertEqual(errors, []); - assertFalse(errors.some((e) => e.code === "UNCLOSED_TAG")); -}); - -test("sibling tags share parent when prior tag has content", () => { - const source = `argument -claim -First claim. -claim -Second claim.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const argument = findElement(ast, "argument"); - const claims = argument.children.filter((c) => c.type === "element" && c.name === "claim"); - assertEqual(claims.length, 2); -}); -//here -test("plain text inside claim becomes text node", () => { - const source = `claim -Markdown is unnecessary.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, "Markdown is unnecessary."); - assertIncludes(html, ""); -}); - -test("plain text inside evidence becomes text node", () => { - const source = `argument -claim -Remote work saves time. -evidence -Employees avoid daily commuting.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const html = compile(ast); - assertIncludes(html, ""); - assertIncludes(html, "Employees avoid daily commuting."); - assertIncludes(html, ""); -}); - -test("plain text inside caption becomes text node", () => { - const source = `media -image -/photo.png -caption -System architecture overview.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - - const html = compile(ast); - assertIncludes(html, "
"); -}); - -test("ordinary text is not parsed as a tag", () => { - const source = `claim -This is just plain text, not a tag.`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - - const html = compile(ast); - assertIncludes(html, "This is just plain text, not a tag."); - assertFalse(html.includes(" { - const { ast, errors } = parse(EXAMPLE_EBOOK); - assertEqual(errors, []); - const validation = validate(ast); - assertTrue(validation.valid, validation.errors.map((e) => e.message).join("; ")); - - const ebook = findElement(ast, "ebook"); - assertTrue(ebook != null); - assertTrue(findElement(ast, "metadata") != null); - assertTrue(findElement(ast, "cover") != null); - assertTrue(findElement(ast, "toc") != null); - assertTrue(findElement(ast, "content") != null); - - const title = findElement(ast, "title"); - assertTrue(title != null); - assertIncludes( - title.children.find((c) => c.type === "text")?.value ?? "", - "Proof I Was Here" - ); -}); - -test("valid ebook with only content", () => { - const source = `ebook -content - heading level="1" "Only Chapter" - paragraph "Body text."`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - assertTrue(validate(ast).valid); - assertTrue(findElement(ast, "content") != null); -}); - -test("TOC generated from heading order", () => { - const { ast } = parse(EXAMPLE_EBOOK); - const ebook = findElement(ast, "ebook"); - const toc = generateEbookToc(ebook); - const labels = []; - - /** @param {import("../export/src/ebook.js").TocNode[]} nodes */ - function flatten(nodes) { - for (const node of nodes) { - labels.push(node.label); - flatten(node.children); - } - } - flatten(toc); - - assertEqual(labels, [ - "Chapter One", - "A Smaller Room", - "Chapter Two", - ]); -}); - -test("nested TOC generated from heading levels", () => { - const { ast } = parse(EXAMPLE_EBOOK); - const ebook = findElement(ast, "ebook"); - const toc = generateEbookToc(ebook); - - assertEqual(toc.length, 2); - assertEqual(toc[0].label, "Chapter One"); - assertEqual(toc[0].children.length, 1); - assertEqual(toc[0].children[0].label, "A Smaller Room"); - assertEqual(toc[1].label, "Chapter Two"); - assertEqual(toc[1].children.length, 0); -}); - -test("heading IDs generated when missing", () => { - const { ast } = parse(EXAMPLE_EBOOK); - const ebook = findElement(ast, "ebook"); - const content = findElement(ast, "content"); - prepareEbookHeadings(ebook); - - const headings = collectHeadings(content); - assertEqual(headings.length, 3); - assertEqual(headings[0].node.attributes.id, "chapter-one"); - assertEqual(headings[1].node.attributes.id, "a-smaller-room"); - assertEqual(headings[2].node.attributes.id, "chapter-two"); -}); - -test("invalid ebook missing required content", () => { - const source = `ebook -metadata - title "No Body"`; - - const { ast, errors } = parse(source); - assertEqual(errors, []); - const validation = validate(ast); - assertFalse(validation.valid); - assertTrue( - validation.errors.some((e) => e.code === "MISSING_REQUIRED_CHILD" && e.element === "ebook") - ); -}); - -test("plain-text export ignores style and javascript", () => { - const { ast } = parse(EXAMPLE_EBOOK); - const output = compile(ast, { format: "plain-text" }); - - assertIncludes(output, "title: Proof I Was Here"); - assertIncludes(output, "Chapter One"); - assertFalse(output.includes("
August 2018"); - assertIncludes(html, "System architecture overview."); - assertIncludes(html, "