asciidoctor 1.5.8 → 2.0.17

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor
-Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
-v1.5.8, 2018-10-28
+Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
+v2.0.17, 2022-01-05
 // settings:
 :idprefix:
 :idseparator: -
@@ -9,7 +9,6 @@ v1.5.8, 2018-10-28
 ifndef::env-github[:icons: font]
 ifdef::env-github[]
 :status:
-:outfilesuffix: .adoc
 :caution-caption: :fire:
 :important-caption: :exclamation:
 :note-caption: :paperclip:
@@ -17,136 +16,123 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 // Variables:
-:release-version: 1.5.8
-// URIs:
-:uri-org: https://github.com/asciidoctor
-:uri-repo: {uri-org}/asciidoctor
-:uri-asciidoctorj: {uri-org}/asciidoctorj
-:uri-asciidoctorjs: {uri-org}/asciidoctor.js
-:uri-gradle-plugin: {uri-org}/asciidoctor-gradle-plugin
-:uri-maven-plugin: {uri-org}/asciidoctor-maven-plugin
-:uri-asciidoclet: {uri-org}/asciidoclet
-:uri-project: https://asciidoctor.org
-ifdef::env-site[:uri-project: link:]
-:uri-docs: {uri-project}/docs
-:uri-news: {uri-project}/news
-:uri-manpage: {uri-project}/man/asciidoctor
-:uri-issues: {uri-repo}/issues
-:uri-contributors: {uri-repo}/graphs/contributors
-:uri-rel-file-base: link:
-:uri-rel-tree-base: link:
-ifdef::env-site[]
-:uri-rel-file-base: {uri-repo}/blob/master/
-:uri-rel-tree-base: {uri-repo}/tree/master/
+:release-version: 2.0.17
+// URLs:
+:url-org: https://github.com/asciidoctor
+:url-repo: {url-org}/asciidoctor
+:url-asciidoctorj: {url-org}/asciidoctorj
+:url-asciidoctorjs: {url-org}/asciidoctor.js
+:url-gradle-plugin: {url-org}/asciidoctor-gradle-plugin
+:url-maven-plugin: {url-org}/asciidoctor-maven-plugin
+:url-asciidoclet: {url-org}/asciidoclet
+:url-project: https://asciidoctor.org
+ifdef::env-site[:url-project: link:]
+:url-docs: https://docs.asciidoctor.org
+:url-news: {url-project}/news
+:url-manpage: {url-project}/man/asciidoctor
+:url-issues: {url-repo}/issues
+:url-contributors: {url-repo}/graphs/contributors
+:url-rel-file-base: link:
+:url-rel-tree-base: link:
+ifdef::env-site,env-yard[]
+:url-rel-file-base: {url-repo}/blob/HEAD/
+:url-rel-tree-base: {url-repo}/tree/HEAD/
 endif::[]
-:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
-:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
-:uri-license: {uri-rel-file-base}LICENSE
-:uri-tests: {uri-rel-tree-base}test
-:uri-discuss: http://discuss.asciidoctor.org
-:uri-irc: irc://irc.freenode.org/#asciidoctor
-:uri-rubygem: https://rubygems.org/gems/asciidoctor
-:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
-:uri-user-manual: {uri-docs}/user-manual
-:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
-//:uri-install-doc: {uri-docs}/install-toolchain
-:uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos
-:uri-render-doc: {uri-docs}/render-documents
-:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
-:uri-gitscm-repo: https://github.com/git/git-scm.com
-:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
-:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
-:uri-foundation: https://foundation.zurb.com
-:uri-opal: https://opalrb.com
-:uri-tilt: https://github.com/rtomayko/tilt
-:uri-ruby: https://www.ruby-lang.org
+:url-changelog: {url-rel-file-base}CHANGELOG.adoc
+:url-contribute: {url-rel-file-base}CONTRIBUTING.adoc
+:url-license: {url-rel-file-base}LICENSE
+:url-tests: {url-rel-tree-base}test
+:url-discuss: https://discuss.asciidoctor.org
+:url-chat: https://asciidoctor.zulipchat.com
+:url-rubygem: https://rubygems.org/gems/asciidoctor
+:url-what-is-asciidoc: {url-docs}/asciidoctor/latest/#relationship-to-asciidoc
+:url-install-docker: https://github.com/asciidoctor/docker-asciidoctor
+:url-opal: https://opalrb.com
+:url-tilt: https://github.com/rtomayko/tilt
+:url-ruby: https://www.ruby-lang.org
 // images:
-:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
+:image-url-screenshot: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor/screenshot.png
 
-{uri-project}[Asciidoctor] is a _fast_, {uri-license}[open source] text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook, PDF, and other formats.
-Asciidoctor is written in Ruby and runs on all major operation systems.
-To simplify installation, Asciidoctor is packaged and distributed as a gem to {uri-rubygem}[RubyGems.org] and is packaged for popular Linux distributions and macOS.
-Asciidoctor can also be run in a JVM using {uri-asciidoctorj}[AsciidoctorJ] or in any JavaScript environment using {uri-asciidoctorjs}[Asciidoctor.js].
-The Asciidoctor project is {uri-repo}[hosted on GitHub].
+{url-project}[Asciidoctor] is a fast, open source, Ruby-based text processor for parsing AsciiDoc(R) into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.
 
-ifndef::env-site[]
+Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in {url-what-is-asciidoc}[AsciiDoc].
+You can find the documentation for these projects at {url-docs}.
+
+In addition to running on Ruby, Asciidoctor can be executed on a JVM using {url-asciidoctorj}[AsciidoctorJ] or in any JavaScript environment using {url-asciidoctorjs}[Asciidoctor.js].
+
+ifndef::env-site,env-yard[]
 This document is also available in the following languages: +
-{uri-rel-file-base}README-zh_CN.adoc[汉语]
+{url-rel-file-base}README-zh_CN.adoc[汉语]
 |
-{uri-rel-file-base}README-de.adoc[Deutsch]
+{url-rel-file-base}README-de.adoc[Deutsch]
 |
-{uri-rel-file-base}README-fr.adoc[Français]
+{url-rel-file-base}README-fr.adoc[Français]
 |
-{uri-rel-file-base}README-jp.adoc[日本語]
+{url-rel-file-base}README-jp.adoc[日本語]
 endif::[]
 
 .Key documentation
 [.compact]
-* {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
-* {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
-* {uri-docs}/user-manual[Asciidoctor User Manual]
-* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
+* {url-docs}/asciidoctor/latest/[Asciidoctor Documentation]
+* {url-docs}/asciidoc/latest/[AsciiDoc Language Documentation]
+* {url-docs}/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
 
 ifdef::status[]
-.*Project health*
-image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
-image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&amp;passingText=green%20bar&amp;failingText=%23fail&amp;pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor]
-//image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor]
-//image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"]
-image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
+image:https://img.shields.io/gem/v/asciidoctor.svg[Latest Release, link={url-rubygem}]
+image:https://img.shields.io/badge/rubydoc.info-{release-version}-blue.svg[library (API) docs,link=https://www.rubydoc.info/gems/asciidoctor/{release-version}]
+image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions]
+image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Project Chat (Zulip),link={url-chat}]
 endif::[]
 
 == Sponsors
 
-We want to recognize our generous sponsors, without whose support Asciidoctor would not be possible.
-Thank you sponsors for your dedication to improving the state of technical documentation!
-
-image:https://www.okta.com/sites/all/themes/Okta/images/blog/Logos/Okta_Logo_BrightBlue_Medium.png[Okta,280,link=https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=logo&utm_campaign=sponsor,title="Add User Auth to Your Apps in Minutes with Okta"]
-&nbsp; &nbsp; &nbsp;
-image:https://secure.gravatar.com/avatar/823717a797dbd78ceff7b26aa397f383.png?size=200[OpenDevise,100,link=https://opendevise.com,title="Let the Creators of Asciidoctor and Antora Help You to Accelerate Your Docs"]
+We want to recognize our {url-project}/supporters[sponsors] for their commitment to improving the state of technical documentation by supporting this project.
+Thank you sponsors!
+Without your generous support, Asciidoctor would not be possible.
 
