asciidoctor-pdf 1.5.0.beta.6 → 1.5.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4efe2963835f293701e1e831c7fc5cafce4c1922362b063e8265bd133e29a1
-  data.tar.gz: '08ff1cbea70552786797786465cfab1c626506287dbd8e56ae0204da000c5807'
+  metadata.gz: 4d563652f77af3a20dcc19c756b55981f7a0efaea638a4678087ca95f12a3048
+  data.tar.gz: e335e4b4ad2487ced3f7ab927bbdb8711aa64405987365b41fc7f6695a19a5ac
 SHA512:
-  metadata.gz: 16733468d925e9e30158073fd0859498c2c70fd9c8f3ede9e49ab57eda7391dbde5eda608dead1fcf01db5414a4d46f5f0e486470f45f467b263cf11fdd95ded
-  data.tar.gz: ed4a9a710c1bf31940265451e4bafb312c1fb4ca4d75a2ab69e89948f6e2975c1410a9335edef5e1fd0ce4bb7bb286b4612149d5d01c52014d571143f4d807f4
+  metadata.gz: c0129884c47560e43eb28149451c618160bfcafe68112fb3d247ec67bae13a3f47130cd65dac9b140c2f20e3eaef8d96661b749afea7a1bed2054cdf7c16b8a4
+  data.tar.gz: 7ece71b33af340fac13ffa6e78187e86c25c38f7f0d472a02aaaea8c8cffda5bf5ccd560f4a5a2e914eaaa1dd9730bf4cfef0d9e931b4b60305b6fc065eff429

data/CHANGELOG.adoc

