asciidoctor-epub3 1.5.1 → 2.0.1

data/lib/asciidoctor-epub3/converter.rb

@@ -2,6 +2,7 @@
 
 require 'mime/types'
 require 'open3'
+require 'sass'
 require_relative 'font_icon_map'
 
 module Asciidoctor
@@ -15,18 +16,19 @@ module Asciidoctor
 
       register_for 'epub3'
 
-      def write output, target
+      def write(output, target)
         epub_file = @format == :kf8 ? %(#{::Asciidoctor::Helpers.rootname target}-kf8.epub) : target
         output.generate_epub epub_file
         logger.debug %(Wrote #{@format.upcase} to #{epub_file})
         if @extract
-          extract_dir = epub_file.sub EpubExtensionRx, ''
+          extract_dir = epub_file.sub EPUB_EXTENSION_RX, ''
           ::FileUtils.remove_dir extract_dir if ::File.directory? extract_dir
           ::Dir.mkdir extract_dir
           ::Dir.chdir extract_dir do
             ::Zip::File.open epub_file do |entries|
               entries.each do |entry|
                 next unless entry.file?
+
                 unless (entry_dir = ::File.dirname entry.name) == '.' || (::File.directory? entry_dir)
                   ::FileUtils.mkdir_p entry_dir
                 end
@@ -38,69 +40,80 @@ module Asciidoctor
         end
 
         if @format == :kf8
-          # QUESTION shouldn't we validate this epub file too?
+          # QUESTION: shouldn't we validate this epub file too?
           distill_epub_to_mobi epub_file, target, @compress
         elsif @validate
           validate_epub epub_file
         end
       end
 
-      CsvDelimiterRx = /\s*,\s*/
+      CSV_DELIMITED_RX = /\s*,\s*/.freeze
 
       DATA_DIR = ::File.expand_path ::File.join(__dir__, '..', '..', 'data')
-      ImageMacroRx = /^image::?(.*?)\[(.*?)\]$/
-      ImgSrcScanRx = /<img src="(.+?)"/
-      SvgImgSniffRx = /<img src=".+?\.svg"/
+      IMAGE_MACRO_RX = /^image::?(.*?)\[(.*?)\]$/.freeze
+      IMAGE_SRC_SCAN_RX = /<img src="(.+?)"/.freeze
+      SVG_IMG_SNIFF_RX = /<img src=".+?\.svg"/.freeze
 
-      LF = ?\n
-      NoBreakSpace = '&#xa0;'
-      RightAngleQuote = '&#x203a;'
-      CalloutStartNum = %(\u2460)
+      LF = "\n"
+      NO_BREAK_SPACE = '&#xa0;'
+      RIGHT_ANGLE_QUOTE = '&#x203a;'
+      CALLOUT_START_NUM = %(\u2460)
 
-      CharEntityRx = /&#(\d{2,6});/
-      XmlElementRx = /<\/?.+?>/
-      TrailingPunctRx = /[[:punct:]]$/
+      CHAR_ENTITY_RX = /&#(\d{2,6});/.freeze
+      XML_ELEMENT_RX = %r{</?.+?>}.freeze
+      TRAILING_PUNCT_RX = /[[:punct:]]$/.freeze
 
-      FromHtmlSpecialCharsMap = {
+      FROM_HTML_SPECIAL_CHARS_MAP = {
         '&lt;' => '<',
         '&gt;' => '>',
-        '&amp;' => '&',
-      }
+        '&amp;' => '&'
+      }.freeze
 
-      FromHtmlSpecialCharsRx = /(?:#{FromHtmlSpecialCharsMap.keys * '|'})/
+      FROM_HTML_SPECIAL_CHARS_RX = /(?:#{FROM_HTML_SPECIAL_CHARS_MAP.keys * '|'})/.freeze
 
-      ToHtmlSpecialCharsMap = {
+      TO_HTML_SPECIAL_CHARS_MAP = {
         '&' => '&amp;',
         '<' => '&lt;',
-        '>' => '&gt;',
-      }
-
-      ToHtmlSpecialCharsRx = /[#{ToHtmlSpecialCharsMap.keys.join}]/
-
-      EpubExtensionRx = /\.epub$/i
-      KindlegenCompression = ::Hash['0', '-c0', '1', '-c1', '2', '-c2', 'none', '-c0', 'standard', '-c1', 'huffdic', '-c2']
-
-      (QUOTE_TAGS = {
-        monospaced: ['<code>', '</code>', true],
-        emphasis: ['<em>', '</em>', true],
-        strong: ['<strong>', '</strong>', true],
-        double: ['“', '”'],
-        single: ['‘', '’'],
-        mark: ['<mark>', '</mark>', true],
-        superscript: ['<sup>', '</sup>', true],
-        subscript: ['<sub>', '</sub>', true],
-        asciimath: ['<code>', '</code>', true],
-        latexmath: ['<code>', '</code>', true],
-      }).default = ['', '']
-
-      def initialize backend, opts = {}
+        '>' => '&gt;'
+      }.freeze
+
+      TO_HTML_SPECIAL_CHARS_RX = /[#{TO_HTML_SPECIAL_CHARS_MAP.keys.join}]/.freeze
+
+      EPUB_EXTENSION_RX = /\.epub$/i.freeze
+      KINDLEGEN_COMPRESSION = {
+        '0' => '-c0',
+        '1' => '-c1',
+        '2' => '-c2',
+        'none' => '-c0',
+        'standard' => '-c1',
+        'huffdic' => '-c2'
+      }.freeze
+
+      QUOTE_TAGS = begin
+        tags = {
+          monospaced: ['<code>', '</code>', true],
+          emphasis: ['<em>', '</em>', true],
+          strong: ['<strong>', '</strong>', true],
+          double: ['“', '”'],
+          single: ['‘', '’'],
+          mark: ['<mark>', '</mark>', true],
+          superscript: ['<sup>', '</sup>', true],
+          subscript: ['<sub>', '</sub>', true],
+          asciimath: ['<code>', '</code>', true],
+          latexmath: ['<code>', '</code>', true]
+        }
+        tags.default = ['', '']
+        tags.freeze
+      end
+
+      def initialize(backend, opts = {})
         super
         basebackend 'html'
         outfilesuffix '.epub' # dummy outfilesuffix since it may be .mobi
         htmlsyntax 'xml'
       end
 
-      def convert node, name = nil, _opts = {}
+      def convert(node, name = nil, _opts = {})
         method_name = %(convert_#{name ||= node.node_name})
         if respond_to? method_name
           send method_name, node
@@ -110,44 +123,41 @@ module Asciidoctor
         end
       end
 
-      # See https://asciidoctor.org/docs/user-manual/#book-parts-and-chapters
-      def get_chapter_name node
-        if node.document.doctype != 'book'
-          return Asciidoctor::Document === node ? node.attr('docname') || node.id : nil
-        end
-        return (node.id || 'preamble') if node.context == :preamble && node.level == 0
-        chapter_level = [node.document.attr('epub-chapter-level', 1).to_i, 1].max
-        Asciidoctor::Section === node && node.level <= chapter_level ? node.id : nil
+      # @param node [Asciidoctor::AbstractNode]
+      # @return [String, nil]
+      def get_chapter_filename(node)
+        node.id if node.chapter?
       end
 
-      def get_numbered_title node
+      def get_numbered_title(node)
         doc_attrs = node.document.attributes
         level = node.level
         if node.caption
-          title = node.captioned_title
+          node.captioned_title
         elsif node.respond_to?(:numbered) && node.numbered && level <= (doc_attrs['sectnumlevels'] || 3).to_i
           if level < 2 && node.document.doctype == 'book'
-            if node.sectname == 'chapter'
-              title = %(#{(signifier = doc_attrs['chapter-signifier']) ? "#{signifier} " : ''}#{node.sectnum} #{node.title})
-            elsif node.sectname == 'part'
-              title = %(#{(signifier = doc_attrs['part-signifier']) ? "#{signifier} " : ''}#{node.sectnum nil, ':'} #{node.title})
+            case node.sectname
+            when 'chapter'
+              %(#{(signifier = doc_attrs['chapter-signifier']) ? "#{signifier} " : ''}#{node.sectnum} #{node.title})
+            when 'part'
+              %(#{(signifier = doc_attrs['part-signifier']) ? "#{signifier} " : ''}#{node.sectnum nil,
+                                                                                                  ':'} #{node.title})
             else
-              title = %(#{node.sectnum} #{node.title})
+              %(#{node.sectnum} #{node.title})
             end
           else
-            title = %(#{node.sectnum} #{node.title})
+            %(#{node.sectnum} #{node.title})
           end
         else
-          title = node.title
+          node.title
         end
-        title
       end
 
       def icon_names
         @icon_names ||= []
       end
 
-      def convert_document node
+      def convert_document(node)
         @format = node.attr('ebook-format').to_sym
 
         @validate = node.attr? 'ebook-validate'
@@ -169,9 +179,9 @@ module Asciidoctor
           @book.primary_identifier node.id, 'pub-identifier', 'uuid'
         end
         # replace with next line once the attributes argument is supported
-        #unique_identifier doc.id, 'pub-id', 'uuid', 'scheme' => 'xsd:string'
+        # unique_identifier doc.id, 'pub-id', 'uuid', 'scheme' => 'xsd:string'
 
-        # NOTE we must use :plain_text here since gepub reencodes
+        # NOTE: we must use :plain_text here since gepub reencodes
         @book.add_title sanitize_doctitle_xml(node, :plain_text), id: 'pub-title'
 
         # see https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dccreator
@@ -181,7 +191,7 @@ module Asciidoctor
         end
 
         publisher = node.attr 'publisher'
-        # NOTE Use producer as both publisher and producer if publisher isn't specified
+        # NOTE: Use producer as both publisher and producer if publisher isn't specified
         publisher = node.attr 'producer' if publisher.nil_or_empty?
         @book.publisher = publisher unless publisher.nil_or_empty?
 
@@ -207,7 +217,7 @@ module Asciidoctor
         @book.source = node.attr 'source' if node.attr? 'source'
         @book.rights = node.attr 'copyright' if node.attr? 'copyright'
 
-        (node.attr 'keywords', '').split(CsvDelimiterRx).each do |s|
+        (node.attr 'keywords', '').split(CSV_DELIMITED_RX).each do |s|
           @book.metadata.add_metadata 'subject', s
         end
 
@@ -216,7 +226,8 @@ module Asciidoctor
           series_volume = node.attr 'series-volume', 1
           series_id = node.attr 'series-id'
 
-          series_meta = @book.metadata.add_metadata 'meta', series_name, id: 'pub-collection', group_position: series_volume
+          series_meta = @book.metadata.add_metadata 'meta', series_name, id: 'pub-collection',
+                                                                         group_position: series_volume
           series_meta['property'] = 'belongs-to-collection'
           series_meta.refine 'dcterms:identifier', series_id unless series_id.nil?
           # Calibre only understands 'series'
@@ -228,10 +239,17 @@ module Asciidoctor
         landmarks = []
 
         front_cover = add_cover_page node, 'front-cover'
+        if front_cover.nil? && @format != :kf8 && node.doctype == 'book'
+          # TODO(#352): add textual front cover similar to PDF
+        end
+
         landmarks << { type: 'cover', href: front_cover.href, title: 'Front Cover' } unless front_cover.nil?
 
         front_matter_page = add_front_matter_page node
-        landmarks << { type: 'frontmatter', href: front_matter_page.href, title: 'Front Matter' } unless front_matter_page.nil?
+        unless front_matter_page.nil?
+          landmarks << { type: 'frontmatter', href: front_matter_page.href,
+                         title: 'Front Matter' }
+        end
 
         nav_item = @book.add_item('nav.xhtml', id: 'nav').nav
 
@@ -256,17 +274,26 @@ module Asciidoctor
         _back_cover = add_cover_page node, 'back-cover'
         # TODO: add landmark for back cover? But what epub:type?
 
-        landmarks << { type: 'bodymatter', href: %(#{get_chapter_name toc_items[0]}.xhtml), title: 'Start of Content' } unless toc_items.empty?
+        unless toc_items.empty?
+          landmarks << { type: 'bodymatter', href: %(#{get_chapter_filename toc_items[0]}.xhtml),
+                         title: 'Start of Content' }
+        end
 
         toc_items.each do |item|
-          landmarks << { type: item.style, href: %(#{get_chapter_name item}.xhtml), title: item.title } if %w(appendix bibliography glossary index preface).include? item.style
+          next unless %w[appendix bibliography glossary index preface].include? item.style
+
+          landmarks << {
+            type: item.style,
+            href: %(#{get_chapter_filename item}.xhtml),
+            title: item.title
+          }
         end
 
         nav_item.add_content postprocess_xhtml(nav_doc(node, toc_items, landmarks, outlinelevels))
         # User is not supposed to see landmarks, so pass empty array here
         toc_item&.add_content postprocess_xhtml(nav_doc(node, toc_items, [], toclevels))
 
-        # NOTE gepub doesn't support building a ncx TOC with depth > 1, so do it ourselves
+        # NOTE: gepub doesn't support building a ncx TOC with depth > 1, so do it ourselves
         toc_ncx = ncx_doc node, toc_items, outlinelevels
         @book.add_item 'toc.ncx', content: toc_ncx.to_ios, id: 'ncx'
 
@@ -278,7 +305,7 @@ module Asciidoctor
             logger.warn %(path is reserved for cover artwork: #{name}; skipping file found in content)
           elsif file[:path].nil? || File.readable?(file[:path])
             mime_types = MIME::Types.type_for name
-            mime_types.delete_if {|x| x.media_type != file[:media_type] }
+            mime_types.delete_if { |x| x.media_type != file[:media_type] }
             preferred_mime_type = mime_types.empty? ? nil : mime_types[0].content_type
             @book.add_item name, content: file[:path], media_type: preferred_mime_type
           else
@@ -286,11 +313,11 @@ module Asciidoctor
           end
         end
 
-        #add_metadata 'ibooks:specified-fonts', true
+        # add_metadata 'ibooks:specified-fonts', true
 
         add_theme_assets node
         if node.doctype != 'book'
-          usernames = [node].map {|item| item.attr 'username' }.compact.uniq
+          usernames = [node].map { |item| item.attr 'username' }.compact.uniq
           add_profile_images node, usernames
         end
 
@@ -298,17 +325,16 @@ module Asciidoctor
       end
 
       # FIXME: move to Asciidoctor::Helpers
-      def sanitize_doctitle_xml doc, content_spec
+      def sanitize_doctitle_xml(doc, content_spec)
         doctitle = doc.doctitle use_fallback: true
         sanitize_xml doctitle, content_spec
       end
 
       # FIXME: move to Asciidoctor::Helpers
-      def sanitize_xml content, content_spec
-        if content_spec != :pcdata && (content.include? '<')
-          if (content = (content.gsub XmlElementRx, '').strip).include? ' '
-            content = content.tr_s ' ', ' '
-          end
+      def sanitize_xml(content, content_spec)
+        if content_spec != :pcdata && (content.include? '<') && ((content = (content.gsub XML_ELEMENT_RX,
+                                                                                          '').strip).include? ' ')
+          content = content.tr_s ' ', ' '
         end
 
         case content_spec
@@ -318,8 +344,8 @@ module Asciidoctor
           # noop
         when :plain_text
           if content.include? ';'
-            content = content.gsub(CharEntityRx) { [$1.to_i].pack 'U*' } if content.include? '&#'
-            content = content.gsub FromHtmlSpecialCharsRx, FromHtmlSpecialCharsMap
+            content = content.gsub(CHAR_ENTITY_RX) { [::Regexp.last_match(1).to_i].pack 'U*' } if content.include? '&#'
+            content = content.gsub FROM_HTML_SPECIAL_CHARS_RX, FROM_HTML_SPECIAL_CHARS_MAP
           end
         else
           raise ::ArgumentError, %(Unknown content spec: #{content_spec})
@@ -327,11 +353,12 @@ module Asciidoctor
         content
       end
 
-      def add_chapter node
-        docid = get_chapter_name node
-        return nil if docid.nil?
+      # @param node [Asciidoctor::AbstractBlock]
+      def add_chapter(node)
+        filename = get_chapter_filename node
+        return nil if filename.nil?
 
-        chapter_item = @book.add_ordered_item %(#{docid}.xhtml)
+        chapter_item = @book.add_ordered_item %(#{filename}.xhtml)
 
         doctitle = node.document.doctitle partition: true, use_fallback: true
         chapter_title = doctitle.combined
@@ -364,12 +391,12 @@ module Asciidoctor
         @xrefs_seen.clear
         content = node.content
 
-        # NOTE must run after content is resolved
+        # NOTE: must run after content is resolved
         # TODO perhaps create dynamic CSS file?
         if icon_names.empty?
           icon_css_head = ''
         else
-          icon_defs = icon_names.map {|name|
+          icon_defs = icon_names.map { |name|
             %(.i-#{name}::before { content: "#{FontIconMap.unicode name}"; })
           } * LF
           icon_css_head = %(<style>
@@ -378,21 +405,26 @@ module Asciidoctor
 )
         end
 
-        header = (title || subtitle) ? %(<header>
+        header = if title || subtitle
+                   %(<header>
 <div class="chapter-header">
 #{byline}<h1 class="chapter-title">#{title}#{subtitle ? %(<small class="subtitle">#{subtitle}</small>) : ''}</h1>
 </div>
-</header>) : ''
+</header>)
+                 else
+                   ''
+                 end
 
         # We want highlighter CSS to be stored in a separate file
         # in order to avoid style duplication across chapter files
         linkcss = true
 
-        # NOTE kindlegen seems to mangle the <header> element, so we wrap its content in a div
-        lines = [%(<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:mml="http://www.w3.org/1998/Math/MathML" xml:lang="#{lang = node.document.attr 'lang', 'en'}" lang="#{lang}">
+        # NOTE: kindlegen seems to mangle the <header> element, so we wrap its content in a div
+        lines = [%(<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:mml="http://www.w3.org/1998/Math/MathML" xml:lang="#{lang = node.document.attr 'lang',
+                                                                                                                                                                          'en'}" lang="#{lang}">
 <head>
-<meta charset="UTF-8"/>
 <title>#{chapter_title}</title>
 <link rel="stylesheet" type="text/css" href="styles/epub3.css"/>
 <link rel="stylesheet" type="text/css" href="styles/epub3-css3-only.css" media="(min-device-width: 0px)"/>
@@ -409,24 +441,27 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         syntax_hl = node.document.syntax_highlighter
         epub_type_attr = node.respond_to?(:section) && node.sectname != 'section' ? %( epub:type="#{node.sectname}") : ''
 
-        lines << (syntax_hl.docinfo :head, node, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl&.docinfo? :head
+        if syntax_hl&.docinfo? :head
+          lines << (syntax_hl.docinfo :head, node, linkcss: linkcss,
+                                                   self_closing_tag_slash: '/')
+        end
 
         lines << %(</head>
 <body>
-<section class="chapter" title=#{chapter_title.encode xml: :attr}#{epub_type_attr} id="#{docid}">
+<section class="chapter" title=#{chapter_title.encode xml: :attr}#{epub_type_attr} id="#{filename}">
 #{header}
         #{content})
 
         unless (fns = node.document.footnotes - @footnotes).empty?
           @footnotes += fns
 
-          # NOTE kindlegen seems to mangle the <footer> element, so we wrap its content in a div
+          # NOTE: kindlegen seems to mangle the <footer> element, so we wrap its content in a div
           lines << '<footer>
 <div class="chapter-footer">
 <div class="footnotes">'
           fns.each do |footnote|
             lines << %(<aside id="note-#{footnote.index}" epub:type="footnote">
-<p><sup class="noteref"><a href="#noteref-#{footnote.index}">#{footnote.index}</a></sup> #{footnote.text}</p>
+<p>#{footnote.text}</p>
 </aside>)
           end
           lines << '</div>
@@ -436,7 +471,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
         lines << '</section>'
 
-        lines << (syntax_hl.docinfo :footer, node.document, linkcss: linkcss, self_closing_tag_slash: '/') if syntax_hl&.docinfo? :footer
+        if syntax_hl&.docinfo? :footer
+          lines << (syntax_hl.docinfo :footer, node.document, linkcss: linkcss,
+                                                              self_closing_tag_slash: '/')
+        end
 
         lines << '</body>
 </html>'
@@ -451,39 +489,43 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         chapter_item
       end
 
-      def convert_section node
-        if add_chapter(node).nil?
-          hlevel = node.level
-          epub_type_attr = node.sectname != 'section' ? %( epub:type="#{node.sectname}") : ''
-          div_classes = [%(sect#{node.level}), node.role].compact
-          title = get_numbered_title node
-          %(<section class="#{div_classes * ' '}" title=#{title.encode xml: :attr}#{epub_type_attr}>
-<h#{hlevel} id="#{node.id}">#{title}</h#{hlevel}>#{(content = node.content).empty? ? '' : %(
-          #{content})}
+      # @param node [Asciidoctor::Section]
+      def convert_section(node)
+        return unless add_chapter(node).nil?
+
+        hlevel = node.level.clamp 1, 6
+        epub_type_attr = node.sectname == 'section' ? '' : %( epub:type="#{node.sectname}")
+        div_classes = [%(sect#{node.level}), node.role].compact
+        title = get_numbered_title node
+        %(<section class="#{div_classes * ' '}" title=#{title.encode xml: :attr}#{epub_type_attr}>
+<h#{hlevel} id="#{node.id}">#{title}</h#{hlevel}>#{if (content = node.content).empty?
+                                                     ''
+                                                   else
+                                                     %(
+          #{content})
+                                                   end}
 </section>)
-        end
       end
 
-      # NOTE embedded is used for AsciiDoc table cell content
-      def convert_embedded node
+      # NOTE: embedded is used for AsciiDoc table cell content
+      def convert_embedded(node)
         node.content
       end
 
       # TODO: support use of quote block as abstract
-      def convert_preamble node
-        if add_chapter(node).nil?
-          if (first_block = node.blocks[0]) && first_block.style == 'abstract'
-            convert_abstract first_block
-            # REVIEW: should we treat the preamble as an abstract in general?
-          elsif first_block && node.blocks.size == 1
-            convert_abstract first_block
-          else
-            node.content
-          end
+      def convert_preamble(node)
+        return unless add_chapter(node).nil?
+
+        if ((first_block = node.blocks[0]) && first_block.style == 'abstract') ||
+           # REVIEW: should we treat the preamble as an abstract in general?
+           (first_block && node.blocks.size == 1)
+          convert_abstract first_block
+        else
+          node.content
         end
       end
 
-      def convert_open node
+      def convert_open(node)
         id_attr = node.id ? %( id="#{node.id}") : nil
         class_attr = node.role ? %( class="#{node.role}") : nil
         if id_attr || class_attr
@@ -495,18 +537,22 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def convert_abstract node
+      def convert_abstract(node)
         %(<div class="abstract" epub:type="preamble">
 #{output_content node}
 </div>)
       end
 
-      def convert_paragraph node
+      def convert_paragraph(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         role = node.role
         # stack-head is the alternative to the default, inline-head (where inline means "run-in")
         head_stop = node.attr 'head-stop', (role && (node.has_role? 'stack-head') ? nil : '.')
-        head = node.title? ? %(<strong class="head">#{title = node.title}#{head_stop && title !~ TrailingPunctRx ? head_stop : ''}</strong> ) : ''
+        head = if node.title?
+                 %(<strong class="head">#{title = node.title}#{head_stop && title !~ TRAILING_PUNCT_RX ? head_stop : ''}</strong> )
+               else
+                 ''
+               end
         if role
           node.set_option 'hardbreaks' if node.has_role? 'signature'
           %(<p#{id_attr} class="#{role}">#{head}#{node.content}</p>)
@@ -515,7 +561,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def convert_pass node
+      def convert_pass(node)
         content = node.content
         if content == '<?hard-pagebreak?>'
           '<hr epub:type="pagebreak" class="pagebreak"/>'
@@ -524,7 +570,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def convert_admonition node
+      def convert_admonition(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         if node.title?
           title = node.title
@@ -547,17 +593,21 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
                       logger.warn %(unknown admonition type: #{type})
                       'notice'
                     end
-        %(<aside#{id_attr} class="admonition #{type}"#{title_attr} epub:type="#{epub_type}">
+        %(<aside#{id_attr} class="admonition #{type}#{(role = node.role) ? " #{role}" : ''}"#{title_attr} epub:type="#{epub_type}">
 #{title_el}<div class="content">
 #{output_content node}
 </div>
 </aside>)
       end
 
-      def convert_example node
+      def convert_example(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
-        title_div = node.title? ? %(<div class="example-title">#{node.title}</div>
-) : ''
+        title_div = if node.title?
+                      %(<div class="example-title">#{node.title}</div>
+)
+                    else
+                      ''
+                    end
         %(<div#{id_attr} class="example">
 #{title_div}<div class="example-content">
 #{output_content node}
@@ -565,23 +615,28 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </div>)
       end
 
-      def convert_floating_title node
+      def convert_floating_title(node)
         tag_name = %(h#{node.level + 1})
         id_attribute = node.id ? %( id="#{node.id}") : ''
         %(<#{tag_name}#{id_attribute} class="#{['discrete', node.role].compact * ' '}">#{node.title}</#{tag_name}>)
       end
 
-      def convert_listing node
+      # @param node [Asciidoctor::Block]
+      def convert_listing(node)
         id_attribute = node.id ? %( id="#{node.id}") : ''
         nowrap = (node.option? 'nowrap') || !(node.document.attr? 'prewrap')
         if node.style == 'source'
           lang = node.attr 'language'
           syntax_hl = node.document.syntax_highlighter
           if syntax_hl
-            opts = syntax_hl.highlight? ? {
-              css_mode: ((doc_attrs = node.document.attributes)[%(#{syntax_hl.name}-css)] || :class).to_sym,
-              style: doc_attrs[%(#{syntax_hl.name}-style)],
-            } : {}
+            opts = if syntax_hl.highlight?
+                     {
+                       css_mode: ((doc_attrs = node.document.attributes)[%(#{syntax_hl.name}-css)] || :class).to_sym,
+                       style: doc_attrs[%(#{syntax_hl.name}-style)]
+                     }
+                   else
+                     {}
+                   end
             opts[:nowrap] = nowrap
           else
             pre_open = %(<pre class="highlight#{nowrap ? ' nowrap' : ''}"><code#{lang ? %( class="language-#{lang}" data-lang="#{lang}") : ''}>)
@@ -600,7 +655,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </figure>)
       end
 
-      def convert_stem node
+      def convert_stem(node)
         return convert_listing node if node.style != 'asciimath' || !asciimath_available?
 
         id_attr = node.id ? %( id="#{node.id}") : ''
@@ -623,7 +678,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         Helpers.require_library('asciimath', true, :warn).nil? ? :unavailable : :loaded
       end
 
-      def convert_literal node
+      def convert_literal(node)
         id_attribute = node.id ? %( id="#{node.id}") : ''
         title_element = node.title? ? %(<figcaption>#{node.captioned_title}</figcaption>) : ''
         %(<figure#{id_attribute} class="literalblock#{prepend_space node.role}">
@@ -632,15 +687,15 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </figure>)
       end
 
-      def convert_page_break _node
+      def convert_page_break(_node)
         '<hr epub:type="pagebreak" class="pagebreak"/>'
       end
 
-      def convert_thematic_break _node
+      def convert_thematic_break(_node)
         '<hr class="thematicbreak"/>'
       end
 
-      def convert_quote node
+      def convert_quote(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         class_attr = (role = node.role) ? %( class="blockquote #{role}") : ' class="blockquote"'
 
@@ -656,8 +711,12 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
         footer_content << %(<span class="context">#{node.title}</span>) if node.title?
 
-        footer_tag = footer_content.empty? ? '' : %(
+        footer_tag = if footer_content.empty?
+                       ''
+                     else
+                       %(
 <footer>~ #{footer_content * ' '}</footer>)
+                     end
         content = (output_content node).strip
         %(<div#{id_attr}#{class_attr}>
 <blockquote>
@@ -666,7 +725,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </div>)
       end
 
-      def convert_verse node
+      def convert_verse(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         class_attr = (role = node.role) ? %( class="verse #{role}") : ' class="verse"'
 
@@ -680,14 +739,18 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           footer_content << %(<cite title="#{citetitle_sanitized}">#{citetitle}</cite>)
         end
 
-        footer_tag = !footer_content.empty? ? %(
-<span class="attribution">~ #{footer_content * ', '}</span>) : ''
+        footer_tag = if footer_content.empty?
+                       ''
+                     else
+                       %(
+<span class="attribution">~ #{footer_content * ', '}</span>)
+                     end
         %(<div#{id_attr}#{class_attr}>
 <pre>#{node.content}#{footer_tag}</pre>
 </div>)
       end
 
-      def convert_sidebar node
+      def convert_sidebar(node)
         classes = ['sidebar']
         if node.title?
           classes << 'titled'
@@ -707,18 +770,21 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </aside>)
       end
 
-      def convert_table node
+      def convert_table(node)
         lines = [%(<div class="table">)]
         lines << %(<div class="content">)
         table_id_attr = node.id ? %( id="#{node.id}") : ''
         table_classes = [
           'table',
           %(table-framed-#{node.attr 'frame', 'rows', 'table-frame'}),
-          %(table-grid-#{node.attr 'grid', 'rows', 'table-grid'}),
+          %(table-grid-#{node.attr 'grid', 'rows', 'table-grid'})
         ]
         if (role = node.role)
           table_classes << role
         end
+        if (float = node.attr 'float')
+          table_classes << float
+        end
         table_styles = []
         if (autowidth = node.option? 'autowidth') && !(node.attr? 'width')
           table_classes << 'fit-content'
@@ -726,21 +792,21 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           table_styles << %(width: #{node.attr 'tablepcwidth'}%;)
         end
         table_class_attr = %( class="#{table_classes * ' '}")
-        table_style_attr = !table_styles.empty? ? %( style="#{table_styles * '; '}") : ''
+        table_style_attr = table_styles.empty? ? '' : %( style="#{table_styles * '; '}")
 
         lines << %(<table#{table_id_attr}#{table_class_attr}#{table_style_attr}>)
         lines << %(<caption>#{node.captioned_title}</caption>) if node.title?
-        if (node.attr 'rowcount') > 0
+        if (node.attr 'rowcount').positive?
           lines << '<colgroup>'
           if autowidth
             lines += (Array.new node.columns.size, %(<col/>))
           else
             node.columns.each do |col|
-              lines << ((col.option? 'autowidth') ? %(<col/>) : %(<col style="width: #{col.attr 'colpcwidth'}%;" />))
+              lines << (col.option?('autowidth') ? %(<col/>) : %(<col style="width: #{col.attr 'colpcwidth'}%;" />))
             end
           end
           lines << '</colgroup>'
-          [:head, :body, :foot].reject {|tsec| node.rows[tsec].empty? }.each do |tsec|
+          %i[head body foot].reject { |tsec| node.rows[tsec].empty? }.each do |tsec|
             lines << %(<t#{tsec}>)
             node.rows[tsec].each do |row|
               lines << '<tr>'
@@ -766,12 +832,12 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
                 cell_tag_name = tsec == :head || cell.style == :header ? 'th' : 'td'
                 cell_classes = [
                   "halign-#{cell.attr 'halign'}",
-                  "valign-#{cell.attr 'valign'}",
+                  "valign-#{cell.attr 'valign'}"
                 ]
-                cell_class_attr = !cell_classes.empty? ? %( class="#{cell_classes * ' '}") : ''
+                cell_class_attr = cell_classes.empty? ? '' : %( class="#{cell_classes * ' '}")
                 cell_colspan_attr = cell.colspan ? %( colspan="#{cell.colspan}") : ''
                 cell_rowspan_attr = cell.rowspan ? %( rowspan="#{cell.rowspan}") : ''
-                cell_style_attr = (node.document.attr? 'cellbgcolor') ? %( style="background-color: #{node.document.attr 'cellbgcolor'}") : ''
+                cell_style_attr = node.document.attr?('cellbgcolor') ? %( style="background-color: #{node.document.attr 'cellbgcolor'}") : ''
                 lines << %(<#{cell_tag_name}#{cell_class_attr}#{cell_colspan_attr}#{cell_rowspan_attr}#{cell_style_attr}>#{cell_content}</#{cell_tag_name}>)
               end
               lines << '</tr>'
@@ -785,10 +851,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         lines * LF
       end
 
-      def convert_colist node
+      def convert_colist(node)
         lines = ['<div class="callout-list">
 <ol>']
-        num = CalloutStartNum
+        num = CALLOUT_START_NUM
         node.items.each_with_index do |item, i|
           lines << %(<li><i class="conum" data-value="#{i + 1}">#{num}</i> #{item.text}</li>)
           num = num.next
@@ -798,7 +864,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       # TODO: add complex class if list has nested blocks
-      def convert_dlist node
+      def convert_dlist(node)
         lines = []
         id_attribute = node.id ? %( id="#{node.id}") : ''
 
@@ -806,7 +872,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
                   when 'horizontal'
                     ['hdlist', node.role]
                   when 'itemized', 'ordered'
-                    # QUESTION should we just use itemized-list and ordered-list as the class here? or just list?
+                    # QUESTION: should we just use itemized-list and ordered-list as the class here? or just list?
                     ['dlist', %(#{node.style}-list), node.role]
                   else
                     ['description-list']
@@ -822,13 +888,13 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           list_tag_name = style == 'itemized' ? 'ul' : 'ol'
           role = node.role
           subject_stop = node.attr 'subject-stop', (role && (node.has_role? 'stack') ? nil : ':')
-          list_class_attr = (node.option? 'brief') ? ' class="brief"' : ''
+          list_class_attr = node.option?('brief') ? ' class="brief"' : ''
           lines << %(<#{list_tag_name}#{list_class_attr}#{list_tag_name == 'ol' && (node.option? 'reversed') ? ' reversed="reversed"' : ''}>)
           node.items.each do |subjects, dd|
             # consists of one term (a subject) and supporting content
-            subject = [*subjects].first.text
+            subject = Array(subjects).first.text
             subject_plain = xml_sanitize subject, :plain
-            subject_element = %(<strong class="subject">#{subject}#{subject_stop && subject_plain !~ TrailingPunctRx ? subject_stop : ''}</strong>)
+            subject_element = %(<strong class="subject">#{subject}#{subject_stop && subject_plain !~ TRAILING_PUNCT_RX ? subject_stop : ''}</strong>)
             lines << '<li>'
             if dd
               # NOTE: must wrap remaining text in a span to help webkit justify the text properly
@@ -844,15 +910,15 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           lines << '<table>'
           if (node.attr? 'labelwidth') || (node.attr? 'itemwidth')
             lines << '<colgroup>'
-            col_style_attribute = (node.attr? 'labelwidth') ? %( style="width: #{(node.attr 'labelwidth').chomp '%'}%;") : ''
+            col_style_attribute = node.attr?('labelwidth') ? %( style="width: #{(node.attr 'labelwidth').chomp '%'}%;") : ''
             lines << %(<col#{col_style_attribute} />)
-            col_style_attribute = (node.attr? 'itemwidth') ? %( style="width: #{(node.attr 'itemwidth').chomp '%'}%;") : ''
+            col_style_attribute = node.attr?('itemwidth') ? %( style="width: #{(node.attr 'itemwidth').chomp '%'}%;") : ''
             lines << %(<col#{col_style_attribute} />)
             lines << '</colgroup>'
           end
           node.items.each do |terms, dd|
             lines << '<tr>'
-            lines << %(<td class="hdlist1#{(node.option? 'strong') ? ' strong' : ''}">)
+            lines << %(<td class="hdlist1#{node.option?('strong') ? ' strong' : ''}">)
             first_term = true
             terms.each do |dt|
               lines << %(<br />) unless first_term
@@ -874,12 +940,13 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         else
           lines << '<dl>'
           node.items.each do |terms, dd|
-            [*terms].each do |dt|
+            Array(terms).each do |dt|
               lines << %(<dt>
 <span class="term">#{dt.text}</span>
 </dt>)
             end
             next unless dd
+
             lines << '<dd>'
             if dd.blocks?
               lines << %(<span class="principal">#{dd.text}</span>) if dd.text?
@@ -896,22 +963,22 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         lines * LF
       end
 
-      def convert_olist node
+      def convert_olist(node)
         complex = false
         div_classes = ['ordered-list', node.style, node.role].compact
-        ol_classes = [node.style, ((node.option? 'brief') ? 'brief' : nil)].compact
+        ol_classes = [node.style, (node.option?('brief') ? 'brief' : nil)].compact
         ol_class_attr = ol_classes.empty? ? '' : %( class="#{ol_classes * ' '}")
-        ol_start_attr = (node.attr? 'start') ? %( start="#{node.attr 'start'}") : ''
+        ol_start_attr = node.attr?('start') ? %( start="#{node.attr 'start'}") : ''
         id_attribute = node.id ? %( id="#{node.id}") : ''
         lines = [%(<div#{id_attribute} class="#{div_classes * ' '}">)]
         lines << %(<h3 class="list-heading">#{node.title}</h3>) if node.title?
-        lines << %(<ol#{ol_class_attr}#{ol_start_attr}#{(node.option? 'reversed') ? ' reversed="reversed"' : ''}>)
+        lines << %(<ol#{ol_class_attr}#{ol_start_attr}#{node.option?('reversed') ? ' reversed="reversed"' : ''}>)
         node.items.each do |item|
           lines << %(<li>
 <span class="principal">#{item.text}</span>)
           if item.blocks?
             lines << item.content
-            complex = true unless item.blocks.size == 1 && ::Asciidoctor::List === item.blocks[0]
+            complex = true unless item.blocks.size == 1 && item.blocks[0].is_a?(::Asciidoctor::List)
           end
           lines << '</li>'
         end
@@ -924,10 +991,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         lines * LF
       end
 
-      def convert_ulist node
+      def convert_ulist(node)
         complex = false
         div_classes = ['itemized-list', node.style, node.role].compact
-        ul_classes = [node.style, ((node.option? 'brief') ? 'brief' : nil)].compact
+        ul_classes = [node.style, (node.option?('brief') ? 'brief' : nil)].compact
         ul_class_attr = ul_classes.empty? ? '' : %( class="#{ul_classes * ' '}")
         id_attribute = node.id ? %( id="#{node.id}") : ''
         lines = [%(<div#{id_attribute} class="#{div_classes * ' '}">)]
@@ -938,7 +1005,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 <span class="principal">#{item.text}</span>)
           if item.blocks?
             lines << item.content
-            complex = true unless item.blocks.size == 1 && ::Asciidoctor::List === item.blocks[0]
+            complex = true unless item.blocks.size == 1 && item.blocks[0].is_a?(::Asciidoctor::List)
           end
           lines << '</li>'
         end
@@ -951,22 +1018,23 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         lines * LF
       end
 
-      def doc_option document, key
+      def doc_option(document, key)
         loop do
           value = document.options[key]
           return value unless value.nil?
+
           document = document.parent_document
           break if document.nil?
         end
         nil
       end
 
-      def root_document document
+      def root_document(document)
         document = document.parent_document until document.parent_document.nil?
         document
       end
 
-      def register_media_file node, target, media_type
+      def register_media_file(node, target, media_type)
         if target.end_with?('.svg') || target.start_with?('data:image/svg+xml')
           chapter = get_enclosing_chapter node
           chapter.set_attr 'epub-properties', [] unless chapter.attr? 'epub-properties'
@@ -991,9 +1059,14 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         @media_files[target] ||= { path: fs_path, media_type: media_type }
       end
 
-      def resolve_image_attrs node
+      # @param node [Asciidoctor::Block]
+      # @return [Array<String>]
+      def resolve_image_attrs(node)
         img_attrs = []
-        img_attrs << %(alt="#{node.attr 'alt'}") if node.attr? 'alt'
+
+        unless (alt = encode_attribute_value(node.alt)).empty?
+          img_attrs << %(alt="#{alt}")
+        end
 
         # Unlike browsers, Calibre/Kindle *do* scale image if only height is specified
         # So, in order to match browser behavior, we just always omit height
@@ -1004,33 +1077,33 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           # HTML5 spec (and EPUBCheck) only allows pixels in width, but browsers also accept percents
           # and there are multiple AsciiDoc files in the wild that have width=percents%
           # So, for compatibility reasons, output percentage width as a CSS style
-          if width[/^\d+%$/]
-            img_attrs << %(style="width: #{width}")
-          else
-            img_attrs << %(width="#{width}")
-          end
+          img_attrs << if width[/^\d+%$/]
+                         %(style="width: #{width}")
+                       else
+                         %(width="#{width}")
+                       end
         end
 
         img_attrs
       end
 
-      def convert_audio node
+      def convert_audio(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         target = node.media_uri node.attr 'target'
         register_media_file node, target, 'audio'
         title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
 
-        autoplay_attr = (node.option? 'autoplay') ? ' autoplay="autoplay"' : ''
-        controls_attr = (node.option? 'nocontrols') ? '' : ' controls="controls"'
-        loop_attr = (node.option? 'loop') ? ' loop="loop"' : ''
+        autoplay_attr = node.option?('autoplay') ? ' autoplay="autoplay"' : ''
+        controls_attr = node.option?('nocontrols') ? '' : ' controls="controls"'
+        loop_attr = node.option?('loop') ? ' loop="loop"' : ''
 
         start_t = node.attr 'start'
         end_t = node.attr 'end'
-        if start_t || end_t
-          time_anchor = %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
-        else
-          time_anchor = ''
-        end
+        time_anchor = if start_t || end_t
+                        %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
+                      else
+                        ''
+                      end
 
         %(<figure#{id_attr} class="audioblock#{prepend_space node.role}">#{title_element}
 <div class="content">
@@ -1042,25 +1115,25 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       # TODO: Support multiple video files in different formats for a single video
-      def convert_video node
+      def convert_video(node)
         id_attr = node.id ? %( id="#{node.id}") : ''
         target = node.media_uri node.attr 'target'
         register_media_file node, target, 'video'
         title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
 
-        width_attr = (node.attr? 'width') ? %( width="#{node.attr 'width'}") : ''
-        height_attr = (node.attr? 'height') ? %( height="#{node.attr 'height'}") : ''
-        autoplay_attr = (node.option? 'autoplay') ? ' autoplay="autoplay"' : ''
-        controls_attr = (node.option? 'nocontrols') ? '' : ' controls="controls"'
-        loop_attr = (node.option? 'loop') ? ' loop="loop"' : ''
+        width_attr = node.attr?('width') ? %( width="#{node.attr 'width'}") : ''
+        height_attr = node.attr?('height') ? %( height="#{node.attr 'height'}") : ''
+        autoplay_attr = node.option?('autoplay') ? ' autoplay="autoplay"' : ''
+        controls_attr = node.option?('nocontrols') ? '' : ' controls="controls"'
+        loop_attr = node.option?('loop') ? ' loop="loop"' : ''
 
         start_t = node.attr 'start'
         end_t = node.attr 'end'
-        if start_t || end_t
-          time_anchor = %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
-        else
-          time_anchor = ''
-        end
+        time_anchor = if start_t || end_t
+                        %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''})
+                      else
+                        ''
+                      end
 
         if (poster = node.attr 'poster').nil_or_empty?
           poster_attr = ''
@@ -1070,7 +1143,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           poster_attr = %( poster="#{poster}")
         end
 
-        %(<figure#{id_attr} class="video#{prepend_space node.role}">#{title_element}
+        %(<figure#{id_attr} class="video#{prepend_space node.role}#{prepend_space node.attr('float')}">#{title_element}
 <div class="content">
 <video src="#{target}#{time_anchor}"#{width_attr}#{height_attr}#{autoplay_attr}#{poster_attr}#{controls_attr}#{loop_attr}>
 <div>Your Reading System does not support (this) video.</div>
@@ -1079,35 +1152,41 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 </figure>)
       end
 
-      def convert_image node
+      # @param node [Asciidoctor::Block]
+      # @return [String]
+      def convert_image(node)
         target = node.image_uri node.attr 'target'
         register_media_file node, target, 'image'
         id_attr = node.id ? %( id="#{node.id}") : ''
         title_element = node.title? ? %(\n<figcaption>#{node.captioned_title}</figcaption>) : ''
         img_attrs = resolve_image_attrs node
-        %(<figure#{id_attr} class="image#{prepend_space node.role}">
+        %(<figure#{id_attr} class="image#{prepend_space node.role}#{prepend_space node.attr('float')}">
 <div class="content">
 <img src="#{target}"#{prepend_space img_attrs * ' '} />
 </div>#{title_element}
 </figure>)
       end
 
-      def get_enclosing_chapter node
+      def get_enclosing_chapter(node)
         loop do
           return nil if node.nil?
-          return node unless get_chapter_name(node).nil?
+          return node unless get_chapter_filename(node).nil?
+
           node = node.parent
         end
       end
 
-      def convert_inline_anchor node
+      def convert_inline_anchor(node)
         case node.type
         when :xref
-          doc, refid, target, text = node.document, node.attr('refid'), node.target, node.text
+          doc = node.document
+          refid = node.attr('refid')
+          target = node.target
+          text = node.text
           id_attr = ''
 
           if (path = node.attributes['path'])
-            # NOTE non-nil path indicates this is an inter-document xref that's not included in current document
+            # NOTE: non-nil path indicates this is an inter-document xref that's not included in current document
             text = node.text || path
           elsif refid == '#'
             logger.warn %(#{::File.basename doc.attr('docfile')}: <<chapter#>> xref syntax isn't supported anymore. Use either <<chapter>> or <<chapter#anchor>>)
@@ -1116,7 +1195,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
             our_chapter = get_enclosing_chapter node
             ref_chapter = get_enclosing_chapter ref
             if ref_chapter
-              ref_docname = get_chapter_name ref_chapter
+              ref_docname = get_chapter_filename ref_chapter
               if ref_chapter == our_chapter
                 # ref within same chapter file
                 id_attr = %( id="xref-#{refid}")
@@ -1140,12 +1219,12 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
           %(<a#{id_attr} href="#{target}" class="xref">#{text || "[#{refid}]"}</a>)
         when :ref
-          # NOTE id is used instead of target starting in Asciidoctor 2.0.0
+          # NOTE: id is used instead of target starting in Asciidoctor 2.0.0
           %(<a id="#{node.target || node.id}"></a>)
         when :link
           %(<a href="#{node.target}" class="link">#{node.text}</a>)
         when :bibref
-          # NOTE reftext is no longer enclosed in [] starting in Asciidoctor 2.0.0
+          # NOTE: reftext is no longer enclosed in [] starting in Asciidoctor 2.0.0
           # NOTE id is used instead of target starting in Asciidoctor 2.0.0
           if (reftext = node.reftext)
             reftext = %([#{reftext}]) unless reftext.start_with? '['
@@ -1159,30 +1238,37 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def convert_inline_break node
+      def convert_inline_break(node)
         %(#{node.text}<br/>)
       end
 
-      def convert_inline_button node
-        %(<b class="button">[<span class="label">#{node.text}</span>]</b>)
+      # @param node [Asciidoctor::Inline]
+      # @return [String]
+      def convert_inline_button(node)
+        %(<b class="button">#{node.text}</b>)
       end
 
-      def convert_inline_callout node
-        num = CalloutStartNum
+      def convert_inline_callout(node)
+        num = CALLOUT_START_NUM
         int_num = node.text.to_i
         (int_num - 1).times { num = num.next }
         %(<i class="conum" data-value="#{int_num}">#{num}</i>)
       end
 
-      def convert_inline_footnote node
+      # @param node [Asciidoctor::Inline]
+      # @return [String]
+      def convert_inline_footnote(node)
         if (index = node.attr 'index')
-          %(<sup class="noteref">[<a id="noteref-#{index}" href="#note-#{index}" epub:type="noteref">#{index}</a>]</sup>)
+          attrs = []
+          attrs << %(id="#{node.id}") if node.id
+
+          %(<sup class="noteref">[<a#{prepend_space attrs * ' '}href="#note-#{index}" epub:type="noteref">#{index}</a>]</sup>)
         elsif node.type == :xref
           %(<mark class="noteref" title="Unresolved note reference">#{node.text}</mark>)
         end
       end
 
-      def convert_inline_image node
+      def convert_inline_image(node)
         if node.type == 'icon'
           icon_names << (icon_name = node.target)
           i_classes = ['icon', %(i-#{icon_name})]
@@ -1190,36 +1276,37 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
           i_classes << %(icon-flip-#{(node.attr 'flip')[0]}) if node.attr? 'flip'
           i_classes << %(icon-rotate-#{node.attr 'rotate'}) if node.attr? 'rotate'
           i_classes << node.role if node.role?
+          i_classes << node.attr('float') if node.attr 'float'
           %(<i class="#{i_classes * ' '}"></i>)
         else
           target = node.image_uri node.target
           register_media_file node, target, 'image'
 
           img_attrs = resolve_image_attrs node
-          img_attrs << %(class="inline#{prepend_space node.role}")
+          img_attrs << %(class="inline#{prepend_space node.role}#{prepend_space node.attr('float')}")
           %(<img src="#{target}"#{prepend_space img_attrs * ' '}/>)
         end
       end
 
-      def convert_inline_indexterm node
+      def convert_inline_indexterm(node)
         node.type == :visible ? node.text : ''
       end
 
-      def convert_inline_kbd node
+      def convert_inline_kbd(node)
         if (keys = node.attr 'keys').size == 1
           %(<kbd>#{keys[0]}</kbd>)
         else
-          key_combo = keys.map {|key| %(<kbd>#{key}</kbd>) }.join '+'
+          key_combo = keys.map { |key| %(<kbd>#{key}</kbd>) }.join '+'
           %(<span class="keyseq">#{key_combo}</span>)
         end
       end
 
-      def convert_inline_menu node
+      def convert_inline_menu(node)
         menu = node.attr 'menu'
-        # NOTE we swap right angle quote with chevron right from FontAwesome using CSS
-        caret = %(#{NoBreakSpace}<span class="caret">#{RightAngleQuote}</span> )
+        # NOTE: we swap right angle quote with chevron right from FontAwesome using CSS
+        caret = %(#{NO_BREAK_SPACE}<span class="caret">#{RIGHT_ANGLE_QUOTE}</span> )
         if !(submenus = node.attr 'submenus').empty?
-          submenu_path = submenus.map {|submenu| %(<span class="submenu">#{submenu}</span>#{caret}) }.join.chop
+          submenu_path = submenus.map { |submenu| %(<span class="submenu">#{submenu}</span>#{caret}) }.join.chop
           %(<span class="menuseq"><span class="menu">#{menu}</span>#{caret}#{submenu_path} <span class="menuitem">#{node.attr 'menuitem'}</span></span>)
         elsif (menuitem = node.attr 'menuitem')
           %(<span class="menuseq"><span class="menu">#{menu}</span>#{caret}<span class="menuitem">#{menuitem}</span></span>)
@@ -1228,16 +1315,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def convert_inline_quoted node
+      def convert_inline_quoted(node)
         open, close, tag = QUOTE_TAGS[node.type]
 
-        if node.type == :asciimath && asciimath_available?
-          content = AsciiMath.parse(node.text).to_mathml 'mml:'
-        else
-          content = node.text
-        end
+        content = if node.type == :asciimath && asciimath_available?
+                    AsciiMath.parse(node.text).to_mathml 'mml:'
+                  else
+                    node.text
+                  end
 
-        node.add_role 'literal' if [:monospaced, :asciimath, :latexmath].include? node.type
+        node.add_role 'literal' if %i[monospaced asciimath latexmath].include? node.type
 
         if node.id
           class_attr = class_string node
@@ -1258,16 +1345,24 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       end
 
-      def output_content node
+      def output_content(node)
         node.content_model == :simple ? %(<p>#{node.content}</p>) : node.content
       end
 
+      def encode_attribute_value(val)
+        val.gsub '"', '&quot;'
+      end
+
       # FIXME: merge into with xml_sanitize helper
-      def xml_sanitize value, target = :attribute
-        sanitized = (value.include? '<') ? value.gsub(XmlElementRx, '').strip.tr_s(' ', ' ') : value
+      def xml_sanitize(value, target = :attribute)
+        sanitized = value.include?('<') ? value.gsub(XML_ELEMENT_RX, '').strip.tr_s(' ', ' ') : value
         if target == :plain && (sanitized.include? ';')
-          sanitized = sanitized.gsub(CharEntityRx) { [$1.to_i].pack 'U*' } if sanitized.include? '&#'
-          sanitized = sanitized.gsub FromHtmlSpecialCharsRx, FromHtmlSpecialCharsMap
+          if sanitized.include? '&#'
+            sanitized = sanitized.gsub(CHAR_ENTITY_RX) do
+              [::Regexp.last_match(1).to_i].pack 'U*'
+            end
+          end
+          sanitized = sanitized.gsub FROM_HTML_SPECIAL_CHARS_RX, FROM_HTML_SPECIAL_CHARS_MAP
         elsif target == :attribute
           sanitized = sanitized.gsub '"', '&quot;' if sanitized.include? '"'
         end
@@ -1275,8 +1370,9 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       # TODO: make check for last content paragraph a feature of Asciidoctor
-      def mark_last_paragraph root
+      def mark_last_paragraph(root)
         return unless (last_block = root.blocks[-1])
+
         last_block = last_block.blocks[-1] while last_block.context == :section && last_block.blocks?
         if last_block.context == :paragraph
           last_block.attributes['role'] = last_block.role? ? %(#{last_block.role} last) : 'last'
@@ -1285,11 +1381,11 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
 
       # Prepend a space to the value if it's non-nil, otherwise return empty string.
-      def prepend_space value
+      def prepend_space(value)
         value ? %( #{value}) : ''
       end
 
-      def add_theme_assets doc
+      def add_theme_assets(doc)
         format = @format
         workdir = if doc.attr? 'epub3-stylesdir'
                     stylesdir = doc.attr 'epub3-stylesdir'
@@ -1306,42 +1402,46 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
                   end
 
         # TODO: improve design/UX of custom theme functionality, including custom fonts
-
-        if format == :kf8
-          # NOTE add layer of indirection so Kindle Direct Publishing (KDP) doesn't strip font-related CSS rules
-          @book.add_item 'styles/epub3.css', content: '@import url("epub3-proxied.css");'.to_ios
-          @book.add_item 'styles/epub3-css3-only.css', content: '@import url("epub3-css3-only-proxied.css");'.to_ios
-          @book.add_item 'styles/epub3-proxied.css', content: (postprocess_css_file ::File.join(workdir, 'epub3.css'), format)
-          @book.add_item 'styles/epub3-css3-only-proxied.css', content: (postprocess_css_file ::File.join(workdir, 'epub3-css3-only.css'), format)
-        else
-          @book.add_item 'styles/epub3.css', content: (postprocess_css_file ::File.join(workdir, 'epub3.css'), format)
-          @book.add_item 'styles/epub3-css3-only.css', content: (postprocess_css_file ::File.join(workdir, 'epub3-css3-only.css'), format)
+        %w[epub3 epub3-css3-only].each do |f|
+          css = load_css_file File.join(workdir, %(#{f}.scss))
+          if format == :kf8
+            # NOTE: add layer of indirection so Kindle Direct Publishing (KDP) doesn't strip font-related CSS rules
+            @book.add_item %(styles/#{f}.css), content: %(@import url("#{f}-proxied.css");).to_ios
+            @book.add_item %(styles/#{f}-proxied.css), content: css.to_ios
+          else
+            @book.add_item %(styles/#{f}.css), content: css.to_ios
+          end
         end
 
         syntax_hl = doc.syntax_highlighter
         if syntax_hl&.write_stylesheet? doc
           Dir.mktmpdir do |dir|
             syntax_hl.write_stylesheet doc, dir
-            Pathname.glob(dir + '/**/*').map do |filename|
+            Pathname.glob("#{dir}/**/*").map do |filename|
               # Workaround for https://github.com/skoji/gepub/pull/117
+              next unless filename.file?
+
               filename.open do |f|
                 @book.add_item filename.basename.to_s, content: f
-              end if filename.file?
+              end
             end
           end
         end
 
-        font_files, font_css = select_fonts ::File.join(DATA_DIR, 'styles/epub3-fonts.css'), (doc.attr 'scripts', 'latin')
-        @book.add_item 'styles/epub3-fonts.css', content: font_css
+        font_files, font_css = select_fonts load_css_file(File.join(DATA_DIR, 'styles/epub3-fonts.scss')),
+                                            (doc.attr 'scripts', 'latin')
+        @book.add_item 'styles/epub3-fonts.css', content: font_css.to_ios
         unless font_files.empty?
-          # NOTE metadata property in oepbs package manifest doesn't work; must use proprietary iBooks file instead
-          #(@book.metadata.add_metadata 'meta', 'true')['property'] = 'ibooks:specified-fonts' unless format == :kf8
-          @book.add_optional_file 'META-INF/com.apple.ibooks.display-options.xml', '<?xml version="1.0" encoding="UTF-8"?>
+          # NOTE: metadata property in oepbs package manifest doesn't work; must use proprietary iBooks file instead
+          # (@book.metadata.add_metadata 'meta', 'true')['property'] = 'ibooks:specified-fonts' unless format == :kf8
+          unless format == :kf8
+            @book.add_optional_file 'META-INF/com.apple.ibooks.display-options.xml', '<?xml version="1.0" encoding="UTF-8"?>
 <display_options>
 <platform name="*">
 <option name="specified-fonts">true</option>
 </platform>
-</display_options>'.to_ios unless format == :kf8
+</display_options>'.to_ios
+          end
 
           font_files.each do |font_file|
             @book.add_item font_file, content: File.join(DATA_DIR, font_file)
@@ -1350,7 +1450,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         nil
       end
 
-      def add_cover_page doc, name
+      # @param doc [Asciidoctor::Document]
+      # @param name [String]
+      # @return [GEPUB::Item, nil]
+      def add_cover_page(doc, name)
         image_attr_name = %(#{name}-image)
 
         return nil if (image_path = doc.attr image_attr_name).nil?
@@ -1359,10 +1462,14 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         imagesdir = (imagesdir == '.' ? '' : %(#{imagesdir}/))
 
         image_attrs = {}
-        if (image_path.include? ':') && image_path =~ ImageMacroRx
+        if (image_path.include? ':') && image_path =~ IMAGE_MACRO_RX
           logger.warn %(deprecated block macro syntax detected in :#{image_attr_name}: attribute) if image_path.start_with? 'image::'
-          image_path = %(#{imagesdir}#{$1})
-          (::Asciidoctor::AttributeList.new $2).parse_into image_attrs, %w(alt width height) unless $2.empty?
+          image_path = %(#{imagesdir}#{::Regexp.last_match(1)})
+          unless ::Regexp.last_match(2).empty?
+            (::Asciidoctor::AttributeList.new ::Regexp.last_match(2)).parse_into image_attrs,
+                                                                                 %w[alt width
+                                                                                    height]
+          end
         end
 
         image_href = %(#{imagesdir}jacket/#{name}#{::File.extname image_path})
@@ -1370,9 +1477,11 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         workdir = doc.attr 'docdir'
         workdir = '.' if workdir.nil_or_empty?
 
+        image_path = File.join workdir, image_path unless File.absolute_path? image_path
+
         begin
-          @book.add_item(image_href, content: File.join(workdir, image_path)).cover_image
-        rescue => e
+          @book.add_item(image_href, content: image_path).cover_image
+        rescue StandardError => e
           logger.error %(#{::File.basename doc.attr('docfile')}: error adding cover image. Make sure that :#{image_attr_name}: attribute points to a valid image file. #{e})
           return nil
         end
@@ -1380,14 +1489,15 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         return nil if @format == :kf8
 
         unless !image_attrs.empty? && (width = image_attrs['width']) && (height = image_attrs['height'])
-          width, height = 1050, 1600
+          width = 1050
+          height = 1600
         end
 
-        # NOTE SVG wrapper maintains aspect ratio and confines image to view box
-        content = %(<!DOCTYPE html>
+        # NOTE: SVG wrapper maintains aspect ratio and confines image to view box
+        content = %(<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="en" lang="en">
 <head>
-<meta charset="UTF-8"/>
 <title>#{sanitize_doctitle_xml doc, :cdata}</title>
 <style type="text/css">
 @page {
@@ -1417,7 +1527,7 @@ body > svg {
         @book.add_ordered_item %(#{name}.xhtml), content: content, id: name
       end
 
-      def get_frontmatter_files doc, workdir
+      def get_frontmatter_files(doc, workdir)
         if doc.attr? 'epub3-frontmatterdir'
           fmdir = doc.attr 'epub3-frontmatterdir'
           fmglob = 'front-matter.*\.html'
@@ -1426,7 +1536,7 @@ body > svg {
             logger.warn %(#{File.basename doc.attr('docfile')}: directory specified by 'epub3-frontmattderdir' doesn't exist! Ignoring ...)
             return []
           end
-          fms = Dir.entries(fm_path).delete_if {|x| !x.match fmglob }.sort.map {|y| File.join fm_path, y }
+          fms = Dir.entries(fm_path).delete_if { |x| !x.match fmglob }.sort.map { |y| File.join fm_path, y }
           if fms && !fms.empty?
             fms
           else
@@ -1440,7 +1550,7 @@ body > svg {
         end
       end
 
-      def add_front_matter_page doc
+      def add_front_matter_page(doc)
         workdir = doc.attr 'docdir'
         workdir = '.' if workdir.nil_or_empty?
 
@@ -1450,30 +1560,32 @@ body > svg {
 
           front_matter_file = File.basename front_matter, '.html'
           item = @book.add_ordered_item "#{front_matter_file}.xhtml", content: (postprocess_xhtml front_matter_content)
-          item.add_property 'svg' if SvgImgSniffRx =~ front_matter_content
+          item.add_property 'svg' if SVG_IMG_SNIFF_RX =~ front_matter_content
           # Store link to first frontmatter page
           result = item if result.nil?
 
-          front_matter_content.scan ImgSrcScanRx do
-            @book.add_item $1, content: File.join(File.dirname(front_matter), $1)
+          front_matter_content.scan IMAGE_SRC_SCAN_RX do
+            @book.add_item ::Regexp.last_match(1),
+                           content: File.join(File.dirname(front_matter), ::Regexp.last_match(1))
           end
         end
 
         result
       end
 
-      def add_profile_images doc, usernames
+      def add_profile_images(doc, usernames)
         imagesdir = (doc.attr 'imagesdir', '.').chomp '/'
         imagesdir = (imagesdir == '.' ? nil : %(#{imagesdir}/))
 
         @book.add_item %(#{imagesdir}avatars/default.jpg), content: ::File.join(DATA_DIR, 'images/default-avatar.jpg')
-        @book.add_item %(#{imagesdir}headshots/default.jpg), content: ::File.join(DATA_DIR, 'images/default-headshot.jpg')
+        @book.add_item %(#{imagesdir}headshots/default.jpg),
+                       content: ::File.join(DATA_DIR, 'images/default-headshot.jpg')
 
-        workdir = (workdir = doc.attr 'docdir').nil_or_empty? ? '.' : workdir
+        workdir = '.' if (workdir = doc.attr 'docdir').nil_or_empty?
 
         usernames.each do |username|
           avatar = %(#{imagesdir}avatars/#{username}.jpg)
-          if ::File.readable? (resolved_avatar = (::File.join workdir, avatar))
+          if ::File.readable?(resolved_avatar = (::File.join workdir, avatar))
             @book.add_item avatar, content: resolved_avatar
           else
             logger.error %(avatar for #{username} not found or readable: #{avatar}; falling back to default avatar)
@@ -1481,7 +1593,7 @@ body > svg {
           end
 
           headshot = %(#{imagesdir}headshots/#{username}.jpg)
-          if ::File.readable? (resolved_headshot = (::File.join workdir, headshot))
+          if ::File.readable?(resolved_headshot = (::File.join workdir, headshot))
             @book.add_item headshot, content: resolved_headshot
           elsif doc.attr? 'builder', 'editions'
             logger.error %(headshot for #{username} not found or readable: #{headshot}; falling back to default headshot)
@@ -1491,11 +1603,12 @@ body > svg {
         nil
       end
 
-      def nav_doc doc, items, landmarks, depth
-        lines = [%(<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="#{lang = doc.attr 'lang', 'en'}" lang="#{lang}">
+      def nav_doc(doc, items, landmarks, depth)
+        lines = [%(<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="#{lang = doc.attr 'lang',
+                                                                                                                 'en'}" lang="#{lang}">
 <head>
-<meta charset="UTF-8"/>
 <title>#{sanitize_doctitle_xml doc, :cdata}</title>
 <link rel="stylesheet" type="text/css" href="styles/epub3.css"/>
 <link rel="stylesheet" type="text/css" href="styles/epub3-css3-only.css" media="(min-device-width: 0px)"/>
@@ -1527,133 +1640,121 @@ body > svg {
         lines * LF
       end
 
-      def nav_level items, depth, state = {}
+      def nav_level(items, depth, state = {})
         lines = []
         lines << '<ol>'
         items.each do |item|
-          #index = (state[:index] = (state.fetch :index, 0) + 1)
-          if (chapter_name = get_chapter_name item).nil?
+          # index = (state[:index] = (state.fetch :index, 0) + 1)
+          if (chapter_filename = get_chapter_filename item).nil?
             item_label = sanitize_xml get_numbered_title(item), :pcdata
             item_href = %(#{state[:content_doc_href]}##{item.id})
           else
-            # NOTE we sanitize the chapter titles because we use formatting to control layout
-            if item.context == :document
-              item_label = sanitize_doctitle_xml item, :cdata
-            else
-              item_label = sanitize_xml get_numbered_title(item), :cdata
-            end
-            item_href = (state[:content_doc_href] = %(#{chapter_name}.xhtml))
+            # NOTE: we sanitize the chapter titles because we use formatting to control layout
+            item_label = if item.context == :document
+                           sanitize_doctitle_xml item, :cdata
+                         else
+                           sanitize_xml get_numbered_title(item), :cdata
+                         end
+            item_href = (state[:content_doc_href] = %(#{chapter_filename}.xhtml))
           end
           lines << %(<li><a href="#{item_href}">#{item_label}</a>)
-          if depth == 0 || (child_sections = item.sections).empty?
+          if depth.zero? || (child_sections = item.sections).empty?
             lines[-1] = %(#{lines[-1]}</li>)
           else
             lines << (nav_level child_sections, depth - 1, state)
             lines << '</li>'
           end
-          state.delete :content_doc_href unless chapter_name.nil?
+          state.delete :content_doc_href unless chapter_filename.nil?
         end
         lines << '</ol>'
         lines * LF
       end
 
-      def ncx_doc doc, items, depth
+      def ncx_doc(doc, items, depth)
         # TODO: populate docAuthor element based on unique authors in work
         lines = [%(<?xml version="1.0" encoding="utf-8"?>
 <ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1" xml:lang="#{doc.attr 'lang', 'en'}">
 <head>
 <meta name="dtb:uid" content="#{@book.identifier}"/>
-%{depth}
+%<depth>s
 <meta name="dtb:totalPageCount" content="0"/>
 <meta name="dtb:maxPageNumber" content="0"/>
 </head>
 <docTitle><text>#{sanitize_doctitle_xml doc, :cdata}</text></docTitle>
 <navMap>)]
         lines << (ncx_level items, depth, state = {})
-        lines[0] = lines[0].sub '%{depth}', %(<meta name="dtb:depth" content="#{state[:max_depth]}"/>)
+        lines[0] = lines[0].sub '%<depth>s', %(<meta name="dtb:depth" content="#{state[:max_depth]}"/>)
         lines << %(</navMap>
 </ncx>)
         lines * LF
       end
 
-      def ncx_level items, depth, state = {}
+      def ncx_level(items, depth, state = {})
         lines = []
         state[:max_depth] = (state.fetch :max_depth, 0) + 1
         items.each do |item|
           index = (state[:index] = (state.fetch :index, 0) + 1)
           item_id = %(nav_#{index})
-          if (chapter_name = get_chapter_name item).nil?
+          if (chapter_filename = get_chapter_filename item).nil?
             item_label = sanitize_xml get_numbered_title(item), :cdata
             item_href = %(#{state[:content_doc_href]}##{item.id})
           else
-            if item.context == :document
-              item_label = sanitize_doctitle_xml item, :cdata
-            else
-              item_label = sanitize_xml get_numbered_title(item), :cdata
-            end
-            item_href = (state[:content_doc_href] = %(#{chapter_name}.xhtml))
+            item_label = if item.context == :document
+                           sanitize_doctitle_xml item, :cdata
+                         else
+                           sanitize_xml get_numbered_title(item), :cdata
+                         end
+            item_href = (state[:content_doc_href] = %(#{chapter_filename}.xhtml))
           end
           lines << %(<navPoint id="#{item_id}" playOrder="#{index}">)
           lines << %(<navLabel><text>#{item_label}</text></navLabel>)
           lines << %(<content src="#{item_href}"/>)
-          unless depth == 0 || (child_sections = item.sections).empty?
+          unless depth.zero? || (child_sections = item.sections).empty?
             lines << (ncx_level child_sections, depth - 1, state)
           end
           lines << %(</navPoint>)
-          state.delete :content_doc_href unless chapter_name.nil?
+          state.delete :content_doc_href unless chapter_filename.nil?
         end
         lines * LF
       end
 
       # Swap fonts in CSS based on the value of the document attribute 'scripts',
       # then return the list of fonts as well as the font CSS.
-      def select_fonts filename, scripts = 'latin'
-        font_css = ::File.read filename
+      def select_fonts(font_css, scripts = 'latin')
         font_css = font_css.gsub(/(?<=-)latin(?=\.ttf\))/, scripts) unless scripts == 'latin'
 
         # match CSS font urls in the forms of:
         # src: url(../fonts/notoserif-regular-latin.ttf);
         # src: url(../fonts/notoserif-regular-latin.ttf) format("truetype");
-        font_list = font_css.scan(/url\(\.\.\/([^)]+\.ttf)\)/).flatten
-
-        [font_list, font_css.to_ios]
-      end
+        font_list = font_css.scan(%r{url\(\.\./([^)]+?\.ttf)\)}).flatten
 
-      def postprocess_css_file filename, format
-        return filename unless format == :kf8
-        postprocess_css ::File.read(filename), format
+        [font_list, font_css]
       end
 
-      def postprocess_css content, format
-        return content.to_ios unless format == :kf8
-        # TODO: convert regular expressions to constants
-        content
-          .gsub(/^  -webkit-column-break-.*\n/, '')
-          .gsub(/^  max-width: .*\n/, '')
-          .to_ios
+      def load_css_file(filename)
+        template = File.read filename
+        load_paths = [File.dirname(filename)]
+        sass_engine = Sass::Engine.new template, syntax: :scss, cache: false, load_paths: load_paths, style: :compressed
+        sass_engine.render
       end
 
-      # NOTE Kindle requires that
-      #      <meta charset="utf-8"/>
-      #      be converted to
-      #      <meta http-equiv="Content-Type" content="application/xml+xhtml; charset=UTF-8"/>
-      def postprocess_xhtml content
+      def postprocess_xhtml(content)
         return content.to_ios unless @format == :kf8
+
         # TODO: convert regular expressions to constants
         content
-          .gsub(/<meta charset="(.+?)"\/>/, '<meta http-equiv="Content-Type" content="application/xml+xhtml; charset=\1"/>')
           .gsub(/<img([^>]+) style="width: (\d\d)%;"/, '<img\1 style="width: \2%; height: \2%;"')
-          .gsub(/<script type="text\/javascript">.*?<\/script>\n?/m, '')
+          .gsub(%r{<script type="text/javascript">.*?</script>\n?}m, '')
           .to_ios
       end
 
-      def get_kindlegen_command
+      def build_kindlegen_command
         unless @kindlegen_path.nil?
           logger.debug %(Using ebook-kindlegen-path attribute: #{@kindlegen_path})
           return [@kindlegen_path]
         end
 
-        unless (result = ENV['KINDLEGEN']).nil?
+        unless (result = ENV.fetch('KINDLEGEN', nil)).nil?
           logger.debug %(Using KINDLEGEN env variable: #{result})
           return [result]
         end
@@ -1669,18 +1770,23 @@ body > svg {
         end
       end
 
-      def distill_epub_to_mobi epub_file, target, compress
-        mobi_file = ::File.basename target.sub(EpubExtensionRx, '.mobi')
-        compress_flag = KindlegenCompression[compress ? (compress.empty? ? '1' : compress.to_s) : '0']
+      def distill_epub_to_mobi(epub_file, target, compress)
+        mobi_file = ::File.basename target.sub(EPUB_EXTENSION_RX, '.mobi')
+        compress_flag = KINDLEGEN_COMPRESSION[if compress
+                                                compress.empty? ? '1' : compress.to_s
+                                              else
+                                                '0'
+                                              end]
 
-        argv = get_kindlegen_command + ['-dont_append_source', compress_flag, '-o', mobi_file, epub_file].compact
+        argv = build_kindlegen_command + ['-dont_append_source', compress_flag, '-o', mobi_file, epub_file].compact
         begin
           # This duplicates Kindlegen.run, but we want to override executable
           out, err, res = Open3.capture3(*argv) do |r|
             r.force_encoding 'UTF-8' if ::Gem.win_platform? && r.respond_to?(:force_encoding)
           end
         rescue Errno::ENOENT => e
-          raise 'Unable to run KindleGen. Either install the kindlegen gem or place `kindlegen` executable on PATH or set KINDLEGEN environment variable with path to it', cause: e
+          raise 'Unable to run KindleGen. Either install the kindlegen gem or place `kindlegen` executable on PATH or set KINDLEGEN environment variable with path to it',
+                cause: e
         end
 
         out.each_line do |line|
@@ -1698,13 +1804,13 @@ body > svg {
         end
       end
 
-      def get_epubcheck_command
+      def build_epubcheck_command
         unless @epubcheck_path.nil?
           logger.debug %(Using ebook-epubcheck-path attribute: #{@epubcheck_path})
           return [@epubcheck_path]
         end
 
-        unless (result = ENV['EPUBCHECK']).nil?
+        unless (result = ENV.fetch('EPUBCHECK', nil)).nil?
           logger.debug %(Using EPUBCHECK env variable: #{result})
           return [result]
         end
@@ -1719,12 +1825,13 @@ body > svg {
         end
       end
 
-      def validate_epub epub_file
-        argv = get_epubcheck_command + ['-w', epub_file]
+      def validate_epub(epub_file)
+        argv = build_epubcheck_command + ['-w', epub_file]
         begin
           out, err, res = Open3.capture3(*argv)
         rescue Errno::ENOENT => e
-          raise 'Unable to run EPUBCheck. Either install epubcheck-ruby gem or place `epubcheck` executable on PATH or set EPUBCHECK environment variable with path to it', cause: e
+          raise 'Unable to run EPUBCheck. Either install epubcheck-ruby gem or place `epubcheck` executable on PATH or set EPUBCHECK environment variable with path to it',
+                cause: e
         end
 
         out.each_line do |line|
@@ -1737,14 +1844,15 @@ body > svg {
         logger.error %(EPUB validation failed: #{epub_file}) unless res.success?
       end
 
-      def log_line line
+      def log_line(line)
         line = line.strip
 
-        if line =~ /^fatal/i
+        case line
+        when /^fatal/i
           logger.fatal line
-        elsif line =~ /^error/i
+        when /^error/i
           logger.error line
-        elsif line =~ /^warning/i
+        when /^warning/i
           logger.warn line
         else
           logger.info line
@@ -1753,7 +1861,7 @@ body > svg {
 
       private
 
-      def class_string node
+      def class_string(node)
         role = node.role
 
         return '' unless role_valid_class? role
@@ -1762,66 +1870,28 @@ body > svg {
       end
 
       # Handles asciidoctor 1.5.6 quirk when role can be parent
-      def role_valid_class? role
+      def role_valid_class?(role)
         role.is_a? String
       end
     end
 
-    class DocumentIdGenerator
-      ReservedIds = %w(cover nav ncx)
-      CharRefRx = /&(?:([a-zA-Z][a-zA-Z]+\d{0,2})|#(\d\d\d{0,4})|#x([\da-fA-F][\da-fA-F][\da-fA-F]{0,3}));/
-      if defined? __dir__
-        InvalidIdCharsRx = /[^\p{Word}]+/
-        LeadingDigitRx = /^\p{Nd}/
-      else
-        InvalidIdCharsRx = /[^[:word:]]+/
-        LeadingDigitRx = /^[[:digit:]]/
-      end
-
-      class << self
-        def generate_id doc, pre = nil, sep = nil
-          synthetic = false
-          unless (id = doc.id)
-            # NOTE we assume pre is a valid ID prefix and that pre and sep only contain valid ID chars
-            pre ||= '_'
-            sep = sep ? sep.chr : '_'
-            if doc.header?
-              id = doc.doctitle sanitize: true
-              id = id.gsub CharRefRx do
-                $1 ? ($1 == 'amp' ? 'and' : sep) : ((d = $2 ? $2.to_i : $3.hex) == 8217 ? '' : ([d].pack 'U*'))
-              end if id.include? '&'
-              id = id.downcase.gsub InvalidIdCharsRx, sep
-              if id.empty?
-                id, synthetic = nil, true
-              else
-                unless sep.empty?
-                  if (id = id.tr_s sep, sep).end_with? sep
-                    if id == sep
-                      id, synthetic = nil, true
-                    else
-                      id = (id.start_with? sep) ? id[1..-2] : id.chop
-                    end
-                  elsif id.start_with? sep
-                    id = id[1..-1]
-                  end
-                end
-                unless synthetic
-                  if pre.empty?
-                    id = %(_#{id}) if LeadingDigitRx =~ id
-                  elsif !(id.start_with? pre)
-                    id = %(#{pre}#{id})
-                  end
-                end
-              end
-            elsif (first_section = doc.first_section)
-              id = first_section.id
-            else
-              synthetic = true
-            end
-            id = %(#{pre}document#{sep}#{doc.object_id}) if synthetic
-          end
-          logger.error %(chapter uses a reserved ID: #{id}) if !synthetic && (ReservedIds.include? id)
-          id
+    class NumericIdGenerator
+      def initialize
+        @counter = 1
+      end
+
+      # @param node [Asciidoctor::AbstractNode]
+      # @return [void]
+      def generate_id(node)
+        if node.chapter? || node.is_a?(Asciidoctor::Document)
+          node.id = %(_generated_id_#{@counter})
+          @counter += 1
+        end
+
+        # Recurse
+        node.blocks.each do |subnode|
+          # dlist contains array of *arrays* of blocks, so just skip them
+          generate_id subnode if subnode.is_a?(Asciidoctor::AbstractBlock)
         end
       end
     end
@@ -1834,27 +1904,33 @@ body > svg {
         document.set_attribute 'pygments-style', 'bw' unless document.attr? 'pygments-style'
         document.set_attribute 'rouge-style', 'bw' unless document.attr? 'rouge-style'
 
-        # Old asciidoctor versions do not have public API for writing highlighter CSS file
-        # So just use inline CSS there.
-        unless Document.supports_syntax_highlighter?
-          document.set_attribute 'coderay-css', 'style'
-          document.set_attribute 'pygments-css', 'style'
-          document.set_attribute 'rouge-css', 'style'
-        end
-
         case (ebook_format = document.attributes['ebook-format'])
         when 'epub3', 'kf8'
           # all good
         when 'mobi'
           ebook_format = document.attributes['ebook-format'] = 'kf8'
         else
-          # QUESTION should we display a warning?
+          # QUESTION: should we display a warning?
           ebook_format = document.attributes['ebook-format'] = 'epub3'
         end
         document.attributes[%(ebook-format-#{ebook_format})] = ''
+
+        # Enable generation of section ids because we use them for chapter filenames
+        document.set_attribute 'sectids'
         treeprocessor do
           process do |doc|
-            doc.id = DocumentIdGenerator.generate_id doc, (doc.attr 'idprefix'), (doc.attr 'idseparator')
+            if ebook_format == 'kf8'
+              # Kindlegen doesn't support unicode ids
+              NumericIdGenerator.new.generate_id doc
+            else
+              # :sectids: doesn't generate id for top-level section (why?), do it manually
+              doc.id = Section.generate_id(doc.first_section&.title || doc.attr('docname') || 'document', doc) if doc.id.nil_or_empty?
+
+              if (preamble = doc.blocks[0]) && preamble.context == :preamble && preamble.id.nil_or_empty?
+                # :sectids: doesn't generate id for preamble (because it is not a section), do it manually
+                preamble.id = Section.generate_id(preamble.title || 'preamble', doc)
+              end
+            end
             nil
           end
         end