move custom role usage and creation to new pages (PR #2070)

* move custom role usage and creation to new pages
* apply revisions to custom role docs updates
* use the phrase "paragraph and inline phrases" instead of "inline phrases and paragraphs"
* show the definition of a custom role on the page that introduces the concept
* bump the Custom Role entry in the nav under Customize the Theme
* clarify when the lead role is applied and how it is defined by the built-in themes

Co-authored-by: Dan Allen <dan.j.allen@gmail.com>

7 files changed, 164 insertions, 47 deletions

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index eb1f2dcb..87dbc225 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -9,6 +9,7 @@
 * xref:inline-images.adoc[]
 * xref:import-pdf-pages.adoc[]
 * xref:interdocument-xrefs.adoc[]
+* xref:roles.adoc[]
 * xref:verbatim-blocks.adoc[]
 ** xref:syntax-highlighting.adoc[]
 ** xref:autofit-text.adoc[]
diff --git a/docs/modules/ROOT/pages/roles.adoc b/docs/modules/ROOT/pages/roles.adoc
new file mode 100644
index 00000000..5eadf32d
--- /dev/null
+++ b/docs/modules/ROOT/pages/roles.adoc
@@ -0,0 +1,52 @@
+= Roles
+:description: Assign built-in and custom roles to paragraphs and inline phrases.
+
+You can apply the built-in roles Asciidoctor PDF provides as well as custom roles you define in your theme to paragraphs and inline phrases.
+
+== Use a built-in role
+
+The following built-in roles can be assigned to paragraphs and inline phrases:
+
+include::theme:page$role.adoc[tag=user-formatting]
+
+In the example below, the built-in role `big` is applied to an inline phrase.
+
+[,asciidoc]
+----
+The sign spelled out [.big]#WELCOME# in glowing neon lights.
+----
+
+When text is enclosed in a pair of single or double hash symbols (`#`) and has at least one role, the role(s) will be applied to that text without adding any other implicit formatting.
+That is, the text won't be highlighted.
+
+== Use a custom role
+
+NOTE: Before you can use a custom role in your document, you need to define it in your theme.
+See xref:theme:custom-role.adoc[] and xref:theme:role.adoc[] to learn how to create a custom role.
+
+Let's assume you've defined a custom role named `labeled` in your theme.
+
+[,yaml]
+----
+role:
+  labeled:
+    font-color: #0000FF
+----
+
+Now, you can use this role in your documents.
+In the following example, the custom role is assigned to the second paragraph and an inline phrase in the last paragraph.
+
+[,asciidoc]
+----
+== Section title
+
+A paragraph.
+
+[.labeled]
+A paragraph styled according to the custom role assigned to it.
+
+Another paragraph.
+The text [.labeled]#label me# is formatted using the styles of the custom role.
+----
+
+Custom roles only apply to paragraphs and inline phrases.
diff --git a/docs/modules/theme/nav.adoc b/docs/modules/theme/nav.adoc
index a376d179..d4437e9a 100644
--- a/docs/modules/theme/nav.adoc
+++ b/docs/modules/theme/nav.adoc
@@ -13,6 +13,7 @@
 *** xref:fallback-font.adoc[]
 *** xref:cjk.adoc[]
 ** xref:extend-theme.adoc[]
+** xref:custom-role.adoc[]
 ** xref:apply-theme.adoc[]
 ** xref:asciidoc-attributes.adoc[]
 ** xref:page-numbers.adoc[]
diff --git a/docs/modules/theme/pages/color.adoc b/docs/modules/theme/pages/color.adoc
index af907a73..121e46c1 100644
--- a/docs/modules/theme/pages/color.adoc
+++ b/docs/modules/theme/pages/color.adoc
@@ -2,7 +2,7 @@
 
 The theme language supports color values in three formats:
 
-Hex:: A string of 3 or 6 characters with an optional leading `#`, optional surrounding quotes, or both.
+[[hex]]Hex:: A string of 3 or 6 characters with an optional leading `#`, optional surrounding quotes, or both.
 RGB:: An array of numeric values ranging from 0 to 255.
 CMYK:: An array of numeric values ranging from 0 to 1 or from 0% to 100%.
 Transparent:: The special value `transparent` indicates that a color should not be used.
diff --git a/docs/modules/theme/pages/custom-role.adoc b/docs/modules/theme/pages/custom-role.adoc
new file mode 100644
index 00000000..3f1a0b31
--- /dev/null
+++ b/docs/modules/theme/pages/custom-role.adoc
@@ -0,0 +1,75 @@
+= Custom Roles
+:description: Define custom roles in the PDF theme configuration file to apply special formatting to paragraphs and inline phrases.
+
+Use the keys in the `role` category to define custom roles or redefine the built-in roles.
+Custom roles only apply to paragraphs and inline phrases.
+
+== Define a custom role
+
+Custom roles are defined under the `role` category key.
+The name of a custom role may contain a hyphen, but *a role name cannot contain an underscore*.
+
+[,yaml]
+----
+role: <.>
+  rolename: <.>
+    font-color: #ff7f50 <.>
+    font-style: bold
+    text-decoration: underline
+  another-role: <.>
+    border-width: 0.5
+----
+<.> Custom roles are defined under the `role` category key.
+<.> Create a name for your custom role.
+<.> Enter a formatting key and its value on a new line under the name of the role.
+Each key that you want applied to a role should be entered on a new line.
+<.> You can define more than one custom role under the `role` category key.
+Role names can contain hyphens, but not underscores.
+
+The formatting keys that a custom role can accept are listed in xref:role.adoc[].
+Let's look at some custom role definition and usage examples in the next section.
+
+== Custom role examples
+
+In the following example, a custom role named `red` is defined.
+The keys `background-color` and `font-color` are set and each key is assigned a color value using the xref:color.adoc#hex[hex format].
+
+[,yaml]
+----
+role:
+  red:
+    background-color: #333333
+    font-color: #ff0000
+----
+
+You can also use a custom role to unset the default styling of a paragraph or inline phrase and make it inherit the styling of its parent element.
+In the example below, a custom role named `heading-code` is defined and the `font-color` key is unset by assigning a tilde (`~`) as its value.
+
+[,yaml]
+----
+role:
+  heading-code:
+    font-color: ~
+----
+
+In the next example, the `red` and `heading-code` custom roles are assigned to text in a document.
+
+[,asciidoc]
+----
+= Document Title
+
+== Section title
+
+[.red] <.>
+Error text is shown in red.
+
+=== [.heading-code]`SELECT` clause <.>
+
+A paragraph.
+----
+<.> The `red` custom role is assigned to a paragraph.
+<.> The `heading-code` custom role is assigned to an inline phrase marked up with the codespan syntax.
+The code phrase will inherit the font color of the section heading, because the `heading-code` role unsets the font color that would usually be applied to a code phrase.
+However, the phrase `Select` will inherit all the other code phrase styles.
+
+See xref:role.adoc[] for the list of keys a custom role can accept.
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index 9a27c351..6d3539f4 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -1,4 +1,5 @@
 = Role Category Keys
+:description: Asciidoctor PDF provides built-in roles and the ability to define custom roles that can be applied to paragraphs and inline phrases.
 :navtitle: Role
 :source-language: yaml
 
@@ -7,20 +8,10 @@
 
 The keys in the `role` category define custom roles for formatting.
 The name of the role is the first subkey level.
-The role name may contain a hyphen, but *a role name can't contain an underscore*.
+The role name may contain a hyphen, but *a role name cannot contain an underscore*.
 The keys under the role are the theming properties.
 
-IMPORTANT: Custom roles only apply to inline phrases and paragraphs.
-
-The converter provides several predefined roles, which can all be redefined.
-
-* The `lead` defines the font properties for a lead paragraph, whether the role is assign implicitly or explicitly.
-* The `big` and `small` roles map the font size to the `$base-font-size-large` and `$base-font-size-small` values, respectively.
-* The `underline` and `line-through` roles add the underline and strikethrough decorations, respectively.
-* The `subtitle` role is used to configure the font properties of the subtitle of a section title.
-* The `unresolved` role is applied to the text of an unresolved reference (currently footnotes only).
-* The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
-You'll need to define these color roles in your theme if you'd like to make use of them when converting to PDF.
+IMPORTANT: Custom roles only apply to paragraphs and inline phrases.
 
 [cols="3,4,5a"]
 |===
@@ -31,8 +22,8 @@ You'll need to define these color roles in your theme if you'd like to make use
 (default: _not set_)
 |[source]
 role:
-  highlight:
-    background-color: '#ffff00'
+  high-contrast:
+    background-color: #121212
 
 |border-color
 |xref:color.adoc[Color] +
@@ -40,7 +31,7 @@ role:
 |[source]
 role:
   found:
-    border-color: '#cccccc'
+    border-color: #cccccc
 
 |border-offset
 |xref:language.adoc#values[Number] +
@@ -72,7 +63,7 @@ role:
 |[source]
 role:
   red:
-    font-color: '#ff0000'
+    font-color: #ff0000
 
 |font-family
 |xref:font-support.adoc[Font family name] +
@@ -112,7 +103,7 @@ role:
 |[source]
 role:
   deleted:
-    text-decoration-color: '#ff0000'
+    text-decoration-color: #ff0000
 
 |text-decoration-width
 |xref:language.adoc#values[Number] +
@@ -121,38 +112,35 @@ role:
 role:
   underline:
     text-decoration-width: 0.5
-|===
 
-== Define a role
-
-Here's an example of a role for making text red:
-
-[source,yaml]
-----
+|text-transform
+|xref:text.adoc#transform[Text transform] +
+(default: _inherit_)
+|[source]
 role:
-  red:
-    font-color: '#ff0000'
-----
-
-This role can be used as follows:
+  heavy:
+    text-transform: uppercase
+|===
 
-[source,asciidoc]
-----
-Error text is shown in [.red]#red#.
-----
+To learn more about defining a custom role, see xref:custom-role.adoc[].
 
-You can also use a role to unset a font color (to make it inherit):
+== Built-in roles
 
-[source,yaml]
-----
-role:
-  heading-code:
-    font-color: ~
-----
+Asciidoctor PDF provides several predefined roles.
+You can xref:ROOT:roles.adoc[use these roles] when using a built-in theme or a custom theme that extends a built-in theme.
+You can also redefine the built-in roles in your theme configuration file.
 
-This role can be used as follows:
+// tag::user-formatting[]
+lead:: The `lead` role defines the font properties for a lead paragraph.
+The lead role is automatically assigned to the first paragraph of the preamble if a role is not already declared.
+The built-in themes configure this role to set the font size to the `$base-font-size-large` value.
+big:: The `big` role maps the font size to the `$base-font-size-large` value.
+small:: The `small` role maps the font size to the `$base-font-size-small` value.
+underline:: The `underline` role adds the underline decoration.
+line-through:: The `line-through` role adds the strikethrough decoration.
+subtitle:: The `subtitle` role is used to configure the font properties of the subtitle of a section title.
+// end::user-formatting[]
+unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.
 
-[source,asciidoc]
-----
-== [.heading-code]`SELECT` clause
-----
+NOTE: The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
+You'll need to define these color roles as xref:custom-role.adoc[custom roles] in your theme if you'd like to make use of them when converting to PDF.
diff --git a/docs/theming-guide.adoc b/docs/theming-guide.adoc
index 41f18e3e..31bc066e 100644
--- a/docs/theming-guide.adoc
+++ b/docs/theming-guide.adoc
@@ -1147,7 +1147,7 @@ The name of the role is the first subkey level.
 The role name may contain a hyphen, but *a role name cannot contain an underscore*.
 The keys under the role are the theming properties.
 
-IMPORTANT: Custom roles only apply to inline phrases and paragraphs.
+IMPORTANT: Custom roles only apply to paragraphs and inline phrases.
 
 Here's an example of a role for making text red: