diff options
Diffstat (limited to 'docs/modules/migrate/pages/asciidoc-python.adoc')
| -rw-r--r-- | docs/modules/migrate/pages/asciidoc-python.adoc | 368 |
1 files changed, 368 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..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. +//// |