Skip to content
Merged
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
105 changes: 102 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,9 +142,9 @@ All notable changes to this project are documented here. The format follows
---
```

A slide's values are laid over the template's, and the template's over the theme's, and one
value laid over another leaves the rest alone: a slide that names one colour leaves the
other eleven as they were.
A slide's values are laid over the template's, the template's over the deck's and the deck's
over the theme's, and one value laid over another leaves the rest alone: a slide that names
one colour leaves the other eleven as they were.

The four roles the theme has — the page, the ink, the subtle ink and the panel — sit on
**four different slots**, so overriding a slot moves exactly one of them and `dark:` says
Expand Down Expand Up @@ -175,6 +175,105 @@ All notable changes to this project are documented here. The format follows
settings arrived, and a template defined twice is refused rather than left to win
quietly.

- **A deck may name its own settings.** There was no layer for the deck: a deck's frontmatter
is its first slide's, and `theme-variables:` is read per slide, so a deck that named an
accent in its frontmatter painted the first slide in that accent and left every other slide
in the theme's own.

A deck's frontmatter may now carry `deck-settings:`, and every slide of the deck is drawn
with it:

```markdown
---
theme: corporate-dark
deck-settings:
background: "#101014"
theme-variables:
colors:
accent1: "#123456"
---
```

The ordinary keys mean the **slide's** own everywhere, so the deck's settings are named as
the deck's, the way a template's are named as the template's. The precedence is
**slide → template → deck → theme**: a slide's own settings are laid over the template's,
the template's over the deck's and the deck's over the theme's, and one value laid over
another leaves the rest alone.

It belongs in slide 1's front matter, which is the deck's own, and it is refused on any
other slide — the way `theme:` is.

`examples/markdown/20-deck-settings.md` is the deck that shows it: the deck's page and
ink on every slide of it, and the two slides that name a setting of their own — one that
wins over the deck's, and one that leaves the deck's other settings standing.

### Changed

- **A theme is one file.** A theme was a directory of up to five files: `theme.yml` for
the look, `layouts.yml` for the eight layout roles, `text-styles.yml` for the named
text styles, `styles.yml` for the Word half's style slots, and `template.pptx` for the
master. It is now `theme.yml` and the master, with the roles and the named styles as
two sections of the file:

```yaml
name: Acme
layouts:
title: Title Slide
content: Title and Content
textStyles:
brand:
color: accent1
bold: true
```

**What a theme that exists has to do.** Move the contents of `layouts.yml` into a
`layouts:` section of the `theme.yml` beside it, and the contents of `text-styles.yml`
into a `textStyles:` section of it, and delete both files. A `styles.yml` is the Word
half's file and this half does not read it, so it goes.

The three files are **refused** when they are beside a theme, each with a message
saying what the reader has to do with the file:

> The theme "acme" has a "layouts.yml" beside it. A theme is one file: move its content into the "layouts:" section of its "theme.yml", and delete the file.

> The theme "acme" has a "text-styles.yml" beside it. A theme is one file: move its content into the "textStyles:" section of its "theme.yml", and delete the file.

> The theme "acme" has a "styles.yml" beside it. That file is the Word half's, and this half does not read it: its slots name Word styles, which a deck of slides has no use for. Delete it, and the theme is read again.

They are refused rather than ignored, because **a file that is quietly not read is a
theme that looks like the one its author wrote and is not**: the author renames a
layout in the file beside the theme, the deck is drawn with the old mapping, and
nothing in the output says so.

- **The library ships the default layout mapping.** All five themes that ship with the
library carried a byte-identical `layouts.yml` — the same eight Office names — so for
a theme without a master it was a default written out five times. A theme with no
`layouts:` section is drawn with the library's own mapping now:

| Role | Layout |
| --- | --- |
| `title` | Title Slide |
| `content` | Title and Content |
| `two-column` | Two Content |
| `section` | Section Header |
| `blank` | Blank |
| `image-text` | Picture Left |
| `image-title` | Picture with Caption |
| `image-slide` | Full Bleed Picture |

A theme **with** a `layouts:` section has the whole mapping: a role the section does
not name is a role the theme does not map, and the deck that asks for one is told which
roles the theme does map.

The five themes that ship with the library lost their `layouts.yml`, because it was the
library's own mapping written out.

- **The Word half's style slots are gone from this half.** `Theme\StyleSlots`,
`Exception\UnknownStyleSlot` and `LoadedTheme::styles()` existed for a `styles.yml`
this half loaded and never used: the slots name Word styles, and a deck of slides has
no use for them. A theme that carried one looked like a theme with Word styles in it
and was not one.

### Fixed

- **The anchor of a template's placeholder is read and written.** The renderer read a
Expand Down
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,12 +66,12 @@ renders of one deck differ; the parts are what a test reads.
| The theme's twelve colours become the colour scheme | `ppt/theme/theme1.xml` |
| A dark theme swaps the colour map, and its shapes follow it | `ppt/slideMasters/slideMaster1.xml`, `ppt/slides/slideN.xml` |
| The theme's `heading`, `body` and `mono` reach the runs that use them | `<a:latin typeface="…">` |
| `styles.yml` reaches no shape, because a `.pptx` has no use for a `.docx` style id | — |
| A `styles.yml` beside a theme is refused, because a `.pptx` has no use for a `.docx` style id | — |

The last row is the only one asserted by what is *absent*. `styles.yml` is not read, and
a slot that does not exist still fails when the theme is loaded, so a typo in one is never
rendered as silence — which is a test, but a test of the theme loader rather than of a
rendered file.
The last row is the only one asserted by what is *absent*. A `styles.yml` beside a theme is
refused when the theme is loaded, so a theme that carries one is never read as though it had
said nothing — which is a test, but a test of the theme loader rather than of a rendered
file.

Reading has the opposite problem, and it is where the fixtures earn their place. Everything
above is checked against files this library wrote, which agree with the reader about every
Expand Down
Loading
Loading