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

+
-

REQUIRES

+

REQUIRES

-
-

AS A CHILD OF ---> IS ONLY VALID ---> WHEN MULTIPLES EXIST

+

AS A CHILD OF ---> IS ONLY VALID ---> WHEN MULTIPLES EXIST


-

PAIRS & SETS ---> CANNOT EXIST OUTSIDE OF

+

PAIRS & SETS ---> CANNOT EXIST OUTSIDE OF


-

CANNOT EXIST OUTSIDE OF

+

CANNOT EXIST OUTSIDE OF


-

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

-
- - +

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..1979fdf 100644 --- a/tests/run-tests.js +++ b/tests/run-tests.js @@ -1084,6 +1084,206 @@ prompt "Your name?"`); assertIncludes(result.html, ''); }); +// --- Creative-work records --- + +test("film example keeps repeated genres and credits as sibling fields", () => { + const result = processSource(`film +title +The Menu +director +Mark Mylod +director +Another Director +release-year +2022 +genre +dark-comedy +genre +horror +/film`); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + const film = result.ast.children[0]; + assertEqual(film.name, "film"); + assertEqual(film.children.map(child => child.name), ["title", "director", "director", "release-year", "genre", "genre"]); + assertEqual(film.children[0].children[0].value, "The Menu"); + assertEqual(film.children.at(-1).children[0].value, "horror"); + assertIncludes(result.html, "2022"); + assertEqual((result.html.match(//g) ?? []).length, 2); +}); + +test("all work types parse, validate, and compile as consecutive sibling records", () => { + const entries = [ + ["film", 'director "Director"'], + ["song", 'artist "Artist"\nalbum "Album Name"'], + ["book", 'author "Author"\npublisher "Publisher"'], + ["series", 'creator "Creator"\nstart-year "2020"'], + ["episode", 'season-number "0"\nepisode-number "1"\ndate "2022-11-18"'], + ["album", 'artist "Artist"'], + ["game", 'creator "Creator"\npublisher "Publisher"'], + ["podcast", 'creator "Creator"'], + ]; + const result = processSource(entries.map(([type, fields]) => `${type}\ntitle "Example ${type}"\n${fields}\nrelease-year "2022"\ngenre "Example"\ndescription "A description"`).join("\n")); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + assertEqual(result.ast.children.map(child => child.name), entries.map(([type]) => type)); + for (const [type] of entries) { + assertIncludes(result.html, `<${type}>`); + assertIncludes(result.html, ``); + } +}); + +test("same-type works stay siblings with multiline values and no closers", () => { + const result = processSource(`film +title +First Movie +genre +horror +film +title +Second Movie +genre +comedy`); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + assertEqual(result.ast.children.map(child => child.name), ["film", "film"]); +}); + +test("song album field stays scalar and later fields belong to song", () => { + const result = processSource(`song +title +Song Name +artist +Artist Name +album +Album Name +release-year +1996 +genre +alternative`); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + const song = result.ast.children[0]; + assertEqual(song.children.map(child => child.name), ["title", "artist", "album", "release-year", "genre"]); + assertEqual(song.children[2].children[0].value, "Album Name"); +}); + +test("explicit song closer permits a standalone album record", () => { + const result = processSource(`song +title "Song Name" +album "Album Name" +/song +album +title "Album Name" +artist "Artist Name" +/album`); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + assertEqual(result.ast.children.map(child => child.name), ["song", "album"]); +}); + +test("work container closer finishes a final scalar field; mismatched closers still fail", () => { + for (const source of ['film\ntitle\nThe Menu\n/film', 'film\ntitle\nThe Menu\n/title\n/film']) { + assertTrue(processSource(source).valid, source); + } + assertFalse(processSource('film\ntitle\nThe Menu\n/book').valid); + assertFalse(processSource('film\ntitle\nThe Menu\n/director').valid); +}); + +test("work records need exactly one nonempty title and named fields", () => { + for (const source of ["film", 'film\nThe Menu', 'film\ntitle ""', 'film\ntitle "First"\ntitle "Second"']) { + assertFalse(processSource(source).valid, source); + } +}); + +test("work validation rejects blank fields, wrong field parents, and invalid child elements", () => { + for (const source of [ + 'film\ntitle "The Menu"\ndirector ""', + 'film\ntitle "The Menu"\nrelease-year ""', + 'director "Someone"', 'genre "horror"', 'release-year "2022"', + 'book\ntitle "Book Name"\ndirector "Someone"', + 'film\ntitle "The Menu"\ncreator "Someone"', + 'episode\ntitle "Pilot"\nartist "Someone"', + 'film\ntitle "The Menu"\nlist\nitem "An unrelated child"', + ]) assertFalse(processSource(source).valid, source); +}); + +test("work fields accept only text, even when validating an AST directly", () => { + const { ast } = parse('film\ntitle "The Menu"\ndirector "Mark Mylod"'); + findElement(ast, "director").children.push({ type: "element", name: "section", attributes: {}, children: [], line: 4 }); + assertTrue(validate(ast).errors.some(error => error.code === "INVALID_WORK_FIELD")); +}); + +test("work years use four digits and series ranges may be open-ended", () => { + for (const year of ["22", "2022-01-01", "2022x", "unknown", "2022.0"]) { + assertFalse(processSource(`film\ntitle "Film Name"\nrelease-year "${year}"`).valid, year); + } + for (const fields of ['start-year "2020"', 'end-year "2022"', 'start-year "2020"\nend-year "2022"']) { + assertTrue(processSource(`series\ntitle "Series Name"\n${fields}`).valid, fields); + } + assertFalse(processSource('series\ntitle "Series Name"\nstart-year "2022"\nend-year "2020"').valid); +}); + +test("episode numbers reject negative, fractional, and zero episode values", () => { + for (const fields of ['season-number "-1"', 'season-number "1.5"', 'episode-number "0"', 'episode-number "1x"']) { + assertFalse(processSource(`episode\ntitle "Pilot"\n${fields}`).valid, fields); + } +}); + +test("repeated credits are allowed but duplicate scalar fields are rejected", () => { + const valid = processSource('book\ntitle "Book Name"\nauthor "First Author"\nauthor "Second Author"\npublisher "First Publisher"\npublisher "Second Publisher"'); + assertTrue(valid.valid, JSON.stringify(valid.validationErrors)); + for (const fields of ['release-year "2022"\nrelease-year "2023"', 'description "One"\ndescription "Two"']) { + assertTrue(processSource(`film\ntitle "The Menu"\n${fields}`).validationErrors.some(error => error.code === "DUPLICATE_WORK_FIELD")); + } +}); + +test("work compilation preserves semantic tags and escapes field text", () => { + const result = processSource('book\ntitle "A < B & C"\nauthor "A & B"'); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + assertIncludes(result.html, ""); + assertIncludes(result.html, "A < B & C"); + assertIncludes(result.html, "A & B"); +}); + +test("book records and ebook metadata keep independent nesting rules", () => { + const source = `book +title "Book Name" +author "Author Name" +publisher "Publisher Name" +/book +ebook +metadata +title "Ebook Title" +author "Ebook Author" +publisher "Ebook Publisher" +date "2022-11-18" +content +paragraph "Actual ebook content"`; + const { ast, errors } = parse(source); + assertTrue(validateAll(errors, ast).valid, JSON.stringify(validateAll(errors, ast).errors)); + assertEqual(ast.children.map(child => child.name), ["book", "ebook"]); + assertEqual(findElement(ast, "metadata").children.map(child => child.name), ["title", "author", "publisher", "date"]); + assertIncludes(compile(ast.children[0]), ""); + assertIncludes(compile(ast.children[1]), "Actual ebook content"); +}); + +test("series year and episode date additions preserve timeline and event behavior", () => { + const source = `series +title "Series Name" +start-year "2020" +end-year "2022" +/series +episode +title "Pilot" +date "2020-01-01" +/episode +timeline +start-year "2020" +end-year "2022" +event +date "2021-01-01"`; + const result = processSource(source); + assertTrue(result.valid, JSON.stringify(result.validationErrors)); + assertEqual(result.ast.children.map(child => child.name), ["series", "episode", "timeline"]); + assertFalse(processSource('timeline\nstart-year "2020"\nend-year "2022"\nevent\ndate "2023-01-01"').valid); +}); + // --- Runner --- let passed = 0;