-Major funding for Asciidoctor is provided by our *Change Makers*, https://developer.okta.com/signup?utm_source=asciidoctor&utm_medium=text-link&utm_campaign=sponsor[Okta] and https://opendevise.com[OpenDevise], and our *Strategy Sponsors*, https://www.khronos.org/[Khronos Group] and Linda Roberts.
-Additional funding is provided by our https://asciidoctor.org/supporters[Community Backers].
+You can support this project by becoming a sponsor through https://opencollective.com/asciidoctor[OpenCollective].
 
-You can support this project by becoming a sponsor on https://opencollective.com/asciidoctor[OpenCollective].
+== AsciiDoc Processing and Built-in Converters
 
-== The Big Picture
+AsciiDoc is the language. +
+Asciidoctor is the processor.
 
-Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel.
-Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.
+Asciidoctor reads the AsciiDoc source, as shown in the panel on the left in the image below, and converts it to publishable formats, such as HTML 5, as shown rendered in the panel on the right.
 
-image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
+image::{image-url-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
 
-== AsciiDoc Processing
+Asciidoctor provides built-in {url-docs}/asciidoctor/latest/converters/[converters] for three output formats by default: {url-docs}/asciidoctor/latest/html-backend/[HTML 5], {url-docs}/asciidoctor/latest/docbook-backend/[DocBook 5], and {url-docs}/asciidoctor/latest/manpage-backend/[man page] (short for manual page).
+Additional converters, such as PDF and EPUB 3, are provided by separate gems.
+Asciidoctor also provides an out-of-the-box HTML experience complete with a {url-docs}/asciidoctor/latest/html-backend/default-stylesheet/[default stylesheet] and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).
 
-Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5, and man(ual) page output.
-You have the option of using your own converter or loading {uri-tilt}[Tilt]-supported templates to customize the generated output or produce additional formats.
+== Asciidoctor Ecosystem
 
-Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
-The Asciidoctor test suite has {uri-tests}[> 2,000 tests] to ensure compatibility with the AsciiDoc syntax.
+Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it.
+Asciidoctor can be executed on a JVM using {url-docs}/asciidoctorj/latest/[AsciidoctorJ] or in any JavaScript environment (including the browser) using {url-docs}/asciidoctor.js/latest/[Asciidoctor.js].
 
-In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., `+icon:fire[]+`) and UI elements (e.g., `+button:[Save]+`).
-Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.
+Installing an Asciidoctor processor is just the beginning of your publishing experience.
+Asciidoctor gives you access to a ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments:
 
-== Where Ruby goes, Asciidoctor follows
+* {url-docs}/diagram-extension/latest/[Asciidoctor Diagram]
+* {url-docs}/maven-tools/latest/[Maven plugin and site module]
+* {url-gradle-plugin}[Gradle plugin]
+* {url-docs}/asciidoclet/latest/[Asciidoclet]
+* {url-docs}/reveal.js-converter/latest/[reveal.js converter]
+* {url-docs}/epub3-converter/latest/[EPUB 3 converter]
+* https://intellij-asciidoc-plugin.ahus1.de/docs[IntelliJ plugin]
+* {url-docs}/asciidoctor/latest/tooling/#web-browser-add-ons-preview-only[web browser extensions]
+* {url-org}[and more]
 
-You can run Asciidoctor on the JVM using JRuby.
-To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ].
-There are plugins available for {uri-maven-plugin}[Apache Maven], {uri-gradle-plugin}[Gradle], and {uri-asciidoclet}[Javadoc], which allow you to integrate AsciiDoc processing directly into your build using AsciidoctorJ.
-
-Asciidoctor also runs in JavaScript.
-{uri-opal}[Opal] is used to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js].
-Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
-It's used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.
+Asciidoctor is the successor to AsciiDoc.py.
+If you're using AsciiDoc.py, see {url-docs}/asciidoctor/latest/migrate/asciidoc-py/[Migrate from AsciiDoc.py] to learn how to upgrade to Asciidoctor.
 
 == Requirements
 
-Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:
+Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {url-ruby}[Ruby]:
 
-* Ruby (MRI/CRuby 1.8.7 - 2.5)
-* JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
-* Rubinius 2.2.x
-* Opal (JavaScript)
+* CRuby (aka MRI) 2.3 - 3.0
+* JRuby 9.1 - 9.2
+* TruffleRuby (GraalVM)
 
 [CAUTION]
 ====
@@ -162,11 +148,11 @@ Asciidoctor works best when you use UTF-8 everywhere.
 
 == Installation
 
-Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the `gem install` command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler.
-
-The benefit of using your operating system's package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
+Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) named {url-rubygem}[asciidoctor^].
+The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).
+Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).
 
-=== (a) Linux package managers
+=== Linux package managers
 
 The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor.
 Consult the package repository for your distribution to find out which version is packaged per distribution release.
@@ -178,7 +164,7 @@ Consult the package repository for your distribution to find out which version i
 * https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)]
 * https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)]
 
-If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the <<gem-install,gem installation instructions>>.
+If you want to use a version of Asciidoctor that's newer than what is installed by the package manager, see the <<gem-install,gem installation instructions>>.
 
 ==== apk (Alpine Linux)
 
@@ -206,20 +192,33 @@ To install the package, open a terminal and type:
 
  $ sudo dnf install -y asciidoctor
 
-=== (b) Homebrew (macOS)
+=== macOS
+
+==== Homebrew
+
+You can use https://brew.sh[Homebrew], the macOS package manager, to install Asciidoctor.
+If you don't have Homebrew on your computer, complete the https://brew.sh[installation instructions] first.
 
-You can use Homebrew, the macOS package manager, to install Asciidoctor.
-If you don’t have Homebrew on your computer, complete the installation instructions at https://brew.sh/[brew.sh] first.
-Once Homebrew is installed, you’re ready to install the `asciidoctor` gem.
+Once Homebrew is installed, you're ready to install the `asciidoctor` gem.
 Open a terminal and type:
 
  $ brew install asciidoctor
 
 Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.
 
-=== (c) Windows
+==== MacPorts
 
-To use Asciidoctor with Windows, you have two easy options.
+You can also use https://www.macports.org[MacPorts], another package manager for macOS, to install Asciidoctor.
+If you don't have MacPorts on your computer, complete the https://www.macports.org/install.php[installation instructions] first.
+
+Once MacPorts is installed, you're ready to install the `asciidoctor` gem via the https://ports.macports.org/port/asciidoctor/[Asciidoctor port].
+Open a terminal and type:
+
+ $ sudo port install asciidoctor
+
+=== Windows
+
+To use Asciidoctor with Windows, you have two options.
 
 ==== Chocolatey
 
