diff -Nru asciidoctor-2.0.18/asciidoctor.gemspec asciidoctor-2.0.20/asciidoctor.gemspec --- asciidoctor-2.0.18/asciidoctor.gemspec 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/asciidoctor.gemspec 2023-05-18 07:16:38.000000000 +0000 @@ -38,9 +38,9 @@ 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 'haml', '~> 6.1.0' s.add_development_dependency 'minitest', '~> 5.14.0' - s.add_development_dependency 'nokogiri', '~> 1.10.0' + s.add_development_dependency 'nokogiri', '~> 1.13.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' diff -Nru asciidoctor-2.0.18/CHANGELOG.adoc asciidoctor-2.0.20/CHANGELOG.adoc --- asciidoctor-2.0.18/CHANGELOG.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/CHANGELOG.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,21 +1,76 @@ = Asciidoctor Changelog -:uri-asciidoctor: https://asciidoctor.org -:uri-asciidoc: {uri-asciidoctor}/docs/what-is-asciidoc -:uri-repo: https://github.com/asciidoctor/asciidoctor +:url-asciidoctor: https://asciidoctor.org +:url-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/ +:url-repo: https://github.com/asciidoctor/asciidoctor :icons: font :star: icon:star[role=red] ifndef::icons[] :star: ★ endif::[] -{uri-asciidoctor}[Asciidoctor] is a _fast_, open source text processor and publishing toolchain for converting {uri-asciidoc}[AsciiDoc] content into HTML 5, DocBook 5, and other formats. +{url-asciidoctor}[Asciidoctor] is a _fast_, open source text processor and publishing toolchain for converting {url-asciidoc}[AsciiDoc] content into HTML 5, DocBook 5, and other formats. This document provides a high-level view of the changes introduced in Asciidoctor by release. -For an even more detailed look at what has changed, refer to the {uri-repo}/commits/[commit history] on GitHub. +For an even more detailed look at what has changed, refer to the {url-repo}/commits/[commit history] on GitHub. This project utilizes semantic versioning. // tag::compact[] +== 2.0.20 (2023-05-18) - @mojavelinux + +Bug Fixes:: + + * Update `release-version` attribute in READMEs and man page during release + * Rebuild man page during release + +=== Details + +{url-repo}/releases/tag/v2.0.20[git tag] | {url-repo}/compare/v2.0.19\...v2.0.20[full diff] +// end::compact[] + +== 2.0.19 (2023-05-17) - @mojavelinux + +Improvements:: + + * Return empty string instead of nil if raw or verbatim block has no lines + * Don't uppercase monospace span in section title in manpage output (#4402) + * Simplify processing of implicit link (i.e., autolink) by separating implicit and explicit match + * Generate partintro block consistently (#4450) + * Add Kiswahili translation for built-in labels (PR #4454) (*@bkmgit*) + +Compliance:: + + * Fix call order so use of an include file with invalid encoding continues to raise error when using Ruby >= 3.2.0 + * Fix test assertion for fallback Rouge stylesheet to be compatible with Rouge 4.1 (#4406) (*@tmzullinger*) + * Support `notitle` option on section as alternative to `untitled` to hide title (#4437) + * Add support for Haml 6 to template converter (#4429) + +Bug Fixes:: + + * Process constrained inline passthrough inside monospace span (#4458) + * Catalog inline ref defined using anchor macro even when resolved reftext is empty + * Use while loop rather than recursion to locate next line to process; prevents stack limit error (#4368) + * Avoid matching numeric character references when searching for # in xref target (#4393) + * Use correct selector to collapse margin on first and last child of sidebar + * Don't allow target of include directive to start with a space (to distinguish it from a dlist item) or to end with a space + * Manify alt text of block image in manpage output (#4401) + * Adjust font size of term in horizontal dlist to match font size of term in regular dlist + * Implicitly attach nested list that starts with block attribute lines to dlist entry (#4268) + * Don't swallow square brackets when processing escaped URL macro + * Treat `uri:classloader:` as an absolute path prefix when running on JRuby (#3929) + * Apply reftext substitutions to value of `mantitle` attribute in DocBook output (#4448) + * Enclose `` tag in `
` tag in DocBook output for man page (#4452) + * Correctly handle compat role on monospace and constrained passthrough when box attrlist or formatted text is escaped + +Build / Infrastructure:: + + * Update latest CRuby in CI workflow to 3.2 + * Update latest JRuby in CI workflow to 9.4.2.0 + +=== Details + +{url-repo}/releases/tag/v2.0.19[git tag] | {url-repo}/compare/v2.0.18\...v2.0.19[full diff] + == 2.0.18 (2022-10-15) - @mojavelinux Improvements:: @@ -38,8 +93,7 @@ === Details -{url-repo}/releases/tag/v2.0.18[git tag] | {url-repo}/compare/v2.0.17\...v2.0.18[source diff] -// end::compact[] +{url-repo}/releases/tag/v2.0.18[git tag] | {url-repo}/compare/v2.0.17\...v2.0.18[full diff] == 2.0.17 (2022-01-05) - @mojavelinux diff -Nru asciidoctor-2.0.18/data/locale/attributes-sw.adoc asciidoctor-2.0.20/data/locale/attributes-sw.adoc --- asciidoctor-2.0.18/data/locale/attributes-sw.adoc 1970-01-01 00:00:00.000000000 +0000 +++ asciidoctor-2.0.20/data/locale/attributes-sw.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -0,0 +1,23 @@ +// Kiswahili translation, Benson Muite +:appendix-caption: Kiambatisho +:appendix-refsig: {appendix-caption} +:caution-caption: Hatari +:chapter-signifier: Somo +:chapter-refsig: {chapter-signifier} +:example-caption: Mfano +:figure-caption: Picha +:important-caption: Muhimu +:last-update-label: Geuza la mwisho +ifdef::listing-caption[:listing-caption: Orodha] +ifdef::manname-title[:manname-title: Jina] +:note-caption: Muhtasari +:part-signifier: Sehemu +:part-refsig: {part-signifier} +ifdef::preface-title[:preface-title: Dibaji] +:section-refsig: Fungu +:table-caption: Ratiba +:tip-caption: Shauri +:toc-title: Fahirisi +:untitled-label: Bila kichwa +:version-label: Toleo +:warning-caption: Onyo diff -Nru asciidoctor-2.0.18/data/stylesheets/asciidoctor-default.css asciidoctor-2.0.20/data/stylesheets/asciidoctor-default.css --- asciidoctor-2.0.18/data/stylesheets/asciidoctor-default.css 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/data/stylesheets/asciidoctor-default.css 2023-05-18 07:16:38.000000000 +0000 @@ -198,13 +198,10 @@ .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} .exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px} -.exampleblock>.content>:first-child{margin-top:0} -.exampleblock>.content>:last-child{margin-bottom:0} .sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px} -.sidebarblock>:first-child{margin-top:0} -.sidebarblock>:last-child{margin-bottom:0} .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} -.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} +.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0} +.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} .literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} @@ -383,7 +380,7 @@ dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em} p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} -p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem} +p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem} p{margin-bottom:1.25rem} .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc} diff -Nru asciidoctor-2.0.18/debian/changelog asciidoctor-2.0.20/debian/changelog --- asciidoctor-2.0.18/debian/changelog 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/changelog 2023-06-13 15:08:01.000000000 +0000 @@ -1,3 +1,12 @@ +asciidoctor (2.0.20-1) unstable; urgency=medium + + * New upstream version 2.0.20 + + Add support for ruby-rouge >= 4.1 (Closes: #1037470) + * Refresh fix-blocks-test.patch + * Drop 0001-Port-tests-to-haml-6.patch, applied upstream + + -- Cédric Boutillier Tue, 13 Jun 2023 17:08:01 +0200 + asciidoctor (2.0.18-2) unstable; urgency=medium * Team upload. diff -Nru asciidoctor-2.0.18/debian/gbp.conf asciidoctor-2.0.20/debian/gbp.conf --- asciidoctor-2.0.18/debian/gbp.conf 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/gbp.conf 1970-01-01 00:00:00.000000000 +0000 @@ -1,4 +0,0 @@ -[DEFAULT] -pristine-tar = true -debian-branch = debian/master -sign-tag = true diff -Nru asciidoctor-2.0.18/debian/patches/0001-Port-tests-to-haml-6.patch asciidoctor-2.0.20/debian/patches/0001-Port-tests-to-haml-6.patch --- asciidoctor-2.0.18/debian/patches/0001-Port-tests-to-haml-6.patch 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/patches/0001-Port-tests-to-haml-6.patch 1970-01-01 00:00:00.000000000 +0000 @@ -1,139 +0,0 @@ -From 25ee484dd66cc813eaa421d1c104ae64478e51ff Mon Sep 17 00:00:00 2001 -From: Antonio Terceiro -Date: Mon, 26 Dec 2022 13:11:36 -0300 -Subject: [PATCH] Port tests to haml 6 - -Forwarded: https://github.com/asciidoctor/asciidoctor/pull/4395 -Fixes: #4382 ---- - asciidoctor.gemspec | 2 +- - lib/asciidoctor/converter/template.rb | 2 +- - test/converter_test.rb | 10 +++++----- - .../haml/docbook5/block_paragraph.xml.haml | 6 +++--- - .../haml/html5-tweaks/block_paragraph.html.haml | 2 +- - .../haml/html5-tweaks/embedded.html.haml | 2 +- - .../haml/html5/block_paragraph.html.haml | 4 ++-- - .../custom-backends/haml/html5/block_sidebar.html.haml | 4 ++-- - test/invoker_test.rb | 2 +- - 9 files changed, 17 insertions(+), 17 deletions(-) - ---- a/asciidoctor.gemspec -+++ b/asciidoctor.gemspec -@@ -38,7 +38,7 @@ Gem::Specification.new do |s| - 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 'haml', '~> 6.1' - s.add_development_dependency 'minitest', '~> 5.14.0' - s.add_development_dependency 'nokogiri', '~> 1.10.0' - s.add_development_dependency 'rake', '~> 12.3.0' ---- a/lib/asciidoctor/converter/template.rb -+++ b/lib/asciidoctor/converter/template.rb -@@ -29,7 +29,7 @@ class Converter::TemplateConverter < Con - erb: { trim: 0 }, - # TODO line 466 of haml/compiler.rb sorts the attributes; file an issue to make this configurable - # NOTE AsciiDoc syntax expects HTML/XML output to use double quotes around attribute values -- haml: { format: :xhtml, attr_wrapper: '"', escape_attrs: false, ugly: true }, -+ haml: { format: :xhtml, attr_quote: '"', escape_attrs: false, ugly: true }, - slim: { disable_escape: true, sort_attrs: false, pretty: false }, - } - ---- a/test/converter_test.rb -+++ b/test/converter_test.rb -@@ -9,7 +9,7 @@ context 'Converter' do - assert_kind_of Asciidoctor::Converter::CompositeConverter, doc.converter - selected = doc.converter.find_converter('paragraph') - assert_kind_of Asciidoctor::Converter::TemplateConverter, selected -- assert_kind_of Tilt::HamlTemplate, selected.templates['paragraph'] -+ assert_kind_of Haml::Template, selected.templates['paragraph'] - assert_equal :html5, selected.templates['paragraph'].options[:format] - end - -@@ -18,7 +18,7 @@ context 'Converter' do - assert_kind_of Asciidoctor::Converter::CompositeConverter, doc.converter - selected = doc.converter.find_converter('paragraph') - assert_kind_of Asciidoctor::Converter::TemplateConverter, selected -- assert_kind_of Tilt::HamlTemplate, selected.templates['paragraph'] -+ assert_kind_of Haml::Template, selected.templates['paragraph'] - assert_equal :xhtml, selected.templates['paragraph'].options[:format] - end - -@@ -95,7 +95,7 @@ context 'Converter' do - %w(paragraph sidebar).each do |node_name| - selected = doc.converter.find_converter node_name - assert_kind_of Asciidoctor::Converter::TemplateConverter, selected -- assert_kind_of Tilt::HamlTemplate, selected.templates[node_name] -+ assert_kind_of Haml::Template, selected.templates[node_name] - assert_equal %(block_#{node_name}.html.haml), File.basename(selected.templates[node_name].file) - end - end -@@ -126,7 +126,7 @@ context 'Converter' do - %w(paragraph).each do |node_name| - selected = doc.converter.find_converter node_name - assert_kind_of Asciidoctor::Converter::TemplateConverter, selected -- assert_kind_of Tilt::HamlTemplate, selected.templates[node_name] -+ assert_kind_of Haml::Template, selected.templates[node_name] - assert_equal %(block_#{node_name}.xml.haml), File.basename(selected.templates[node_name].file) - end - end -@@ -215,7 +215,7 @@ context 'Converter' do - refute_empty caches[:templates] - paragraph_template = caches[:templates].values.find {|t| File.basename(t.file) == 'block_paragraph.html.haml' } - refute_nil paragraph_template -- assert_kind_of ::Tilt::HamlTemplate, paragraph_template -+ assert_kind_of Haml::Template, paragraph_template - end - - test 'should be able to disable template cache' do ---- a/test/fixtures/custom-backends/haml/docbook5/block_paragraph.xml.haml -+++ b/test/fixtures/custom-backends/haml/docbook5/block_paragraph.xml.haml -@@ -1,6 +1,6 @@ - - if title? - %formalpara{'xml:id'=>@id, role: (attr :role), xreflabel: (attr :reftext)} -- %title=title -- %para=content -+ %title!=title -+ %para!=content - - else -- %para{'xml:id'=>@id, role: (attr :role), xreflabel: (attr :reftext)}=content -+ %para{'xml:id'=>@id, role: (attr :role), xreflabel: (attr :reftext)}!=content ---- a/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml -+++ b/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml -@@ -1 +1 @@ --%p=content -+%p!=content ---- a/test/fixtures/custom-backends/haml/html5-tweaks/embedded.html.haml -+++ b/test/fixtures/custom-backends/haml/html5-tweaks/embedded.html.haml -@@ -1 +1 @@ --=content -+!=content ---- a/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml -+++ b/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml -@@ -1,3 +1,3 @@ - - if title? -- .title=title --%p{id: @id, class: (attr 'role')}=content -+ .title!=title -+%p{id: @id, class: (attr 'role')}!=content ---- a/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml -+++ b/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml -@@ -1,5 +1,5 @@ - %aside{id: @id, class: (attr 'role')} - - if title? - %header -- %h1=title -- =content.chomp -+ %h1!=title -+ !=content.chomp ---- a/test/invoker_test.rb -+++ b/test/invoker_test.rb -@@ -616,7 +616,7 @@ context 'Invoker' do - assert_kind_of Asciidoctor::Converter::CompositeConverter, doc.converter - selected = doc.converter.find_converter 'paragraph' - assert_kind_of Asciidoctor::Converter::TemplateConverter, selected -- assert_kind_of Tilt::HamlTemplate, selected.templates['paragraph'] -+ assert_kind_of Haml::Template, selected.templates['paragraph'] - end - - test 'should load custom templates from multiple template directories' do diff -Nru asciidoctor-2.0.18/debian/patches/fix-blocks-test.patch asciidoctor-2.0.20/debian/patches/fix-blocks-test.patch --- asciidoctor-2.0.18/debian/patches/fix-blocks-test.patch 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/patches/fix-blocks-test.patch 2023-06-13 15:08:01.000000000 +0000 @@ -7,11 +7,9 @@ test/blocks_test.rb | 83 --------------------------------------------- 1 file changed, 83 deletions(-) -diff --git a/test/blocks_test.rb b/test/blocks_test.rb -index 663679b..c882c62 100644 --- a/test/blocks_test.rb +++ b/test/blocks_test.rb -@@ -2462,47 +2462,6 @@ def names +@@ -2474,47 +2474,6 @@ assert_css 'svg circle', output, 1 end @@ -59,7 +57,7 @@ test 'converts to alt text for SVG with inline option set if SVG cannot be read' do input = <<~'EOS' [%inline] -@@ -2915,48 +2874,6 @@ def names +@@ -2942,48 +2901,6 @@ assert_xpath '//img[@src="data:image/gif;base64,R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="][@alt="Dot"]', output, 1 end @@ -108,6 +106,3 @@ test 'uses remote image uri when data-uri attribute is set and image cannot be retrieved' do image_uri = "http://#{resolve_localhost}:9876/fixtures/missing-image.gif" input = <<~EOS --- -2.30.2 - diff -Nru asciidoctor-2.0.18/debian/patches/series asciidoctor-2.0.20/debian/patches/series --- asciidoctor-2.0.18/debian/patches/series 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/patches/series 2023-06-13 15:08:01.000000000 +0000 @@ -1,5 +1,4 @@ data_path.patch run-cucumber-without-bundler.patch fix-blocks-test.patch -0001-Port-tests-to-haml-6.patch autopkgtest.patch diff -Nru asciidoctor-2.0.18/debian/salsa-ci.yml asciidoctor-2.0.20/debian/salsa-ci.yml --- asciidoctor-2.0.18/debian/salsa-ci.yml 2023-02-06 17:29:43.000000000 +0000 +++ asciidoctor-2.0.20/debian/salsa-ci.yml 1970-01-01 00:00:00.000000000 +0000 @@ -1,7 +0,0 @@ ---- -include: - - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/salsa-ci.yml - - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/pipeline-jobs.yml - -reprotest: - allow_failure: true # rdoc diff -Nru asciidoctor-2.0.18/docs/antora.yml asciidoctor-2.0.20/docs/antora.yml --- asciidoctor-2.0.18/docs/antora.yml 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/antora.yml 2023-05-18 07:16:38.000000000 +0000 @@ -1,11 +1,11 @@ name: asciidoctor title: Asciidoctor -version: '2.0.18' +version: '2.0.20' asciidoc: attributes: xrefstyle: short@ listing-caption: Example@ - release-version: '2.0.18' + release-version: '2.0.20' ruby-description: 'ruby 3.1.2p20 [x86_64-linux]' ruby-version: '3.1' url-api-gems: https://www.rubydoc.info/gems @@ -23,7 +23,6 @@ - modules/cli/nav.adoc - modules/api/nav.adoc - modules/ROOT/nav-safe-modes.adoc -- modules/ROOT/nav-docinfo.adoc - modules/tooling/nav.adoc - modules/syntax-highlighting/nav.adoc - modules/stem/nav.adoc diff -Nru asciidoctor-2.0.18/docs/modules/api/nav.adoc asciidoctor-2.0.20/docs/modules/api/nav.adoc --- asciidoctor-2.0.18/docs/modules/api/nav.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/api/nav.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -5,4 +5,5 @@ ** xref:set-safe-mode.adoc[] ** xref:sourcemap.adoc[] ** xref:catalog-assets.adoc[] +** xref:find-blocks.adoc[] ** xref:options.adoc[] diff -Nru asciidoctor-2.0.18/docs/modules/api/pages/catalog-assets.adoc asciidoctor-2.0.20/docs/modules/api/pages/catalog-assets.adoc --- asciidoctor-2.0.18/docs/modules/api/pages/catalog-assets.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/api/pages/catalog-assets.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -20,8 +20,13 @@ * block or inline anchors (key: `:refs`) * footnotes (key: `:footnotes`) -Inline elements are not cataloged until conversion. +Generally speaking, inline elements are not cataloged until conversion. Therefore, they're only available after the document has been converted, not after it has been loaded. +However, inline anchors are an exception. + +Inline anchors in paragraphs and list items are cataloged when the document is parsed. +However, the scan for inline anchors happens before inline passthroughs are processed. +Therefore, to escape an inline anchor, you must use a backslash instead of an inline passthrough. == Set :catalog_assets option diff -Nru asciidoctor-2.0.18/docs/modules/api/pages/find-blocks.adoc asciidoctor-2.0.20/docs/modules/api/pages/find-blocks.adoc --- asciidoctor-2.0.18/docs/modules/api/pages/find-blocks.adoc 1970-01-01 00:00:00.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/api/pages/find-blocks.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -0,0 +1,198 @@ += Find Blocks + +Once the document has been loaded (or partially loaded), you can traverse the document to find block nodes. +There are two ways to look for block nodes. +One way is to start walking down the tree starting from the Document object. +All blocks can be reached from the Document object. +However, a much quicker way to find blocks is to use the `find_by` method, which does the walking for you. +We'll start there, then look at how to use the custom traversal approach. + +== find_by + +Every block node (a parsed block), including the Document object, provides the {url-api-gems}/asciidoctor/{release-version}/Asciidoctor/AbstractBlock#find_by-instance_method[find_by] method. +The purpose of this method is to help you quickly find descendant blocks. +Since some blocks have different models, this method can help you navigate the document without having to worry about those nuances. + +IMPORTANT: The `find_by` method only finds block nodes. +It does not find inline nodes. + +If you want to look for any block in the parsed document, call the `find_by` method on the Document object. +Otherwise, you can look for blocks in a specific area of the document by calling it on the relevant ancestor of those blocks. + +The return value of this method is a flat array of blocks in document order which were matched. +The relationship between those blocks is only preserved by way of their own model. +If no blocks are matched, the method returns an empty array. + +=== All blocks + +If not called with any arguments, the `find_by` method will return all blocks starting from the block on which it was called. +If called on the Document object, it will return all blocks in the document (except for blocks in AsciiDoc table cells), including the document itself. +Here's an example: + +[,ruby] +---- +require 'asciidoctor' + +doc = Asciidoctor.load_file 'input.adoc', safe: :safe +puts doc.find_by +---- + +Here's an example of how to find all the blocks in the first section: + +[,ruby] +---- +doc.sections.first.find_by +---- + +Notice that the `find_by` method always returns the block that you start with as the first result (assuming it also matches the provided selector, covered later). +If you want to exclude that block, slice it off from the results: + +[,ruby] +---- +puts doc.find_by.slice 1..-1 +---- + +If youre just looking for the first result, you can pluck it from the result array: + +[,ruby] +---- +puts doc.find_by.first +---- + +By default, and for backwards compatibility, the `find_by` method does not traverse into AsciiDoc table cells. +If you want it to look in these cells for blocks, set the `:traverse_documents` key on the selector Hash to true. + +[,ruby] +---- +all_blocks = doc.find_by traverse_documents: true +---- + +The next section will look at how to filter the blocks that are returned. + +=== Filter blocks + +When using the `find_by` method, you're probably looking for specific blocks. +The method accepts an optional selector (a Hash) and an optional block filter (a Ruby proc). +The method will walk the entire tree (including in AsciiDoc table cells if `:traverse_documents` is `true`) to find blocks. +By default, it will descend into a block which does not match, though this behavior can be controlled using the block filter. + +The simplest way to match blocks is to use the selector. +The selector is a Hash that accepts four predefined symbol keys: + +:context:: A single block xref:convert:contexts-ref.adoc[context] (i.e., block name), such as `:paragraph`. +:style:: A single block style, such as `source`. +:id:: An ID. +:role:: A single role. + +If an `:id` is specified, the method will never return more than one block since an ID is, by natural, globally unique. +Here's an example of how to find a block by ID using the `:id` selector: + +[,ruby] +---- +match = (doc.find_by id: 'prerequisites').first +---- + +Now let's assume we want to match all listing blocks that are source blocks. +We can do so by combining the `:context` and `:style` selectors: + +[,ruby] +---- +some_source_blocks = doc.find_by context: :listing, style: 'source' +---- + +Since literal blocks can also be source blocks, if we want all source blocks, we'd need to leave off the `:context` selector: + +[,ruby] +---- +all_source_blocks = doc.find_by style: 'source' +---- + +If we want all blocks marked with a specific role, we can find them using the `:role` selector: + +[,ruby] +---- +blocks_with_role = doc.find_by role: 'try-it' +---- + +The selector Hash is intentionally simple to make it easy to find blocks. +If the blocks you're looking for cannot be described using that selector, then you'll want to use a block filter instead. + +A block filter is a Ruby proc that runs on each block visited. +It accepts the candidate block as the sole argument (i.e., the candidate block is yielded to the proc). +If the proc returns true, then the candidate is considered matched. + +Here's an example of using the block filter to find all top-level sections: + +[,ruby] +---- +top_level_sections = doc.find_by {|block| block.context == :section && block.level == 1 } +---- + +We can make this slightly more efficient by combining it with a selector: + +[,ruby] +---- +top_level_sections = doc.find_by(context: :section) {|section| section.level == 1 } +---- + +If a Ruby block is given, it's applied as a supplemental filter to the selector. +In other words, the candidate block must match the selector and the filter. + +=== Control the traversal + +The benefit of the block filter is that it also allows you to control the traversal. +The filter method can return any of the following keywords: + +true:: +:accept:: +The block is accepted and the traversal continues. + +false:: +:skip:: +The block is skipped but its children are traversed. + +:reject:: +The block is rejected and its children are not traversed. + +:prune:: +The block is accepted, but its descendants are not traversed. + +Here's an efficient way to match all sidebars that are not contained within another block. + +[,ruby] +---- +top_level_sidebars = doc.find_by do |block| + if block == block.document + :skip + elsif block.context == :sidebar + :prune + else + :reject + end +end +---- + +The filter has to return `:skip` instead of `:reject` for the document object or else no blocks will be traversed. + +If you combine the selector and the block filter, you will have less control over which nodes are traversed. +Therefore, if you're going to be using the block filter to control the traversal, it's best to do all logic in that filter. + +== Custom traversal + +Another way to find blocks is to traverse the tree explicitly. +Starting at the document object, you can access its children by calling the `blocks` method. + +[,ruby] +---- +doc.blocks.each do |block| + puts block +end +---- + +CAUTION: Not all blocks have the same model. +For example, each item in a description list is an array of two nodes. +And tables have a very different model from other blocks. +These differences are important to be aware of when traversing the document model. + +If the block or blocks you're looking for are close at hand or in a known location, it may be more efficient to use a custom traversal. +However, if you aren't sure where the block is located in the document tree, you'd be much better off using the `find_by` method to locate it. diff -Nru asciidoctor-2.0.18/docs/modules/api/pages/sourcemap.adoc asciidoctor-2.0.20/docs/modules/api/pages/sourcemap.adoc --- asciidoctor-2.0.18/docs/modules/api/pages/sourcemap.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/api/pages/sourcemap.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -31,7 +31,7 @@ There are certain edge cases, such as when the block is split across multiple files or the block starts and ends on the last line of an include file, when the sourcemap may report the wrong file or line information. If you're writing a processor that relies on the sourcemap, it's a good idea to verify that the line at the cursor is the one you expect to find, then adjust accordingly. -== Set :sourcemap option +== Enable using :sourcemap option The sourcemap feature can be controlled from the API using the `:sourcemap` option. The value of this option is a boolean. @@ -46,7 +46,29 @@ doc = Asciidoctor.load_file 'doc.adoc', safe: :safe, sourcemap: true ---- -Now that the sourcemap is enabled, you can access the source location of the block elements in the parsed document. +== Enable from extension + +You can enable the sourcemap using an Asciidoctor preprocessor extension. +This technique is useful if your extension needs access to the source location of blocks, but you don't want to require users to pass an additional option to Asciidoctor. + +[,ruby] +---- +Asciidoctor::Document.prepend (Module.new do + attr_writer :sourcemap +end) unless Asciidoctor::Document.method_defined? :sourcemap= + +# A preprocessor that enables the sourcemap feature if not already enabled via the API. +Asciidoctor::Extensions.register do + preprocessor do + process do |doc, reader| + doc.sourcemap = true + nil + end + end +end +---- + +Now that the sourcemap is enabled, your extension can access the source location of the block elements in the parsed document. == Use the sourcemap diff -Nru asciidoctor-2.0.18/docs/modules/cli/partials/man-asciidoctor.adoc asciidoctor-2.0.20/docs/modules/cli/partials/man-asciidoctor.adoc --- asciidoctor-2.0.18/docs/modules/cli/partials/man-asciidoctor.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/cli/partials/man-asciidoctor.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,7 +1,7 @@ = asciidoctor(1) Dan Allen; Sarah White :doctype: manpage -:release-version: 2.0.17 +:release-version: 2.0.20 :man manual: Asciidoctor Manual :man source: Asciidoctor {release-version} ifdef::backend-manpage[:!author:] diff -Nru asciidoctor-2.0.18/docs/modules/convert/pages/contexts-ref.adoc asciidoctor-2.0.20/docs/modules/convert/pages/contexts-ref.adoc --- asciidoctor-2.0.18/docs/modules/convert/pages/contexts-ref.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/convert/pages/contexts-ref.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,6 +1,6 @@ = Convertible Contexts -When Asciidoctor converters a document, it delegates to the converter to convert each node (block or inline element) in the document as it visits each node in document order (though it's the `#content` method on a block that continues the traversal of its child nodes). +When Asciidoctor converts a document, it delegates to the converter to convert each node (block or inline element) in the document as it visits each node in document order (though it's the `#content` method on a block that continues the traversal of its child nodes). Asciidoctor then combines the result of all those calls to produce the output document. To convert a node, Asciidoctor calls the `convert` method on the converter and passes in the node. diff -Nru asciidoctor-2.0.18/docs/modules/extensions/nav.adoc asciidoctor-2.0.20/docs/modules/extensions/nav.adoc --- asciidoctor-2.0.18/docs/modules/extensions/nav.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/extensions/nav.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,5 +1,6 @@ * xref:index.adoc[] ** xref:register.adoc[] +** xref:logging.adoc[] ** xref:preprocessor.adoc[] ** xref:tree-processor.adoc[] ** xref:postprocessor.adoc[] diff -Nru asciidoctor-2.0.18/docs/modules/extensions/pages/index.adoc asciidoctor-2.0.20/docs/modules/extensions/pages/index.adoc --- asciidoctor-2.0.18/docs/modules/extensions/pages/index.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/extensions/pages/index.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,12 +1,12 @@ = Extensions -:url-exten-lab: https://github.com/asciidoctor/asciidoctor-extensions-lab +:url-ext-lab: https://github.com/asciidoctor/asciidoctor-extensions-lab Extensions are central to the success of AsciiDoc because they open up the language to new use cases. -Asciidoctor provides an extension API that offers a superset of extension points. +Asciidoctor provides an {url-api-gems}/asciidoctor/{release-version}/Asciidoctor/Extensions[extension API^] that offers a superset of extension points. As a result, extensions in Asciidoctor are easy to write, powerful, and simple to distribute. Asciidoctor also allows extensions to be written using the full power of a programming language (whether it be Ruby, Java, Groovy or JavaScript). -You don't have to shave yaks to get the functionality you want, and you can distribute the extension using de facto standard packaging mechanisms like RubyGems or JARs. +You don't have to shave yaks to get the functionality you want, and you can distribute the extension using de facto standard packaging mechanisms like gems or JARs. == Available extension points @@ -48,4 +48,4 @@ Processes the `include::[]` directive. See xref:include-processor.adoc[]. -There are additional extension examples in the {url-exten-lab}[Asciidoctor extensions lab^]. +There are additional extension examples in the {url-ext-lab}[Asciidoctor extensions lab^]. diff -Nru asciidoctor-2.0.18/docs/modules/extensions/pages/logging.adoc asciidoctor-2.0.20/docs/modules/extensions/pages/logging.adoc --- asciidoctor-2.0.18/docs/modules/extensions/pages/logging.adoc 1970-01-01 00:00:00.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/extensions/pages/logging.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -0,0 +1,183 @@ += Log from an Extension + +If a problem occurs while an extension is running, you probably want to communicate that information to the user. +The extension should only throw an error (i.e., raise an exception) if the problem is so severe that no additional processing should be done. +Otherwise, we recommend that extensions report the problem as a log message at an appropriate severity level. +You can use Asciidoctor's logger to log messages. + +When Asciidoctor processes a document, it creates a https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html[Logger^] instance scoped to that document. +You can access that logger in your extension to log messages. +This page describes how to do that. + +== Mix in the Logger + +To access the instance of Asciidoctor's Logger, you need to include the `Asciidoctor::Logging` module into your extension. +In doing so, it will provide access to the static `logger` method, which will retrieve the instance from the `LoggerManager`. + +If you're writing a class-based extension, you can include the `Logging` module using the `include` keyword. + +[,ruby] +---- +class CustomBlock < Asciidoctor::Extensions::BlockProcessor + include Asciidoctor::Logging + + # ... +end + +Asciidoctor::Extensions.register do + block CustomBlock, :custom +end +---- + +If you're writing an extension purely using the DSL, the processor class is created dynamically. +Therefore, you need to mix in the `Logging` module by referencing the `include` method on that class instead. + +[,ruby] +---- +Asciidoctor::Extensions.register do + block :custom do + singleton_class.include Asciidoctor::Logging + + # ... + end +end +---- + +In order to log a message, pass the message string to one of the severity methods (e.g., `error`, `warn`, `info`, etc) on the logger instance returned by the `logger` method. +Here's an example of how to log a warning message in the process method. + +[,ruby] +---- +def process doc, reader, attr + logger.warn 'We are logging!' + + # ... +end +---- + +Here's what Asciidoctor will print to the log: + +[.output] +.... +asciidoctor: WARN: We are logging! +.... + +Refer to the documentation for https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html[Logger^] to learn about the available methods. + +Here's a complete example to show where these additions are used in context: + +[,ruby] +---- +Asciidoctor::Extensions.register do + block :custom do + singleton_class.include Asciidoctor::Logging + + on_context :paragraph + process do |parent, reader, attrs| + logger.warn 'We are logging!' + create_paragraph parent, reader.lines, attrs + end + end +end +---- + +Keep in mind that the message will only be displayed if its severity level is enabled by the user. +By default, error and warn(ing) messages will be displayed. + +You should refrain from using the `fatal` method unless the extension is in the process of throwing an error. + +== Add context to the message + +If you pass a string to the log method, Asciidoctor will only print the severity level and the message. +That means the user won't know what AsciiDoc source the message refers to nor that the message is coming from an extension. +Therefore, you'll probably want to provide more detail. +Let's begin by including the extension name in the message. + +=== Add the extension name + +First, when logging a message, you should prefix that message with the name of the extension. + +[,ruby] +---- +logger.warn '(custom-block-extension) Something is out of sorts.' +---- + +That will print the message as follows: + +[.output] +.... +asciidoctor: WARN: (custom-block-extension) Something is out of sorts. +.... + +Alternately, you can move your extension name so that it immediately follows the program name (i.e., `asciidoctor`). + +[,ruby] +---- +logger.log ::Logger::WARN, 'hi', %(#{logger.progname} (custom-block-extension)) +---- + +That will print the message as follows: + +[.output] +.... +asciidoctor (custom-block-extension): WARN: Something is out of sorts. +.... + +Another way to get the same output is to use the form that accepts the message as a block. + +[,ruby] +---- +logger.warn(%(#{logger.progname} (custom-block-extension))) { 'Something is out of sorts.' } +---- + +The block form is useful in other ways. +If the computation of the message is expensive, the block form defers evaluation of the message until (and thus if) it is logged. + +Now the reader knows that the message is coming from an extension, but not the location of the AsciiDoc source the extension is processing. +Let's look at how to do that. + +=== Add the source location + +In addition to the `logger` method, Asciidoctor's `Logging` module also adds a helper named `message_with_context` that generates a message object that bundles source information with the string message. + +For block and block macro extensions, you probably want to reference the location where the block is found, which you can retrieve using the `parent.document.reader.cursor_at_mark` method call. +For a tree processor extension, you can retrieve the source location from the `source_location` method on the block. +For most other extensions, you likely want to reference the current cursor, which is accessible from `parent.document.reader.cursor` or (`doc.reader` for extensions that only provide access to the document object). + +Here's an example that replaces the message with an object that includes the source location: + +[,ruby] +---- +logger.warn(%(#{logger.progname} (custom-block-extension))) { + message_with_context 'Something is out of sorts.', source_location: parent.document.reader.cursor_at_mark +} +---- + +Here's an example of what Asciidoctor will print: + +[.output] +.... +asciidoctor (custom-block-extension): WARNING: test.adoc: line 4: Something is out of sorts. +.... + +In a tree processor extension, you can get the source location from any block if the sourcemap is enabled. +If it's not enabled, the code will degrade gracefully by logging the message without the source location. + +[,ruby] +---- +Asciidoctor::Extensions.register do + tree_processor do |doc| + singleton_class.include Asciidoctor::Logging + doc.find_by context: :paragraph do |paragraph| + logger.warn(%(#{logger.progname} (custom-tree-processor))) { + message_with_context 'Found paragraph.', source_location: paragraph.source_location + } + end + nil + end +end +---- + +Source location tracking in Asciidoctor is not perfect, so you may need to retrieve the cursor and adjust it slightly to align it with the line you want to reference in the message. + +Refer to {url-api-gems}/asciidoctor/{release-version}/Asciidoctor/Reader#cursor-instance_method[Reader#cursor^] for a list of cursor methods. diff -Nru asciidoctor-2.0.18/docs/modules/extensions/pages/preprocessor.adoc asciidoctor-2.0.20/docs/modules/extensions/pages/preprocessor.adoc --- asciidoctor-2.0.18/docs/modules/extensions/pages/preprocessor.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/extensions/pages/preprocessor.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,13 +1,38 @@ -= Preprocessor Extension Example += Preprocessor Extension :navtitle: Preprocessor +The {url-api-gems}/asciidoctor/{release-version}/Asciidoctor/Extensions/Preprocessor[Preprocessor^] extension runs prior to the AsciiDoc source being parsed. +Specifically, it runs after the Document instance has been created and its PreprocessorReader has been initialized to start reading the lines of the source document. + +[WARNING] +==== +If the preprocessor extension reads lines from the reader, it will cause side effects. +One of these side effects is that document attributes in the header may not be interpreted correctly. +Another is that it may interfere with line number tracking. +If the extension adds or removes lines, the parser could produce misleading line number information. +Thus, interacting with the reader in a prepreprocessor extension should be avoided, if possible. + +A preprocessor extension can still be used to modify options on the Document object, in which case there's no side effect. +It may also be possible to avoid side effects by reading lines which are not interpreted as AsciiDoc, as is shown in the example on this page. +==== + +Prior to invoking the preprocessor extension, Asciidoctor splits the source text of the primary document into lines and xref:asciidoc::normalization.adoc[normalizes them]. +It then creates an instance of PreprocessorReader from these lines. + +Asciidoctor then passes the Document and PreprocessorReader instances to the `Asciidoctor::Extensions::Processor#process` method of the extension. +If the extension reads lines from reader, those lines will first be preprocessed by Asciidoctor's internal preprocessor. +The extension can modify the Reader and either return the same Reader (or falsy, which is equivalent) or a new Reader instance to replace it. +However, as stated above, be careful when reading lines from the original PreprocessorReader instance as it can have side effets. + +== Preprocessor Extension Example + Purpose:: -Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct. +Skim off front matter from the top of the document that gets used by site generators like Jekyll. -== sample-with-front-matter.adoc +=== sample-with-front-matter.adoc [source,asciidoc] ----- +.... tags: [announcement, website] --- = Document Title @@ -16,14 +41,14 @@ [subs=+attributes] .Captured front matter -.... +---- --- {front-matter} --- -.... ---- +.... -== FrontMatterPreprocessor +=== FrontMatterPreprocessor [source,ruby] ---- @@ -53,7 +78,7 @@ end ---- -== Usage +=== Usage [source,ruby] ---- diff -Nru asciidoctor-2.0.18/docs/modules/extensions/pages/tree-processor.adoc asciidoctor-2.0.20/docs/modules/extensions/pages/tree-processor.adoc --- asciidoctor-2.0.18/docs/modules/extensions/pages/tree-processor.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/extensions/pages/tree-processor.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,10 +1,21 @@ -= Tree Processor Extension Example += Tree Processor Extension :navtitle: Tree Processor +A {url-api-gems}/asciidoctor/{release-version}/Asciidoctor/Extensions/TreeProcessor[TreeProcessor^] extension is run on the Document instance after the blocks in the source have been parsed into a document structure, as represented by the Document object and its child AbstractNode objects (e.g., Section, Block, List, ListItem). + +Asciidoctor invokes the `Processor#process` method on an instance of each registered TreeProcessor extension. + +IMPORTANT: A TreeProcessor extension is run before any inline markup is interpreted. +At the time the process method on the TreeProcessor extension is invoked, the block nodes in the document have unprocessed, unconverted text. +Conversion of inline markup is done when the document is being converted. +Thus, it's possible for the TreeProcessor extension to replace the source text on the nodes, but it must consider the fact that the text is still going to be parsed (according to the content model of the block). + +== Tree Processor Extension Example + Purpose:: Detect literal blocks that contain shell commands, strip the prompt character and style the command using CSS in such a way that the prompt character cannot be selected (as seen on help.github.com). -== sample-with-shell-session.adoc +=== sample-with-shell-session.adoc [source,asciidoc] ---- @@ -14,7 +25,7 @@ $ gem install asciidoctor ---- -== ShellSessionTreeProcessor +=== ShellSessionTreeProcessor [source,ruby] ---- @@ -47,7 +58,7 @@ end ---- -== Usage +=== Usage [source,ruby] ---- diff -Nru asciidoctor-2.0.18/docs/modules/html-backend/examples/wrap.adoc asciidoctor-2.0.20/docs/modules/html-backend/examples/wrap.adoc --- asciidoctor-2.0.18/docs/modules/html-backend/examples/wrap.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/html-backend/examples/wrap.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,5 +1,5 @@ // tag::nowrap[] -[source%nowrap,java] +[%nowrap,java] ---- public class ApplicationConfigurationProvider extends HttpConfigurationProvider { diff -Nru asciidoctor-2.0.18/docs/modules/html-backend/pages/custom-stylesheet.adoc asciidoctor-2.0.20/docs/modules/html-backend/pages/custom-stylesheet.adoc --- asciidoctor-2.0.18/docs/modules/html-backend/pages/custom-stylesheet.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/html-backend/pages/custom-stylesheet.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -151,20 +151,25 @@ NOTE: This situation is unique to when `linkcss` is set. It's not a problem when the converter embeds the stylesheet since there is no secondary reference involved. -The `copycss` attribute can accepts a value. -Asciidoctor uses that value as an override for where to look for the stylesheet to read. +The `copycss` attribute can accept a non-empty value. +Asciidoctor uses this value as an override for where to look for the stylesheet to read. The converter, on the other hand, does not use this value. That means we can use `stylesdir` and `stylesheet` to assemble the path relative to the output directory where Asciidoctor should write and link to the stylesheet independent of the location where it reads the file. Let's revisit the broken scenario from the previous section and use `copycss` to reconcile the problem: $ asciidoctor -a stylesdir=css -a stylesheet=default.css \ - -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public my-document.adoc + -a copycss=$PWD/my-styles/my-stylesheet.css -a linkcss -D public my-document.adoc Asciidoctor copies the stylesheet from the absolute path specified by the `copycss` attribute to the path [.path]_public/css/default.css_ and links to it using the path [.path]_css/default.css_. -Notice that we even changed the name of the folder and stylesheet file in the output. +Notice that we changed the name of the folder and stylesheet file in the output. That demonstrates that we have decoupled the path where the stylesheet is read from the location where the stylesheet is published and referenced. +TIP: When running on JRuby, you can point `copycss` to a classloader URI to load a stylesheet from a JAR file (e.g., `uri:classloader:/css/styles.css`). +However, the HTML cannot link to that location. +Therefore, you must use the `stylesheet` attribute (and optionally the `stylesdir`) to specify a filename or relative path where Asciidoctor will write the stylesheet. +The HTML will then be able to link to that destination. + == Styles directory and nested documents when linking When xref:cli:process-multiple-files.adoc[invoking Asciidoctor on a nested set of documents], it's currently not possible to specify a single relative path for the `stylesdir` attribute that works for all of the documents. diff -Nru asciidoctor-2.0.18/docs/modules/html-backend/pages/local-font-awesome.adoc asciidoctor-2.0.20/docs/modules/html-backend/pages/local-font-awesome.adoc --- asciidoctor-2.0.18/docs/modules/html-backend/pages/local-font-awesome.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/html-backend/pages/local-font-awesome.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,4 +1,4 @@ -= Local Font Awesome += Use Local Font Awesome When font-based icons are enabled, the HTML converter configures the HTML document to retrieve the Font Awesome assets (CSS and fonts) from a CDN. This default behavior provides a convenience for users who want the visual enhancement of font-based icons without having to do any extra steps. diff -Nru asciidoctor-2.0.18/docs/modules/html-backend/pages/verbatim-line-wrap.adoc asciidoctor-2.0.20/docs/modules/html-backend/pages/verbatim-line-wrap.adoc --- asciidoctor-2.0.18/docs/modules/html-backend/pages/verbatim-line-wrap.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/html-backend/pages/verbatim-line-wrap.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -15,8 +15,8 @@ You can use the `nowrap` option on literal or listing blocks to prevent lines from being wrapped in the HTML. -// FIXME this section is creating broken AsciiDoc!! .Listing block with nowrap option syntax +[source,asciidoc] .... include::example$wrap.adoc[tag=nowrap] .... @@ -30,7 +30,7 @@ To prevent lines from wrapping globally, unset the `prewrap` attribute on the document. .Disable prewrap globally (thus, enabling nowrap) -[source,asciidoc] +[,asciidoc] ---- :prewrap!: ---- diff -Nru asciidoctor-2.0.18/docs/modules/install/pages/index.adoc asciidoctor-2.0.20/docs/modules/install/pages/index.adoc --- asciidoctor-2.0.18/docs/modules/install/pages/index.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/install/pages/index.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,7 +1,7 @@ = Install and Update -To simplify installation, Asciidoctor is packaged and published as a {url-rubygems}/asciidoctor[RubyGem to the package repository at RubyGems.org^]. -It's also distributed as a package for popular Linux distributions and macOS. +To simplify installation, Asciidoctor is packaged as a gem and published to the gem hosting service at {url-rubygems}/asciidoctor[RubyGems.org^]. +Asciidoctor is also distributed as a managed package for popular Linux distributions and macOS. TIP: In addition to running on Ruby, Asciidoctor can be executed on a JVM using xref:asciidoctorj::index.adoc[AsciidoctorJ] or in any JavaScript environment (including the browser) using xref:asciidoctor.js::index.adoc[Asciidoctor.js]. @@ -15,10 +15,11 @@ * the `gem install` command (recommended for Windows users), or * the Asciidoctor Docker image +IMPORTANT: To update or uninstall Asciidoctor, you should use the same method you used to install it. + Bundler is the preferred method of installation as it keeps the gems scoped to your project or workspace. -However, it does not make the `asciidoctor` command globally available in your terminal. +However, this method of installation does not make the `asciidoctor` command available globally in your terminal. That's when a package manager is more appropriate. -The benefit of using your operating system's package manager to install the gem is that it adds the `asciidoctor` command to your PATH and it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. -On the other hand, if you're familiar with Docker, using the Asciidoctor Docker image gives you the best isolation from your system. -You should use the same method to update and uninstall Asciidoctor as you use to install it. +The benefit of using your operating system's package manager to install the gem is that it adds the `asciidoctor` command to your PATH and it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine. +On the other hand, if you're familiar with Docker, using the Asciidoctor Docker image may give you the best isolation from your system. diff -Nru asciidoctor-2.0.18/docs/modules/install/pages/ruby-packaging.adoc asciidoctor-2.0.20/docs/modules/install/pages/ruby-packaging.adoc --- asciidoctor-2.0.18/docs/modules/install/pages/ruby-packaging.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/install/pages/ruby-packaging.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,9 +1,11 @@ = Install Using Ruby Packaging -Using Ruby packaging entails using commands provided by Ruby (`gem` and `bundle`) to install RubyGems. +Using Ruby packaging entails making use of commands provided by Ruby (`gem` and `bundle`) to install gems. +A gem is a packaged Ruby application or library, often retrieved from {url-rubygems}[RubyGems.org^]. + The benefit of using Ruby packaging to install Asciidoctor is that it's universal. -Provided you have configured Ruby correctly, Ruby packaging works the same way across Ruby runtimes and operating systems. -This page explains how to use Ruby packaging to install Asciidoctor. +Provided you have configured Ruby correctly, Ruby packaging works the same way across all Ruby runtimes and operating systems. +This page explains how to use Ruby packaging to install Asciidoctor from the *asciidoctor* gem. WARNING: Unless you're running in a container (Docker, podman, OCI), _never_ install gems using `gem install` as the root user. Doing so will almost certainly interfere with, and possibly corrupt, the Ruby installation on your system. diff -Nru asciidoctor-2.0.18/docs/modules/install/pages/supported-platforms.adoc asciidoctor-2.0.20/docs/modules/install/pages/supported-platforms.adoc --- asciidoctor-2.0.18/docs/modules/install/pages/supported-platforms.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/install/pages/supported-platforms.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -48,3 +48,19 @@ |=== While the community tests Asciidoctor on a variety of Linux distributions, it's only officially tested on Ubuntu and Fedora. + +== System encoding + +Asciidoctor assumes you're using UTF-8 encoding. +To minimize encoding problems, make sure the default encoding of your system is set to UTF-8. + +If you're using a non-English Windows environment, you may bump into an `Encoding::UndefinedConversionError` when invoking Asciidoctor. +To solve this issue, we recommend overriding the default external and internal character encodings to `utf-8`. +You can do so by setting the `RUBYOPT` environment variable as follows: + + RUBYOPT="-E utf-8:utf-8" + +Once you make this change, all your Unicode headaches should be behind you. + +If you're using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. +Asciidoctor is optimized to work with UTF-8 as the default encoding. diff -Nru asciidoctor-2.0.18/docs/modules/manpage-backend/pages/index.adoc asciidoctor-2.0.20/docs/modules/manpage-backend/pages/index.adoc --- asciidoctor-2.0.18/docs/modules/manpage-backend/pages/index.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/manpage-backend/pages/index.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -46,6 +46,7 @@ Subsequent sections are optional, but typical sections include "`Description`", "`Options`", "`Bugs`", "`See Also`", "`Copyright`", and "`Author`". You can write the section titles in all uppercase, but it's better to let the man page converter handle that for you. +See <> for details. TIP: Since the structure required by the `manpage` doctype is standard AsciiDoc, you can opt to declare the `manpage` doctype at runtime. When the `doctype` attribute is not set, Asciidoctor will parse the document as an article and not give it any special treatment. @@ -75,6 +76,7 @@ To use the man page converter, assign `manpage` to the `backend` option. The man page converter sets the output file name to `progname.1`, where `progname` is the name of the command and `1` is the volume number, as defined by the doctitle of the source document (e.g., `progname(1)`). +[#generate] == Generate a man page Before running Asciidoctor, make sure your source document conforms to the <> and the `doctype` attribute is set and has the value `manpage`. @@ -84,8 +86,9 @@ $ asciidoctor -b manpage progname.adoc When converting to the man page format, Asciidoctor uppercases the titles of all level-0 and level-1 sections. -This saves you from having to type section titles in all uppercase in the source document. -It also makes the document portable to other output formats since this style is only used for the man page output to align with conventions. +This transformation is applied to conform to the widely adopted convention used by most man pages found on *nix systems. +By applying this transform in the converter, it saves you from having to type section titles in all uppercase in the source document. +It also makes the document portable to other output formats since this style is only needed for the man page output. If the titles are uppercased in the source, that casing ends up getting used in all output formats. CAUTION: Prior to Ruby 2.4, Ruby could only uppercase Latin letters. diff -Nru asciidoctor-2.0.18/docs/modules/migrate/examples/convert.groovy asciidoctor-2.0.20/docs/modules/migrate/examples/convert.groovy --- asciidoctor-2.0.18/docs/modules/migrate/examples/convert.groovy 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/migrate/examples/convert.groovy 2023-05-18 07:16:38.000000000 +0000 @@ -35,7 +35,7 @@ serializer.writeToFile( result, tmpHtml.absolutePath, "utf-8" ) - "pandoc -f html -t asciidoc -R -S --normalize -e $tmpHtml -o ${target}.adoc".execute().waitFor() + "pandoc -f html-native_divs -t asciidoctor $tmpHtml --wrap=none -o ${target}.adoc".execute().waitFor() tmpHtml.delete() }/* else { "cp html/$relative $target".execute() diff -Nru asciidoctor-2.0.18/docs/modules/migrate/pages/asciidoc-py.adoc asciidoctor-2.0.20/docs/modules/migrate/pages/asciidoc-py.adoc --- asciidoctor-2.0.18/docs/modules/migrate/pages/asciidoc-py.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/migrate/pages/asciidoc-py.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -178,7 +178,6 @@ To ensure your IDs have maximum portability, it's best to define them explicitly if the section title contains special characters or formatting. - === Tables [cols="~,~,~,~"] @@ -280,6 +279,15 @@ See xref:asciidoc:directives:include-with-indent.adoc[normalize block indentation]. |=== +=== docinfo attributes + +`docinfo` attribute values were introduced into AsciiDoc by Asciidoctor 1.5.5 to replace the less descriptive `docinfo1` and `docinfo2` attributes. +Here are the equivalents of the old attributes using the new values: + +* `:docinfo:` = `:docinfo: private` +* `:docinfo1:` = `:docinfo: shared` +* `:docinfo2:` = `:docinfo: shared,private` + === showcomments In AsciiDoc.py, single line comments could be turned into DocBook `` elements using `showcomments`. diff -Nru asciidoctor-2.0.18/docs/modules/migrate/pages/ms-word.adoc asciidoctor-2.0.20/docs/modules/migrate/pages/ms-word.adoc --- asciidoctor-2.0.18/docs/modules/migrate/pages/ms-word.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/migrate/pages/ms-word.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -4,7 +4,6 @@ :url-pandoc: https://pandoc.org :url-google-asciidoc: https://chrome.google.com/webstore/detail/asciidoc-processor/eghlmnhjljbjodpeehjjcgfcjegcfbhk/ :url-google-asciidoc-source: https://github.com/Mogztter/asciidoc-googledocs-addon/ -// from migrating-from-msword.adoc == Pandoc @@ -18,20 +17,20 @@ .pandoc < 2.11.2 - $ pandoc --from=docx --to=asciidoc --wrap=none --atx-headers \ - --extract-media=extracted-media input.docx > output.adoc + $ pandoc -f docx -t asciidoctor --wrap=none --atx-headers \ + --extract-media=extracted-media -o output.adoc .pandoc (2.11.2 or newer) - $ pandoc input.docx -f docx -t asciidoc --wrap=none --markdown-headings=atx \ - --extract-media=extracted-media -o output2.adoc + $ pandoc input.docx -f docx -t asciidoctor --wrap=none --markdown-headings=atx \ + --extract-media=extracted-media -o output.adoc .pandoc (2.11.2 or newer) and docker If you use docker you can also use the latest version of pandoc with docker without installing it: - $ docker run --rm --volume "`pwd`:/data" --user `id -u`:`id -g` pandoc/core input.docx -f docx \ - -t asciidoc --wrap=none --markdown-headings=atx --extract-media=extracted-media -o output2.adoc + $ docker run --rm --volume "$PWD:/data" --user `id -u`:`id -g` pandoc/core input.docx -f docx \ + -t asciidoctor --wrap=none --markdown-headings=atx --extract-media=extracted-media -o output.adoc Then, edit the output file to tidy it up. diff -Nru asciidoctor-2.0.18/docs/modules/ROOT/nav-docinfo.adoc asciidoctor-2.0.20/docs/modules/ROOT/nav-docinfo.adoc --- asciidoctor-2.0.18/docs/modules/ROOT/nav-docinfo.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/ROOT/nav-docinfo.adoc 1970-01-01 00:00:00.000000000 +0000 @@ -1,3 +0,0 @@ -* xref:docinfo.adoc[] -//** Adding Header Content -//** Adding Footer Content diff -Nru asciidoctor-2.0.18/docs/modules/ROOT/pages/docinfo.adoc asciidoctor-2.0.20/docs/modules/ROOT/pages/docinfo.adoc --- asciidoctor-2.0.18/docs/modules/ROOT/pages/docinfo.adoc 2022-10-15 06:25:57.000000000 +0000 +++ asciidoctor-2.0.20/docs/modules/ROOT/pages/docinfo.adoc 2023-05-18 07:16:38.000000000 +0000 @@ -1,280 +1,4 @@ = Docinfo Files -:url-docbook-info-ref: https://tdg.docbook.org/tdg/5.0/info.html -:url-docinfo-example: https://github.com/clojure-cookbook/clojure-cookbook/blob/master/book-docinfo.xml +:page-location: asciidoc:docinfo:index.adoc -Docinfo is a feature of AsciiDoc that allows you to insert custom content into the head, header, or footer of the output document. -This custom content is read from files known as docinfo files by the converter. -Docinfo files are intended as convenient way to supplement the output produced by a converter. -Examples include injecting auxiliary metadata, stylesheets, and scripting logic not already provided by the converter. - -The docinfo feature does not apply to all backends. -While it works when converting to output formats such as HTML and DocBook, it does not work when converting to PDF using Asciidoctor PDF. - -The docinfo feature must be explicitly enabled using the `docinfo` attribute (see <>). -Which docinfo files are consumed depends on the value of the `docinfo` attribute as well as the backend. - -[#head] -== Head docinfo files - -The content of head docinfo files gets injected into the top of the document. -For HTML, the content is append to the `` element. -For DocBook, the content is appended to the root `` element. - -The docinfo file for HTML output may contain valid elements to populate the HTML `` element, including: - -* `` -* `` -* `` -* `