From c99aec4c318f4bcee48064182e9df8a5bc50d9c8 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Mon, 3 Jan 2022 14:05:40 -0700 Subject: [PATCH] update Asciidoctor upgrade notes page --- .../ROOT/pages/asciidoctor-upgrade-notes.adoc | 104 ++++++++++++++---- 1 file changed, 84 insertions(+), 20 deletions(-) diff --git a/docs/modules/ROOT/pages/asciidoctor-upgrade-notes.adoc b/docs/modules/ROOT/pages/asciidoctor-upgrade-notes.adoc index d32383797..10e1c3cff 100644 --- a/docs/modules/ROOT/pages/asciidoctor-upgrade-notes.adoc +++ b/docs/modules/ROOT/pages/asciidoctor-upgrade-notes.adoc @@ -5,7 +5,9 @@ Asciidoctor 2 introduces many new features and a few substantive changes to exis == Asciidoctor 2 feature changes -The following table describes the new behavior of existing Asciidoctor features and suggests the actions you should take prior to upgrading to Antora {page-component-version}. +The following sections describe the new behavior of existing Asciidoctor features and suggest the actions you should take prior to upgrading to Antora {page-component-version}. + +=== Non-AsciiDoc files and the include directive |=== |Feature |New behavior |Action @@ -22,6 +24,12 @@ This can change how the output is displayed. |Including non-AsciiDoc files with callouts into a verbatim block using the include directive |Since trailing spaces aren't removed, callout numbers may no longer be detected. +|=== + +=== Listing and source blocks + +|=== +|Feature |New behavior |Action |Delimited listing blocks without an explicit style when `source-language` is set |Delimited listing blocks (`+----+`) that don't have an explicit style are automatically promoted to source blocks if `source-language` is set in the document, component descriptor, or playbook. @@ -45,30 +53,84 @@ Otherwise, do one of the following: * assign the appropriate language to the source block, or * remove the `source` style and replace it with the `listing` style, or * remove the `source` style and change the block to a delimited literal block (`+....+`). +|=== -|Section and block title substitution order -|The order of substitutions applied to section and block titles now matches the normal substitution order. -This can affect section and block titles that use attribute references. -|Review section and block titles that contain attribute references for errors. +=== Tables + +|=== +|Feature |New behavior |Action |`a` and `l` column modifiers |Normal substitutions and default header formatting are now correctly applied to the cells in an implicit header row when the AsciiDoc (`a`) and literal (`l`) modifiers are applied to the columns in a table. |Update tables that use the `a` and `l` modifiers in combination with an implicit header row so your desired output is displayed. +|`v` modifier +|The verse modifier (`v`) is deprecated. +Columns or cells assigned the `v` modifier are now treated as regular table cells. +|No action is needed if it's acceptable for the cell content to be displayed as regular content. + |`table-topbot` CSS class |The CSS class `table-ends` replaces the deprecated `table-topbot` CSS class. |If you customized the styles for `table-topbot` in your UI, update the class name to `table-ends` and build a new UI bundle version. +|Table column width +|The rounding used when calculating table column widths changed minutely. +|No action is needed as the change shouldn't be noticeable to site visitors. +|=== + +=== Lists + +|=== +|Feature |New behavior |Action + +|Description list delimiters (`::`) +|Description list delimiters, that is, double colons (`::`) that are bare or at the start of line are no longer mistaken for a description list item. +|Remove escape syntax around double colons (`::`) that were previously mistaken for description list delimiters. +|=== + +=== Section and block titles + +|=== +|Feature |New behavior |Action + +|Section and block title substitution order +|The order of substitutions applied to section and block titles now matches the normal substitution order. +This can affect section and block titles that use attribute references. +|Review section and block titles that contain attribute references for errors. +|=== + +=== Invalid and unresolved references and attributes + +|=== +|Feature |New behavior |Action + |"`Unresolved include directive`" message in the content |The message has changed to "`Unresolved directive`". |No action unless you're using a postprocessor that looks for this message in the output. +|`page unresolved` class +|The class `page unresolved` in now added to the output when the target of an xref is an invalid resource ID. +Previously, this was only added when the target of an xref was a valid resource ID that couldn't be resolved. +|No action unless you're using a postprocessor that looks for this class in the output. + +|Reference validation for inline anchor +|If Asciidoctor cannot locate a reference to an inline anchor, even if it exists, it will log a message at the info level about a possible invalid reference. +|Define inline anchors using the double square bracket enclosure, and only place them in locations where Asciidoctor scans for them. +Valid locations include anywhere in paragraph text or at the start of a list item or table cell. +You could also ignore these messages or not enable the info log level. + |`attribute-missing` |The `attribute-missing` setting is now honored when include directives and block macros are processed. This may reveal new missing include files and references. |Check the log messages for new warnings and fix any reported errors. +|=== + +=== Footnotes + +|=== +|Feature |New behavior |Action -|Footnotes +|Footnote macro |The `footnoteref` macro is deprecated and the structure of the `footnote` macro has changed to be consistent with other AsciiDoc macros. Previously, the footnote target was placed inside the macro's square brackets. Now the target is placed directly after the colon (`+footnote:[]+`). @@ -77,25 +139,27 @@ Now the target is placed directly after the colon (`+footnote:[