rearrange pages in extend docs module

6 files changed, 27 insertions, 24 deletions

diff --git a/docs/modules/extend/nav.adoc b/docs/modules/extend/nav.adoc
index d345443b..9183896c 100644
--- a/docs/modules/extend/nav.adoc
+++ b/docs/modules/extend/nav.adoc
@@ -1,5 +1,4 @@
 * xref:index.adoc[]
-** xref:converter-class-and-methods.adoc[]
-** xref:define-converter.adoc[]
-** xref:require-converter.adoc[]
+** xref:create-converter.adoc[]
+** xref:use-converter.adoc[]
 ** xref:use-cases.adoc[]
diff --git a/docs/modules/extend/pages/converter-class-and-methods.adoc b/docs/modules/extend/pages/converter-class-and-methods.adoc
deleted file mode 100644
index 44f2dcf8..00000000
--- a/docs/modules/extend/pages/converter-class-and-methods.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= Converter Class and Methods
-
-== Tailoring conversion
-
-The methods on a converter class that handle conversion follow the pattern `convert_<name>` for block elements (e.g., `convert_example`) and `convert_inline_<name>` for inline elements (e.g., `convert_inline_anchor`), where `<name>` is the name of the element.
-
-When you override a block element, you write PDF objects directly to the Prawn Document (the current context).
-When you override an inline element, you return pseudo-HTML, which is then parsed and converted into PDF objects.
-
-The pseudo-HTML in Asciidoctor PDF evolved from the inline formatting in Prawn, now supporting the following elements: a, br, button, code, color, del, em, font, img, key, mark, span, strong, sub, sup.
-All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g., `\&apos;`).
-You can change the font color using the `rgb` attribute on the `color` element (e.g., `<color rgb="#ff0000">`) and the font family and size using the `name` and `size` attributes on the `font` element, respectively (e.g., `<font name="sans" size="12">`).
-You can also use the `style` attribute on `span` to control the font color, weight, and style using the relevant CSS property names.
-The pseudo-HTML in Asciidoctor PDF also supports the `class` attribute on any element for applying roles from the theme.
-(Though not recommended, you can pass this pseudo-HTML straight through to Prawn using an inline passthrough in AsciiDoc).
-
-To find all the available methods to override, see the {url-api-docs}[API docs^].
diff --git a/docs/modules/extend/pages/define-converter.adoc b/docs/modules/extend/pages/create-converter.adoc
index c29385e5..edd2e770 100644
--- a/docs/modules/extend/pages/define-converter.adoc
+++ b/docs/modules/extend/pages/create-converter.adoc
@@ -1,6 +1,7 @@
 = Create an Extended Converter
+:navtitle: Create a Converter
 
-== Define an extended converter
+== Register an extended converter
 
 Asciidoctor provides a mechanism for looking up a registered converter so it can be extended (i.e., used as a base class), then another mechanism for registering the extended converter in its place.
 Let's see how that looks.
@@ -23,4 +24,6 @@ Let's start by overriding the thematic break (i.e., horizontal rule) to make it
 include::example$pdf-converter-custom-thematic-break.rb[tag=convert_thematic_break]
 ----
 
-Now that you've made a change to the converter, let's xref:require-converter.adoc[learn how to apply it].
+To find all the available methods to override, see the {url-api-docs}[API docs^].
+
+Now that you've made a change to the converter, let's xref:use-converter.adoc[learn how to activate it].
diff --git a/docs/modules/extend/pages/index.adoc b/docs/modules/extend/pages/index.adoc
index 7fb7d1d7..cdf09ec7 100644
--- a/docs/modules/extend/pages/index.adoc
+++ b/docs/modules/extend/pages/index.adoc
@@ -23,4 +23,16 @@ The theme support is there to provide basic customizations (fonts, colors, borde
 But it can only go so far.
 At some point, it becomes necessary to extend the converter to meet advanced design requirements.
 
+== Tailoring the conversion
 
+The methods on a converter class that handle conversion follow the pattern `convert_<name>` for block elements (e.g., `convert_example`) and `convert_inline_<name>` for inline elements (e.g., `convert_inline_anchor`), where `<name>` is the name of the element.
+
+When you override a block element, you write PDF objects directly to the Prawn Document (the current context).
+When you override an inline element, you return pseudo-HTML, which is then parsed and converted into PDF objects.
+
+The pseudo-HTML in Asciidoctor PDF evolved from the inline formatting in Prawn, now supporting the following elements: a, br, button, code, color, del, em, font, img, key, mark, span, strong, sub, sup.
+All decimal and hexadecimal character references are supported, as well as the named entities amp, apos, gt, lt, nbsp, and quot (e.g., `\&apos;`).
+You can change the font color using the `rgb` attribute on the `color` element (e.g., `<color rgb="#ff0000">`) and the font family and size using the `name` and `size` attributes on the `font` element, respectively (e.g., `<font name="sans" size="12">`).
+You can also use the `style` attribute on `span` to control the font color, weight, and style using the relevant CSS property names.
+The pseudo-HTML in Asciidoctor PDF also supports the `class` attribute on any element for applying roles from the theme.
+(Though not recommended, you can pass this pseudo-HTML straight through to Prawn using an inline passthrough in AsciiDoc).
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 13391fff..90af4bff 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -1,7 +1,8 @@
 = Extended Converter Use Cases
+:navtitle: Customization Use Cases
 
 This page presents common use cases that can be accomplished by extending and customizing the converter.
-In xref:define-converter.adoc[], we were just biting around the edges of what you can do with an extended converter.
+In xref:create-converter.adoc[], we were just biting around the edges of what you can do with an extended converter.
 This page gets into more realistic use cases.
 Each section introduces a different use case and presents the code for an extended converter you can use as a starting point.
 
diff --git a/docs/modules/extend/pages/require-converter.adoc b/docs/modules/extend/pages/use-converter.adoc
index 56764cb9..2a0ee24a 100644
--- a/docs/modules/extend/pages/require-converter.adoc
+++ b/docs/modules/extend/pages/use-converter.adoc
@@ -1,4 +1,5 @@
-= Use an Extended Converter
+= Use the Extended Converter
+:navtitle: Use the Converter
 
 == Require the extended converter
 
@@ -6,6 +7,10 @@ To use this converter, require it by passing the path to the `-r` flag when call
 
  $ asciidoctor-pdf -r ./extended-pdf-converter.rb doc.adoc
 
+The converter will self-register with the `pdf` backend and thus get used as the Asciidoctor PDF converter.
+
 That's all there is too it!
 
+== Go further
+
 To get deeper into the world of extended converters, explore the xref:use-cases.adoc[use cases].