refresh statement about the AsciiDoc syntax on the AsciiDoc.py to Asciidoctor migration page

1 files changed, 17 insertions, 8 deletions

diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
index 9120972c..3a1728dc 100644
--- a/docs/modules/migrate/pages/asciidoc-python.adoc
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -7,26 +7,31 @@
 //:uri-diffs: {uri-home}/docs/asciidoc-asciidoctor-diffs/
 // um anchor: migrating-from-asciidoc-python
 
-In order to take advantage of the new features and syntax in Asciidoctor, you'll
-need to migrate legacy AsciiDoc documents written for AsciiDoc Python (AsciiDoc.py) to the AsciiDoc syntax supported by Asciidoctor.
+If you're currently using AsciiDoc.py (aka AsciiDoc Python) to convert your AsciiDoc documents and want to switch to Asciidoctor, you'll need to migrate your legacy AsciiDoc content to the official AsciiDoc syntax defined and supported by Asciidoctor.
+In doing so, you'll also benefit from the enhancements that have been added to the AsciiDoc language since Asciidoctor took over development of the language.
+This page covers those differences and how to migrate.
 
 NOTE: This documentation specifically covers migration from AsciiDoc.py 8 to the latest stable version of Asciidoctor.
 
 == Processor call
 
 The Asciidoctor processor is a drop-in replacement for AsciiDoc.py.
-For most documents, you can simply replace the call to AsciiDoc.py (`asciidoc`) with the equivalent call to Asciidoctor (`asciidoctor`).
+You can simply replace the call to AsciiDoc.py (`asciidoc`) with the equivalent call to Asciidoctor (`asciidoctor`).
 
  $ asciidoctor document.adoc
 
-// $ asciidoctor -a compat-mode document.adoc
+If you're document makes heavy use of the legacy AsciiDoc syntax supported by AsciiDoc.py, you may have better luck enabling compat mode:
 
-You can also run Asciidoctor on the JVM using AsciidoctorJ or with JavaScript using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
+ $ asciidoctor -a compat-mode document.adoc
+
+However, compat mode is strictly a migration aid.
+You should only use it as an interim measure while your migrating your content.
+It's not something you want to rely on long term and is considered deprecated.
 
 == Default HTML backend
 
 AsciiDoc.py used XHTML 1.1 as its default output.
-Asciidoctor's default output is HTML 5 (the `html5` converter).
+Asciidoctor's default output is HTML 5 (i.e., `backend=html5`) and the `html` backend maps to `html5`.
 
 == Themes
 
@@ -39,7 +44,8 @@ If you require more advanced theming, you can inject additional resources using
 [#migrate-stylesheet]
 === Default HTML stylesheet
 
-The AsciiDoc.py and Asciidoctor stylesheets look quite different, but they are compatible (for the most part) since the formatting is based on the same HTML structure and CSS classes.
+The Asciidoctor and AsciiDoc.py stylesheets look quite different, but they're mostly interchangable since the underlying HTML structure of the two processors is nearly identical.
+
 If you prefer the AsciiDoc.py stylesheet, you can use it by copying it from the AsciiDoc.py [.path]_stylesheets_ directory and instructing Asciidoctor to apply it using:
 
  $ asciidoctor -a stylesheet=asciidoc.css document.adoc
@@ -54,6 +60,9 @@ There are similar attributes to control how additional resources are resolved.
 
 == Updated and deprecated AsciiDoc syntax
 
+Asciidoctor has improved the AsciiDoc syntax to make it more consistent and, in some cases, more concise.
+This section outlines those improvements and how they different from the legacy AsciiDoc supported by AsciiDoc.py.
+
 *If a feature or attribute isn't mentioned in the following tables, than it works in Asciidoctor just like it worked in AsciiDoc.py.*
 
 === Inline formatting
@@ -326,7 +335,7 @@ In both AsciiDoc.py and Asciidoctor, the `--help` CLI option shows the command u
 It can also show a syntax crib sheet using `--help syntax` or the man page using `--help manpage`.
 
 In AsciiDoc.py, the `--help manpage` option emits a plaintext version of the man page.
-Asciidoctor, on the other hand, outputs the formatted man page.
+Asciidoctor, on the other hand, outputs the formatted man page so you can use it with a man pager.
 To view it, you need to pipe the result to the `man` command as follows:
 
  $ asciidoctor --help manpage | man /dev/stdin