@@ -237,13 +236,14 @@ Then follow <<gem-install,gem installation instructions>>.
 Or you use the https://rubyinstaller.org/downloads/[Rubyinstaller], download the package for your Windows Version and after the installation go ahead with <<gem-install,gem installation instructions>>.
 
 [#gem-install]
-=== (d) gem install
+=== gem install
 
-Before installing Asciidoctor using `gem install`, you should use https://rvm.io[RVM] to install Ruby in your home directory (i.e., user space).
-Then, you can safely use the `gem` command to install or update the Asciidoctor gem.
+Before installing Asciidoctor using `gem install`, you should set up https://rvm.io[RVM] (or similar) to install Ruby in your home directory (i.e., user space).
+Then, you can safely use the `gem` command to install or update the Asciidoctor gem, or any other gem for that matter.
 When using RVM, gems are installed in a location isolated from the system.
+(You should never use the gem command to install system-wide gems).
 
-Open a terminal and type:
+Once you've installed Ruby using RVM, and you have activated it using `rvm use 3.0`, open a terminal and type:
 
  $ gem install asciidoctor
 
@@ -251,11 +251,11 @@ If you want to install a pre-release version (e.g., a release candidate), use:
 
  $ gem install asciidoctor --pre
 
-=== (e) Docker
+=== Docker
 
-See {uri-install-docker}[Installing Asciidoctor using Docker].
+See {url-install-docker}[Installing Asciidoctor using Docker].
 
-=== (f) Bundler
+=== Bundler
 
 . Create a Gemfile in the root folder of your project (or the current directory)
 . Add the `asciidoctor` gem to your Gemfile as follows:
@@ -305,6 +305,13 @@ To upgrade the gem, use:
  $ brew update
  $ brew upgrade asciidoctor
 
+=== MacPorts (macOS)
+
+To upgrade the gem, use:
+
+ $ sudo port selfupdate
+ $ sudo port upgrade asciidoctor
+
 === gem install
 
 If you previously installed Asciidoctor using the `gem` command, you'll need to manually upgrade Asciidoctor when a new version is released.
@@ -329,12 +336,9 @@ You should see information about the Asciidoctor version and your Ruby environme
 [.output,subs=attributes+]
 ....
 Asciidoctor {release-version} [https://asciidoctor.org]
-Runtime Environment (ruby 2.5.1p57 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
+Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
 ....
 
-Asciidoctor also provides an API.
-The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).
-
 === Command line interface (CLI)
 
 The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).
@@ -352,15 +356,18 @@ For instance, to write the file to a different directory, use:
 
  $ asciidoctor -D output README.adoc
 
-The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.
+The `asciidoctor` {url-manpage}[man page] provides a complete reference of the command line interface.
 
 Refer to the following resources to learn more about how to use the `asciidoctor` command.
 
-* {uri-render-doc}[How do I convert a document?]
-* {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
+* {url-docs}/asciidoctor/latest/cli/[Process AsciiDoc using the CLI]
+* {url-docs}/asciidoctor/latest/cli/options/[CLI options]
 
 === Ruby API
 
+Asciidoctor also provides an API.
+The API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).
+
 To use Asciidoctor in your application, you first need to require the gem:
 
 [source]
@@ -405,10 +412,14 @@ Keep in mind that if you don't like the output Asciidoctor produces, _you can ch
 Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.
 
 One easy way to customize the output piecemeal is by using the template converter.
-The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.
+The template converter allows you to supply a {url-tilt}[Tilt]-supported template file to handle converting any node in the document.
 
 However you go about it, you _can_ have 100% control over the output.
-For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].
+For more information about how to use the API or to customize the output, see:
+
+* {url-docs}/asciidoctor/latest/api/[Process AsciiDoc using the API]
+* {url-docs}/asciidoctor/latest/api/options/[API options]
+* {url-docs}/asciidoctor/latest/safe-modes/[Safe modes]
 
 == Contributing
 
@@ -427,10 +438,10 @@ Here are some ways *you* can contribute:
 ** clean up inconsistent whitespace
 ** write tests!
 * by refactoring code
-* by fixing {uri-issues}[issues]
+* by fixing {url-issues}[issues]
 * by reviewing patches
 
