From 4d2e89cb49755ff483a33a936ec404b287ce2e07 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Mon, 21 Dec 2020 15:51:09 -0700 Subject: rename asciidoc-python.adoc to asciidoc-py and use AsciiDoc.py to refer to original processor --- docs/modules/ROOT/pages/converters.adoc | 2 +- docs/modules/ROOT/pages/index.adoc | 4 +- docs/modules/ROOT/pages/localization-support.adoc | 2 +- docs/modules/ROOT/pages/whats-new.adoc | 2 +- docs/modules/migrate/nav.adoc | 2 +- docs/modules/migrate/pages/asciidoc-py.adoc | 394 +++++++++++++++++++++ docs/modules/migrate/pages/asciidoc-python.adoc | 395 ---------------------- docs/modules/migrate/pages/upgrade.adoc | 2 +- 8 files changed, 401 insertions(+), 402 deletions(-) create mode 100644 docs/modules/migrate/pages/asciidoc-py.adoc delete mode 100644 docs/modules/migrate/pages/asciidoc-python.adoc (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/converters.adoc b/docs/modules/ROOT/pages/converters.adoc index 31c54489..d46e8a7d 100644 --- a/docs/modules/ROOT/pages/converters.adoc +++ b/docs/modules/ROOT/pages/converters.adoc @@ -88,7 +88,7 @@ The tool provides built-in theming via a YAML configuration file, which is docum TIP: Asciidoctor PDF is the preferred tool for converting to PDF and is fully supported by the Asciidoctor community. a2x:: -A DocBook toolchain frontend provided by that AsciiDoc Python project. +A DocBook toolchain frontend provided by that AsciiDoc.py project. + To use this tool, you should first convert to DocBook using Asciidoctor, then convert the DocBook to PDF using a2x. a2x accepts a DocBook file as input and can convert it to a PDF using either Apache FOP or dblatex. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 0644b608..d74c563f 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -18,8 +18,8 @@ Asciidoctor is also distributed as a package for numerous Linux distributions as Asciidoctor is open source software that is available under the terms of the MIT license and {url-org}[hosted on GitHub^]. -Asciidoctor is the successor to AsciiDoc Python (AsciiDoc.py). -If you're using AsciiDoc.py, follow xref:migrate:asciidoc-python.adoc[] to learn how to upgrade to Asciidoctor. +Asciidoctor is the successor to AsciiDoc.py (aka AsciiDoc Python). +If you're using AsciiDoc.py, follow xref:migrate:asciidoc-py.adoc[] to learn how to upgrade to Asciidoctor. == Basic usage diff --git a/docs/modules/ROOT/pages/localization-support.adoc b/docs/modules/ROOT/pages/localization-support.adoc index 5a357f33..cf2d0bc0 100644 --- a/docs/modules/ROOT/pages/localization-support.adoc +++ b/docs/modules/ROOT/pages/localization-support.adoc @@ -18,7 +18,7 @@ See {url-org}/asciidoctor/issues/1601[issue #1601^] for details. In the interim, you can leverage the DocBook toolchain to get right-to-left support. * Attributes that store dates and times (e.g., `docdatetime`) are always formatted like `2019-01-04 19:26:06 GMT+0000`. * Message (aka logging) strings are always in English. -* Asciidoctor does not support the language conf files used by AsciiDoc Python. +* Asciidoctor does not support the language conf files used by AsciiDoc.py. However, Asciidoctor does provide {url-lang-attributes}[a translation file^] that can be used for a similar purpose. [#customizing-labels] diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index 7c7b2305..7a0c6384 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -389,7 +389,7 @@ _**Release date:** 2019.03.22_ == Build and infrastructure * clear SOURCE_DATE_EPOCH env var when testing timezones (PR #2969) (*@aerostitch*) -* remove compat folder (removes the AsciiDoc Python config file that provides pseudo-compliance with Asciidoctor and a stylesheet for an old Font Awesome migration) +* remove compat folder (removes the AsciiDoc.py config file that provides pseudo-compliance with Asciidoctor and a stylesheet for an old Font Awesome migration) * add Ruby 2.6.0 to build matrix * stop running CI job on unsupported versions of Ruby * exclude test suite, build script, and Gemfile from gem (#3044) diff --git a/docs/modules/migrate/nav.adoc b/docs/modules/migrate/nav.adoc index 6df6ade3..2c35826a 100644 --- a/docs/modules/migrate/nav.adoc +++ b/docs/modules/migrate/nav.adoc @@ -1,6 +1,6 @@ * Migration Guides ** xref:upgrade.adoc[] -** xref:asciidoc-python.adoc[] +** xref:asciidoc-py.adoc[] ** xref:docbook-xml.adoc[] ** xref:markdown.adoc[] ** xref:confluence-xhtml.adoc[] diff --git a/docs/modules/migrate/pages/asciidoc-py.adoc b/docs/modules/migrate/pages/asciidoc-py.adoc new file mode 100644 index 00000000..a5f1cac8 --- /dev/null +++ b/docs/modules/migrate/pages/asciidoc-py.adoc @@ -0,0 +1,394 @@ += 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/ + +AsciiDoc.py (aka AsciiDoc Python) is the original AsciiDoc processor, which has now been superseded by Asciidoctor. +If you're currently using AsciiDoc.py to convert your AsciiDoc documents and are ready 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.6. + +== Processor call + +The Asciidoctor processor is a drop-in replacement for AsciiDoc.py. +You can simply replace the call to AsciiDoc.py (`asciidoc`) with the equivalent call to Asciidoctor (`asciidoctor`). + + $ asciidoctor 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: + + $ 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 (i.e., `backend=html5`) and the `html` backend maps to `html5`. + +== 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=`. + +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 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 + +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 + +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 + +[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 `+[.]+` 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 `+[.]+` 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: +` +|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 `` 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[] + ++++ + Your comment here + ++++ + 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 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 + +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. +//// diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc deleted file mode 100644 index 3a1728dc..00000000 --- a/docs/modules/migrate/pages/asciidoc-python.adoc +++ /dev/null @@ -1,395 +0,0 @@ -= 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 - -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. -You can simply replace the call to AsciiDoc.py (`asciidoc`) with the equivalent call to Asciidoctor (`asciidoctor`). - - $ asciidoctor 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: - - $ 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 (i.e., `backend=html5`) and the `html` backend maps to `html5`. - -== 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=`. - -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 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 - -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 - -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 - -[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 `+[.]+` 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 `+[.]+` 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: +` -|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 `` 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[] - ++++ - Your comment here - ++++ - 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 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 - -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. -//// diff --git a/docs/modules/migrate/pages/upgrade.adoc b/docs/modules/migrate/pages/upgrade.adoc index 7fae3f9b..6a270979 100644 --- a/docs/modules/migrate/pages/upgrade.adoc +++ b/docs/modules/migrate/pages/upgrade.adoc @@ -1,7 +1,7 @@ = Upgrade from Asciidoctor 1.5.x to 2.0 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[]. +If your migrating from AsciiDoc.py, see xref:asciidoc-py.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. -- cgit v1.2.3