diff options
Diffstat (limited to 'docs/modules/migrate')
| -rw-r--r-- | docs/modules/migrate/examples/convert.groovy | 43 | ||||
| -rw-r--r-- | docs/modules/migrate/nav.adoc | 7 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/asciidoc-python.adoc | 368 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/confluence-xhtml.adoc | 29 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/docbook-xml.adoc | 19 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/markdown.adoc | 6 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/ms-word.adoc | 196 | ||||
| -rw-r--r-- | docs/modules/migrate/pages/upgrade.adoc | 158 |
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., \“) +| + +|Curved '`single quotes`' +|pass:[`single quotes'] +|pass:['`single quotes`'], editor keybinding, or the Unicode character in numeric character reference form (e.g., \’) +| + +|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., \“) +|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., \’) +|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*. +//// |