-The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.
+The {url-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.
 
 == Getting Help
 
@@ -438,35 +449,51 @@ Asciidoctor is developed to help you easily write and publish your content.
 But we can't do it without your feedback!
 We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.
 
-Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
-Discussion list (Nabble):: {uri-discuss}
-Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention
+Chat (Zulip):: {url-chat}
+Discussion list (Nabble):: {url-discuss}
+Twitter:: Follow https://twitter.com/asciidoctor[@asciidoctor] or search for the https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag
 
 ifdef::env-github[]
 Further information and documentation about Asciidoctor can be found on the project's website.
 
-{uri-project}[Home] | {uri-news}[News] | {uri-docs}[Docs]
+{url-project}[Home] | {url-news}[News] | {url-docs}[Docs]
 endif::[]
 
 The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.
 
-Source repository (git):: {uri-repo}
-Issue tracker:: {uri-issues}
-Asciidoctor organization on GitHub:: {uri-org}
+Source repository (git):: {url-repo}
+Issue tracker:: {url-issues}
+Asciidoctor organization on GitHub:: {url-org}
+
+== Code of Conduct
+
+The core Asciidoctor project is governed by the https://github.com/asciidoctor/.github/blob/HEAD/CODE-OF-CONDUCT.md[Code of Conduct] for the Asciidoctor community of projects.
+By participating, you're agreeing to honor this code.
+Let's work together to make this a welcoming, professional, inclusive, and safe environment for everyone.
+
+== Versioning and Release Policy
 
-== License
+This project adheres to semantic versioning (*major.minor.patch*).
+Typically, patch releases are only made for the current minor release.
+However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.
 
-Copyright (C) 2012-2018 Dan Allen, Sarah White and the individual contributors to Asciidoctor.
+== Copyright and License
+
+Copyright (C) 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.
 Use of this software is granted under the terms of the MIT License.
 
-See the {uri-license}[LICENSE] for the full license text.
+See the {url-license}[LICENSE] for the full license text.
 
 == Authors
 
-*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many individuals] in Asciidoctor's awesome community.
-The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {uri-prototype}[a prototype] written by https://github.com/nickh[Nick Hengeveld].
+*Asciidoctor* is led by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {url-contributors}[many individuals] in Asciidoctor's awesome community.
+The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] based on a prototype written by https://github.com/nickh[Nick Hengeveld] for the Git website.
+
+*AsciiDoc.py* was started and maintained by Stuart Rackham from https://github.com/asciidoc-py/asciidoc-py2/blob/HEAD/CHANGELOG.txt[2002 to 2013] and has received contributions from many individuals in the https://github.com/asciidoc-py/asciidoc-py2/graphs/contributors[AsciiDoc.py community].
+
+== Trademarks
 
-*AsciiDoc* was started by Stuart Rackham and has received contributions from many individuals in the AsciiDoc community.
+AsciiDoc(R) and AsciiDoc Language(TM) are trademarks of the Eclipse Foundation, Inc.
 
 ifndef::env-site[]
 == Changelog
@@ -475,5 +502,5 @@ ifeval::[{safe-mode-level} < 20]
 include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
 endif::[]
 
-Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
+Refer to the {url-changelog}[CHANGELOG] for a complete list of changes in older releases.
 endif::[]

data/asciidoctor.gemspec

@@ -1,59 +1,47 @@
-# encoding: UTF-8
 begin
-  require File.expand_path '../lib/asciidoctor/version', __FILE__
+  require_relative 'lib/asciidoctor/version'
 rescue LoadError
   require 'asciidoctor/version'
 end
 
-require 'open3' unless defined? Open3
-
 Gem::Specification.new do |s|
   s.name = 'asciidoctor'
   s.version = Asciidoctor::VERSION
-  s.summary = 'An implementation of the AsciiDoc text processor and publishing toolchain in Ruby'
-  s.description = 'A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats.'
+  s.summary = 'An implementation of the AsciiDoc text processor and publishing toolchain'
+  s.description = 'A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.'
   s.authors = ['Dan Allen', 'Sarah White', 'Ryan Waldron', 'Jason Porter', 'Nick Hengeveld', 'Jeremy McAnally']
   s.email = ['dan.j.allen@gmail.com']
-  s.homepage = 'http://asciidoctor.org'
+  s.homepage = 'https://asciidoctor.org'
   s.license = 'MIT'
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.3.0'
   s.metadata = {
     'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor/issues',
-    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor/blob/HEAD/CHANGELOG.adoc',
     'mailing_list_uri' => 'http://discuss.asciidoctor.org',
     'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor'
   }
 
   # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
-  files = begin
-    # NOTE popen3 is used instead of backticks to fail properly when used with JRuby
-    (result = Open3.popen3('git ls-files -z') {|_, out| out.read }.split %(\0)).empty? ? Dir['**/*'] : result
+  begin
+    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
   rescue
-    Dir['**/*']
+    files = Dir['**/*']
   end
