more clearly document the supported built-in roles and what they do

2 files changed, 50 insertions, 11 deletions

diff --git a/docs/modules/ROOT/pages/roles.adoc b/docs/modules/ROOT/pages/roles.adoc
index 99dbeda0..148fd56a 100644
--- a/docs/modules/ROOT/pages/roles.adoc
+++ b/docs/modules/ROOT/pages/roles.adoc
@@ -1,12 +1,20 @@
 = 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.
+You can apply the built-in roles that Asciidoctor PDF supports as well as custom roles you define in your theme.
+Built-in roles are not supported universally, but rather on specific elements.
+Custom roles are limited to paragraphs and inline phrases.
 
 [#built-in]
 == Use a built-in role
 
-The following built-in roles can be assigned to paragraphs and inline phrases:
+Asciidoctor PDF supports a subset of the built-in roles defined in AsciiDoc.
+Where these built-in roles can be applied is limited.
+If a built-in role is not listed in this section, then you can expect that it's not supported.
+
+=== On text
+
+The following built-in roles can be assigned to paragraphs and inline phrases.
 
 include::theme:page$role.adoc[tag=user-formatting]
 
@@ -17,18 +25,43 @@ In the example below, the built-in role `big` is applied to an inline phrase.
 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.
+When text is enclosed in a pair of single or double hash symbols (`#`) and has at least one role, the role or roles will be applied to the text without any other implicit formatting.
+That is, the text will appear with custom styling rather than being displayed as marked (i.e., highlighted) text.
+
+The following built-in roles can be assigned to paragraphs, list items, and discrete headings.
+
+include::theme:page$role.adoc[tag=para-roles]
+
+In the example below, the built-in role `text-right` is applied to a paragraph so it aligns to the right.
+
+[,asciidoc]
+----
+[.text-right]
+A response is often shown right-aligned like this.
+----
+
+=== On block images
+
+The following built-in roles can be assigned to block images.
+
+left:: Aligns the image to the left margin.
+Analogous to `align=left`.
+
+right:: Aligns the image to the right margin.
+Analogous to `align=right`.
+
+center:: Aligns the image to the middle of the page.
+Analogous to `align=center`.
+
+noborder:: The border will not be drawn even if configured on the `image` category in the theme.
 
-Roles are sometimes used to control behavior.
-For example, if the `noborder` role is present on a block image, the border will not be drawn even if configured on the `image` category in the theme.
-The `noborder` role cannot be redefined.
+The purpose of the built-in roles on block images cannot be redefined.
 
 [#custom]
 == Use a custom role
 
 In AsciiDoc, you can add any role name to an element that supports roles.
-However, in order for that role to have an effect, you must map it to theme settings.
+However, in order for that role to have any effect, you must assign styles to it in a theme.
 
 NOTE: In Asciidoctor PDF, the theme properties mapped to custom roles currently only apply to paragraphs and inline phrases.
 
diff --git a/docs/modules/theme/pages/role.adoc b/docs/modules/theme/pages/role.adoc
index 5ebc7c99..958228ca 100644
--- a/docs/modules/theme/pages/role.adoc
+++ b/docs/modules/theme/pages/role.adoc
@@ -155,19 +155,25 @@ You can xref:ROOT:roles.adoc[use these roles] when using a built-in theme or a c
 You can also redefine the built-in roles in your theme configuration file.
 
 // 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.
+lead:: The `lead` role defines the font properties for a lead paragraph or phrase.
 The built-in themes configure this role to set the font size to the `$base-font-size-large` value.
+This role is automatically assigned to the first paragraph of the preamble if a role is not already declared.
 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[]
+// tag::para-roles[]
+text-justify:: Aligns the text to the left margin with justification.
+text-left:: Aligns the text to the left margin (without justification).
+text-right:: Aligns the text to the right margin.
+text-center:: Aligns the text to the center of the page.
+// end::para-roles[]
 unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.
 (Only recognizes the `font-color` theme key).
 noborder:: Only applies to block images.
-If this role is present on the block image, the border will not be added.
+If this role is present on the block image, the border will not be drawn even if configured on the `image` category in the theme.
 This role cannot be redefined.
 
 NOTE: The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.