1 files changed, 386 insertions, 0 deletions
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
new file mode 100644
index 00000000..9120972c
--- /dev/null
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -0,0 +1,386 @@
+= Migrate from AsciiDoc.py to Asciidoctor
+:navtitle: Migrate from AsciiDoc.py
+:url-diagram: {url-org}/asciidoctor-diagram
+:url-tests: {url-org}/asciidoctor/tree/master/test
+:url-doctest: {url-org}/asciidoctor-doctest
+:url-manpage: {url-project}/man/asciidoctor
+//: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.
+
+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`).
+
+ $ asciidoctor document.adoc
+
+// $ asciidoctor -a compat-mode document.adoc
+
+You can also run Asciidoctor on the JVM using AsciidoctorJ or with JavaScript using xref:asciidoctor.js::index.adoc[Asciidoctor.js].
+
+== Default HTML backend
+
+AsciiDoc.py used XHTML 1.1 as its default output.
+Asciidoctor's default output is HTML 5 (the `html5` converter).
+
+== Themes
+
+AsciiDoc.py provided a theming mechanism that encapsulated CSS, JavaScript, and images.
+The `--theme` option activated one of these themes, which was resolved from your home directory.
+In Asciidoctor, you control the theme using CSS stylesheets, which you specify using `-a stylesheet=<stylesheet>`.
+
+If you require more advanced theming, you can inject additional resources using a xref:ROOT:docinfo.adoc[docinfo file] or a xref:extensions:postprocessor.adoc[postprocessor extension].
+
+[#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.
+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
+
+Keep in mind that the default stylesheet in Asciidoctor is just that, a default.
+If you don't like its appearance, you can customize it.
+
+IMPORTANT: Unlike AsciiDoc.py, Asciidoctor loads some resources from a CDN.
+It's possible to configure Asciidoctor to load all resources from local files.
+For instance, you can unset the `webfonts` attribute so that the generated HTML does not use fonts from Google Fonts.
+There are similar attributes to control how additional resources are resolved.
+
+== Updated and deprecated AsciiDoc syntax
+
+*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
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|_italic text_
+|pass:['italic text']
+|pass:[_italic text_]
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:italic.adoc[].
+
+|`monospace text`
+|pass:[+monospace text+]
+|pass:[`monospace text`]
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc[].
+
+|`+literal monospace text+`
+|pass:[`literal monospace text`]
+|pass:[`+literal monospace text+`]
+|Allowed with `compat-mode`.
+See xref:asciidoc:text:monospace.adoc#literal-monospace[Literal monospace].
+
+|Curved "`double quotes`"
+|pass:[``double quotes'']
+|pass:["`double quotes`"], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
+
+|Curved '`single quotes`'
+|pass:[`single quotes']
+|pass:['`single quotes`'], editor keybinding, or Unicode character in numeric character reference form
+|See xref:asciidoc:text:quotation-marks-and-apostrophes.adoc[].
+
+|Sizes and overline
+|`big`, `small`, `overline`
+|user-specified `+[.<role-name>]+` and associated formatting in stylesheet
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
+
+|Underline and line-through
+|`underline`, `line-through`
+|`+[.underline]+`, `+[.line-through]+`
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
+
+|Colors
+|Name of color
+|user-specified `+[.<role-name>]+` and associated formatting in stylesheet
+|See xref:asciidoc:text:custom-inline-styles.adoc[].
+|===
+
+=== Table of contents
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Scrollable, left margin TOC
+|`toc2`
+|`+:toc: left+`
+|See xref:asciidoc:toc:position.adoc[].
+
+|TOC location
+|`toc-placement` and `toc-position`
+|`+:toc: <value>+`
+|See xref:asciidoc:toc:position.adoc[].
+
+|User-specified TOC location
+|`+:toc-placement: manual+`
+|`+:toc: macro+`
+|See xref:asciidoc:toc:position.adoc[].
+|===
+
+=== Document and section titles
+
+[cols="~,~,30%,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Implicit document title attribute
+|First content line at document top is set as title
+|`= Title`
+|Allowed with `compat-mode`.
+See xref:asciidoc:document:title.adoc[].
+
+|Two-line style (setext) document title
+|`Title` +
+`+=====+`
+|`= Title`
+|Asciidoctor accepts the two-line heading style to set the document title.
+But, by using it, `compat-mode` is implicitly set.
+To use the new syntax, use `= Title` or explicitly unset `compat-mode`.
+See xref:asciidoc:document:title.adoc[].
+
+|Underlined section titles
+|Underline length must match title length +/- 2 characters.
+|`== Level 1 title` +
+`=== Level 2 title` +
+`==== Level 3 title` +
+`===== Level 4 title`
+|See xref:asciidoc:sections:titles-and-levels.adoc[].
+
+|Section numbers
+|`numbered`
+|`sectnums`
+|See xref:asciidoc:sections:numbers.adoc[].
+|===
+
+=== Tables
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Table cell
+|`a{vbar}` or `asciidoc{vbar}`
+|`a{vbar}` only
+|See xref:asciidoc:tables:add-cells-and-rows.adoc[].
+
+|Table cell separator
+|A Python regular expression.
+|One or more literal characters or `\t` for tab.
+|See xref:asciidoc:tables:add-cells-and-rows.adoc[], xref:asciidoc:tables:data-format.adoc[], and xref:asciidoc:tables:data-format.adoc#custom-delimiters[custom separators].
+
+|Horizontal and vertical alignment for tables cells
+|`halign`, `valign`
+|Column and cell specifiers
+|See xref:asciidoc:tables:align-by-column.adoc[] and xref:asciidoc:tables:align-by-cell.adoc[].
+
+|Make tables full page width in DocBook
+|`options="pgwide"`
+|_not implemented_
+|
+|===
+
+=== Blocks
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Block delimiters
+|Delimiter lines do not have to match in length.
+|The length of start and end delimiter lines must match exactly.
+|See xref:asciidoc:blocks:build-basic-block.adoc#delimited-blocks[Delimited blocks].
+|===
+
+=== Substitutions
+
+[cols="~,~,~,~"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Substitute `+`
+|`replacements2`
+|`post_replacements`
+|See xref:asciidoc:subs:post-replacements.adoc[].
+
+|Suppress inline substitutions and retain block indents when importing large blocks of plain text
+|`plaintext`
+|_not implemented_
+|Close equivalent is a xref:asciidoc:pass:pass-block.adoc[passthrough block] or a listing block with xref:asciidoc:directives:include-with-indent.adoc#the-indent-attribute[the indent attribute].
+|===
+
+=== Mathematical expressions
+
+AsciiDoc.py and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., `pass:[asciimath:[expression]]`, `pass:[latexmath:[expression]]`, etc.).
+In Asciidoctor, activate STEM support first using the xref:asciidoc:stem:stem.adoc[stem attribute].
+
+=== Miscellaneous
+
+[cols="~,~,~,30%"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|`+ifeval::[ ]+`
+|Evaluates any Python expression.
+|Evaluates simple logical expressions testing the value of attributes.
+|See xref:asciidoc:directives:ifeval.adoc[].
+
+|Provide name of current document
+|`infile`
+|_not implemented_
+|
+
+|Provide directory of current document
+|`indir`
+|_not implemented_
+|
+
+|Apply special formatting to named text
+|`specialwords`
+|_not implemented_
+|
+
+|Replace tabs with spaces in all text, using a default tab size of 8
+|`tabsize` (in-document and include directive)
+|in-document only
+|Asciidoctor only replaces tabs with spaces in verbatim blocks, and the attribute has no default.
+In other words, tabs are not expanded in verbatim content blocks unless this attribute is set on the block or the document.
+For all other text, Asciidoctor tabs are fixed at 4 spaces by the CSS.
+See xref:asciidoc:directives:include-with-indent.adoc[normalize block indentation].
+|===
+
+=== showcomments
+
+In AsciiDoc.py, single line comments could be turned into DocBook `<remark>` elements using `showcomments`.
+This feature isn't implemented in Asciidoctor, but you can send remarks to the output, using an extension, or ifdef directives and passthrough blocks like the example shown below.
+
+[source,asciidoc]
+----
+ ifdef::showcomments+basebackend-docbook[]
+ ++++
+ <remark>Your comment here</remark>
+ ++++
+ endif::[]
+----
+
+== Configuration files
+
+Asciidoctor does not use [.path]_.conf_ files or filters, so `--conf-file`, `--dump-conf`, and `--filter` are not applicable.
+Instead, Asciidoctor provides an xref:extensions:register.adoc[extension API] that replaces the configuration-based extension and filter mechanisms in AsciiDoc.py.
+
+=== Localization
+
+AsciiDoc.py had built-in [.path]_.conf_ files that translated built-in labels.
+In Asciidoctor, you must define the translations for these labels explicitly.
+See xref:ROOT:localization-support.adoc[] for details.
+
+[#migrate-extensions]
+== AsciiDoc.py extensions
+
+The extension mechanism is completely different in Asciidoctor, but most of the standard extensions have been re-implemented, so they should work with minor changes.
+
+[cols="~,~"]
+|===
+|AsciiDoc.py |Asciidoctor
+
+|`source`
+a|
+* You can choose from a number of xref:asciidoc:verbatim:source-highlighter.adoc#built-in-values[source highlighters].
+* Source highlighter values are built-in.
+* `src_numbered`, `src_tab`, `args` are not implemented directly, but check the highlighter you are using for what features it has and how to configure them.
+
+|music
+|Not implemented.
+
+|`[latex]` block macro
+|Use a xref:asciidoc:stem:stem.adoc#block[stem block].
+
+|`graphviz`
+|Use {url-diagram}[Asciidoctor Diagram^].
+|===
+
+=== Custom extensions
+
+AsciiDoc.py custom extensions are Python commands, so they don't work with Asciidoctor.
+Depending on the Asciidoctor processor you choose, you can re-write your xref:extensions:index.adoc[extensions in Ruby, Java, or JavaScript].
+
+== Doctest
+
+AsciiDoc.py `--doctest` ran its unit tests.
+See the {url-tests}[test suite^] for how to run the Asciidoctor unit tests.
+Asciidoctor also has a {url-doctest}[doctest tool^] which you can use when creating custom HTML or XML-based converters.
+
+== Help topics
+
+In both AsciiDoc.py and Asciidoctor, the `--help` CLI option shows the command usage by default.
+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.
+To view it, you need to pipe the result to the `man` command as follows:
+
+ $ asciidoctor --help manpage | man /dev/stdin
+
+or
+
+ $ asciidoctor --help manpage | man -l -
+
+If you want to view the plaintext version with Asciidoctor, you can route the output through the `col` command as follows:
+
+ $ asciidoctor --help manpage | man -l - | col -bx
+
+Alternately, you can view the manpage for Asciidoctor online at {url-manpage}[asciidoctor(1)].
+
+////
+This content needs to be move to the specific subject docs pages if applicable
+
+== Features Introduced by Asciidoctor
+
+=== New Syntax
+
+Asciidoctor has shorthand for id, role, style and options.
+The following longhand syntax in AsciiDoc.py:
+
+[source,asciidoc]
+----
+[[id]]
+[style,role="role",options="option1,option2"]
+----
+
+can be written using the shorthand supported by Asciidoctor:
+
+[source,asciidoc]
+----
+[style#id.role%option1%option2]
+----
+
+The longhand forms still work, but you should use the new forms for future compatibility, convenience and readability.
+
+=== Enhancements
+
+There are lots of new features and improvements Asciidoctor.
+These are some of the more interesting ones when migrating:
+
+* xref:directives:include-lines-and-tags.adoc[Partial includes]
+* xref:attributes:safe-modes.adoc[Additional safe modes]
+* xref:macros:icons.adoc[Icon-based fonts and inline icons]
+* {url-diagram}[Asciidoctor Diagram^]
+
+A detailed list of the improvements is shown in #Differences between Asciidoctor and AsciiDoc.py#.
+
+This is the compat mode summary which needs a page.
+
+These changes are not backward-compatible, but if you set the `compat-mode` attribute, Asciidoctor will accept the AsciiDoc.py syntax.
+For the long term, you should update to the Asciidoctor syntax.
+Consult the {uri-migrate}[Migration Guide] to get the full details and learn how to migrate smoothly.
+////