add title page and covers examples (PR #2154)

9 files changed, 244 insertions, 124 deletions

diff --git a/docs/modules/theme/nav.adoc b/docs/modules/theme/nav.adoc
index 4d2f6414..d62bd7c9 100644
--- a/docs/modules/theme/nav.adoc
+++ b/docs/modules/theme/nav.adoc
@@ -11,11 +11,14 @@
 *** xref:fallback-font.adoc[]
 *** xref:cjk.adoc[]
 ** xref:blocks.adoc[]
+** xref:block-images.adoc[]
 ** xref:tables.adoc[]
 ** xref:text.adoc[]
 ** xref:images.adoc[]
 ** xref:extend-theme.adoc[]
 ** xref:custom-role.adoc[]
+** xref:covers.adoc[]
+** xref:title-pages.adoc[]
 ** xref:add-running-content.adoc[]
 ** xref:page-numbers.adoc[]
 ** xref:print-and-prepress.adoc[]
@@ -59,15 +62,3 @@
 ** xref:title-page.adoc[]
 ** xref:toc.adoc[]
 ** xref:verse.adoc[]
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/modules/theme/pages/block-images.adoc b/docs/modules/theme/pages/block-images.adoc
new file mode 100644
index 00000000..e8a9e21c
--- /dev/null
+++ b/docs/modules/theme/pages/block-images.adoc
@@ -0,0 +1,37 @@
+= Block Image Styles
+:description: In addition to the general block and caption keys, the theming language provides keys for arranging and styling block images, alt text, and image captions.
+
+You can customize how the block images, alt text, and image captions are arranged and styled using the xref:block-image.adoc[] and the xref:caption.adoc[].
+In general, the xref:blocks.adoc[] and xref:caption.adoc[] apply to block images and their captions.
+You can further customize how the block images, alt text, and image captions are arranged and styled using the xref:block-image.adoc[].
+The following sections provide additional information about the keys that are unique to the block images.
+
+[#end]
+== Caption end
+
+The `caption-end` key specifies whether the image caption is located on top or below the image.
+The key accepts the following keywords:
+
+bottom:: The caption block is placed below the image.
+top:: The caption block is place above the image.
+
+[,yaml]
+----
+image:
+  caption:
+    end: bottom
+----
+
+[#caption-text-align]
+== Caption text alignment
+
+The `caption-text-align` key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `image` category.
+
+[,yaml]
+----
+image:
+  caption:
+    text-align: inherit
+----
+
+The value `inherit` resolves to the block alignment (`image-align`) assigned to the `image` category.
diff --git a/docs/modules/theme/pages/cover.adoc b/docs/modules/theme/pages/cover.adoc
index 7632731d..b7614481 100644
--- a/docs/modules/theme/pages/cover.adoc
+++ b/docs/modules/theme/pages/cover.adoc
@@ -1,26 +1,28 @@
 = Cover Category Keys
+:description: Reference list of the available front and back cover theme keys and their value types.
 :navtitle: Cover
 :source-language: yaml
 
 The keys in the `cover` category control the front and back cover images.
-Currently, the only supported feature is setting an image for each cover face.
-`<face>` is either `front` or `back`.
+See xref:covers.adoc[] for examples and more information.
 
 [cols="3,4,6a"]
 |===
 |Key |Value Type |Example
 
-|<face>-image
-|path, image macro +
+|back-image
+|xref:covers.adoc[image macro] {vbar} xref:covers.adoc[path] +
+(default: _not set_)
+|[source]
+cover:
+  back:
+    image: image:solid-cover.pdf[]
+
+|front-image
+|xref:covers.adoc[image macro] {vbar} xref:covers.adoc[path] +
 (default: _not set_)
 |[source]
 cover:
   front:
     image: image:cover.pdf[page=2]
 |===
-
-When assigning a value to `image` using the image macro, the target of the macro can be an image file or a PDF file.
-A relative path of the target file is resolved relative to the value of the `pdf-themesdir` attribute.
-An image file is handled just like a background image.
-If a PDF file is specified, the first page is used unless another page is specified by the `page` attribute.
-The page from the PDF file will be imported as is.
diff --git a/docs/modules/theme/pages/covers.adoc b/docs/modules/theme/pages/covers.adoc
new file mode 100644
index 00000000..a280500c
--- /dev/null
+++ b/docs/modules/theme/pages/covers.adoc
@@ -0,0 +1,26 @@
+= Covers
+
+== Front and back covers
+
+You can specify an image or import a PDF page for the front cover and back cover of a document directly in your theme.
+The front cover image is assigned using the `front-image` key, and the back cover image using the `back-image` key.
+Both keys are set on the xref:cover.adoc[cover category] and accept either a bare absolute or relative path or a target wrapped in an inline image macro as a value.
+By default, a target file is resolved relative to the value of the `pdf-themesdir` attribute.
+
+[,yaml]
+----
+cover:
+  front:
+    image: image:cover.pdf[page=2]
+  back:
+    image: image:splash.png[fit=fill]
+----
+
+When the value is wrapped in an inline image macro, the target can be the absolute path or relative path to an image file or PDF file.
+See xref:images.adoc#specify[Specify a background image in the theme] for configuring a path that's not relative to `pdf-themesdir`.
+The target can also be a data URI.
+A cover image is handled like a xref:images.adoc#background[background image], and the xref:images.adoc#attributes[fit, width, and position attributes] can be specified.
+
+If a PDF file is assigned to the image macro, the first page of the file is used unless another page is specified by the `page` attribute.
+The PDF page will be imported as is.
+
diff --git a/docs/modules/theme/pages/images.adoc b/docs/modules/theme/pages/images.adoc
index 89ea78a8..5f09f85a 100644
--- a/docs/modules/theme/pages/images.adoc
+++ b/docs/modules/theme/pages/images.adoc
@@ -1,98 +1,121 @@
-= Images
+= Theme Images
+:description: Some category keys allow background, foreground, logo, and category-specific images to be specified directly in the theme.
 
-== Background images
+Some category keys allow background, foreground, and other category-specific images to be specified directly in the theme.
 
 [#formats]
-=== Supported image formats
+== Supported image formats
 
-The following image types (and corresponding file extensions) are supported:
+The theme supports the following image formats:
 
 * PNG (.png)
 * JPEG (.jpg)
 * SVG (.svg)
 
+When specified, the filename of the image must use the file extension that matches its format.
+
 CAUTION: CAUTION: The GIF (.gif), TIFF (.tiff), BMP (.bmp), and interlaced PNG formats are not supported unless you install prawn-gmagick.
 See xref:ROOT:image-paths-and-formats.adoc#other-image-formats[Supporting additional image file formats] for details.
 
-[#specify]
-=== Specify an image in a theme
+[#background]
+== Background images
+
+Several key categories, such as `page`, `title-page`, and the running content `header` and `footer`, allow a background image to be specified directly by the theme with the `background-image` key.
+xref:covers.adoc[Front and back cover images] are handled like background images, too.
 
-An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax.
-Images in the theme file are currently resolved relative to the value of the `pdf-themesdir` attribute.
-(If `pdf-theme` is a path that ends in `.yml`, and `pdf-themesdir` is not set, then the images are resolved relative to the directory of the path specified by `pdf-theme`).
-If you want to use an image in your theme that's relative to the document you're converting, you can prefix the target with the `\{docdir}` attribute reference.
+[#specify]
+=== Specify a background image in the theme
 
-Here's how an image is specified in the theme file as a bare image path:
+In the theme, a background image is specified as a bare image path or as an AsciiDoc inline image macro.
+Here's how a background image is specified in the theme file as a bare path:
 
-[source,yaml]
+[,yaml]
 ----
 title-page:
   background-image: title-cover.png
 ----
 
-Here's how the image is specified using the inline image macro:
+By default, the bare path is resolved relative to the value of the `pdf-themesdir` attribute.
+The path can also be an absolute path.
+
+Here's how the background image is specified using the inline image macro:
 
-[source,yaml]
+[,yaml]
 ----
 title-page:
   background-image: image:title-cover.png[]
 ----
 
-In either case, the image is resolved relative to the value of the `pdf-themesdir` attribute.
+The target of the inline image macro can be a path relative to the `pdf-themesdir` attribute (default), an absolute path, or a data URI.
+If `pdf-theme` is a path that ends in `.yml`, and `pdf-themesdir` is not set, then the images are resolved relative to the directory of the path specified by `pdf-theme`.
 If you want to reference an image relative to the document you're converting, then prefix the target with the `\{docdir}` attribute reference.
 
-[source,yaml]
+[,yaml]
 ----
 title-page:
   background-image: image:{docdir}/images/title-cover.png[]
 ----
 
-[#align]
-=== Width, fit, and alignment
+[#attributes]
+=== Fit, width, and position
 
-Like in the AsciiDoc syntax, wrapping the value in the image macro allows you to specify other settings, such as `pdfwidth`, `fit`, and `align`.
-For example:
+By default, background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
+Wrapping the value in the image macro allows you to customize an image's size and position.
+The size of the image assigned with an image macro can be controlled using the sizing attributes, `fit`, `pdfwidth`, `scaledwidth`, or `width`, when `fit=none`.
+The position of the image can be controlled using the `position` attribute.
 
-[source,yaml]
+[,yaml]
 ----
-title-page:
-  logo-image: image:logo.png[pdfwidth=2.5in,align=center]
+page:
+  background-image: image:page-bg.png[fit=none,position=top center]
 ----
 
-The `align` setting is used to align block images within the parent container.
-See xref:blocks.adoc[] for accepted alignment keywords.
+See xref:ROOT:background-images.adoc[] for the available `fit` and `position` values.
+See xref:ROOT:image-scaling.adoc[] to learn about the sizing attributes the image macro accepts.
+
+[#recto-and-verso]
+=== Recto and verso
+
+The `page` category allows a background image to be set for recto pages (right-hand, odd-numbered pages) and verso pages (left-hand, even-numbered pages).
+The recto background image is specified using `page-background-image-recto` and the verso background image using `page-background-image-verso`.
 
-== Block images
+[,yaml]
+----
+page:
+  background-image:
+    recto: image:page-bg-recto.png[]
+    verso: image:page-bg-verso.png[]
+----
 
-You can customize how the block images, alt text, and image captions are arranged and styled using the xref:block-image.adoc[] and the xref:caption.adoc[].
-The following sections provide information about a few of the theme keys and values that are unique to block images.
+If you define the keys using the flattened structure (e.g., `page-background-image-recto`), you can also set the default page background image (`page-background-image`), which will be used as a fallback if a background image isn't specified for a given side.
 
-[#end]
-=== Caption end
+[,yaml]
+----
+page-background-image: image:page-bg.png[]
+page-background-image-verso: image:verso-bg.png[]
+----
 
-The `caption-end` key specifies whether the image caption is located on top or below the image.
-The key accepts the following keywords:
+=== Deactivate a background image
 
-bottom:: The caption block is placed below the image.
-top:: The caption block is place above the image.
+To deactivate an inherited background image, assign the value `none` to `background-image`.
 
 [,yaml]
 ----
-image:
-  caption:
-    end: bottom
+title-page:
+  background-image: none
 ----
 
-[#caption-text-align]
-=== Caption text alignment
+[#foreground]
+== Foreground images
 
-The `caption-text-align` key accepts the keyword `inherit` in addition to the xref:text.adoc#text-align[usual text alignment values] when it is set on the `image` category.
+In addition to the `background-image` key, the `page` category has a `foreground-image` key.
+The `page-foreground-image` key accepts the same types of values and image macro attributes as `background-image`.
 
 [,yaml]
 ----
-image:
-  caption:
-    text-align: inherit
+page:
+  foreground-image: image:watermark.svg[]
 ----
 
-The value `inherit` resolves to the block alignment (`image-align`) assigned to the `image` category.
+By default, a foreground image is automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
+A foreground image can't be assigned only to recto pages or verso pages.
diff --git a/docs/modules/theme/pages/page.adoc b/docs/modules/theme/pages/page.adoc
index 4cec80a5..64df40f7 100644
--- a/docs/modules/theme/pages/page.adoc
+++ b/docs/modules/theme/pages/page.adoc
@@ -1,15 +1,16 @@
 = Page Category Keys
+:description: Reference list of the available page category keys and their value types.
 :navtitle: Page
 :source-language: yaml
 
 [#page]
 == page
 
-The keys in the `page` category control the size, margins, and background of each page (i.e., canvas).
+The keys in the `page` category control the size, margins, and background of the pages in a document (i.e., canvas).
 We recommended that you define this category before all other categories.
 
 NOTE: The background of the title page can be styled independently of other pages.
-See xref:title-page.adoc[] for details.
+See xref:title-pages.adoc[] and xref:title-page.adoc[] for details.
 
 [cols="3,4,5a"]
 |===
@@ -20,17 +21,17 @@ See xref:title-page.adoc[] for details.
 (default: `'FFFFFF'`)
 |[source]
 page:
-  background-color: #fefefe
+  background-color: #FEFEFE
 
-|<<images,background-image>>
-|image macro +
+|xref:images.adoc#background[background-image]
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 page:
   background-image: image:page-bg.png[]
 
-|<<images,background-image-(recto{vbar}verso)>>
-|image macro +
+|xref:images.adoc#recto-and-verso[background-image-(recto{vbar}verso)]
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 page:
@@ -38,8 +39,8 @@ page:
     recto: image:page-bg-recto.png[]
     verso: image:page-bg-verso.png[]
 
-|<<images,foreground-image>>
-|image macro +
+|xref:images.adoc#foreground[foreground-image]
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 page:
@@ -101,18 +102,6 @@ page:
 To disable the background color for the page, set the value of `background-color` to white (i.e., `#FFFFFF`).
 The color keyword `transparent` is not recognized in this context.
 
-[#images]
-=== Background and foreground images
-
-By default, page background and foreground images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
-The size of the image can be controlled using any of the sizing attributes on the image macro (i.e., `fit`, `pdfwidth`, `scaledwidth`, or `width`) when `fit=none`.
-The position of the image can be controlled using the `position` attribute.
-If the recto (right-hand, odd-numbered pages) or verso (left-hand, even-numbered pages) background image is specified, it will be used only for that side (not available for the foreground image).
-If you define the keys using the flattened structure (e.g., `page-background-image-recto`), you can also set the default page background image (`page-background-image`), which will then be used as a fallback if a background image isn't specified for a given side.
-To disable the image, use the value `none`.
-
-The target of the image macro assigned to the background or foreground image keys may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
-
 [#margins]
 === Inner and outer margins
 
diff --git a/docs/modules/theme/pages/running-content.adoc b/docs/modules/theme/pages/running-content.adoc
index 68587355..7fe445be 100644
--- a/docs/modules/theme/pages/running-content.adoc
+++ b/docs/modules/theme/pages/running-content.adoc
@@ -24,7 +24,7 @@ header:
   background-color: #eeeeee
 
 |background-image
-|image macro +
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 header:
@@ -252,7 +252,7 @@ footer:
   background-color: #eeeeee
 
 |background-image
-|image macro +
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 footer:
diff --git a/docs/modules/theme/pages/title-page.adoc b/docs/modules/theme/pages/title-page.adoc
index 10228b09..1a58b4ca 100644
--- a/docs/modules/theme/pages/title-page.adoc
+++ b/docs/modules/theme/pages/title-page.adoc
@@ -1,33 +1,27 @@
 = Title Page Category Keys
+:description: Reference list of the available title page category keys and their value types.
 :navtitle: Title Page
 :source-language: yaml
 
 [#title-page]
 == title-page
 
-The keys in the `title-page` category control the style of the title page and the arrangement and style of the elements on it.
-
-IMPORTANT: The title page is only enabled by default for the book doctype (e.g., `:doctype: book`).
-If you want to enable the title page when using a different doctype (such as the article doctype), you must define the `title-page` attribute in the document header (i.e., `:title-page:`).
-
-TIP: For documents that declare the book doctype, the title page can be omitted by setting the `notitle` attribute in the AsciiDoc document header (i.e., `:notitle:`) or by setting the value of the `title_page` category key in the theme to `false`.
-(It's counterpart, `:!showtitle:`, does not work with Asciidoctor PDF).
-For all other doctypes, the title page is not added by default.
-In that case, setting the `:notitle:` attribute only removes the document title from the first page of content.
+The keys in the `title-page` category control the title page and the arrangement and style of the elements on it.
+See xref:title-pages.adoc[] for examples and more information.
 
 [cols="3,4,6a"]
 |===
 |Key |Value Type |Example
 
-|<<background-color,background-color>>
+|xref:title-pages.adoc#background-color[background-color]
 |xref:color.adoc[Color] +
 (default: _inherit_)
 |[source]
 title-page:
-  background-color: #eaeaea
+  background-color: #EAEAEA
 
-|<<background-image,background-image>>
-|image macro +
+|xref:title-pages.adoc#background-image[background-image]
+|xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] +
 (default: _not set_)
 |[source]
 title-page:
@@ -88,22 +82,13 @@ title-page:
 |[source]
 title-page:
   text-transform: uppercase
-|===
-
-[#background-color]
-=== background-color
-
-To disable the background color for the title page, set the value of the `background-color` key to white (i.e., `FFFFFF`).
-The color keyword `transparent` is not recognized in this context.
-
-[#background-image]
-=== background-image
 
-By default, page background images are automatically scaled to fit the bounds of the page (i.e., `fit=contain`) and centered (i.e., `position=center`).
-The size of the background image can be controlled using any of the sizing attributes on the image macro (i.e., `fit`, `pdfwidth`, `scaledwidth`, or `width`) when `fit=none`.
-The position of the background image can be controlled using the `position` attribute.
-
-The target of the image macro assigned as a value to the `background-image` key may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
+|title-page
+|flag +
+(default: _set when doctype is book_)
+|[source]
+title-page: false
+|===
 
 [#logo]
 == title-page-logo
@@ -122,8 +107,8 @@ title-page:
   logo:
     align: right
 
-|<<image,image>>
-|image macro +
+|xref:title-pages.adoc#logo-image[image]
+|image macro {vbar} path +
 (default: _not set_)
 |[source]
 title-page:
@@ -144,11 +129,6 @@ title-page:
 
 The `%` unit is relative to content height; `vh` unit is relative to page height.
 
-[#image]
-=== image
-
-The target of the image macro assigned as a value to the `image` key may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
-
 [#title]
 == title-page-title
 
diff --git a/docs/modules/theme/pages/title-pages.adoc b/docs/modules/theme/pages/title-pages.adoc
new file mode 100644
index 00000000..d4fd3013
--- /dev/null
+++ b/docs/modules/theme/pages/title-pages.adoc
@@ -0,0 +1,72 @@
+= Title Page
+:description: The title page layout, background, logo image, and document title, authors, and revision information can be styled from the theme.
+
+The layout, background, and styling of the title page and the title, author, and revision information displayed on it is controlled from the theme using the keys in the `title-page` category.
+
+IMPORTANT: The title page is only enabled by default for the book document type (e.g., `:doctype: book`).
+To enable the title page when using a different doctype, such as the default `article` doctype, you must define the xref:ROOT:title-page.adoc[title-page attribute in the document header].
+
+For the list of all available `title-page` theme keys, see xref:title-page.adoc[].
+
+[#deactivate]
+== Deactivate
+
+The title page can be deactivated from the theme by assigning `false` to the `title-page` category key.
+
+[,yaml]
+----
+title-page: false
+----
+
+You can also xref:ROOT:title-page.adoc#notitle-attribute[deactivate the title page from the document header] using the `notitle` attribute.
+
+[#background-color]
+== Background color
+
+A background color can be applied to the title page with the `background-color` key.
+The key accepts the xref:color.adoc[hex, RGB, and CMYK formats].
+
+[,yaml]
+----
+title-page:
+  background-color: #EAEAEA
+----
+
+To disable the background color for the title page, set the value to white (`#FFFFFF`).
+The color keyword `transparent` isn't recognized in this context.
+
+[,yaml]
+----
+title-page:
+  background-color: #FFFFFF
+----
+
+[#background-image]
+== Background image
+
+You can apply a background image to the title page using the `background-image` key.
+
+[,yaml]
+----
+title-page:
+  background-image: image:title.png[]
+----
+
+For accepted values and attributes, see xref:images.adoc#background[Background images].
+
+[#logo-image]
+== Logo image
+
+The target of the image macro assigned to the `image` key may be a data URI, absolute path, or a path relative to the value of the `pdf-themesdir` attribute.
+Like in the AsciiDoc syntax, wrapping the `image` value in the image macro allows you to specify other settings, including `pdfwidth` and `align`.
+For example:
+
+[,yaml]
+----
+title-page:
+  logo:
+    image: image:logo.png[pdfwidth=2.5in,align=center]
+----
+
+The `align` setting is used to align block images within the parent container.
+See xref:blocks.adoc[] for accepted alignment keywords.