` is a number ranging from 1 to 6, representing each of the six TOC entry levels.
+
+### `body`
+
+Default body text, for example `` elements.
+
+### `chapter`
+
+Chapter title.
+
+- `title-numbering: 'true' | 'false'`
+
+### `chapter-toc`
+
+Chapter table of contents.
+
+- `maximum-level: ` — Number of TOC levels to show
+
+### `chapter-toc-`
+
+TOC entry in chapter TOC. `` is a number ranging from 1 to 6, representing each of the six TOC entry levels.
+
+### `codeblock`
+
+Code block element.
+
+- `line-numbering: 'true' | 'false'` — Line numbering.
+- `show-whitespace: 'true' | 'false'` — Show whitespace characters.
+
+### `cover`
+
+Cover page.
+
+### `cover-title`
+
+Cover page title.
+
+- `content: content-template`
+
+### `cover-titlealt`
+
+Cover page subtitle or alternative title.
+
+### `dl`
+
+Definition list element.
+
+- `dl-type: 'table' | 'list' | 'html'` — Style definition list as bulleted list or indented list.
+
+### `example`
+
+Example element.
+
+### `example-title`
+
+Example element title.
+
+### `fig`
+
+Figure element.
+
+- `caption-number: 'chapter' | 'document'` — Number figures with chapter prefix or use whole document numbering.
+- `caption-position: 'before' | 'after'` — Place figure caption before or after figure.
+
+### `fig-caption`
+
+Figure caption.
+
+- `content`: Contents of figure caption. Supported fields are:
+ - `number`: caption number
+ - `title`: caption contents
+
+### `glossary`
+
+Glossary title.
+
+### `h`
+
+Topic titles. `` is a number ranging from 1 to 6, representing each of the six heading levels.
+
+- `title-numbering: 'true' | 'false'`
+
+### `hazardstatement`
+
+Hazard statement element.
+
+### `hazardstatement-label`
+
+Hazard statement label element.
+
+### `hazardstatement--label`
+
+Label for hazard statement elements with `@type`.
+
+### `index`
+
+Index title.
+
+### `note`
+
+Note element with `@type` `note` or without `@type`.
+
+### `note-label`
+
+Label for note elements.
+
+- `content` — Content template.
+
+### `note-`
+
+Note element with `@type`. Type values are:
+
+- `note`
+- `tip`
+- `fastpath`
+- `restriction`
+- `important`
+- `remember`
+- `attention`
+- `caution`
+- `notice`
+- `danger`
+- `warning`
+- `trouble`
+- `other`
+
+To add an image to a note, use the `background-image` property.
+
+```yaml
+style:
+ note-other:
+ background-image: legal.svg
+ background-repeat: no-repeat
+ # image width plus padding
+ padding-start: 60pt + 1em
+ # image width plus parent indentation
+ start-indent: 60pt + from-parent(start-indent)
+```
+
+### `note--label`
+
+Label for note elements with `@type`.
+
+- `content` — Content template.
+
+### `ol`
+
+Ordered list.
+
+### `parml`
+
+Parameter list element.
+
+### `part`
+
+Part title.
+
+- `title-numbering: 'true' | 'false'`
+
+### `part-toc`
+
+Part table of contents.
+
+- `maximum-level: ` — Number of TOC levels to show
+
+### `part-toc-chapter`
+
+Bookmap chapter TOC entry in part TOC.
+
+### `part-toc-`
+
+TOC entry in part TOC. `` is a number ranging from 1 to 6, representing each of the six TOC entry levels.
+
+### `pd`
+
+Parameter definition element within a parameter list entry.
+
+### `plentry`
+
+Parameter list entry element.
+
+### `pre`
+
+Preformatted element.
+
+### `pt`
+
+Parameter term element within a parameter list entry.
+
+### `section`
+
+Section element.
+
+### `section-title`
+
+Section element title.
+
+### `shortdesc`
+
+Short description and abstract styles.
+
+### `table`
+
+Table element.
+
+- `caption-number: 'chapter' | 'document'` — Number figures with chapter prefix or use whole document numbering.
+- `caption-position: 'before' | 'after'` — Place figure caption before or after figure.
+- `table-continued: 'true' | 'false'` — Output "table continued" when table breaks across pages.
+
+### `table-caption`
+
+Table caption.
+
+- `content: content-template` — Contents of table caption. Supported fields are:
+ - `number`: caption number
+ - `title`: caption contents
+
+### `table-header`
+
+Table header row
+
+### `task-labels`
+
+Boolean key to generate default section labels for tasks.
+
+### `toc`
+
+Table of contents.
+
+- `maximum-level: ` — Number of TOC levels to show
+
+### `toc-appendix`
+
+Bookmap appendix TOC entry.
+
+### `toc-chapter`
+
+Bookmap chapter TOC entry.
+
+### `toc-part`
+
+Bookmap part TOC entry.
+
+### `toc-`
+
+TOC entry in main TOC. `` is a number ranging from 1 to 6, representing each of the six TOC entry levels.
+
+### `ul`
+
+Unordered list.
+
+[XSL fo:block]: https://www.w3.org/TR/xsl11/#fo_block
+[XSL extensions]: ./Styles.md#xsl-fo-extension-properties
diff --git a/resources/theme/Extending-themes.md b/resources/theme/Extending-themes.md
index b9c137691..88deec488 100644
--- a/resources/theme/Extending-themes.md
+++ b/resources/theme/Extending-themes.md
@@ -1,4 +1,6 @@
-A theme can extend another theme using the `extends` key. The value of `extends` is a relative path from the current theme file to the theme being extended.
+A theme can extend another theme using the `extends` key.
+
+If the value is `default`, it resolves to the built-in default theme. Otherwise the value of `extends` is a relative path from the current theme file to the theme being extended. If a theme doesn't have an `extends` key, default PDF2 plug-in styles are used.
`base.yaml`
diff --git a/resources/theme/Header-and-footer.md b/resources/theme/Header-and-footer.md
index 0626c5245..c8172a9f9 100644
--- a/resources/theme/Header-and-footer.md
+++ b/resources/theme/Header-and-footer.md
@@ -2,29 +2,139 @@ The `content` key in `header` or `footer` can be used to add text to running hea
The following variable fields are currently supported:
-- `title`: Map title
-- `chapter`: Map chapter title
-- `folio`: current page number
-- `folio-with-total`: current page number with total number of pages
-- `page-number`: current page number
-- `page-count`: total number of pages
-- `year`: current year
+- `{title}`: Map title
+- `{chapter-or-part-or-appendix}`: Map chapter, part, or appendix number and title
+- `{chapter}`: Map chapter number and title
+- `{chapter-title}`: Map chapter title
+- `{chapter-number}`: Map chapter number
+- `{part}`: Map part number and title
+- `{part-title}`: Map part title
+- `{part-number}`: Map part number
+- `{appendix}`: Map appendix number and title
+- `{appendix-title}`: Map appendix title
+- `{appendix-number}`: Map appendix number
+- `{folio}`: Current page number
+- `{folio-with-total}`: Current page number with total number of pages
+- `{page-number}`: Current page number
+- `{page-count}`: Total number of pages
+- `{year}`: Current year
```yaml
header:
content: '{title} — {chapter}'
- border-after: solid 1pt black
+ border-bottom: solid 1pt black
```
+## Header and footer size and alignment
+
+To adjust the placement of page headers and footers, define the [Page settings](Page-settings.md) and use the `extent` and `display-align` keys.
+
+```yaml
+page:
+ size: A4
+ # The body content starts 30 mm from top of page edge.
+ top: 30mm
+ outside: 20mm
+ # The body content ends 30 mm from bottom of page edge.
+ bottom: 30mm
+ inside: 20mm
+header:
+ content: '{title}'
+ # The header starts directly from top of page edge and is 20 mm high.
+ extent: 20mm
+ # The header starts 20 mm from start/left of page edge
+ start-indent: 20mm
+ # The header content is vertically aligned to bottom of header.
+ display-align: after
+footer:
+ content: '{folio-with-total}'
+ # The footer starts directly from bottom of page edge and is 20 mm high.
+ extent: 20mm
+ # The footer starts 20 mm from start/left of page edge
+ start-indent: 20mm
+ # The footer content is vertically aligned to top of footer.
+ display-align: before
+```
+
+If `extent` is not set, the value defaults to page `top` for header and page `bottom` for footer.
+
+## Simple header and footer
+
+The same headers and footers can be used on all pages.
+
+```yaml
+header:
+ content: '{title}'
+ start-indent: 10mm
+ end-indent: 10mm
+ border-bottom: solid 1pt black
+ text-align: center
+footer:
+ content: '{folio-with-total}'
+ start-indent: 10mm
+ end-indent: 10mm
+ border-top: solid 1pt black
+ text-align: center
+```
+
+
+
+## Duplex header and footer
+
To define separate headers or footers for recto (right) and verso (left) pages, use the `odd` and `even` keys.
```yaml
+# Generate duplex header and footer
+mirror-page-margins: true
header:
- border-after: solid 1pt black
+ start-indent: 10mm
+ end-indent: 10mm
+ padding-after: 6pt
+ border-bottom: solid 1pt black
odd:
content: '{title}'
+ # On odd/right/recto pages, horizontally align content to end/right side.
text-align: end
even:
content: '{chapter}'
+ # On even/left/verso pages, horizontally align content to start/left side.
+ text-align: start
+footer:
+ start-indent: 10mm
+ end-indent: 10mm
+ padding-after: 6pt
+ border-bottom: solid 1pt black
+ odd:
+ content: '{folio-with-total}'
+ text-align: end
+ even:
+ content: '{folio-with-total}'
text-align: start
```
+
+ 
+
+## Header image
+
+To add an image to page headers, use the `background-image` key and adjust the placement via `padding`, `space-before`, `start-indent`, etc.
+
+```yaml
+header:
+ content: 'DITA-OT'
+ # Text starts 25 mm from left page edge.
+ start-indent: 25mm
+ # Header starts 10 mm from top page edge.
+ space-before: 10mm
+ # Header height is 10 mm
+ line-height: 10mm
+ # Image left edge is 15 mm from left text edge (10 mm from left page edge)
+ padding-left: 15mm
+ text-align: start
+ font-family: Helvetica
+ dominant-baseline: middle
+ # 10 mm x 10 mm image
+ background-image: dita-ot-logo.svg
+ background-repeat: no-repeat
+```
+
+
diff --git a/resources/theme/How-to.md b/resources/theme/How-to.md
deleted file mode 100644
index d08fd5380..000000000
--- a/resources/theme/How-to.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Configure header and footer
-
-Examples of theme files.
-
-## Page size
-
-```yaml
-page:
- size: A4
- top: 20mm
- outside: 20mm
- bottom: 20mm
- inside: 20mm
-```
-
-## Simple header and footer
-
-```yaml
-header:
- content: '{title}'
- start-indent: 10mm
- end-indent: 10mm
- border-bottom: solid 1pt black
- text-align: center
-footer:
- content: '{folio-with-total}'
- start-indent: 10mm
- end-indent: 10mm
- border-top: solid 1pt black
- text-align: center
-```
-
-
-
-## Header and footer size and alignment
-
-```yaml
-page:
- size: A4
- # The body content starts 30 mm from top of page edge.
- top: 30mm
- outside: 20mm
- # The body content ends 30 mm from bottom of page edge.
- bottom: 30mm
- inside: 20mm
-header:
- content: '{title}'
- # The header starts directly from top of page edge and is 20 mm high.
- extent: 20mm
- # The header starts 20 mm from start/left of page edge
- start-indent: 20mm
- # The header content is vertically aligned to bottom of header.
- display-align: after
-footer:
- content: '{folio-with-total}'
- # The footer starts directly from bottom of page edge and is 20 mm high.
- extent: 20mm
- # The footer starts 20 mm from start/left of page edge
- start-indent: 20mm
- # The footer content is vertically aligned to top of footer.
- display-align: before
-```
-
-If `extent` is not set, the value defaults to page `top` for header and page `bottom` for footer.
-
-## Duplex header and footer
-
-```yaml
-# Generate duplex header and footer
-mirror-page-margins: true
-header:
- start-indent: 10mm
- end-indent: 10mm
- padding-after: 6pt
- border-bottom: solid 1pt black
- odd:
- content: '{title}'
- # On odd/right/recto pages, horizontally align content to end/right side.
- text-align: end
- even:
- content: '{chapter}'
- # On even/left/verso pages, horizontally align content to start/left side.
- text-align: start
-footer:
- start-indent: 10mm
- end-indent: 10mm
- padding-after: 6pt
- border-bottom: solid 1pt black
- odd:
- content: '{folio-with-total}'
- text-align: end
- even:
- content: '{folio-with-total}'
- text-align: start
-```
-
- 
-
-## Header image
-
-```yaml
-header:
- content: 'DITA-OT'
- # Text starts 25 mm from left page edge.
- start-indent: 25mm
- # Header starts 10 mm from top page edge.
- space-before: 10mm
- # Header height is 10 mm
- line-height: 10mm
- # Image left edge is 15 mm from left text edge (10 mm from left page edge)
- padding-left: 15mm
- text-align: start
- font-family: Helvetica
- dominant-baseline: middle
- # 10 mm x 10 mm image
- background-image: dita-ot-logo.svg
- background-repeat: no-repeat
-```
-
-
diff --git a/resources/theme/Inline-styles.md b/resources/theme/Inline-styles.md
new file mode 100644
index 000000000..bbbc33753
--- /dev/null
+++ b/resources/theme/Inline-styles.md
@@ -0,0 +1,224 @@
+The presentation of inline elements can be adjusted by setting `style` keys. Inline keys support styling properties from [XSL fo:inline] and [XSL extensions].
+
+## Inline keys
+
+### `apiname`
+
+API name element.
+
+### `b`
+
+Bold highlighting element.
+
+### `cmdname`
+
+Comment name element.
+
+### `codeph`
+
+Code phrase element.
+
+### `delim`
+
+Syntax delimiter character element.
+
+### `filepath`
+
+File path element.
+
+### `fragment`
+
+Syntax fragment element.
+
+### `fragref`
+
+Syntax fragment reference element.
+
+### `groupchoice`
+
+Group choice element.
+
+### `groupcomp`
+
+Group composite element.
+
+### `groupseq`
+
+Group sequence element.
+
+### `i`
+
+Italic highlighting element.
+
+### `keyword`
+
+Keyword element.
+
+### `kwd`
+
+Syntax keyword element.
+
+### `line-through`
+
+Strikethrough highlighting element.
+
+### `link`
+
+Link elements.
+
+- `link-url: 'true' | 'false'` — Output URL for external links after explicitly defined link text. Defaults to `false`.
+- `link-page-number: 'true' | 'false'` — Generate page number reference after link text. Defaults to `true`.
+- `content: content-template` — Link text template. Supported fields are:
+ - `link-text`: link text
+ - `pagenum`: page number reference
+
+### `link-external`
+
+External link elements.
+
+- `content: content-template` — Link text template. Supported fields are:
+ - `link-text`: link text
+ - `url`: link URL
+
+### `markupname`
+
+Named markup token element.
+
+### `menucascade`
+
+Menu cascade element used to document a series of menu choices.
+
+- `separator-content: content-template` — Separator between **uicontrol** elements, defaults to “`>`”.
+
+### `numcharref`
+
+XML character reference element.
+
+### `oper`
+
+Syntax operator element.
+
+### `option`
+
+Option element.
+
+### `overline`
+
+Overline highlighting element.
+
+### `parameterentity`
+
+XML parameter entity element.
+
+### `parmname`
+
+Parameter name element.
+
+### `repsep`
+
+Syntax repeat separator character element.
+
+### `screen`
+
+Screen element.
+
+### `sep`
+
+Syntax separator character element.
+
+### `shortcut`
+
+Keyboard shortcut element.
+
+### `sub`
+
+Subscript highlighting element.
+
+### `sup`
+
+Superscript highlighting element.
+
+### `synblk`
+
+Syntax block element.
+
+### `synnote`
+
+Syntax note element.
+
+### `synnoteref`
+
+Syntax note reference element.
+
+### `synph`
+
+Syntax phrase element.
+
+### `syntaxdiagram`
+
+Syntax diagram element.
+
+### `systemoutput`
+
+System output element.
+
+### `term`
+
+Term element.
+
+### `textentity`
+
+XML text entity element.
+
+### `tm`
+
+Trademark element.
+
+- `symbol-scope: 'always' | 'chapter' | 'never'` — Output trademark symbol always, once per chapter, or never.
+
+### `tt`
+
+Teletype highlighting element.
+
+### `u`
+
+Underline highlighting element.
+
+### `uicontrol`
+
+User interface control element.
+
+### `userinput`
+
+User input element.
+
+### `var`
+
+Syntax variable element.
+
+### `varname`
+
+Variable name element.
+
+### `wintitle`
+
+Window or dialog title element.
+
+### `xmlatt`
+
+XML attribute element.
+
+### `xmlelement`
+
+XML element element.
+
+### `xmlnsname`
+
+XML namespace name element.
+
+### `xmlpi`
+
+XML processing instruction element.
+
+[XSL fo:inline]: https://www.w3.org/TR/xsl11/#fo_inline
+[XSL extensions]: ./Styles.md#xsl-fo-extension-properties
diff --git a/resources/theme/Styles.md b/resources/theme/Styles.md
index 6b1ed4489..30b8ed476 100644
--- a/resources/theme/Styles.md
+++ b/resources/theme/Styles.md
@@ -1,13 +1,11 @@
-The presentation of various block and inline elements can be adjusted by setting `style` keys. Each category takes XSL-FO key definitions and keys specific to that style.
+The presentation of various [block](./Block-styles.md) and [inline](./Inline-styles.md) elements can be adjusted by setting `style` keys. Each category takes XSL-FO key definitions and keys specific to that style.
While the style keys may look like CSS, the keys are XSL-FO properties and the underlying PDF2 plug-in does not use CSS compatibility properties.
- Instead of `padding-top`, use `padding-before`.
- Instead of `margin-left`, use `start-indent`. Note that these two keys do not have matching semantics, see [XSL 1.1][refine-margin-space-indent].
-[refine-margin-space-indent]: https://www.w3.org/TR/xsl11/#refine-margin-space-indent
-
-There is no default theme that defines base key values. Instead, a theme extends the PDF2 default styling. If you want to define common settings, create a theme file for shared settings, and use the [`extends` key](#extending-themes) in other themes to build on the common foundation.
+The built-in `default` theme defines base key values that extend the PDF2 default styling. To define common settings of your own, create a theme file for shared settings, and use the [`extends` key](./Extending-themes.md) in other themes to build on the common foundation.
```yaml
style:
@@ -25,604 +23,10 @@ style:
text-decoration: underline
```
-## Block keys
-
-### `body`
-
-Default body text, for example `` elements.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `shortdesc`
-
-Shortdesc and abstract styles.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `h1`
-
-First-level topic titles.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `title-numbering = boolean`
-
-### `h2`
-
-Second-level topic titles.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `title-numbering = boolean`
-
-### `h3`
-
-Third-level topic titles.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `title-numbering = boolean`
-
-### `h4`
-
-Fourth-level topic titles.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `title-numbering = boolean`
-
-### `cover`
-
-Cover page.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `cover-title`
-
-Cover page title.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `content = content-template`
-
-### `cover-titlealt`
-
-Cover page subtitle or alternative title.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `section`
-
-Section element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `section-title`
-
-Section element title.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `dl`
-
-Definition list element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `dl-type = 'table' | 'list' | 'html'` — Style definition list as bulleted list or indented list.
-
-### `example`
-
-Example element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `example-title`
-
-Example element title.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `fig`
-
-Figure element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `caption-number = 'chapter' | 'document'` — Number figures with chapter prefix or use whole document numbering.
-- `caption-position = 'before' | 'after'` — Place figure caption before or after figure.
-
-### `fig-caption`
-
-Figure caption.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `content`: Contents of figure caption. Supported fields are:
- - `number`: caption number
- - `title`: caption contents
-
-### `note`
-
-Note element with `@type` `note` or without `@type`.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `note-label`
-
-Label for note elements.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-- `content` — Content template.
-
-### `note-`
-
-Note element with `@type`. Type values are:
-
-- `note`
-- `tip`
-- `fastpath`
-- `restriction`
-- `important`
-- `remember`
-- `attention`
-- `caution`
-- `notice`
-- `danger`
-- `warning`
-- `trouble`
-- `other`
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `note--label`
-
-Label for note elements with `@type`.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-- `content` — Content template.
-
-### `ol`
-
-Ordered list.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `ul`
-
-Unordered list.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `pre`
-
-Preformatted element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `codeblock`
-
-Code block element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `line-numbering = boolean` — Line numbering.
-- `show-whitespace = boolean` — Show whitespace characters.
-
-### `table`
-
-Table element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `caption-number = 'chapter' | 'document'` — Number figures with chapter prefix or use whole document numbering.
-- `caption-position = 'before' | 'after'` — Place figure caption before or after figure.
-- `table-continued = boolean` — Output "table continued" when table breaks across pages.
-
-### `table-caption`
-
-Table caption.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-- `content = content-template` — Contents of table caption. Supported fields are:
- - `number`: caption number
- - `title`: caption contents
-
-### `table-header`
-
-Table header row
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `toc-1`
-
-First-level TOC entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `toc-2`
-
-Second-level TOC entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `toc-3`
-
-Third-level TOC entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `toc-4`
-
-Fourth-level TOC entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `parml`
-
-Parameter list element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `plentry`
-
-Parameter list entry element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `pt`
-
-Parameter term element within a parameter list entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `pd`
-
-Parameter definition element within a parameter list entry.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `hazardstatement`
-
-Hazard statement element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `hazardstatement-label`
-
-Hazard statement label element.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-### `hazardstatement--label`
-
-Label for hazard statement elements with `@type`.
-
-The styling properties that can be used are listed in [XSL fo:block](https://www.w3.org/TR/xsl11/#fo_block).
-
-## Inline keys
-
-### `link`
-
-Link elements.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-- `link-url = 'true' | 'false'` — Output URL for external links after explicitly defined link text. Defaults to `false`.
-- `link-page-number = 'true' | 'false'` — Generate page number reference after link text. Defaults to `true`.
-- `content = content-template` — Link text template. Supported fields are:
- - `link-text`: link text
- - `pagenum`: page number reference
-
-### `link-external`
-
-External link elements.
-
-- `content = content-template` — Link text template. Supported fields are:
- - `link-text`: link text
- - `url`: link URL
-
-### `tm`
-
-Trademark element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-- `symbol-scope = 'always' | 'chapter' | 'never'` — Output trademark symbol always, once per chapter, or never.
-
-### `keyword`
-
-Keyword element.
+## XSL-FO extension properties
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
+In addition to the block and inline styles, themes support XSL-FO extension properties implemented by XSL formatters:
-### `term`
+- `background-size: [ | | auto ]{1,2}` — Size of background image.
-Term element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `codeph`
-
-Code phrase element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `filepath`
-
-File path element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `cmdname`
-
-Comment name element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `varname`
-
-Variable name element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `userinput`
-
-User input element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `systemoutput`
-
-System output element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `apiname`
-
-API name element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `option`
-
-Option element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `parmname`
-
-Parameter name element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `synph`
-
-Syntax phrase element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `syntaxdiagram`
-
-Syntax diagram element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `groupseq`
-
-Group sequence element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `groupchoice`
-
-Group choice element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `groupcomp`
-
-Group composite element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `fragment`
-
-Syntax fragment element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `fragref`
-
-Syntax fragment reference element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `synblk`
-
-Syntax block element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `synnote`
-
-Syntax note element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `synnoteref`
-
-Syntax note reference element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `kwd`
-
-Syntax keyword element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `var`
-
-Syntax variable element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `oper`
-
-Syntax operator element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `delim`
-
-Syntax delimiter character element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `sep`
-
-Syntax separator character element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `repsep`
-
-Syntax repeat separator character element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `b`
-
-Bold highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `i`
-
-Italic highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `u`
-
-Underline highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `tt`
-
-Teletype highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `sup`
-
-Superscript highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `sub`
-
-Subscript highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `line-through`
-
-Strikethrough highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `overline`
-
-Overline highlighting element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `markupname`
-
-Named markup token element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `uicontrol`
-
-User interface control element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `wintitle`
-
-Window or dialog title element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `menucascade`
-
-Menu cascade element used to document a series of menu choices.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `shortcut`
-
-Keyboard shortcut element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `screen`
-
-Screen element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `filepath`
-
-File path element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `xmlelement`
-
-XML element element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `xmlatt`
-
-XML attribute element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `textentity`
-
-XML text entity element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `parameterentity`
-
-XML parameter entity element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `numcharref`
-
-XML character reference element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `xmlnsname`
-
-XML namespace name element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
-
-### `xmlpi`
-
-XML processing instruction element.
-
-The styling properties that can be used are listed in [XSL fo:inline](https://www.w3.org/TR/xsl11/#fo_inline).
+[refine-margin-space-indent]: https://www.w3.org/TR/xsl11/#refine-margin-space-indent
diff --git a/resources/theme/Syntactic-sugar.md b/resources/theme/Syntactic-sugar.md
index f8314aa68..dda2267a8 100644
--- a/resources/theme/Syntactic-sugar.md
+++ b/resources/theme/Syntactic-sugar.md
@@ -69,7 +69,7 @@ header:
## Topic titles
-Style keys `h1`, `h2`, `h3`, and `h4` are desugared to `topic`, `topic-topic`, `topic-topic-topic`, and `topic-topic-topic-topic`, respectively.
+Style keys `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` are desugared to `topic`, `topic-topic`, `topic-topic-topic`, `topic-topic-topic-topic`, `topic-topic-topic-topic-topic`, and `topic-topic-topic-topic-topic-topic`, respectively.
```yaml
style:
diff --git a/resources/theme/Theme.md b/resources/theme/Theme.md
index 18bb06f1a..bc88f9bd4 100644
--- a/resources/theme/Theme.md
+++ b/resources/theme/Theme.md
@@ -36,5 +36,7 @@ style:
color: gray
```
+Keys can be divided and nested wherever a hyphen (`-`) appears in the name. For example, the key `page-size` can be expressed as the `size` key under the `page` category key. This nested structure is for organizational purposes and not required. All keys are flatted when the theme is loaded.
+
[json]: https://json.org
[yaml]: https://yaml.org
diff --git a/resources/theme/Variables.md b/resources/theme/Variables.md
index 51968fa3b..becbd2956 100644
--- a/resources/theme/Variables.md
+++ b/resources/theme/Variables.md
@@ -1,6 +1,6 @@
Theme key values can use variables to reference settings in other keys. Any previously defined key can be referenced in the value of another key.
-Variable references are text values that start with a dollar sign (`$`). Variable declarations are normal keys where the name of the key is a concatenated value of flattened key names separated with a hyphen.
+Variable references are text values that start with a dollar sign (`$`). Variable declarations are normal keys where the name of the key is a concatenated value of flattened key names separated with a hyphen (`-`).
The example below shows how to set a custom color value and header font, and point to those values in `style` keys.
diff --git a/topics/pdf-themes.ditamap b/topics/pdf-themes.ditamap
index 9c81183b0..e89dcf801 100644
--- a/topics/pdf-themes.ditamap
+++ b/topics/pdf-themes.ditamap
@@ -7,7 +7,10 @@
-
+
+
+
+