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>

2 files changed, 53 insertions, 0 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.