@@ -5,6 +5,28 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.5.0.beta.7 (2019-10-29) - @mojavelinux
+
+* fix value of implicit page-count attribute when page numbering and running content don't start on same page (#1334)
+* fix value of implicit chapter-title attribute on preface pages (#1340)
+* show value of untitled-label attribute in outline if doctitle is not set (#1348)
+* don't show entry for doctitle in outline if doctitle is not set and untitled-label attribute is unset (#1348)
+* generate outline if document has doctitle but no body (#1349)
+* allow elements on title page to be disabled from theme using display: none (#1346)
+* set chapter-title attribute to value of toc-title attribute on toc pages in book (#1338)
+* set section-title attribute to value of toc-title attribute on toc pages in article if page has no other sections (#1338)
+* allow ranges of pages from PDF file to be imported using image macro as specified by pages attribute (#1300)
+* set default footer content in base theme; remove logic to process `footer_<side>_content: none` key (#1320)
+* include doctitle in outline for article when article is only a single page (#1322)
+* allow custom (inline) role to control text decoration property (#1326)
+* point doctitle entry in outline to first page of content when doctype is article and document has front cover
+* fix asciidoctor-pdf-optimize script and register it as a bin script
+* rename `-q` CLI option of asciidoctor-pdf-optimize script to `--quality`
+* only promote first paragraph of preamble to lead paragraph (assuming it has no role) (#1332)
+* don't promote first paragraph of preamble to lead paragraph if it already has a role (#1332)
+* fix crash when document has no doctitle or sections and untitled-label attribute is unset
+* ignore invalid align value for title logo image (#1352)
+
 == 1.5.0.beta.6 (2019-10-11) - @mojavelinux
 
 * reorganize source files under asciidoctor/pdf folder (instead of asciidoctor-pdf)

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.beta.6, 2019-10-12
+v1.5.0.beta.7, 2019-10-29
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.6
+:release-version: 1.5.0.beta.7
 // URIs:
 :url-asciidoctor: http://asciidoctor.org
 :url-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -203,6 +203,38 @@ You then activate syntax highlighting for a given document by adding the `source
 :source-highlighter: rouge
 ----
 
+==== Upgrade Prawn and Extensions (optional)
+
+{project-name} uses Prawn to handle the PDF generation, which has a different release cycle.
+At times, there may are development features in Prawn and its extensions you need to use which haven't yet been released.
+No problem.
+You can still gain access to these features by installing the unreleased gems directly from GitHub.
+
+To get started, first create a [.path]_Gemfile_ in the root of your project.
+In that file, declare the gem soruce, the {project-handle} gem, and the prawn gem and/or one of its extension gems.
+In this example, we'll install both the prawn and prawn-table gems from GitHub.
+
+.Gemfile
+[source,ruby]
+----
+source 'https://rubygems.org'
+
+gem 'asciidoctor-pdf'
+gem 'prawn', github: 'prawnpdf/prawn'
+gem 'prawn-table', github: 'prawnpdf/prawn-table'
+----
+
+You can then install the gems into your project using the `bundle` command:
+
+ $ bundle --path=.bundle/gems
+
+Since you are using Bundler to manage the gems, you'll need to prefix all commands with `bundle exec`.
+For example:
+
+ $ bundle exec asciidoctor-pdf -v
+
+Thus, to any command present in the following sections, be sure to include this prefix.
+
 === Run the Application
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
@@ -616,25 +648,36 @@ To import the first page from a PDF file, use the block image macro with the PDF
 image::custom-page.pdf[]
 ----
 
+The converter will insert the page from the PDF as a dedicated page that matches the size and layout of the page being imported (no matter where the block image occurs).
+Therefore, there's no need to put a manual page break (i.e., `<<<`) around the image macro.
+
 By default, this macro will import the first page of the PDF.
 To import a different page, specify it as a 1-based index using the `page` attribute.
 
 [source,asciidoc]
 ----
-image::custom-page.pdf[page=2]
+image::custom-pages.pdf[page=2]
 ----
 
-To import multiple pages, you'll need to use multiple image macros, each specifying the page number to import.
+You can import multiple pages either using multiple image macros or using the `pages` attribute.
+The `pages` attribute accepts individual page numbers or page number ranges (two page numbers separated by `..`).
+The values can be separated either by commas or semi-colons.
+(The syntax is similar to the syntax uses for the `lines` attribute of the AsciiDoc include directive).
 
-CAUTION: An image macro that imports a PDF page should never be nested inside a delimited block or table.
-It should be a direct descendant of the document or a section.
-Otherwise, the behavior is unspecified.
+[source,asciidoc]
+----
+image::custom-pages.pdf[pages=3;1..2]
+----
 
-The converter will insert the page from the PDF as a dedicated page that matches the size and layout of the page being imported (no matter where the block image occurs).
-Therefore, there's no need to put a manual page break (i.e., `<<<`) around the image macro.
+Pages are imported in the order listed.
 
 To see a practical example of how to use this feature, refer to the blog post https://fromplantoprototype.com/blog/2019/08/07/importing-pdf-pages-in-asciidoctor-pdf/[Importing PDF Pages in asciidoctor-pdf].
 
+CAUTION: An image macro used to imports PDF pages should never be nested inside a delimited block or table cell.
+It should be a direct descendant of the document or a section.
+That's because what it imports are entire pages.
+If it's used inside a delimited block or table cell, the behavior is unspecified.
+
 == Crafting Interdocument Xrefs
 
 This converter produces a single PDF file, which means content from multiple source documents get colocated into the same output file.
@@ -917,7 +960,8 @@ That's why {project-name} always creates this file in addition to the PDF.
 IMPORTANT: The `asciidoctor-pdf-optimize` is not guaranteed to reduce the size of the PDF file.
 It may actually make the PDF larger.
 You should probably only consider using it if the file size of the original PDF is several megabytes.
-You can also try reducing the quality of the output file using the `-q` flag (e.g., `-q screen`).
+You can also try reducing the quality of the output file using the `--quality` flag (e.g., `--quality screen`).
+The `--quality` flag accepts the following keywords: `default` (default), `screen`, `ebook`, `printer`, and `prepress`.
 
 === hexapdf
 
@@ -989,11 +1033,9 @@ We'll leverage the project configuration to install the necessary dependencies.
 
 === Install Dependencies
 
-If you're using {url-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
+We recommend using {url-rvm}[RVM] to manage the installation of Ruby you'll use to build and develop the project.
 
- $ rvm use 2.5@asciidoctor-pdf --create
-
-We like RVM because it keeps the dependencies required by various projects isolated.
+ $ rvm use 2.6
 
 The dependencies needed to use {project-name} are defined in the [.path]_Gemfile_ at the root of the project.
 We can use Bundler to install the dependencies for us.
@@ -1006,11 +1048,11 @@ If it's not installed, use the `gem` command to install it.
 
  $ gem install bundler
 
-Then use the `bundle` command to install the project dependencies:
+Then use the `bundle` command with the `--path` option to install the project dependencies into the project:
 
- $ bundle
+ $ bundle --path=.bundle/gems
 
-NOTE: You need to call `bundle` from the project directory so that it can find the [.path]_Gemfile_.
+NOTE: You must call `bundle` from the project directory so that it can find the [.path]_Gemfile_.
 
 === Run the Tests
 
@@ -1021,11 +1063,11 @@ To run the tests, simply invoke rspec via bundler.
 
 To disable the visual integration tests, pass the `` option:
 
- $ bundle exec rspec -t ~integration
+ $ bundle exec rspec -t ~visual
 
 If a visual integration test fails, you can instruct the test suite to keep the files in the [.path]_spec/output_ directory by setting the `DEBUG` environment variable:
 
- $ DEBUG=true bundle exec rspec -t integration
+ $ DEBUG=true bundle exec rspec -t visual
 
 If you want to see the name of each test as it is run, add the `-fd` option:
 
@@ -1146,6 +1188,23 @@ You'll see a total coverage score, a detailed coverage report, and a link to HTM
 The HTML report helps you understand which lines and branches were missed, if any.
 ////
 
+=== Rebuild the Formatter Text Parser
+
+The formatted text is first converted to a pseudo-HTML language, then converted from there into Prawn text fragments using a https://github.com/cjheath/treetop[treetop] parser.
+treetop is a Ruby-based parsing DSL based on parsing expression grammars.
+This strategy allows the converter to manipulate the formatted text without needing the know the internal details of how Prawn arranges text fragments.
+It also allows Asciidoctor to behave in a consistent manner, since some of the inline parsing in Asciidoctor assumes that the converter is generating an SGML-based language like HTML or DocBook.
+
+The parsing expression grammar is defined in the source file [.path]_lib/asciidoctor/pdf/formatted_text/parser.treetop_.
+If you make a change to this file, you must regenerate the parser, which is defined in the source file _lib/asciidoctor/pdf/formatted_text/parser.rb_.
+(Don't modify the generated parser directly).
+
+Use the following command to regenerate the parser:
+
+ bundle exec tt lib/asciidoctor/pdf/formatted_text/parser.treetop
+
+You then need to commit both files.
+
 [[resources,Links]]
 == Resources
 

data/asciidoctor-pdf.gemspec

@@ -30,7 +30,6 @@ Gem::Specification.new do |s|
   end
   s.files = files.grep %r/^(?:(?:data|lib)\/.+|docs\/theming-guide\.adoc|(?:CHANGELOG|LICENSE|NOTICE|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
   s.executables = (files.grep %r/^bin\//).map {|f| File.basename f }
-  s.executables = ['asciidoctor-pdf']
   s.require_paths = ['lib']
   #s.test_files = files.grep %r/^(?:test|spec|feature)\/.*$/
 

data/bin/asciidoctor-pdf-optimize

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+optimizer = File.absolute_path '../lib/asciidoctor/pdf/optimizer.rb', __dir__
+if File.exist? optimizer
+  require optimizer
+else
+  require 'asciidoctor-pdf/optimizer'
+end
+
+args = ARGV.dup
+
+unless (filename = args.pop)
+  warn 'asciidoctor-pdf-optimize: Please specify a PDF file to optimize.'
+  exit 1
+end
+
+quality = args[0] == '--quality' ? args[1].to_s : ''
+
+(Asciidoctor::PDF::Optimizer.new quality).generate_file filename

data/data/themes/base-theme.yml

@@ -114,3 +114,5 @@ toc_indent: 15
 toc_line_height: 1.4
 footnotes_font_size: 9
 footnotes_item_space: 3
+footer_recto_right_content: '{page-number}'
+footer_verso_left_content: '{page-number}'

data/docs/theming-guide.adoc

@@ -3,7 +3,7 @@ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
 // Settings:
 :idprefix:
 :idseparator: -
-:toc: preamble
+:toc: macro
 :experimental:
 ifndef::env-github[:icons: font]
 ifdef::env-github[]
@@ -845,8 +845,11 @@ This will allow you to use the same font names (aka families) in both your graph
 === Fallback Fonts
 
 If a TrueType font is missing a character needed to render the document, such as a special symbol, you can have Asciidoctor PDF look for the character in a fallback font.
+
 You only need to specify a single fallback font, typically one that provides a full set of symbols.
-If the character isn't found in the fallback font, it will mostly likely be replaced by a box (guaranteed if you're using the bundled fallback font).
+If the character isn't found in the fallback font, it will mostly likely be replaced by a box (which is guaranteed if you're using the bundled fallback font).
+
+IMPORTANT: When defining the fallback font, you *must specify all four variants* (normal, bold, italic, bold_italic), even if you use the same font file for each.
 
 IMPORTANT: The fallback font only gets used when the primary font is a TrueType font (i.e., TTF, DFont, TTC).
 Any glyph missing from an AFM font is simply replaced with the "`not`" glyph (`&#172;`).
@@ -877,6 +880,9 @@ font:
       bold_italic: droid-sans-fallback.ttf
 ----
 
+Notice that we define all four variants for the fallback font, even though we're use the same font file for each variant.
+This ensures the fallback font will be used regardless of which font style is active when it gets called on.
+
 Next, add the key name to the `fallbacks` key under the `font-catalog` key.
 The `fallbacks` key accepts an array of values, meaning you can specify more than one fallback font.
 However, we recommend using a single fallback font, if possible, as shown here:
@@ -1156,7 +1162,7 @@ See <<Title Page>> for details.
 |page:
   size: Letter
 
-|numbering-start-at
+|numbering-start-at^[5]^
 |title {vbar} toc {vbar} body +
 (default: body)
 |page:
@@ -1174,6 +1180,8 @@ To disable the image, use the value `none`.
 . Target may be an absolute path or a path relative to the value of the `pdf-themesdir` attribute.
 . The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin-inner and margin-outer values.
 These margins and used when the value `prepress` is assigned to the `media` document attribute.
+. The `toc` value only applies if the toc is in the default location (before the first page of the body).
+If the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
 
 [#keys-base]
 === Base
@@ -1412,6 +1420,7 @@ The keys in this category are used for inline monospaced text in prose and table
 |literal:
   font-style: bold
 |===
+
 . The border is only used if a border color is specified and the border width is not explicitly set to 0.
 The border only works properly if the literal phrase does not have nested formatting.
 Otherwise, the border will be inherited, producing a less than desirable result.
@@ -1590,11 +1599,13 @@ The keys in this category control the style of a section body.
 3+|[#key-prefix-section]*Key Prefix:* <<key-prefix-section,section>>
 
 |indent
-|<<measurement-units,Measurement>> +
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[left,right]>>^[1]^ +
 (default: 0)
 |section:
-  indent: 36
+  indent: [0.5in, 0]
 |===
+. A single value gets applied to both the left and right side (e.g., `0.5in`).
+A two-value array configures the left and right side independently (e.g., `[0.5in, 0]`).
 
 [#keys-title-page]
 === Title Page
@@ -1604,6 +1615,8 @@ The keys in this category control the style of the title page as well as the arr
 IMPORTANT: The title page is only enabled by default for the book doctype (e.g., `:doctype: book`).
 If you want to enable the title page when using a different doctype (such as the article doctype), you must define the `title-page` attribute in the document header (i.e., `:title-page:`).
 
+NOTE: Subtitle partitioning of the doctitle is only enabled when the title page is also enabled.
+
 TIP: The title page can be disabled for the book doctype by setting the `notitle` attribute in the AsciiDoc document header (i.e., `:notitle:`).
 (For other doctypes, just don't set the `title-page` attribute).
 
@@ -1692,6 +1705,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 
 3+|[#key-prefix-title-page-title]*Key Prefix:* <<key-prefix-title-page-title,title-page-title>>
 
+|display
+|none +
+(default: _not set_)
+|title-page:
+  title:
+    display: none
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -1757,6 +1777,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 
 3+|[#key-prefix-title-page-subtitle]*Key Prefix:* <<key-prefix-title-page-subtitle,title-page-subtitle>>
 
+|display
+|none +
+(default: _not set_)
+|title-page:
+  subtitle:
+    display: none
+
 |font-color
 |<<colors,Color>> +
 (default: _inherit_)
@@ -1815,6 +1842,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 
 3+|[#key-prefix-authors]*Key Prefix:* <<key-prefix-authors,title-page-authors>>
 
+|display
+|none +
+(default: _not set_)
+|title-page:
+  authors:
+    display: none
+
 |delimiter
 |<<quoted-string,Quoted string>> +
 (default: ', ')
@@ -1873,6 +1907,13 @@ TIP: The title page can be disabled for the book doctype by setting the `notitle
 
 3+|[#key-prefix-revision]*Key Prefix:* <<key-prefix-revision,title-page-revision>>
 
+|display
+|none +
+(default: _not set_)
+|title-page:
+  revision:
+    display: none
+
 |delimiter
 |<<quoted-string,Quoted string>> +
 (default: ', ')
@@ -2171,6 +2212,7 @@ The keys in this category are used to control the style of literal, listing and
 |code:
   linenum-font-color: #ccc
 |===
+
 . The line-gap property is used to tune the height of the background color applied to a span of block text highlighted using Rouge.
 . The code-linenum category only applies when using Pygments as the source highlighter.
 Otherwise, the style is controlled by the source highlighter theme.
@@ -2300,6 +2342,7 @@ The keys in this category apply to a button reference (generated from the inline
 |button:
   font-style: normal
 |===
+
 . The border is only used if a border color is specified and the border width is not explicitly set to 0.
 . The border offset is the amount that the background and border swells around the text.
 It does not affect the distance between the formatted phrase and the phrases that surround it.
@@ -2376,6 +2419,7 @@ The keys in this category apply to a key reference (generated from the inline kb
 |key:
   font-style: normal
 |===
+
 . The border is only used if a border color is specified and the border width is not explicitly set to 0.
 . The border offset is the amount that the background and border swells around the text.
 It does not affect the distance between the formatted phrase and the phrases that surround it.
@@ -3062,6 +3106,7 @@ The keys in this category control the SVG integration.
 |svg:
   fallback_font_family: Times-Roman
 |===
+
 . The fallback font family is only used when the font family in the SVG does not map to a known font name from the font catalog.
 
 [#keys-lead]
@@ -3725,6 +3770,7 @@ The keys in this category control the arrangement and style of tables and table
   header-cell:
     text-transform: uppercase
 |===
+
 . This key only controls the color that is used for stripes.
 The appearance of stripes is controlled using the `stripes` table attribute, the `table-stripes` document attribute (since Asciidoctor 2), or the `stripes` document attribute (prior to Asciidoctor 2).
 Permitted attribute values are even, odd, all, and none.
@@ -3979,14 +4025,6 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |===
 |Key |Value Type |Example
 
-3+|[#key-prefix-running-content]*Key Prefix:* <<key-prefix-running-content,running-content>>
-
-|start-at
-|title {vbar} toc {vbar} body +
-(default: body)
-|running-content:
-  start-at: toc
-
 3+|[#key-prefix-header]*Key Prefix:* <<key-prefix-header,header>>
 
 |background-color^[1]^
@@ -4083,7 +4121,7 @@ To avoid this problem, reduce the height of the running content periphery or mak
 |top {vbar} middle {vbar} bottom +
 (default: middle)
 |header:
-  vertical-align: center
+  vertical-align: middle
 
 |<side>-columns^[5]^
 |Column specs triple +
@@ -4212,7 +4250,16 @@ To avoid this problem, reduce the height of the running content periphery or mak
   verso:
     center:
       content: '\{page-number}'
+
+3+|[#key-prefix-running-content]*Key Prefix:* <<key-prefix-running-content,running-content>>
+
+|start-at^[7]^
+|title {vbar} toc {vbar} body +
+(default: body)
+|running-content:
+  start-at: toc
 |===
+
 . The background color spans the width of the page, as does the border when a background color is specified.
 . *If the height is not set, the running content at this periphery is disabled.*
 . If the side padding is negative, the content will bleed into the margin of the page.
@@ -4221,16 +4268,65 @@ To avoid this problem, reduce the height of the running content periphery or mak
 The `columns` key can also be defined one level up (on `header` or `footer`), in which case the setting will be inherited.
 Where the page sides fall in relation to the physical or printed page number is controlled using the `pdf-folio-placement` attribute (except when `media=prepress`, which implies `physical`).
 . `<position>` can be `left`, `center` or `right`.
+. The `toc` value only applies if the toc is in the default location (before the first page of the body).
+If the toc macro is used to position the toc, the start-at behavior is the same as if the toc is not enabled.
 
 IMPORTANT: If you don't specify a height for either the header or footer key, it effectively disables the content at that periphery.
 
+TIP: Although not listed in the table above, you can control the font settings (font-family, font-size, font-color, font-style, text-transform) that get applied to the running content in each column position for each page side (e.g., `footer-<side>-<position>-font-color`).
+For example, you can set the font color used for the right-hand column on recto pages by setting `footer-recto-right-font-color: 6CC644`.
+
 If you define running header and footer content in your theme (including the height), you can still disable this content per document by setting the `noheader` and `nofooter` attributes in the AsciiDoc document header, respectively.
 
-If content is not specified for the running footer, the page number (i.e., `\{page-number}`) is shown on the left on verso pages and the right on recto pages.
-You can disable this behavior by defining the attribute `nofooter` in the AsciiDoc document header or by defining the key `footer-<side>-content: none` in the theme.
+If you extend either the base or default theme, and don't specify content for the footer, the current page number will be added to the right side on recto pages and the left side on verso pages.
+To disable this behavior, you can use the following snippet:
 
-TIP: Although not listed in the table above, you can control the font settings (font-family, font-size, font-color, font-style, text-transform) that get applied to the running content in each column position for each page side (e.g., `footer-<side>-<position>-font-color`).
-For example, you can set the font color used for the right-hand column on recto pages by setting `footer-recto-right-font-color: 6CC644`.
+[source,yaml]
+----
+extends: default
+footer:
+  recto:
+    right:
+      content: ~
+  verso:
+    left:
+      content: ~
+----
+
+Instead of erasing the content (which is what the `~` does), you can specify content of your choosing.
+
+If you want to replace the alternating page numbers with a centered page number, then you can restrict the footer to a single column and specify the content for the center position.
+
+[source,yaml]
+----
+extends: default
+footer:
+  columns: =100%
+  recto:
+    center:
+      content: '{page-number}'
+  verso:
+    center:
+      content: '{page-number}'
+----
+
+In the last two examples, the recto and verso both have the same content.
+In this case, you can reduce the amount of configuring using a YAML reference.
+For example:
+
+[source,yaml]
+----
+extends: default
+footer:
+  columns: =100%
+  recto: &shared_footer
+    center:
+      content: '{page-number}'
+  verso: *shared_footer
+----
+
+The `&shared_footer` assigns an ID to the YAML subtree under the `recto` key and the `*shared_footer` outputs a copy of it under the `verso` key.
+This technique can be used thoughout the theme file as it's a core feature of YAML.
 
 ==== Attribute References
 
@@ -4247,10 +4343,11 @@ In addition, the following attributes are also available when defining the conte
 * section-or-chapter-title
 
 If you reference an attribute which is not defined, all the text on that same line in the running content will be dropped.
+This feature allows you to have alternate lines that are selected when all the attribute references are satisfied.
 One case where this is useful is when referencing the `page-number` attribute.
 If you unset the `pagenums` attribute on the document, any line in the running content that makes reference to `\{page-number}` will be dropped.
 
-You can also built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+&#169;+` and inline formatting (e.g., bold, italic, monospace).
+You can also built-in AsciiDoc text replacements like `+(C)+`, numeric character references like `+&#169;+`, hexidecimal character references like `+&#x20ac;+`, and inline formatting (e.g., bold, italic, monospace).
 
 Here's an example that shows how attributes and replacements can be used in the running footer:
 
@@ -4469,7 +4566,11 @@ These settings override equivalent keys defined in the theme file, where applica
 |flag (default: _not set_)
 |:pdfmark:
 
-|text-align^[7]^
+|scripts^[7]^
+|cjk (default: _not set_)
+|:scripts: cjk
+
+|text-align^[8]^
 |<<text-alignments,Text alignment>>
 |:text-align: left
 
@@ -4477,7 +4578,7 @@ These settings override equivalent keys defined in the theme file, where applica
 |path^[2]^ {vbar} image macro^[3]^
 |:title-logo-image: image:logo.png[top=25%, align=center, pdfwidth=0.5in]
 
-|title-page^[8]^
+|title-page^[9]^
 |flag (default: _not set_)
 |:title-page:
 
@@ -4485,7 +4586,7 @@ These settings override equivalent keys defined in the theme file, where applica
 |path^[2]^ {vbar} image macro^[3]^
 |:title-page-background-image: image:title-bg.jpg[]
 
-|toc-max-pagenum-digits^[9]^
+|toc-max-pagenum-digits^[10]^
 |Integer (default: 3)
 |:toc-max-pagenum-digits: 4
 |===
@@ -4503,6 +4604,10 @@ To disable the background image for a side, use the value `none`.
 . Controls whether the implicit `page-number` attribute is to the running header and footer content specified in the theme file.
 Instead of disabling page numbers, you can use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively.
 . Enables generation of the http://milan.kupcevic.net/ghostscript-ps-pdf/#marks[pdfmark] file, which contains metadata that is fed to Ghostscript when optimizing the PDF file.
+. Activates line break rules for CJK languages (specifically Chinese and Japanese).
+Chinese and Japanese are written without spaces (and may not use spaces when mixing with English words either).
+This setting allows a line break to be placed between any two CJK characters to accommodate wrapping.
+These languages also use different punctuation for pause, full stop, and dash, which are taken into account when breaking lines.
 . _(Experimental)_ The `text-align` document attribute is intended as a simple way to toggle text justification.
 The value of this attribute overrides the `base-align` key set by the theme.
 For more fine-grained control, you should customize using the theme.