Summary
This is an important patch release that resolves a significant regression in the include directive introduced in 2.0.11, patches a discovered security vulnerability with the counter attribute directives, fixes numerous bugs in the man page converter, and brings a handful of other fixes and improvements. We strongly recommend upgrading to this version. This release will also be the candidate for making the switch to Asciidoctor 2 upgrade in Antora.
In an attempt to fix the detection of a document header inside an include file, the processor was changed in 2.0.11 to remove leading and trailing empty lines in included AsciiDoc content. This turned out to be the wrong decision because it broke documents that relied on these empty lines to separate blocks. It also didn't fully address the problem. That change has been rolled back and the correct fix applied. We also discovered that it was possible to assign a value to an attribute locked by the API using the counter and counter2 attribute directives. This back door has been closed so that the locked state of the attribute is closed. The processor was also updated so non-ASCII characters used as the value of a counter attribute no longer cause the processor to crash. Thanks to a handful of reports filed by the community, we were able to substantially improve the man page output, including adding support for footnotes and page breaks, not mangling formatting macros when transforming section titles to uppercase, and substituting attribute references in the purpose part of the name section. Thanks to @slonopotamus, the Pygments adapter was updated to support the pygments.rb 2 gem in addition to the pygments.rb 1 gem. You're encouraged to upgrade to pygments.rb 2 as it is both maintained and more stable. If you're using Rouge, thanks to @Oblomov, you should now find it easier to extend the built-in adapter to customize the lexer or formatter as the logic to instantiate them have been extracted so they can be overridden. Finally, to silence all log messages when using the API, you can pass the logger: nil option.
Consult the CHANGELOG to find the full list of changes in this release.
During this release cycle, the documentation for the Asciidoctor processor was imported into this repository and is published on the new https://docs.asciidoctor.org site powered by Antora. Thanks to @graphitefriction for her incredibly hard work to make that happen.
Distributions
Asciidoctor is also packaged for Fedora, Debian, Ubuntu, Alpine Linux, OpenSUSE, and Homebrew. You can use the system's package manager to install the package named asciidoctor.
Release meta
Released on: 2021-04-10
Released by: @mojavelinux
Release beer: Rumpin by Avery Brewing Company
Logs: resolved issues | full diff | issues resolved in 2.0.x (cumulative)
Changelog
Bug Fixes
- Don't allow counter and counter2 attribute directives to override locked attributes (#3939)
- Fix crash when resolving next value in sequence for counter with non-numeric value (#3940)
- Rollback change for #3470, which added logic to remove leading and trailing empty lines in an AsciiDoc include file; instead skip empty lines before processing document header (#3997)
- Update default stylesheet to remove dash in front of cite on nested quote block (#3847)
- Don't mangle formatting macros when uppercasing section titles in man page output (#3892)
- Don't escape hyphen in manname in man page output
- Remove extra .sp before content of verse block in man page output
- Fix layout of footnotes in man page output (#3989)
- Fix formatting of footnote text with URL in man page output (#3988)
- Remove redundant trailing space on URL followed by non-adjacent text in man page output (#4004)
- Use .bp macro at location of page break in man page output (#3992)
Improvements
- Extract method to create lexer and formatter in Rouge adapter (#3953) (@Oblomov)
- Add support for pygments.rb 2.x (#3969) (@slonopotamus)
- Allow NullLogger to be enabled by setting the
:loggeroption to a falsy value (#3982) - Substitute attributes in manpurpose in NAME section of man page (#4000)
- Output all mannames in name section of HTML output for manpage doctype (#3757)
Build / Infrastructure
- Import documentation for processor into this repository (#3861) (@graphitefriction)
- Run tests against both pygments.rb 1.x and 2.x (#3969) (@slonopotamus)
Documentation
Credits
A very special thanks to all the awesome supporters of the Asciidoctor OpenCollective campaign who provided critical funding for the development of this release as well as ongoing development of the project. We'd also like to thank the maintainers of the Rouge project, who helped us work through the compatibility issue with Rouge and applied a fix to restore it ahead of our own release.