rearchitect modules and filenames and drop asciidoctor folder under docs

8 files changed, 826 insertions, 0 deletions

diff --git a/docs/modules/migrate/examples/convert.groovy b/docs/modules/migrate/examples/convert.groovy
new file mode 100644
index 00000000..6dba705c
--- /dev/null
+++ b/docs/modules/migrate/examples/convert.groovy
@@ -0,0 +1,43 @@
+// This script is provided by melix.
+// The source can be found at https://gist.github.com/melix/6020336
+
+@Grab('net.sourceforge.htmlcleaner:htmlcleaner:2.4')
+import org.htmlcleaner.*
+
+def src = new File('html').toPath()
+def dst = new File('asciidoc').toPath()
+
+def cleaner = new HtmlCleaner()
+def props = cleaner.properties
+props.translateSpecialEntities = false
+def serializer = new SimpleHtmlSerializer(props)
+
+src.toFile().eachFileRecurse { f ->
+    def relative = src.relativize(f.toPath())
+    def target = dst.resolve(relative)
+    if (f.isDirectory()) {
+        target.toFile().mkdir()
+    } else if (f.name.endsWith('.html')) {
+        def tmpHtml = File.createTempFile('clean', 'html')
+        println "Converting $relative"
+        def result = cleaner.clean(f)
+        result.traverse({ tagNode, htmlNode ->
+                tagNode?.attributes?.remove 'class'
+                if ('td' == tagNode?.name || 'th'==tagNode?.name) {
+                    tagNode.name='td'
+                    String txt = tagNode.text
+                    tagNode.removeAllChildren()
+                    tagNode.insertChild(0, new ContentNode(txt))
+                }
+
+            true
+        } as TagNodeVisitor)
+        serializer.writeToFile(
+                result, tmpHtml.absolutePath, "utf-8"
+        )
+        "pandoc -f html -t asciidoc -R -S --normalize -s $tmpHtml -o ${target}.adoc".execute().waitFor()
+        tmpHtml.delete()
+    }/* else {
+        "cp html/$relative $target".execute()
+    }*/
+}
diff --git a/docs/modules/migrate/nav.adoc b/docs/modules/migrate/nav.adoc
new file mode 100644
index 00000000..6df6ade3
--- /dev/null
+++ b/docs/modules/migrate/nav.adoc
@@ -0,0 +1,7 @@
+* Migration Guides
+** xref:upgrade.adoc[]
+** xref:asciidoc-python.adoc[]
+** xref:docbook-xml.adoc[]
+** xref:markdown.adoc[]
+** xref:confluence-xhtml.adoc[]
+** xref:ms-word.adoc[]
diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc
new file mode 100644
index 00000000..c18e26c4
--- /dev/null
+++ b/docs/modules/migrate/pages/asciidoc-python.adoc
@@ -0,0 +1,368 @@
+= 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="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|_italic text_
+|pass:['italic text']
+|pass:[_italic text_]
+|Allowed with `compat-mode`
+
+|`monospace text`
+|pass:[+monospace text+]
+|pass:[`monospace text`]
+|Allowed with `compat-mode`
+
+|`+literal monospace text+`
+|pass:[`literal monospace text`]
+|pass:[`+literal monospace text+`]
+|Allowed with `compat-mode`
+
+|Curved "`double quotes`"
+|pass:[``double quotes'']
+|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
+|
+
+|Curved '`single quotes`'
+|pass:[`single quotes']
+|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
+|
+
+|Sizes, lines, and colors
+|`big`, `small`, `underline`, `overline`, `line-through`, colors
+|user-specified `+[.<role-name>]+` and associated formatting in stylesheet
+|See xref:asciidoc:text:custom-inline-styles.adoc[custom text styles]
+|===
+
+=== Table of contents
+
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Scrollable, left margin ToC
+|`toc2`
+|`+:toc: left+`
+|
+
+|ToC location
+|`toc-placement` and `toc-position`
+|`+:toc: <value>+`
+|
+
+|User-specified ToC location
+|`+:toc-placement: manual+`
+|`+:toc: macro+`
+|
+|===
+
+=== Document header
+
+[cols="15,20,15,35"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Implicit document title attribute
+|First content line at document top is set as title
+|pass:[= Title]
+|Allowed with `compat-mode`
+
+|Two-line style document title
+|pass:[= Title] +
+pass:[=====]
+|pass:[= Title]
+|Asciidoctor accepts the two-line heading style to set the document title.
+But by using it, you implicitly set `compat-mode`.
+If you want to use the new Asciidoctor syntax, make sure to use `= Title` or explicitly unset the `compat-mode` attribute.
+|===
+
+.Sections
+[cols="15,20,30,15"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|Underlined titles
+|Underline length must match title length +/- 2 characters.
+|pass:[== Level 1 section title] +
+pass:[=== Level 2 section title] +
+pass:[==== Level 3 section title] +
+pass:[===== Level 4 section title] +
+|See xref:asciidoc:sections:titles-and-levels.adoc[section levels and titles]
+
+|Section numbers
+|`numbered`
+|`sectnums`
+|
+|===
+
+=== Tables
+
+[cols="15,20,20,20"]
+|===
+|Feature |AsciiDoc.py |Asciidoctor |Notes
+
+|AsciiDoc table cell
+|`a{vbar}` or `asciidoc{vbar}`
+|`a{vbar}` only
+|
+
+|Table cell separator
+|A Python regular expression.
+|One or more literal characters or \t for tab.
+|
+
+|Horizontal and vertical alignment for tables cells
+|`halign`, `valign`
+|Column and cell specifiers
+|See xref:asciidoc:tables:align-by-column.adoc[align column content] or xref:asciidoc:tables:align-by-cell.adoc[cell content].
+
+|Make tables full page width in DocBook
+|`options="pgwide"`
+|_not implemented_
+|
+|===
+
+=== Blocks
+
+[cols="15,20,30,15"]
+|===
+|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.
+|
+|===
+
+.General
+[cols="15,20,30,15"]
+|===
+|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[ifeval directive]
+
+|Provide name of current document
+|`infile`
+|_not implemented_
+|
+
+|Provide directory of current document
+|`indir`
+|_not implemented_
+|
+
+|Substitute (`+`)
+|`replacements2`
+|Renamed to `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_
+|Closest Asciidoctor equivalent is a xref:asciidoc:pass:pass-block.adoc[passthrough block] or a listing block with an indent attribute.
+
+|Turn single line comments into DocBook `<remark>` elements
+|`showcomments`
+|_not implemented_
+a|If you want to send remarks to the output, use an extension, or:
+
+----
+ ifdef::showcomments+basebackend-docbook[]
+ ++++
+ <remark>Your comment here</remark>
+ ++++
+ endif::[]
+----
+
+|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 content blocks (listing, literal, etc.), 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] for more detail.
+|===
+
+== Mathematical expressions
+
+AsciiDoc.py and Asciidoctor can convert embedded LaTeX and AsciiMath expressions (e.g., `pass:[asciimath:[expression]]`, `pass:[latexmath:[expression]]`, etc.).
+In Asciidoctor, you'll need to activate STEM support first using the xref:asciidoc:stem:stem.adoc[stem attribute].
+
+== 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.
+
+=== Internationalization
+
+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:language-support.adoc[language support] for details.
+
+[#migrate-extensions]
+== AsciiDoc.py extensions
+
+The extension mechanism is completely different in Asciidoctor, but the most of the standard extensions have been re-implemented, so they should work with minor changes.
+
+[cols="<20,<80"]
+|===
+|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#stem-bl[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:register.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]
+----
+[[id]]
+[style,role="role",options="option1,option2"]
+----
+
+can be written using the shorthand supported by Asciidoctor:
+
+[source]
+----
+[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.
+////
diff --git a/docs/modules/migrate/pages/confluence-xhtml.adoc b/docs/modules/migrate/pages/confluence-xhtml.adoc
new file mode 100644
index 00000000..744cf0f1
--- /dev/null
+++ b/docs/modules/migrate/pages/confluence-xhtml.adoc
@@ -0,0 +1,29 @@
+= Migrate from Confluence XHTML to Asciidoctor
+:navtitle: Migrate from Confluence XHTML
+:url-pandoc: https://pandoc.org
+
+You can convert Atlassian Confluence XHTML pages to Asciidoctor using this Groovy script.
+
+The script calls {url-pandoc}[Pandoc^] to convert single or multiple HTML files exported from Confluence to AsciiDoc files.
+You'll need Pandoc installed before running this script.
+If you have trouble running this script, you can use the Pandoc command referenced inside the script to convert XHTML files to AsciiDoc manually.
+
+.convert.groovy
+[source,groovy]
+----
+include::example$convert.groovy[]
+----
+
+This script was created by Cédric Champeau (https://gist.github.com/melix[melix]).
+You can find the source of this script hosted at this https://gist.github.com/melix/6020336[gist].
+
+The script is designed to be run locally on HTML files or directories containing HTML files exported from Confluence.
+
+== Usage
+
+. Save the script contents to a `convert.groovy` file in a working directory.
+. Make the file executable according to your specific OS requirements.
+. Place individual files, or a directory containing files into the working directory.
+. Run `groovy convert filename.html` to convert a single file.
+. Confirm the output file meets requirements
+. Recurse through a directory by using this command pattern: `groovy convert directory/*.html`
diff --git a/docs/modules/migrate/pages/docbook-xml.adoc b/docs/modules/migrate/pages/docbook-xml.adoc
new file mode 100644
index 00000000..06cb5a96
--- /dev/null
+++ b/docs/modules/migrate/pages/docbook-xml.adoc
@@ -0,0 +1,19 @@
+= Migrate from DocBook XML to Asciidoctor
+:navtitle: Migrate from DocBook XML
+:url-docbookrx: https://github.com/opendevise/docbookrx
+// docbookrx.adoc, included in user-manual: Convert DocBook XML to AsciiDoc
+
+One of the things Asciidoctor excels at is converting AsciiDoc source into valid and well-formed DocBook XML content.
+
+What if you're in the position where you need to go the other way: migrate all your legacy DocBook XML content to AsciiDoc?
+The prescription (℞) you need to get rid of your DocBook pains could be {url-docbookrx}[DocBookRx^].
+
+DocBookRx is an early version of a DocBook to AsciiDoc converter written in Ruby.
+This converter is far from perfect at the moment, but it improves with each document it converts.
+
+The plan is to evolve it into a robust library for performing this conversion in a reliable way.
+You can read more about this initiative in the {url-docbookrx}/blob/master/README.adoc[README^].
+
+The best thing about this tool is all the active users who are putting it through its paces.
+The more advanced the DocBook XML this tool tackles, and the more feedback we receive, the better the tool will become.
+Use it today to escape from XML hell!
diff --git a/docs/modules/migrate/pages/markdown.adoc b/docs/modules/migrate/pages/markdown.adoc
new file mode 100644
index 00000000..eab57dc3
--- /dev/null
+++ b/docs/modules/migrate/pages/markdown.adoc
@@ -0,0 +1,6 @@
+= Migrate from Markdown to Asciidoctor
+:navtitle: Migrate from Markdown
+
+Asciidoctor recognizes a fair amount of Markdown syntax, thus allowing you to migrate from Markdown to AsciiDoc gradually.
+See #asciidoc-syntax-quick-reference/markdown-compatibility,Markdown Compatibility# to learn what syntax is shared.
+The syntax you must change is listed in #asciidoc-vs-markdown#.
diff --git a/docs/modules/migrate/pages/ms-word.adoc b/docs/modules/migrate/pages/ms-word.adoc
new file mode 100644
index 00000000..aea595c6
--- /dev/null
+++ b/docs/modules/migrate/pages/ms-word.adoc
@@ -0,0 +1,196 @@
+= Migrate from MS Word to Asciidoctor
+:navtitle: Migrate from MS Word
+:description: This document presents various tools and strategies for migrating from MS Word to AsciiDoc.
+:url-pandoc: https://pandoc.org
+:url-google-asciidoc: https://chrome.google.com/webstore/detail/asciidoc-processor/eghlmnhjljbjodpeehjjcgfcjegcfbhk/
+:url-google-asciidoc-source:  https://github.com/Mogztter/asciidoc-googledocs-addon/
+// from migrating-from-msword.adoc
+
+== Pandoc
+
+{url-pandoc}[Pandoc^] is a swiss army knife for converting one markup format to another.
+It does an admirable job converting simple docx files to AsciiDoc.
+
+NOTE: Generally, we don't like to recommend pandoc because it doesn't create AsciiDoc the way we prefer.
+However, in this case, it's a good choice.
+
+To perform the conversion from MS Word docx to AsciiDoc, you need to perform the following command:
+
+ $ pandoc --from=docx --to=asciidoc --wrap=none --atx-headers \
+     --extract-media=extracted-media input.docx > output.adoc
+
+Then, edit the output file to tidy it up.
+
+The conversions you can expect are shown in the following table (tested using MS Word 2010 and 2013 + Pandoc 2.0 and 2.5 (Windows)):
+
+.Pandoc MS Word to AsciiDoc conversions
+|===
+|MS Word Feature |Conversion
+
+|Headings (using MS Word Heading styles 1-5)
+|Yes
+
+|Tables
+|Yes. +
+Merged cells are unmerged.
+Column widths are ignored.
+
+|Unordered and ordered lists
+|Yes
+
+|Footnotes
+|Yes
+
+|Figure and table captions
+|Normal paragraph
+
+|Other MS Word styled paragraphs
+|Normal paragraph
+
+|Embedded images
+|Yes
+
+|Character formatting (bold, underline and italic)
+|Yes
+
+|URL links
+|No - see <<remove-refs,how to remove hyperlinks>> to fix it
+
+|email links
+|Yes
+
+|Document automation (fields, auto-generated figure and table numbers)
+|Ignored
+
+|Internal references (e.g., "`See Figure 3`")
+|Plain text
+
+|Drawing canvas
+|Ignored
+
+|Text boxes
+|Ignored
+
+|Linked (not embedded) images
+|Ignored
+
+|Vector graphics (MS Word "`insert shape`")
+|Ignored
+|===
+
+== Optimizing for Pandoc
+
+The basic usage documented above is fine for one-off imports.
+If you have a lot to do, it's worth while cleaning the input document first, and automating the post-conversion tidy up.
+
+. Clean up the MS Word document:
+// Title pages are usually easier to recreate manually
+** Remove non-essential material (title pages, headers and footers, table of contents etc.); it is usually easiest to copy just the body text into a new blank document
+// Technically not necessary as pandoc ignores them by default, but it simplifies the document, which is a good thing in principle
+** Switch off tracking and accept all changes
+// Important - pandoc recognizes the style name to define headings
+** Ensure you have used Heading styles for headings
+//** Remove automatic heading numbering (this limitation may be removed in the next release of pandoc)
+// So you can turn them back into captions just with a .
+** Ensure table titles are immediately *above* their table
+// So you can turn them back into captions just with a .
+** Ensure figure titles are immediately *above* their figure
+// linked images are ignored (according to my testing)
+** Ensure images are inserted as embedded files, not as links
+// canvases are ignored (according to my testing)
+** Remove canvases and put any images they contained into the main flow as paragraph images (this limitation may be removed in the next release of pandoc)
+// results of SEQ formulas are ignored (MS Word inserts them to generate figure and table numbers)
+** [[remove-refs]]Remove hyperlinks and replace all internal references and auto-generated sequence numbers with their literal values (kbd:[Ctrl+A], kbd:[Ctrl+Shift+F9])
+// No - this will turn manually applied list formatting back to plain text. Fine if you have used a list style though.
+// * Remove all non style-based formatting (kbd:[Ctrl+A], kbd:[Ctrl+space], kbd:[Ctrl+Q])
+// text boxes are ignored (according to my testing)
+** Remove text boxes and put their text into the main flow
+// Back to plain text.
+// Not sure about this - they don't show properly in PSPad, but look fine when converted to HTML.
+** Replace special characters: smart quotes with simple quotes, non-breaking hyphens with normal hyphens.
+** Remove all character formatting (kbd:[Ctrl+A], kbd:[Ctrl+B], kbd:[Ctrl+B], kbd:[Ctrl+I], kbd:[Ctrl+I], kbd:[Ctrl+U], kbd:[Ctrl+U])
+// pandoc just treats them as plain text as passes them through.
+** Optional: insert ids and cross references using AsciiDoc notation
+(You might find it easier doing it now rather than in the AsciiDoc document later.)
+// Not sure if it is significant, but pandoc seems to be designed against this spec, rather than the normal docx.
+** Save as "`Strict Open-xml document (docx)``"
+. Convert using pandoc as shown above.
+. Check that the output document looks OK, and that all images have been extracted.
++
+[NOTE]
+====
+If for some reason pandoc is not extracting images, you can always extract them by using unzip tool.
+Docx is just a zip file with a docx file extension.
+Embedded images are located in [.path}_word/media_ directory.
+
+ $ unzip input.docx -d input-docx
+   ls input-docx/word/media/
+
+====
+
+. Fix up the output, preferably with an editor that can do regular expressions:
+// tocs and cross refs introduce dozens of these. They are just noise.
+** Delete automatic ids (those beginning with underscores)
+// Style issue - pandoc seems to extend the line to cover the longest row
+** Replace long table delimiters with short ones.
+// Style issue
+** Insert line-breaks to get to 1 sentence per paragraph.
+// can do this with a regexp, but is depends on exactly what format you used for them
+** Re-insert images and turn caption paragraphs back into Asciidoctor captions.
+// can do this with a regexp, but is depends on exactly what format you used for them
+** Replace the hard cross references with AsciiDoc references.
+// checked vertical merge, assume h merge same
+** Fix tables - merged cells will have unmerged, column widths need putting back.
+. Try to convert it, and fix any errors that come up.
+// pandoc supposedly only uses UTF-8, and the xml file is windows encoded, but I haven't found any problems so far.
+// You definitely do get encoding errors if you go via HTML.
+
+The following are POSIX shell one-liners to automate some of these steps (adjust the regexps to match your particular document):
+
+* Delete automatically inserted ids
+
+ $ perl -W -pe  's!\[\[_.*]]!!g' -i output.adoc
+
+* Shorten table delimiters
+
+ $ perl -W -pe  's!\|==*!|====!g' -i output.adoc
+
+* 1 sentence per line.
+Be careful not to match lists.
+It will get confused by abbreviations, but there is no way around that.
+
+ $ perl -W -pe 's!(\w\w+)\.\s+(\w)!$1.\n$2!g' -i output.adoc
+
+* Replace figure captions with id and title
+
+ $ perl -W -pe 's!^Figure (\d+)\s?(.*)![[fig-$1]]\n.$2\n!g' -i output.adoc
+
+* Replace references to figures with asciidoc xref
+
+ $ perl -W -pe 's!Figure (\d+)!<<fig-$1>>!g' -i output.adoc
+
+== Google Docs
+
+Google Docs can already upload and edit MS Word docx files.
+Using the {url-google-asciidoc}[AsciiDoc Processor add-on^] by https://github.com/Mogztter[Guillaume Grossetie], you can copy and paste part or all of the document from Google Docs as AsciiDoc text.
+The features that it can handle seem to be substantially fewer than pandoc but expect further development.
+The source for the add-on can be found in {url-google-asciidoc-source}[its repository^].
+
+== Plain text
+
+This method is only useful for very small files or if the other methods are not available.
+
+It keeps the text, and _fixes_ fields like auto-numbered lists and cross references.
+
+It loses tables (converted to plain paragraphs), images, symbols, form fields, and textboxes.
+
+In MS Word, use "Save as > Plain text", then when the File Conversion dialog appears, set:
+
+* Other encoding: UTF-8
+* Do not insert line breaks
+* Allow character substitution
+
+Save the file then apply AsciiDoc markup manually.
+
+Experiment with the encoding.
+Try UTF-8 first, but if you get problems you can always revert to US-ASCII.
diff --git a/docs/modules/migrate/pages/upgrade.adoc b/docs/modules/migrate/pages/upgrade.adoc
new file mode 100644
index 00000000..9ad2d9fa
--- /dev/null
+++ b/docs/modules/migrate/pages/upgrade.adoc
@@ -0,0 +1,158 @@
+= Upgrade from Asciidoctor 1.5.x to 2.0
+//Syntax, Attributes, and Commands: What's Changed?
+
+IMPORTANT: This page if for users upgrading from a previous version of Asciidoctor to the latest stable version of Asciidoctor.
+If your migrating from AsciiDoc Python, see xref:asciidoc-python.adoc[].
+
+When you upgrade Asciidoctor you may also need to update some of the syntax and attributes in your AsciiDoc documents.
+Major version releases can include new AsciiDoc syntax capabilities as well as syntax changes that make it more consistent.
+
+== Updated and deprecated features
+
+The syntax, attributes, and commands listed below have been updated or deprecated.
+In most cases, they've been replaced with a new feature that provides improved functionality.
+
+=== Inline formatting
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|_italic text_
+|pass:['italic text']
+|pass:[_italic text_]
+|1.5.0
+|Allowed with `compat-mode`
+
+|`monospace text`
+|pass:[+monospace text+]
+|pass:[`monospace text`]
+|1.5.0
+|Allowed with `compat-mode`
+
+|`+literal monospace text+`
+|pass:[`literal monospace text`]
+|pass:[`+literal monospace text+`]
+|1.5.0
+|Allowed with `compat-mode`
+
+|Curved "`double quotes`"
+|pass:[``double quotes'']
+|pass:["`double quotes`"], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8220;)
+|1.5.0
+|
+
+|Curved '`single quotes`'
+|pass:[`single quotes']
+|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \&#8217;)
+|1.5.0
+|
+|===
+
+=== Table of contents
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|Scrollable, left margin TOC
+|`toc2`
+|`+:toc: left+`
+|1.5.0
+|
+
+|TOC location
+|`toc-placement` and `toc-position`
+|`+:toc: <value>+`
+|1.5.0
+|
+
+|User-specified TOC location
+|`+:toc-placement: manual+`
+|`+:toc: macro+`
+|1.5.0
+|
+
+|===
+
+=== Document header
+
+[cols="15,20,15,5,25"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|Setext (i.e., two-line style) document title
+l|Title
+=====
+l|= Title
+|
+|Asciidoctor accepts the two-line heading style to set the document title.
+However, by using it, you implicitly set `compat-mode`.
+If you want to use the new Asciidoctor syntax, make sure to use `= Title` or explicitly unset the `compat-mode` attribute.
+|===
+
+=== API
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|render class method
+|+.render(input, options = {}) ⇒ Object+
+|+.convert(input, options = {}) ⇒ Object+
+|1.5.7
+|
+|===
+
+== New features
+
+Visit xref:ROOT:whats-new.adoc[] for a complete list of new Asciidoctor features.
+
+////
+== Proposed changes for future versions
+
+[cols="15,20,20,5,20"]
+|===
+|Feature |Deprecated |New |As of Version |Notes
+
+|Delimited open block
+|pass:[--] +
+open block content +
+pass:[--]
+|New syntax will allow for nested delimited open blocks
+|2.0
+|
+
+|Set backend
+|Set the backend from a document
+|Backends can only be set in the CLI, environment, and API
+|2.0
+|
+
+|Link attributes
+|Set `linkattrs` to use link attribute syntax
+|`linkattrs` is set implicitly so link attributes are available automatically
+|2.0
+|
+
+|UI macros
+|Set `experimental` to use the UI macros
+|UI macros are available automatically
+|2.0
+|
+
+|Document roles
+|Roles are inherited; roles don't wrap the document
+|Roles aren't inherited; roles wrap the document
+|2.0
+|
+|===
+////
+
+////
+== Compatibility mode
+
+When it isn't feasibly to update your documents prior to upgrading Asciidoctor, you can run Asciidoctor in compatibility mode.
+Compatibility mode is activated by setting the `compat-mode` attribute and allows Asciidoctor to accept and apply the deprecated syntax and/or behavior.
+However, *not all deprecated syntax or behavior is available under the compatibility mode*.
+////