asciidoctor 2.0.12 → 2.0.16

Sign up to get free protection for your applications and to get access to all the features.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +142 -22
  3. data/LICENSE +1 -1
  4. data/README-de.adoc +15 -6
  5. data/README-fr.adoc +14 -8
  6. data/README-jp.adoc +15 -6
  7. data/README-zh_CN.adoc +14 -5
  8. data/README.adoc +135 -125
  9. data/asciidoctor.gemspec +4 -11
  10. data/data/locale/attributes-be.adoc +23 -0
  11. data/data/locale/attributes-it.adoc +4 -4
  12. data/data/locale/attributes-nl.adoc +6 -6
  13. data/data/locale/attributes-th.adoc +23 -0
  14. data/data/locale/attributes-vi.adoc +23 -0
  15. data/data/reference/syntax.adoc +14 -7
  16. data/data/stylesheets/asciidoctor-default.css +51 -52
  17. data/lib/asciidoctor.rb +12 -12
  18. data/lib/asciidoctor/abstract_block.rb +4 -4
  19. data/lib/asciidoctor/abstract_node.rb +10 -9
  20. data/lib/asciidoctor/attribute_list.rb +6 -6
  21. data/lib/asciidoctor/block.rb +6 -6
  22. data/lib/asciidoctor/cli/invoker.rb +0 -1
  23. data/lib/asciidoctor/cli/options.rb +27 -26
  24. data/lib/asciidoctor/convert.rb +1 -0
  25. data/lib/asciidoctor/converter.rb +5 -3
  26. data/lib/asciidoctor/converter/docbook5.rb +45 -26
  27. data/lib/asciidoctor/converter/html5.rb +89 -69
  28. data/lib/asciidoctor/converter/manpage.rb +113 -86
  29. data/lib/asciidoctor/converter/template.rb +11 -12
  30. data/lib/asciidoctor/document.rb +44 -51
  31. data/lib/asciidoctor/extensions.rb +10 -12
  32. data/lib/asciidoctor/helpers.rb +3 -6
  33. data/lib/asciidoctor/list.rb +2 -6
  34. data/lib/asciidoctor/load.rb +13 -11
  35. data/lib/asciidoctor/logging.rb +10 -8
  36. data/lib/asciidoctor/parser.rb +135 -150
  37. data/lib/asciidoctor/path_resolver.rb +3 -3
  38. data/lib/asciidoctor/reader.rb +72 -71
  39. data/lib/asciidoctor/rx.rb +4 -3
  40. data/lib/asciidoctor/substitutors.rb +117 -117
  41. data/lib/asciidoctor/syntax_highlighter.rb +8 -11
  42. data/lib/asciidoctor/syntax_highlighter/coderay.rb +2 -1
  43. data/lib/asciidoctor/syntax_highlighter/highlightjs.rb +1 -1
  44. data/lib/asciidoctor/syntax_highlighter/pygments.rb +6 -5
  45. data/lib/asciidoctor/syntax_highlighter/rouge.rb +33 -26
  46. data/lib/asciidoctor/table.rb +17 -19
  47. data/lib/asciidoctor/timings.rb +3 -3
  48. data/lib/asciidoctor/version.rb +1 -1
  49. data/man/asciidoctor.1 +10 -11
  50. data/man/asciidoctor.adoc +8 -7
  51. metadata +14 -67
data/README-zh_CN.adoc CHANGED
@@ -1,6 +1,6 @@
1
1
  = Asciidoctor
2
2
  Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
3
- v2.0.12, 2020-11-10
3
+ v2.0.16, 2021-08-03
4
4
  // settings:
5
5
  :page-layout: base
6
6
  :idprefix:
@@ -9,6 +9,7 @@ v2.0.12, 2020-11-10
9
9
  :language: {source-language}
10
10
  ifndef::env-github[:icons: font]
11
11
  ifdef::env-github[]
12
+ :status:
12
13
  :outfilesuffix: .adoc
13
14
  :caution-caption: :fire:
14
15
  :important-caption: :exclamation:
@@ -17,7 +18,7 @@ ifdef::env-github[]
17
18
  :warning-caption: :warning:
18
19
  endif::[]