-  s.files = files.grep %r/^(?:(?:data|lib|man)\/.+|Gemfile|Rakefile|LICENSE|(?:CHANGELOG|CONTRIBUTING|README(?:-\w+)?)\.adoc|#{s.name}\.gemspec)$/
+  s.files = files.grep %r/^(?:(?:data|lib|man)\/.+|LICENSE|(?:CHANGELOG|README(?:-\w+)?)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
   s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
   s.require_paths = ['lib']
-  s.test_files = files.grep %r/^(?:(?:features|test)\/.+)$/
-  s.rdoc_options = ['--charset=UTF-8']
-  s.extra_rdoc_files = ['CHANGELOG.adoc', 'CONTRIBUTING.adoc', 'LICENSE']
+  #s.test_files = files.grep %r/^(?:features|test)\/.+$/
 
-  # asciimath is needed for testing AsciiMath in DocBook backend
-  s.add_development_dependency 'asciimath', '~> 1.0.0'
-  # coderay is needed for testing syntax highlighting
-  s.add_development_dependency 'coderay', '~> 1.1.0'
-  s.add_development_dependency 'cucumber', '~> 2.4.0'
-  # erubis is needed for testing use of alternative eRuby impls
-  s.add_development_dependency 'erubis', '~> 2.7.0'
-  # haml is needed for testing custom templates
-  s.add_development_dependency 'haml', '~> 5.0.0'
-  s.add_development_dependency 'nokogiri', '~> 1.8.5'
-  s.add_development_dependency 'rake', '~> 10.0.0'
-  s.add_development_dependency 'rspec-expectations', '~> 2.14.0'
-  # slim is needed for testing custom templates
-  s.add_development_dependency 'slim', '~> 4.0.0'
-  # concurrent-ruby is defined in Gemfile due to enforcement of minimum required Ruby version
-  #s.add_development_dependency 'concurrent-ruby', '~> 1.0.0'
-  # tilt is needed for testing custom templates
+  # concurrent-ruby, haml, slim, and tilt are needed for testing custom templates
+  s.add_development_dependency 'concurrent-ruby', '~> 1.1.0'
+  s.add_development_dependency 'cucumber', '~> 3.1.0'
+  # erubi is needed for testing alternate eRuby impls
+  s.add_development_dependency 'erubi', '~> 1.10.0'
+  s.add_development_dependency 'haml', '~> 5.2.0'
+  s.add_development_dependency 'minitest', '~> 5.14.0'
+  s.add_development_dependency 'nokogiri', '~> 1.10.0'
+  s.add_development_dependency 'rake', '~> 12.3.0'
+  s.add_development_dependency 'slim', '~> 4.1.0'
   s.add_development_dependency 'tilt', '~> 2.0.0'
-  s.add_development_dependency 'minitest', '~> 5.3.0'
 end

data/bin/asciidoctor

@@ -1,13 +1,14 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'rubygems' unless defined? Gem
-
-if File.exist?(asciidoctor = (File.expand_path '../../lib/asciidoctor', __FILE__))
+asciidoctor = File.absolute_path '../lib/asciidoctor.rb', __dir__
+if File.exist? asciidoctor
   require asciidoctor
+  require File.join Asciidoctor::LIB_DIR, 'asciidoctor/cli'
 else
   require 'asciidoctor'
+  require 'asciidoctor/cli'
 end
-require 'asciidoctor/cli'
 
 invoker = Asciidoctor::Cli::Invoker.new ARGV
 GC.start

data/data/locale/attributes-ar.adoc

@@ -2,8 +2,8 @@
 :appendix-caption: ملحق
 :appendix-refsig: {appendix-caption}
 :caution-caption: تنبيه
-//:chapter-label: ???
-//:chapter-refsig: {chapter-label}
+//:chapter-signifier: ???
+//:chapter-refsig: {chapter-signifier}
 :example-caption: مثال
 :figure-caption: الشكل
 :important-caption: مهم
@@ -11,7 +11,8 @@
 ifdef::listing-caption[:listing-caption: قائمة]
 ifdef::manname-title[:manname-title: اسم]
 :note-caption: ملاحظة
-//:part-refsig: ???
+//:part-signifier: ???
+//:part-refsig: {part-signifier}
 ifdef::preface-title[:preface-title: تمهيد]
 //:section-refsig: ???
 :table-caption: جدول