Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 26 additions & 9 deletions DOCS/DEPENDENCIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -88,20 +88,37 @@ 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 |
| heading | content or section |
| paragraph | content or section |
| | |

## CREATIVE-WORK RECORDS

`film`, `song`, `album`, `book`, `series`, `episode`, `game`, and `podcast` require exactly one nonempty `title`. They have no required parent. Each record accepts optional `description`, `release-year`, and repeated `genre`, plus the following fields:

| Record | Additional children |
| --- | --- |
| film | director |
| song | artist, album (text field) |
| album | artist |
| book | author, publisher |
| series | creator, start-year, end-year |
| episode | season-number, episode-number, date |
| game | creator, publisher |
| podcast | creator |

Fields contain nonempty text only. Credits and genres may repeat; other fields may occur once. Years use four digits, series end-year cannot precede start-year, season-number is nonnegative, and episode-number is positive. Consecutive work records become siblings; close `/song` explicitly before a standalone album record. See [SPEC](SPEC.md#19-creative-work-records).

## CONTEXTUAL VALIDATION

- event ---> **AS A CHILD OF** ---> timeline ---> **MUST HAVE** date **BETWEEN** start-year AND end-year
Expand Down Expand Up @@ -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

---
Expand Down
29 changes: 25 additions & 4 deletions DOCS/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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). |
Expand Down Expand Up @@ -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`):
Expand Down Expand Up @@ -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.

---
Expand Down
112 changes: 112 additions & 0 deletions DOCS/SCHEMA-INDEX.md
Original file line number Diff line number Diff line change
@@ -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.
98 changes: 96 additions & 2 deletions DOCS/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<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:

Expand All @@ -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.

Expand Down
31 changes: 29 additions & 2 deletions DOCS/TAGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
Loading
Loading