19
20
  // Variables:
20
- :release-version: 2.0.12
21
+ :release-version: 2.0.16
21
22
  // URIs:
22
23
  :uri-org: https://github.com/asciidoctor
23
24
  :uri-repo: {uri-org}/asciidoctor
@@ -41,7 +42,7 @@ endif::[]
41
42
  :uri-license: {uri-rel-file-base}LICENSE
42
43
  :uri-tests: {uri-rel-tree-base}test
43
44
  :uri-discuss: https://discuss.asciidoctor.org
44
- :uri-irc: irc://irc.freenode.org/#asciidoctor
45
+ :uri-chat: https://asciidoctor.zulipchat.com
45
46
  :uri-rubygem: https://rubygems.org/gems/asciidoctor
46
47
  :uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
47
48
  :uri-user-manual: {uri-docs}/user-manual
@@ -77,6 +78,14 @@ Asciidoctor 是开源的,link:{uri-repo}[代码托管在 GitHub],遵从 {uri
77
78
  * {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc 语法快速参考]
78
79
  * {uri-docs}/user-manual[Asciidoctor 用户手册]
79
80
 
81
+ ifdef::status[]
82
+ image:https://img.shields.io/gem/v/asciidoctor.svg[Latest Release, link={uri-gem}]
83
+ image:https://img.shields.io/badge/rubydoc.info-{release-version}-blue.svg[library (API) docs,link=https://www.rubydoc.info/gems/asciidoctor/{release-version}]
84
+ image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[Build Status (GitHub Actions),link={uri-repo}/actions]
85
+ image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs,link=https://inch-ci.org/github/asciidoctor/asciidoctor]
86
+ image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[project chat,link=https://asciidoctor.zulipchat.com/]
87
+ endif::[]
88
+
80
89
  .Ruby 所至, Asciidoctor 相随
81
90
  ****
82
91
  使用 JRuby 让 Asciidoctor 运行在 Java 虚拟机上。
@@ -383,9 +392,9 @@ Asciidoctor 支持自定义转化器,它可以操作从待处理文件到生
383
392
  但是,如果没有反馈,我们将寸步难行。
384
393
  我们鼓励你在讨论组、Twitter或聊天室里,提问为题,讨论项目的方方面面,
385
394
 
395
+ 聊天 (Zulip):: {uri-chat}
386
396
  讨论组 (Nabble):: {uri-discuss}
387
397
  Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] 来加入话题 或 https://twitter.com/asciidoctor[@asciidoctor] at并提醒我们
388
- 聊天 (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
389
398
 
390
399
  ifdef::env-github[]
391
400
  Further information and documentation about Asciidoctor can be found on the project's website.
@@ -402,7 +411,7 @@ Asciidoctor 组织在 GitHub 托管代码、议案跟踪和相关子项目。
402
411
  [#copyright-and-licensing]
403
412
  == 版权和协议
404
413
 
405
- Copyright (C) 2012-2020 Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.
414
+ Copyright (C) 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.
406
415
  这个软件的免费使用是在MIT许可条款授予的。
407
416
 
408
417
  请看 {uri-license}[版权声明] 文件来获取更多详细信息。
data/README.adoc CHANGED
@@ -1,6 +1,6 @@
1
1
  = Asciidoctor
2
2
  Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
3
- v2.0.12, 2020-11-10
3
+ v2.0.16, 2021-08-03
4
4
  // settings:
5
5
  :idprefix:
6
6
  :idseparator: -
@@ -17,134 +17,127 @@ ifdef::env-github[]
17
17
  :warning-caption: :warning:
18
18
  endif::[]
19
19
  // Variables:
20
- :release-version: 2.0.12
21
- // URIs:
22
- :uri-org: https://github.com/asciidoctor
23
- :uri-repo: {uri-org}/asciidoctor
24
- :uri-asciidoctorj: {uri-org}/asciidoctorj
25
- :uri-asciidoctorjs: {uri-org}/asciidoctor.js
26
- :uri-gradle-plugin: {uri-org}/asciidoctor-gradle-plugin
27
- :uri-maven-plugin: {uri-org}/asciidoctor-maven-plugin
28
- :uri-asciidoclet: {uri-org}/asciidoclet
29
- :uri-project: https://asciidoctor.org
30
- :uri-gem: https://rubygems.org/gems/asciidoctor
31
- ifdef::env-site[:uri-project: link:]
32
- :uri-docs: {uri-project}/docs
33
- :uri-news: {uri-project}/news
34
- :uri-manpage: {uri-project}/man/asciidoctor
35
- :uri-issues: {uri-repo}/issues
36
- :uri-contributors: {uri-repo}/graphs/contributors
37
- :uri-rel-file-base: link:
38
- :uri-rel-tree-base: link:
20
+ :release-version: 2.0.16
21
+ // URLs:
22
+ :url-org: https://github.com/asciidoctor
23
+ :url-repo: {url-org}/asciidoctor
24
+ :url-asciidoctorj: {url-org}/asciidoctorj
25
+ :url-asciidoctorjs: {url-org}/asciidoctor.js
26
+ :url-gradle-plugin: {url-org}/asciidoctor-gradle-plugin
27
+ :url-maven-plugin: {url-org}/asciidoctor-maven-plugin
28
+ :url-asciidoclet: {url-org}/asciidoclet
29
+ :url-project: https://asciidoctor.org
30
+ ifdef::env-site[:url-project: link:]
31
+ :url-docs: https://docs.asciidoctor.org
32
+ :url-news: {url-project}/news
33
+ :url-manpage: {url-project}/man/asciidoctor
34
+ :url-issues: {url-repo}/issues
35
+ :url-contributors: {url-repo}/graphs/contributors
36
+ :url-rel-file-base: link:
37
+ :url-rel-tree-base: link:
39
38
  ifdef::env-site,env-yard[]
40
- :uri-rel-file-base: {uri-repo}/blob/master/
41
- :uri-rel-tree-base: {uri-repo}/tree/master/
39
+ :url-rel-file-base: {url-repo}/blob/master/
40
+ :url-rel-tree-base: {url-repo}/tree/master/
42
41
  endif::[]
43
- :uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
44
- :uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
45
- :uri-license: {uri-rel-file-base}LICENSE
46
- :uri-tests: {uri-rel-tree-base}test
47
- :uri-discuss: https://discuss.asciidoctor.org
48
- :uri-irc: irc://irc.freenode.org/#asciidoctor
49
- :uri-rubygem: https://rubygems.org/gems/asciidoctor
50
- :uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
51
- :uri-user-manual: {uri-docs}/user-manual
52
- :uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
53
- //:uri-install-doc: {uri-docs}/install-toolchain
54
- :uri-install-macos-doc: {uri-docs}/install-asciidoctor-macos
55
- :uri-convert-doc: {uri-docs}/convert-documents
56
- :uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
57
- :uri-gitscm-repo: https://github.com/git/git-scm.com
58
- :uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
59
- :uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
60
- :uri-foundation: https://foundation.zurb.com
61
- :uri-opal: https://opalrb.com
62
- :uri-tilt: https://github.com/rtomayko/tilt
63
- :uri-ruby: https://www.ruby-lang.org
42
+ :url-changelog: {url-rel-file-base}CHANGELOG.adoc
43
+ :url-contribute: {url-rel-file-base}CONTRIBUTING.adoc
44
+ :url-license: {url-rel-file-base}LICENSE
45
+ :url-tests: {url-rel-tree-base}test
46
+ :url-discuss: https://discuss.asciidoctor.org
47
+ :url-chat: https://asciidoctor.zulipchat.com
48
+ :url-rubygem: https://rubygems.org/gems/asciidoctor
49
+ :url-what-is-asciidoc: {url-docs}/asciidoctor/latest/#relationship-to-asciidoc
50
+ :url-install-docker: https://github.com/asciidoctor/docker-asciidoctor
51
+ :url-opal: https://opalrb.com
52
+ :url-tilt: https://github.com/rtomayko/tilt
53
+ :url-ruby: https://www.ruby-lang.org
54
+ //:url-prototype: https://github.com/git/git-scm.com/commits/master/lib/asciidoc.rb This page doesn't exist anymore.
64
55
  // images:
65
- :image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
56
+ :image-url-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
66
57
 
67
- {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.
68
- Asciidoctor is written in Ruby and runs on all major operating systems.
69
- The Asciidoctor project is {uri-repo}[hosted on GitHub].
58
+ {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.
70
59
 
71
- To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to {uri-rubygem}[RubyGems.org].
72
- It's also distributed as a package for popular Linux distributions and macOS.
73
- In addition to running on Ruby, Asciidoctor can be executed on a JVM using {uri-asciidoctorj}[AsciidoctorJ] or in any JavaScript environment (including the browser) using {uri-asciidoctorjs}[Asciidoctor.js].
60
+ 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].
61
+ You can find the documentation for these projects at {url-docs}.
62
+
63
+ 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].
74
64
 
75
65
  ifndef::env-site,env-yard[]
76
66
  This document is also available in the following languages: +
77
- {uri-rel-file-base}README-zh_CN.adoc[汉语]
67
+ {url-rel-file-base}README-zh_CN.adoc[汉语]
78
68
  |
79
- {uri-rel-file-base}README-de.adoc[Deutsch]
69
+ {url-rel-file-base}README-de.adoc[Deutsch]
80
70
  |
81
- {uri-rel-file-base}README-fr.adoc[Français]
71
+ {url-rel-file-base}README-fr.adoc[Français]
82
72
  |
83
- {uri-rel-file-base}README-jp.adoc[日本語]
73
+ {url-rel-file-base}README-jp.adoc[日本語]
84
74
  endif::[]
85
75
 
86
76
  .Key documentation
87
77
  [.compact]
88
- * {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
89
- * {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
90
- * {uri-docs}/user-manual[Asciidoctor User Manual]
91
- * {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
78
+ * {url-docs}/asciidoctor/latest/[Asciidoctor Documentation]
79
+ * {url-docs}/asciidoc/latest/[AsciiDoc Language Documentation]
80
+ * {url-docs}/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
92
81
 
93
82
  ifdef::status[]
94
- //.*Project health*
95
- image:https://img.shields.io/gem/v/asciidoctor.svg[Latest Release, link={uri-gem}]
83
+ image:https://img.shields.io/gem/v/asciidoctor.svg[Latest Release, link={url-rubygem}]
96
84
  image:https://img.shields.io/badge/rubydoc.info-{release-version}-blue.svg[library (API) docs,link=https://www.rubydoc.info/gems/asciidoctor/{release-version}]
97
- image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[Build Status (GitHub Actions),link={uri-repo}/actions]
98
- //image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status,link=https://coveralls.io/r/asciidoctor/asciidoctor]
85
+ image:https://github.com/asciidoctor/asciidoctor/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions]
86
+ //image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Code Coverage,link=https://coveralls.io/r/asciidoctor/asciidoctor]
99
87
  //image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate,link=https://codeclimate.com/github/asciidoctor/asciidoctor]
100
- image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs,link=https://inch-ci.org/github/asciidoctor/asciidoctor]
88
+ //image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Docs Coverage,link=https://inch-ci.org/github/asciidoctor/asciidoctor]
89
+ image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Project Chat (Zulip),link={url-chat}]
101
90
  endif::[]
102
91
 
103
92
  == Sponsors
104
93
 
105
- We want to recognize our {uri-project}/supporters[sponsors] for their commitment to improving the state of technical documentation by supporting this project.
94
+ We want to recognize our {url-project}/supporters[sponsors] for their commitment to improving the state of technical documentation by supporting this project.
106
95
  Thank you sponsors!
107
96
  Without your generous support, Asciidoctor would not be possible.
108
97
 
109
98
  You can support this project by becoming a sponsor through https://opencollective.com/asciidoctor[OpenCollective].
110
99
 
111
- == The Big Picture
100
+ == AsciiDoc Processing and Built-in Converters
112
101
 
113
- 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.
114
- Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.
102
+ AsciiDoc is the language. +
103
+ Asciidoctor is the processor.
115
104
 
116
- image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
105
+ 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.
117
106
 
118
- == AsciiDoc Processing
107
+ image::{image-url-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
119
108
 
120
- 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.
121
- 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.
109
+ 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).
110
+ Additional converters, such as PDF and EPUB 3, are provided by separate gems.
111
+ 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).
122
112
 
123
- Asciidoctor is a drop-in replacement for its predecessor, AsciiDoc Python (`asciidoc.py`).
124
- The Asciidoctor test suite has {uri-tests}[> 2,350 tests] to ensure compatibility with the AsciiDoc syntax.
113
+ == Asciidoctor Ecosystem
125
114
 
126
- 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]+`).
127
- Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.
115
+ Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it.
116
+ 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].
128
117
 
129
- == Where Ruby goes, Asciidoctor follows
118
+ Installing an Asciidoctor processor is just the beginning of your publishing experience.
119
+ 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:
130
120
 
131
- You can run Asciidoctor on the JVM using JRuby.
132
- To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ].
133
- 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.
121
+ * {url-docs}/diagram-extension/latest/[Asciidoctor Diagram]
122
+ * {url-docs}/maven-tools/latest/[Maven plugin and site module]
123
+ * {url-gradle-plugin}[Gradle plugin]
124
+ * {url-docs}/asciidoclet/latest/[Asciidoclet]
125
+ * {url-docs}/reveal.js-converter/latest/[reveal.js converter]
126
+ * {url-docs}/epub3-converter/latest/[EPUB 3 converter]
127
+ * https://intellij-asciidoc-plugin.ahus1.de/docs[IntelliJ plugin]
128
+ * {url-docs}/asciidoctor/latest/tooling/#web-browser-add-ons-preview-only[web browser extensions]
129
+ * {url-org}[and more]
134
130
 
135
- Asciidoctor also runs in JavaScript.
136
- {uri-opal}[Opal] is used to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js].
137
- Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
138
- It's used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.
131
+ Asciidoctor is the successor to AsciiDoc.py.
132
+ 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.
139
133
 
140
134
  == Requirements
141
135
 
142
- Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:
136
+ Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of {url-ruby}[Ruby]:
143
137
 
144
- * CRuby (aka MRI) 2.3 - 2.6
138
+ * CRuby (aka MRI) 2.3 - 3.0
145
139
  * JRuby 9.1 - 9.2
146
140
  * TruffleRuby (GraalVM)
147
- * Opal (JavaScript)
148
141
 
149
142
  [CAUTION]
150
143
  ====
@@ -160,11 +153,11 @@ Asciidoctor works best when you use UTF-8 everywhere.
160
153
 
161
154
  == Installation
162
155
 
163
- 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 or if you'll be installing additional gems), (d) the Asciidoctor Docker image, or (e) Bundler.
164
-
165
- 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.
156
+ Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) named {url-rubygem}[asciidoctor^].
157
+ The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle).
158
+ Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew).
166
159
 
167
- === (a) Linux package managers
160
+ === Linux package managers
168
161
 
169
162
  The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor.
170
163
  Consult the package repository for your distribution to find out which version is packaged per distribution release.
@@ -176,7 +169,7 @@ Consult the package repository for your distribution to find out which version i
176
169
  * https://software.opensuse.org/package/rubygem-asciidoctor[OpenSUSE (rubygem-asciidoctor)]
177
170
  * https://packages.ubuntu.com/search?keywords=asciidoctor[Ubuntu (asciidoctor)]
178
171
 
179
- 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>>.
172
+ 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>>.
180
173
 
181
174
  ==== apk (Alpine Linux)
182
175
 
@@ -204,7 +197,7 @@ To install the package, open a terminal and type:
204
197
 
205
198
  $ sudo dnf install -y asciidoctor
206
199
 
207
- === (b) Homebrew (macOS)
200
+ === Homebrew (macOS)
208
201
 
209
202
  You can use Homebrew, the macOS package manager, to install Asciidoctor.
210
203
  If you don’t have Homebrew on your computer, complete the installation instructions at https://brew.sh/[brew.sh] first.
@@ -215,9 +208,9 @@ Open a terminal and type:
215
208
 
216
209
  Homebrew installs the `asciidoctor` gem into an exclusive prefix that's independent of system gems.
217
210
 
218
- === (c) Windows
211
+ === Windows
219
212
 
220
- To use Asciidoctor with Windows, you have two easy options.
213
+ To use Asciidoctor with Windows, you have two options.
221
214
 
222
215
  ==== Chocolatey
223
216
 
@@ -235,13 +228,14 @@ Then follow <<gem-install,gem installation instructions>>.
235
228
  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>>.
236
229
 
237
230
  [#gem-install]
238
- === (d) gem install
231
+ === gem install
239
232
 
240
- Before installing Asciidoctor using `gem install`, you should set up https://rvm.io[RVM] to install Ruby in your home directory (i.e., user space).
233
+ 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).
241
234
  Then, you can safely use the `gem` command to install or update the Asciidoctor gem, or any other gem for that matter.
242
235
  When using RVM, gems are installed in a location isolated from the system.
236
+ (You should never use the gem command to install system-wide gems).
243
237
 
244
- Once you've installed Ruby using RVM, and you have activated it using `rvm use 2.6`, open a terminal and type:
238
+ Once you've installed Ruby using RVM, and you have activated it using `rvm use 3.0`, open a terminal and type:
245
239
 
246
240
  $ gem install asciidoctor
247
241
 
@@ -249,11 +243,11 @@ If you want to install a pre-release version (e.g., a release candidate), use:
249
243
 
250
244
  $ gem install asciidoctor --pre
251
245
 
252
- === (e) Docker
246
+ === Docker
253
247
 
254
- See {uri-install-docker}[Installing Asciidoctor using Docker].
248
+ See {url-install-docker}[Installing Asciidoctor using Docker].
255
249
 
256
- === (f) Bundler
250
+ === Bundler
257
251
 
258
252
  . Create a Gemfile in the root folder of your project (or the current directory)
259
253
  . Add the `asciidoctor` gem to your Gemfile as follows:
@@ -327,12 +321,9 @@ You should see information about the Asciidoctor version and your Ruby environme
327
321
  [.output,subs=attributes+]
328
322
  ....
329
323
  Asciidoctor {release-version} [https://asciidoctor.org]
330
- Runtime Environment (ruby 2.6.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
324
+ Runtime Environment (ruby 3.0.1p64 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
331
325
  ....
332
326
 
333
- Asciidoctor also provides an API.
334
- 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]).
335
-
336
327
  === Command line interface (CLI)
337
328
 
338
329
  The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).
@@ -350,15 +341,18 @@ For instance, to write the file to a different directory, use:
350
341
 
351
342
  $ asciidoctor -D output README.adoc
352
343
 
353
- The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.
344
+ The `asciidoctor` {url-manpage}[man page] provides a complete reference of the command line interface.
354
345
 
355
346
  Refer to the following resources to learn more about how to use the `asciidoctor` command.
356
347
 
357
- * {uri-convert-doc}[How do I convert a document?]
358
- * {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
348
+ * {url-docs}/asciidoctor/latest/cli/[Process AsciiDoc using the CLI]
349
+ * {url-docs}/asciidoctor/latest/cli/options/[CLI options]
359
350
 
360
351
  === Ruby API
361
352
 
353
+ Asciidoctor also provides an API.
354
+ 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).
355
+
362
356
  To use Asciidoctor in your application, you first need to require the gem:
363
357
 
364
358
  [source]
@@ -403,10 +397,14 @@ Keep in mind that if you don't like the output Asciidoctor produces, _you can ch
403
397
  Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.
404
398
 
405
399
  One easy way to customize the output piecemeal is by using the template converter.
406
- The template converter allows you to supply a {uri-tilt}[Tilt]-supported template file to handle converting any node in the document.
400
+ The template converter allows you to supply a {url-tilt}[Tilt]-supported template file to handle converting any node in the document.
407
401
 
408
402
  However you go about it, you _can_ have 100% control over the output.
409
- For more information about how to use the API or to customize the output, refer to the {uri-user-manual}[user manual].
403
+ For more information about how to use the API or to customize the output, see:
404
+
405
+ * {url-docs}/asciidoctor/latest/api/[Process AsciiDoc using the API]
406
+ * {url-docs}/asciidoctor/latest/api/options/[API options]
407
+ * {url-docs}/asciidoctor/latest/safe-modes/[Safe modes]
410
408
 
411
409
  == Contributing
412
410
 
@@ -425,10 +423,10 @@ Here are some ways *you* can contribute:
425
423
  ** clean up inconsistent whitespace
426
424
  ** write tests!
427
425
  * by refactoring code
428
- * by fixing {uri-issues}[issues]
426
+ * by fixing {url-issues}[issues]
429
427
  * by reviewing patches
430
428
 
431
- The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.
429
+ The {url-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.
432
430
 
433
431
  == Getting Help
434
432
 
@@ -436,39 +434,51 @@ Asciidoctor is developed to help you easily write and publish your content.
436
434
  But we can't do it without your feedback!
437
435
  We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.
438
436
 
439
- Chat (Gitter):: image:https://badges.gitter.im/Join%20In.svg[Gitter, link=https://gitter.im/asciidoctor/asciidoctor]
440
- Discussion list (Nabble):: {uri-discuss}
441
- Twitter:: https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag or https://twitter.com/asciidoctor[@asciidoctor] mention
437
+ Chat (Zulip):: {url-chat}
438
+ Discussion list (Nabble):: {url-discuss}
439
+ Twitter:: Follow https://twitter.com/asciidoctor[@asciidoctor] or search for the https://twitter.com/search?f=tweets&q=%23asciidoctor[#asciidoctor] hashtag
442
440
 
443
441
  ifdef::env-github[]
444
442
  Further information and documentation about Asciidoctor can be found on the project's website.
445
443
 
446
- {uri-project}[Home] | {uri-news}[News] | {uri-docs}[Docs]
444
+ {url-project}[Home] | {url-news}[News] | {url-docs}[Docs]
447
445
  endif::[]
448
446
 
449
447
  The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.
450
448
 
451
- Source repository (git):: {uri-repo}
452
- Issue tracker:: {uri-issues}
453
- Asciidoctor organization on GitHub:: {uri-org}
449
+ Source repository (git):: {url-repo}
450
+ Issue tracker:: {url-issues}
451
+ Asciidoctor organization on GitHub:: {url-org}
452
+
453
+ == Code of Conduct
454
+
455
+ The core Asciidoctor project is governed by the https://github.com/asciidoctor/.github/blob/main/CODE-OF-CONDUCT.md[Code of Conduct] for the Asciidoctor community of projects.
456
+ By participating, you're agreeing to honor this code.
457
+ Let's work together to make this a welcoming, professional, inclusive, and safe environment for everyone.
458
+
459
+ == Versioning and Release Policy
460
+
461
+ This project adheres to semantic versioning (*major.minor.patch*).
462
+ Typically, patch releases are only made for the current minor release.
463
+ However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.
454
464
 
455
465
  == Copyright and License
456
466
 
457
- Copyright (C) 2012-2020 Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.
467
+ Copyright (C) 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor.
458
468
  Use of this software is granted under the terms of the MIT License.
459
469
 
460
- See the {uri-license}[LICENSE] for the full license text.
470
+ See the {url-license}[LICENSE] for the full license text.
461
471
 
462
472
  == Authors
463
473
 
464
- *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.
465
- 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].
474
+ *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.
475
+ 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.
466
476
 
467
- *AsciiDoc* was started and maintained by Stuart Rackham from https://github.com/asciidoc/asciidoc/blob/master/CHANGELOG.txt[2002 to 2013] and has received contributions from many individuals in the https://github.com/asciidoc/asciidoc/graphs/contributors[AsciiDoc community].
477
+ *AsciiDoc.py* was started and maintained by Stuart Rackham from https://github.com/asciidoc-py/asciidoc-py2/blob/master/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].
468
478
 
469
479
  == Trademarks
470
480
 
471
- AsciiDoc is a Trademark of the Eclipse Foundation, Inc.
481
+ AsciiDoc(R) and AsciiDoc Language(TM) are trademarks of the Eclipse Foundation, Inc.
472
482
 
473
483
  ifndef::env-site[]
474
484
  == Changelog
@@ -477,5 +487,5 @@ ifeval::[{safe-mode-level} < 20]
477
487
  include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
478
488
  endif::[]
479
489
 
480
- Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.
490
+ Refer to the {url-changelog}[CHANGELOG] for a complete list of changes in older releases.
481
491
  endif::[]