apply minor revisions and rephrasing to Converter Templates page

1 files changed, 14 insertions, 12 deletions

diff --git a/docs/modules/convert/pages/templates.adoc b/docs/modules/convert/pages/templates.adoc
index 152385f4..72a4142d 100644
--- a/docs/modules/convert/pages/templates.adoc
+++ b/docs/modules/convert/pages/templates.adoc
@@ -11,18 +11,18 @@ All output produced by Asciidoctor is customizable.
 One way to customize the output is to use a custom converter.
 Converter templates offer a simpler way.
 
-Converters that have the `supports_templates` trait enabled, which includes all built-in converters, allow you to substitute the convert handler for any convertible context with a template.
+The built-in converters, and others that have the `supports_templates` trait enabled, allow you to replace the convert handler for any convertible context with a template.
 The goal of this mechanism is to make it easier to customize the output of a converter (e.g., HTML) without having to develop, register, and use a custom converter.
-In other words, you can customize the output of a converter without having to write code (aside from what's in the template).
+In other words, you can customize the output of a converter à la carte without having to write code (aside from what's in the template).
 
-This page explains how the converter template mechanism works in Asciidoctor and how to make use of it to customize the converted output.
+This page explains how the converter template mechanism works in Asciidoctor and how you can make use of it to customize the output of a converter that supports it.
 
 == What is a template?
 
 A template is a type of source file that's focused on producing output.
 When we use the term [.term]_template_ in this context, we're specifically referring to the source file for a Ruby template engine.
 
-You can think of template as source code where the output text forms the primary structure and the programming logic is weaved in between.
+You can think of template as source code in which the output text forms the primary structure and the programming logic is weaved in between.
 If you come from a programming background, it's as though the program logic and strings are flipped.
 
 When you write a template, you begin with static text.
@@ -30,10 +30,6 @@ Then you intersperse logic around regions of that text.
 This logic allows you to either conditionally select text or repeat it based on information provided by a backing data model.
 The syntax of that interspersed logic is the template language.
 
-At runtime, the template engine transforms the template into runnable code and invokes it.
-We refer to this operation as invoking the template.
-Effectively, this operation invokes the logic and expands variable references in the template to produce the resolved output.
-
 The most common template engine in Ruby is ERB because it's built into the language.
 Here's an example of an ERB template that outputs a paragraph element using the content provided by the backing data model:
 
@@ -66,12 +62,17 @@ The equals sign tells Slim and Haml to evaluate the Ruby expression that follows
 In this case, the template is reading the variable `content`, technically a property of the backing data model.
 Slim and Haml use indentation to infer nesting in the HTML structure (much like in YAML).
 
+At runtime, the template engine transforms the template into runnable code and invokes it.
+We refer to this operation as invoking the template.
+Effectively, this operation invokes the logic and expands variable references in the template to produce the resolved output.
+
 Now that you're familiar with the basic concept of a template, let's look at how templates are used in Asciidoctor.
 
 == Templates in Asciidoctor
 
 Templates are used in Asciidoctor to customize the output generated by a converter (as long as the converter has the `supports_templates` trait enabled).
 We refer to these as converter templates.
+Converter templates work in conjunction with the converter over which they are applied.
 
 There are three keys points to understand about using converter templates in Asciidoctor:
 
@@ -122,7 +123,7 @@ The convertible contexts are roughly the nodes in the parsed AsciiDoc document.
 If the name of a template matches the name of a convertible context, Asciidoctor will use that template to produce the output for any node with that context when the convert method is called on that node.
 You can create a template for as many or as few contexts as you like.
 If Asciidoctor is unable to locate a template for a convertible context, it will fall back to using the handler provided by the converter.
-By using templates, you can customize the output of a converter à la carte.
+By using templates, you can customize some or all of the output produced by a converter.
 
 NOTE: Recall that templates can only be used if supported by the converter.
 All built-in converters in Asciidoctor support the use of templates to customize the converter.
@@ -579,12 +580,13 @@ If you're using the API, you specify the template directory (or directories) usi
 
 [,ruby]
 ----
-Asciidoctor.convert_file 'doc.adoc', safe: :safe, template_dirs: ['/path/to/templates'], template_engine: 'slim'
+Asciidoctor.convert_file 'doc.adoc', safe: :safe,
+  template_dirs: ['/path/to/templates'], template_engine: 'slim'
 ----
 
 Notice that we didn't specify the segment [.path]_html5_ in the path where the templates are located.
-That's because Asciidoctor automatically looks for a folder that matches the backend name when scanning for templates.
-However, you can include this segment in the path if you prefer.
+That's because Asciidoctor automatically looks for a folder that matches the backend name when scanning for templates (e.g., [.path]_/path/to/templates/html5_).
+However, you can include the segment for the backend in the path if you prefer.
 
 == Tutorial: Your first converter template