asciidoctor-epub3 1.5.0.alpha.7 → 1.5.0.alpha.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d837e7c36f6d2e47ee9f436d1a7327e42b304aad
-  data.tar.gz: '02679c6c564034d4fefd752cd26ee1611ac8c3cc'
+SHA256:
+  metadata.gz: 56913840726d5e371d1feb61094894bffeec6b28edd87b2dbfc0ef227732b5af
+  data.tar.gz: 584b561949668e02bb4634f70475e168db89586cb2e63607821c42573395236e
 SHA512:
-  metadata.gz: 2d1284f2bca9f66a2a64d8625d812c83ccd29caac1cabd68c834376429632f0f41e0b443e40ebd03394e3ba846480ee092f8c13130061d50da3270d4d0c9ac29
-  data.tar.gz: ff5db3ebee66a7cafafc0ec294355c422c8cac597ec991d1db49166e064db59e7b81314b58c17adcda0926676358864fa0508b78a429e84f195366131a1bee7c
+  metadata.gz: d52c30ad5805c595e675b6b69f4bf8e5cef89a0f6143d5438d88c144c33579151f8c58c3bfc6a5119214e7f1eb38ea21585b36e663f87dc7c311650dae918007
+  data.tar.gz: 3e82757ae00356c2932f506bbacd57d89032da96187dac11f51e080d0712d942c97e0801e03e9ec123eb29daff5dff4f3dfb3c2b03d0b3312a99541bb6560d07

data/CHANGELOG.adoc

@@ -5,6 +5,22 @@
 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.alpha.8 (2018-02-20) - @mojavelinux
+
+* Include inline images in EPUB3 archive (#5)
+* Allow chapter to begin with level-1 section title by adding support for negative leveloffset (#107)
+* Don't transform the chapter title to uppercase (rely on CSS only) (#97)
+* Set correct mimetype for TTF files (#120)
+* Implement support for the custom xrefstyle for references within a chapter (#132)
+* Show correct path of front cover image and the current document when missing (#124)
+* Retain ID of block image (#141)
+* Retain ID of example block (#143)
+* Retain ID of admonition block (#146)
+* Transfer role specified on block image to output (#145)
+* Handle nil response from pygments.rb (#156)
+* Invert the colors for the chapter title (use black on white) (#96)
+* Darken font on Kindle Paperwhite devices (#67)
+
 == 1.5.0.alpha.7 (2017-04-18) - @mojavelinux
 
 * generate TOC levels in navigation document based on toclevels attribute (#90)

data/Gemfile

@@ -4,7 +4,12 @@ source 'https://rubygems.org'
 gemspec
 
 group :optional do
-  gem 'pygments.rb', '1.1.1'
-  gem 'kindlegen', '3.0.3'
   gem 'epubcheck', '3.0.1'
+  if (ruby_version = Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0.0')
+    gem 'kindlegen', '2.9.4'
+    gem 'pygments.rb', '0.6.3'
+  else
+    gem 'kindlegen', '3.0.3'
+    gem 'pygments.rb', '1.1.2'
+  end
 end

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project
+Copyright (C) 2014-2018 OpenDevise Inc. and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.adoc

@@ -1,6 +1,6 @@
 = {project-name}: A _native_ EPUB3 converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.7, 2017-04-18
+v1.5.0.alpha.8, 2018-02-20
 // Settings:
 :experimental:
 :idprefix:
@@ -36,22 +36,33 @@ endif::[]
 :uri-idpf: http://www.idpf.org/
 :uri-epub: http://www.idpf.org/epub/31/spec/epub-spec.html
 :uri-epubcheck: https://github.com/idpf/epubcheck
+:uri-kindlegen: http://www.amazon.com/gp/feature.html?docId=1000765211
+:uri-kf8: http://www.amazon.com/gp/feature.html?docId=1000729511
+:uri-send-to-kindle: https://www.amazon.com/gp/sendtokindle/
+:uri-metadata-elem: http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-metadata-elem
+:uri-dc: http://dublincore.org/documents/2004/12/20/dces
+:uri-github-guides: https://guides.github.com
+:uri-github-guides-fork: https://github.com/opendevise/github-guides-asciidoc
+:uri-asciidoctor-i18n: http://asciidoctor.org/docs/user-manual/#builtin-attributes-i18n
+:uri-epubreadingsystem: http://www.idpf.org/epub/301/spec/epub-contentdocs.html#app-epubReadingSystem
+:uri-android-sdk: http://developer.android.com/sdk/index.html
 
 ifdef::status[]
 image:https://img.shields.io/gem/v/asciidoctor-epub3.svg[Latest Release,link={uri-gem}]
 image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License,link=#copyright]
 endif::[]
 
-{project-name} is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI ebook formats.
+{project-name} is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI e-book formats.
 
 == Introduction
 
-{project-name} is not merely a converter from AsciiDoc to EPUB3 and KF8/MOBI, but rather a tool to help you create aesthetic, professional, _easy-to-read_ ebooks.
-Let's face it, many of the technical ebooks out there--especially those produced from software documentation--are *_hideous_*.
-The Asciidoctor project wants to disrupt the status quo.
+{project-name} is not merely a converter from AsciiDoc to EPUB3 and KF8/MOBI.
+Rather, it's a tool for creating highly aesthetic, professional, _easy-to-read_ e-books.
+Let's face it, many of the technical e-books out there--especially those produced from software documentation--are *_hideous_*.
+{project-name} is on a mission to disrupt the status quo.
 
 ifdef::env-github[]
-.An excerpt from an ebook produced by {project-name} shown in Day, Night and Sepia mode.
+.An excerpt from an e-book produced by {project-name} shown in Day, Night and Sepia mode.
 image::screenshots/text.png[]
 endif::[]
 
@@ -63,22 +74,22 @@ The {project-name} project aims to produce EPUB3 documents that meet the followi
 Fully Semantic::
   Produce deeply semantic XHTML5 documents, including use of the recommended `epub:type` attribute.
 Exceptional Readability::
-  Readers should be drawn into the text so that they read and absorb it, not scared away from it.
-  Maximize the readability of the text using carefully crafted styles, focusing on:
+  Readers should be drawn into the text so that they read and absorb it.
+  Maximize the readability of the text using carefully crafted styles that are focused on:
   - Custom, readable fonts with strong UTF-8 character support
   - Sufficient line spacing and margins
   - Modular font size scale
   - Subtle, pleasing colors with good contrast
   - A responsive design that scales well from small to large screens
   - Widowed and orphaned content avoided where possible
-Complete & Accurate Metadata::
+Complete and Accurate Metadata::
   Fully populate the EPUB3 package metadata using information in the AsciiDoc source document.
 Consistent Rendering::
-  Render consistently across a broad range of EPUB3 (and select EPUB2+) ereading platforms and respond to any size screen.
-Polish, Polish & More Polish::
+  Render consistently across a broad range of EPUB3 (and select EPUB2+) e-readers and respond to any size screen.
+Polish, Polish, and More Polish::
   Add polish to the final product such as font-based icons and callout numbers.
 
-We believe that the ebooks produced by {project-name} are the _very best_ output you can expect to find in digital publishing today.
+We believe that the e-books produced by {project-name} are the _very best_ output you can expect to find in digital publishing today.
 Of course, there's always room for improvement, so we'll continue to work with you to achieve and maintain this goal.
 
 === Notable Features
@@ -86,14 +97,14 @@ Of course, there's always room for improvement, so we'll continue to work with y
 * Direct AsciiDoc to EPUB3 conversion
 * Direct AsciiDoc to KF8/MOBI conversion
 * Highly-aesthetic and readable styles with optimized text legibility
-* Respects font settings (if supported by the ereader) without altering headings, code or icons
+* Respects font settings (if supported by the e-reader) without altering headings, code or icons
 * EPUB3 metadata, manifest and spine (assembled by Gepub)
 * Document metadata (title, authors, subject, keywords, etc.)
-* Internal cross reference links (not yet between chapters)
+* Internal cross reference links
 * Syntax highlighting with CodeRay or Pygments (must use inline styles)
 * Unicode callout numbers
-* Page breaks avoided in block content (so much as it's supported by the ereader)
-* Orphan section titles avoided (so much as it's supported by the ereader)
+* Page breaks avoided in block content (so much as it's supported by the e-reader)
+* Orphan section titles avoided (so much as it's supported by the e-reader)
 * Table border settings honored
 * Support for SVG images in the content
 
@@ -106,16 +117,19 @@ Although the bulk of AsciiDoc content is converted, there's still work needed to
 NOTE: {project-name} only produces variable layout (i.e., reflowable) EPUB3 documents since this layout is best suited for the types of documents typically written in AsciiDoc.
 We may explore the use of fixed layout documents in the future if the need arises.
 
+ifdef::env-github[]
 === Planned Features and Work In Progress
 
 See <<WORKLOG#,WORKLOG.adoc>>.
+endif::[]
 
 == Converter Workflow
 
-{project-name} takes an aggregate AsciiDoc document and its referenced assets as input and converts them to an EPUB3 publication archive (often described as a “website in a box”).
+{project-name} takes an aggregate AsciiDoc document and any assets it references as input and produces an EPUB3 publication archive (often described as a “website in a box”).
 
-{project-name} can also produce a KF8/MOBI file, the format required for viewing on Amazon Kindle, using the EPUB3 publication as the “digital master”.
-The conversion to KF8/MOBI is performed by generating a slightly modified EPUB3 publication (necessary to adhere to Amazon Kindle requirements) and passing it through the http://www.amazon.com/gp/feature.html?docId=1000765211[KindleGen] application.
+{project-name} can also produce KF8/MOBI files, the format required for viewing on Amazon Kindle.
+The conversion to KF8/MOBI is performed by generating a slightly modified EPUB3 publication, then passing it through the {uri-kindlegen}[KindleGen] application.
+The EPUB3 publication, which can be thought of as the “digital master”, is altered to adhere to certain Amazon Kindle requirements.
 
 == Structuring your Manuscript
 
@@ -148,13 +162,13 @@ The cross reference (i.e., xref) from one chapter to another must be in the form
 If you want to reference a section in a chapter, update the fragment (i.e., the value that follows the hash) to match the target section ID.
 The reftext is optional since the reftext of the target is used by default.
 +
-TIP: To assign reference text (i.e., reftext) to chapter title, use the document attribute named `docreftext`.
+TIP: To assign reference text (i.e., reftext) for a chapter title, set the document attribute `docreftext` in the header for that chapter.
 +
 TIP: Rule 2 states that the chapter ID must match the basename of the chapter file.
 In truth, the chapter ID can be a _derivative of_ the chapter filename.
 In that case, an attribute reference can be used to prepend a prefix to an inter-document cross reference.
 For example, if you want each chapter file to begin with `chapter-`, you'd write the xref as `+xref:{chapter-prefix}chapter-id#chapter-id[]+`.
-You'd then assign an empty value to the `chapter-prefix` attribute when converting to an ebook and `chapter-` for all other formats.
+You'd then assign an empty value to the `chapter-prefix` attribute when converting to an e-book and `chapter-` for all other formats.
 
 The next section goes into more detail about how to set up the spine document and include the chapter files.
 
@@ -185,7 +199,7 @@ The rules for generating a chapter ID from the document title are as follows:
 * prepend an underscore if the ID begins with a number
 
 You can think of the master document as the spine of the book and the include directives the individual items being bound together.
-The target of each include directive in the master document is parsed and rendered as a separate AsciiDoc document, with certain options and attributes passed down from the master to ensure consistent behavior.
+The target of each include directive in the master document is parsed and converted as a separate AsciiDoc document, with certain options and attributes passed down from the master to ensure consistent behavior.
 Each resulting XHTML document is then added to the EPUB3 archive as a chapter document and the master document becomes the navigation file (i.e, the table of contents).
 
 Here's an example showing the structure of a spine document:
@@ -243,7 +257,8 @@ To check if you have Ruby available, use the `ruby` command to query the install
 
 == Getting Started
 
-You can get {project-name} by <<Install the Published Gem,installing the published gem>> or <<Development,running the code from source>>.
+You can get {project-name} by <<Install the Published Gem,installing the published gem>>.
+ifndef::env-site[You can also <<Development,run the code from source>> if you want to use the development version or participate in development.]
 
 === Install the Published Gem
 
@@ -252,6 +267,9 @@ You can install the published gem using the following command:
 
  $ NOKOGIRI_USE_SYSTEM_LIBRARIES=1 gem install asciidoctor-epub3 --pre
 
+This optional environment variable tells the gem installer to link against the C libraries on the system, if available, instead of compiling the libraries from scratch.
+This speeds up the installation of Nokogiri considerably.
+
 If you want to syntax highlight source listings, you'll also want to install CodeRay or Pygments.
 Choose one (or more) of the following:
 
@@ -292,7 +310,7 @@ v1.0, 2014-04-15
 :doctype: book
 :creator: {author}
 :producer: Asciidoctor
-:keywords: Asciidoctor, samples, ebook, EPUB3, KF8, MOBI, Asciidoctor.js
+:keywords: Asciidoctor, samples, e-book, EPUB3, KF8, MOBI, Asciidoctor.js
 :copyright: CC-BY-SA 3.0
 :imagesdir: images
 
@@ -310,8 +328,8 @@ v1.0, 2014-04-15
 The metadata in the generated EPUB3 file is populated from attributes in the AsciiDoc document.
 The names of the attributes and the metadata elements to which they map are documented in this section.
 
-The term [term]_package metadata_ in Table 1 is in reference to the http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-metadata-elem[<metadata> element] in the EPUB3 package document (e.g., [file]_package.opf_).
-The `dc` namespace prefix is in reference to the http://dublincore.org/documents/2004/12/20/dces[Dublin Core Metadata Element Set].
+The term [term]_package metadata_ in Table 1 is in reference to the {uri-metadata-elem}[<metadata> element] in the EPUB3 package document (e.g., [file]_package.opf_).
+The `dc` namespace prefix is in reference to the {uri-dc}[Dublin Core Metadata Element Set].
 
 .AsciiDoc attributes that control the EPUB3 metadata (i.e., package.opf)
 [cols="1m,3"]
@@ -343,7 +361,7 @@ The title is added to the metadata in plain text format.
 The authors in each chapter document are aggregated together with the authors in the master file.
 
 |username
-|Used to resolve the avatar for the author that is displayed in the header of a chapter when the `publication-type` is set to a value other than `book`.
+|Used to resolve an avatar for the author that is displayed in the header of a chapter when the `publication-type` is set to a value other than `book`.
 The avatar image should be located at the path _\{imagesdir}/avatars/\{username}.jpg_, where `\{username}` is the value of this attribute.
 
 |producer
@@ -351,7 +369,7 @@ The avatar image should be located at the path _\{imagesdir}/avatars/\{username}
 
 |creator
 |Populates the creator (`<dc:creator>`) in the package metadata.
-*If the creator is not specified, Asciidoctor is added as the creator with the role "mfr" (an abbreviation for manufacturer).*
+*If the creator is not specified, Asciidoctor is set as the creator with the role "mfr" (an abbreviation for manufacturer).*
 
 |description
 |Populates the description (`<dc:description>`) in the package metadata.
@@ -362,7 +380,7 @@ The keywords should be represented as comma-separated values (CSV).
 
 |front-cover-image
 |Populates the front cover image and the image on the cover page (EPUB3 only) in the package metadata.
-The image is also added to the ebook archive.
+The image is also added to the e-book archive.
 The value may be specified as a path or inline image macro.
 Using the inline image macro is preferred as it allows the height and width to be specified.
 
@@ -390,7 +408,7 @@ If set to a value other than book, the byline information (author and avatar) is
 Suggested values include: book (default), anthology, magazine, journal, article.
 |===
 
-When using the EPUB3 converter, the `ebook-format` attribute resolves to the name of the ebook format being generated (epub3 or kf8) and the corresponding attribute `ebook-format-<name>` is defined, where `<name>` is `epub3` or `kf8`.
+When using the EPUB3 converter, the `ebook-format` attribute resolves to the name of the e-book format being generated (epub3 or kf8) and the corresponding attribute `ebook-format-<name>` is defined, where `<name>` is `epub3` or `kf8`.
 You can use these attributes in a preprocessor directive if you only want to show certain content to readers using a particular device.
 For instance, if you want to display a message to readers on Kindle, you can use:
 
@@ -415,7 +433,7 @@ We also recommend specifying an output directory using the `-D` option flag.
  $ asciidoctor-epub3 -D output data/samples/sample-book.adoc
 
 When the script completes, you'll see the file [file]_sample-book.epub_ appear in the [path]_output_ directory.
-Open that file with an EPUB reader (aka ereader) to view the result.
+Open that file with an EPUB reader (aka e-reader) to view the result.
 
 Below are several screenshots of this sample book as it appears on an Android phone.
 
@@ -437,7 +455,7 @@ image::screenshots/table.png[]
 NOTE: The `asciidoctor-epub3` command is a temporary solution for invoking the {project-name} converter.
 We plan to remove this script once we have completed proper integration with the `asciidoctor` command.
 
-TIP: As another example, point `asciidoctor-epub3` at the https://github.com/opendevise/github-guides-asciidoc[GitHub Guides] that we've ported to AsciiDoc, then compare the output to the real https://guides.github.com[GitHub Guides].
+TIP: As another example, point `asciidoctor-epub3` at the {uri-github-guides-fork}[GitHub Guides] that we've ported to AsciiDoc, then compare the output to the real {uri-github-guides}[GitHub Guides].
 
 === Validate the EPUB3 Archive
 
@@ -495,12 +513,24 @@ KindleGen does mandatory validation so you don't need to run the `validate` comm
 ****
 Kindle Format 8 (KF8) is Amazon's next generation file format offering a wide range of new features and enhancements--including HTML5 and CSS3 support--that publishers can use to create a broad range of books.
 The format is close enough to EPUB3 that it's safe to think of it simply as an EPUB3 implementation under most circumstances.
-You can read more about the format on the http://www.amazon.com/gp/feature.html?docId=1000729511[Kindle Format 8 page].
+You can read more about the format on the {uri-kf8}[Kindle Format 8 page].
 
 Amazon continues to use the _.mobi_ file extension for KF8 archives, despite the fact that they've switched from the Mobipocket format to the EPUB3-like KF8 format.
 That's why we refer to the format in this project as KF8/MOBI.
 ****
 
+=== Tuning Listing Captions
+
+Unlike the built-in converters, the EPUB3 converter is configured to add a signifier (e.g., `Listing`) at the start the caption for all listing and source blocks that have a title.
+This behavior is triggered because the `listing-caption` attribute is set by default.
+
+If you don't want the signifier to be included at the beginning of the caption on listing and source blocks, simply unset the `listing-caption` when invoking Asciidoctor EPUB3.
+
+ $ asciidoctor-epub3 -a listing-caption! book.adoc
+
+Now the behavior will match that of the built-in converters.
+For more information about this attribute and other related attributes, see {uri-asciidoctor-i18n}[internationalization and numbering].
+
 === Command Arguments
 
 *-h, --help* ::
@@ -586,7 +616,7 @@ The sample book contains placeholder images for an author avatar and a book cove
 
 Ereaders have different image resolution and file size limits regarding a book's cover.
 Kindle covers tend to be 1050x1600 (16:9 resolution), which is the size of the sample cover provided with {project-name}.
-To ensure your cover displays correctly, you'll want to review the documentation or publisher guidelines for the reading platform you're targeting.
+To ensure your cover displays correctly, you'll want to review the documentation or publisher guidelines for the e-reading platform you're targeting.
 
 WARNING: We've found that if the book cover is more than 1600px on any side, Aldiko will not render it and may even crash.
 
@@ -622,7 +652,7 @@ To do so, use an attribute entry to set the value of the `imagesdir` attribute o
 == About the Theme
 
 EPUB3 and KF8/MOBI files are styled using CSS3.
-However, each ereading platform honors a reduced set of CSS3 styles, and the styles they allow and how they implement them are rarely documented.
+However, each e-reading platform honors a reduced set of CSS3 styles, and the styles they allow and how they implement them are rarely documented.
 All we've got to say is _thank goodness for CSS hacks, media queries and years of CSS experience!_
 
 The theme provided with {project-name} has been crafted to display EPUB3 and KF8/MOBI files as consistently as possible across the most common EPUB3 platforms and to degrade gracefully in select EPUB2 platforms.
@@ -647,7 +677,7 @@ Refer to the <<NOTICE#,NOTICE>> file for further information about the fonts.
 
 === Device-specific Styles
 
-For readers that support JavaScript, {project-name} adds a CSS class to the body element of each chapter that corresponds to the name of the reader as reported by the http://www.idpf.org/epub/301/spec/epub-contentdocs.html#app-epubReadingSystem[epubReadingSystem] JavaScript object.
+For readers that support JavaScript, {project-name} adds a CSS class to the body element of each chapter that corresponds to the name of the reader as reported by the {uri-epubreadingsystem}[epubReadingSystem] JavaScript object.
 This enhancement allows you to use styles targeted specifically at that reader.
 
 Below you can find the readers that are known to support this feature and the CSS class name that gets added to the body element.
@@ -673,7 +703,7 @@ Assuming you have an Android device available, transferring the EPUB3 to the dev
 You transfer files from your computer to an Android phone over a USB connection using a command from the Android SDK Tools called `adb`.
 Follow these steps to get it setup:
 
-. Download the Android SDK Tools zip from the table labeled *SDK Tools Only* on the http://developer.android.com/sdk/index.html[Get the Android SDK] page
+. Download the Android SDK Tools zip from the table labeled *SDK Tools Only* on the {uri-android-sdk}[Get the Android SDK] page
 . Extract the archive
 . Locate the path to the `adb` command (Hint: Look in the platform-tools folder)
 . Set the environment variable named ADB to the path of the `adb` command
@@ -697,12 +727,12 @@ File type,Destination on Android device
 ,===
 
 Amazon Kindle should immediately detect the new file and display it in your “On Device” library.
-You'll have to manually import the EPUB3 into your ereader of choice.
+You'll have to manually import the EPUB3 into your e-reader of choice.
 
 == E-book Reader Recommendations and Quirks
 
-EPUB3 ereaders will provide the best reading experience when viewing the book generated by {project-name}.
-Here's a list of some of the ereaders we know to have good EPUB3 support and the systems on which they run:
+EPUB3 e-readers will provide the best reading experience when viewing the book generated by {project-name}.
+Here's a list of some of the e-readers we know to have good EPUB3 support and the systems on which they run:
 
 * http://www.amazon.com/gp/feature.html?docId=1000493771[Amazon Kindle] (most platforms)
 * http://gitden.com/gitdenreader[Gitden] (Android and iOS)
@@ -710,17 +740,17 @@ Here's a list of some of the ereaders we know to have good EPUB3 support and the
 * https://chrome.google.com/webstore/detail/readium/fepbnnnkkadjhjahcafoaglimekefifl?hl=en-US[Readium] (Chrome)
 * http://www.kobo.com/apps[Kobo] (Android, iOS, OSX and Windows)
 * http://www.namo.com/site/namo/menu/5074.do[Namo PubTreeViewer] (Android, iOS and Windows)
-* http://calibre-ebook.com[Calibre ebook-viewer] (Linux, OSX, Windows)
+* http://calibre-ebook.com[Calibre (ebook-viewer)] (Linux, OSX, Windows)
 
-IMPORTANT: To get the full experience, *ensure that the ereader is configured to use the publisher's styles*.
-Different ereaders word this setting in different ways.
+IMPORTANT: To get the full experience, *ensure that the e-reader is configured to use the publisher's styles*.
+Different e-readers word this setting in different ways.
 Look for the option screen that allows you to set the fonts and font colors and disable it.
 With publisher's styles active, you'll still be able to adjust the relative size of the fonts and margins and toggle between day, night and sepia mode.
 
-When the book is viewed in EPUB2 ereaders and Kindle apps/devices which have reached their end-of-life (EOL), the ebook relies on the strong semantics of the HTML and some fallback styles to render properly.
-EPUB2 ereaders, such as Aldiko, don't understand CSS3 styles and therefore miss out on some of subtleties in the formatting.
+When the book is viewed in EPUB2 e-readers and Kindle apps/devices which have reached their end-of-life (EOL), the e-book relies on the strong semantics of the HTML and some fallback styles to render properly.
+EPUB2 e-readers, such as Aldiko, don't understand CSS3 styles and therefore miss out on some of subtleties in the formatting.
 
-As mentioned in the <<About the Theme,theme section>>, the stylesheet attempts to provide as consistent a reading experience as possible in the common EPUB3 ereaders, despite the different CSS implementation rules and limitations unique to each ebook application.
+As mentioned in the <<About the Theme,theme section>>, the stylesheet attempts to provide as consistent a reading experience as possible in the common EPUB3 e-readers, despite the different CSS implementation rules and limitations unique to each e-book application.
 Most of these obstacles were addressed using media queries or explicit classes.
 Some we haven't conquered.
 Yet.
@@ -751,15 +781,29 @@ To see all of the workarounds and why we chose certain style options, check out
 
 WARNING: Don't use it!
 
-The “Send to Kindle” feature, a convenient tool for transferring a MOBI file to a Kindle device, is utterly broken.
+{uri-send-to-kindle}[“Send to Kindle”] is a tempting choice for transferring MOBI files to a Kindle device.
+However, it's utterly broken.
+If you use this tool, don't be surprised if you see missing font-based icons, default fonts, and other font and style errors in your manuscript.
 It's known to strip out all the font files and break the encoding of the document.
 
-If you use this feature, don't be surprised if you see default fonts, missing font-based icons, and other font and style errors.
-We *strongly* recommend that you transfer the file to your device using other means, such as a USB cable or sync service like Dropbox.
+We *strongly* recommend you transfer the file to your device using either a USB cable or a sync service such as Dropbox.
+Once transferred, Whispersync will detect the new file (usually looking in the Books folder) and add it to the “On Device” library.
 
-It's also important to know that “Send to Kindle” is not indicative of the experience readers will have when shopping in the Kindle store.
+It's important to note that “Send to Kindle” is not reflective of the experience readers will have when shopping in the Kindle store.
 If you use Kindle Direct Publishing (KDP) to publish your book, the integrity of your book will be preserved (to the degree that Amazon allows).
 
+=== Look Inside
+
+The Amazon Kindle store has a “Look Inside” feature, which aims to gives readers a glimpse at the contents of the book.
+Sadly, it does no such thing.
+Instead, it shows pages from the legacy MOBI document that kindlegen adds to your e-book file, not the higher fidelity KF8 document.
+Therefore, the preview won't look at all like what the Kindle reader or application will actually show.
+Custom fonts, font-based icons, and most styles will be missing.
+
+This situation is unfortunate for authors.
+What I recommend is to complain loudly to Amazon that they are hurting your sales by displaying a crippled version of your product.
+Another option is to contact Amazon to opt-out of this so-called feature.
+
 ////
 head-stop (default '.')
 stack-head role (run-in is default)
@@ -803,6 +847,7 @@ Nexus ,
 
 ////
 
+ifndef::env-site[]
 == Contributing
 
 In the spirit of free software, _everyone_ is encouraged to help improve this project.
@@ -900,6 +945,7 @@ or
 You're now ready to test drive the development version of {project-name}!
 
 Jump back to <<Getting Started>> to learn how to create an AsciiDoc document and convert it to EPUB3.
+endif::[]
 
 == Authors
 
@@ -907,7 +953,7 @@ Jump back to <<Getting Started>> to learn how to create an AsciiDoc document and
 
 == Copyright
 
-Copyright (C) 2014-2017 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2018 OpenDevise Inc. and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
 For the full text of the license, see the <<LICENSE#,LICENSE>> file.
@@ -921,5 +967,5 @@ Refer to the <<NOTICE#,NOTICE>> file for information about third-party Open Sour
 * circled numbers from M+ 1mn for annotation numbers in listing blocks
 * avatars for authors
 * document command to generate the M+ 1p latin fonts
-* recommended ereaders (Readium, Gitden, Kindle, etc)
+* recommended e-readers (Readium, Gitden, Kindle, etc)
 ////

data/Rakefile

@@ -7,14 +7,17 @@ default_tasks = []
 
 begin
   require 'bundler/gem_tasks'
+  default_tasks << :build
 
+  # Enhance the release task to create an explicit commit for the release
+  #Rake::Task[:release].enhance [:commit_release]
+
+  # NOTE you don't need to push after updating version and committing locally
+  # WARNING no longer works; it's now necessary to get master in a state ready for tagging
   task :commit_release do
     Bundler::GemHelper.new.send :guard_clean
     sh %(git commit --allow-empty -a -m 'Release #{Asciidoctor::Epub3::VERSION}')
   end
-
-  # Enhance the release task to create an explicit commit for the release
-  Rake::Task[:release].enhance [:commit_release]
 rescue LoadError
 end
 

data/data/styles/epub3-css3-only.css

@@ -104,6 +104,40 @@ body code, body kbd, body pre, pre :not(code) {
   }
 }
 
+/* Use darker font colors on Kindle Paperwhite */
+@media amzn-kf8 and (device-height: 1024px) and (device-width: 758px),
+    amzn-kf8 and (device-height:  758px) and (device-width: 1024px) {
+  body p,
+  div.abstract > p,
+  ul, ol, li, dl, dt, dd, footer,
+  div.verse .attribution, table.table th, table.table td,
+  figcaption, caption,
+  h1, h2, h3, h4, h5 {
+    color: #000000;
+  }
+
+  body a:link,
+  div.abstract > p a:link {
+    color: #000000;
+    -webkit-text-fill-color: #000000;
+  }
+
+  body a:visited {
+    color: #333332;
+    -webkit-text-fill-color: #333332;
+  }
+
+  .chapter-header {
+    color: #191918;
+    border-bottom-color: #191918;
+  }
+  
+  h1.chapter-title .subtitle,
+  .chapter-header p.byline {
+    color: #000000;
+  }
+}
+
 .chapter-header p.byline {
   height: auto; /* Aldiko requires this value to be 0; reset it for all others */
 }

data/data/styles/epub3.css

@@ -81,7 +81,7 @@ b, strong {
 
 b.button {
   font-weight: normal;
-  text-shadow: 1px 0 0 #B3B3B1;
+  text-shadow: 1px 0 0 #666665;
   color: #191918;
   white-space: nowrap;
 }
@@ -138,6 +138,7 @@ kbd {
 
 img {
   border: 0;
+  max-width: 100%;
 }
 
 mark {
@@ -568,7 +569,7 @@ h5 {
 
   font-size: 0.9em;
   font-weight: 700;
-  text-transform: uppercase;
+  text-transform: uppercase; /* not supported in Adobe Digital Editions */
   margin-top: 1.11em; /* 1rem */
   margin-bottom: -0.972em; /* -0.875rem */
 }
@@ -583,10 +584,12 @@ h5 code {
 
 /* Kindle strips (or unwraps) <header> tags, so we use an inner div to style */
 .chapter-header {
-  background-color: #333332;
   /* NOTE div must have at least 1px top padding for background to fill */
-  padding: 0.75em 1.5em 0.25em 1.5em; /* would like to use 1.5vh 1.5em */
+  /* would like to use vh units for top and bottom padding */
+  /*padding: 0.75em 1.5em 0.25em 1.5em;*/
+  padding: 0.25em 0;
   margin-bottom: 2.5em;
+  border-bottom: 1px solid #666665;
   /* TODO maybe what we need to get articles to start in left column
   -webkit-column-break-before: left;
   page-break-before: left;
@@ -599,16 +602,15 @@ h1.chapter-title {
   margin-top: 3.5em; /* 4.2rem - would like to use 9vh */
   margin-bottom: 0;
   padding-bottom: 0.8333em; /* 1.2rem */
-  color: #B3B3B1;
-  text-transform: uppercase;
+  color: #666665;
+  text-transform: uppercase; /* not supported in Adobe Digital Editions */
   word-spacing: -0.075em;
   letter-spacing: -0.01em;
-  border-bottom: 1px solid #DCDCDE;
 }
 
 h1.chapter-title .subtitle {
   font-weight: 400;
-  color: #FFFFFF;
+  color: #333332;
   display: block;
   font-size: 1.5em;
   margin: 0 0 0 0.75em; /* would like to use 2vw */
@@ -625,7 +627,7 @@ h1.chapter-title b {
 }
 
 .chapter-header p.byline {
-  color: #DCDCDE;
+  color: #333332;
   /* float left and height 0 takes this line out of the flow */
   float: left;
   height: 0;
@@ -728,7 +730,8 @@ figure.image {
 }
 
 figure.image img {
-  max-width: 100%;
+  display: block;
+  margin: 0 auto;
 }
 
 figure.coalesce {
@@ -794,7 +797,7 @@ aside.sidebar.titled {
 }
 
 aside.sidebar > h2 {
-  /*text-transform: uppercase;*/ /* uppercase done manually to support Aldiko */
+  text-transform: uppercase; /* not supported in Adobe Digital Editions */
   font-size: 1em;
   /*
   font-weight: 700;
@@ -899,18 +902,6 @@ blockquote footer .context {
   color: #666665;
 }
 
-/* Kindle requires text-align: center on surrounding div to align image to center */
-figure.image div.content {
-  text-align: center;
-}
-
-/* in the event the viewer adds display: block to the image */
-figure.image img {
-  /* max-width not supported in Kindle, need to use a media query to add */
-  /*max-width: 95%;*/
-  margin: 0 auto;
-}
-
 pre {
   text-align: left; /* fix for Namo */
   margin-top: 1em; /* 0.85rem */

data/lib/asciidoctor-epub3/converter.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# encoding: utf-8
 require_relative 'spine_item_processor'
 require_relative 'font_icon_map'
 
@@ -58,8 +58,6 @@ class ContentConverter
 
   XmlElementRx = /<\/?.+?>/
   CharEntityRx = /&#(\d{2,6});/
-  NamedEntityRx = /&([A-Z]+);/
-  UppercaseTagRx = /<(\/)?([A-Z]+)>/
 
   FromHtmlSpecialCharsMap = {
     '&lt;' => '<',
@@ -100,22 +98,17 @@ class ContentConverter
   def document node
     docid = node.id
 
-    if (doctitle = node.doctitle partition: true, sanitize: true, use_fallback: true).subtitle?
-      title = doctitle.main
-      title_upper = title.upcase
+    if (doctitle = node.doctitle partition: true, use_fallback: true).subtitle?
+      title = %(#{doctitle.main} )
       subtitle = doctitle.subtitle
     else
       # HACK until we get proper handling of title-only in CSS
-      title = title_upper = ''
+      title = ''
       subtitle = doctitle.combined
     end
 
-    doctitle_sanitized = doctitle.combined
+    doctitle_sanitized = (node.doctitle sanitize: true, use_fallback: true).to_s
     subtitle_formatted = subtitle.split.map {|w| %(<b>#{w}</b>) } * ' '
-    # FIXME use uppercase pcdata helper to make less fragile (see logic in Asciidoctor PDF)
-    subtitle_formatted_upper = subtitle_formatted.upcase
-        .gsub(UppercaseTagRx) { %(<#{$1}#{$2.downcase}>) }
-        .gsub(NamedEntityRx) { %(&#{$1.downcase};) }
 
     if (node.attr 'publication-type', 'book') == 'book'
       byline = nil
@@ -171,7 +164,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 <section class="chapter" title="#{doctitle_sanitized.gsub '"', '&quot;'}" epub:type="chapter" id="#{docid}">
 #{icon_css_scoped}<header>
 <div class="chapter-header">
-#{byline}<h1 class="chapter-title">#{title_upper}#{subtitle ? %[ <small class="subtitle">#{subtitle_formatted_upper}</small>] : nil}</h1>
+#{byline}<h1 class="chapter-title">#{title}#{subtitle ? %[<small class="subtitle">#{subtitle_formatted}</small>] : ''}</h1>
 </div>
 </header>
 #{content})]
@@ -274,6 +267,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   end
 
   def admonition node
+    id_attr = node.id ? %( id="#{node.id}") : nil
     if node.title?
       title = node.title
       title_sanitized = xml_sanitize title
@@ -294,7 +288,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
     when 'important', 'warning', 'caution'
       'warning'
     end
-    %(<aside class="admonition #{type}"#{title_attr} epub:type="#{epub_type}">
+    %(<aside#{id_attr} class="admonition #{type}"#{title_attr} epub:type="#{epub_type}">
 #{title_el}<div class="content">
 #{convert_content node}
 </div>
@@ -302,9 +296,10 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   end
 
   def example node
+    id_attr = node.id ? %( id="#{node.id}") : nil
     title_div = node.title? ? %(<div class="example-title">#{node.title}</div>
 ) : nil
-    %(<div class="example">
+    %(<div#{id_attr} class="example">
 #{title_div}<div class="example-content">
 #{convert_content node}
 </div>
@@ -344,6 +339,9 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   end
 
   def quote node
+    id_attr = %( id="#{node.id}") if node.id
+    class_attr = (role = node.role) ? %( class="blockquote #{role}") : ' class="blockquote"'
+
     footer_content = []
     if (attribution = node.attr 'attribution')
       footer_content << attribution
@@ -363,7 +361,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
     content = (convert_content node).strip.
       sub(OpenParagraphTagRx, '<p><span class="open-quote">“</span>').
       sub(CloseParagraphTagRx, '<span class="close-quote">”</span></p>')
-    %(<div class="blockquote">
+    %(<div#{id_attr}#{class_attr}>
 <blockquote>
 #{content}#{footer_tag}
 </blockquote>
@@ -371,6 +369,9 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   end
 
   def verse node
+    id_attr = %( id="#{node.id}") if node.id
+    class_attr = (role = node.role) ? %( class="verse #{role}") : ' class="verse"'
+
     footer_content = []
     if (attribution = node.attr 'attribution')
       footer_content << attribution
@@ -383,7 +384,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
 
     footer_tag = footer_content.size > 0 ? %(
 <span class="attribution">~ #{footer_content * ', '}</span>) : nil
-    %(<div class="verse">
+    %(<div#{id_attr}#{class_attr}>
 <pre>#{node.content}#{footer_tag}</pre>
 </div>)
   end
@@ -395,9 +396,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       title = node.title
       title_sanitized = xml_sanitize title
       title_attr = %( title="#{title_sanitized}")
-      # FIXME use uppercase pcdata helper to make less fragile (see logic in Asciidoctor PDF)
-      title_upper = title.upcase.gsub(NamedEntityRx) { %(&#{$1.downcase};) }
-      title_el = %(<h2>#{title_upper}</h2>
+      title_el = %(<h2>#{title}</h2>
 )
     else
       title_attr = nil
@@ -418,14 +417,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
     frame_class = {
       'all' => 'table-framed',
       'topbot' => 'table-framed-topbot',
-      'sides' => 'table-framed-sides'
+      'sides' => 'table-framed-sides',
+      'none' => ''
     }
     grid_class = {
       'all' => 'table-grid',
       'rows' => 'table-grid-rows',
-      'cols' => 'table-grid-cols'
+      'cols' => 'table-grid-cols',
+      'none' => ''
     }
-    table_classes = %W(table #{frame_class[(node.attr 'frame')] || frame_class['topbot']} #{grid_class[(node.attr 'grid')] || grid_class['rows']})
+    table_classes = %W(table #{frame_class[node.attr 'frame'] || frame_class['topbot']} #{grid_class[node.attr 'grid'] || grid_class['rows']})
     if (role = node.role)
       table_classes << role
     end
@@ -625,16 +626,14 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
   def image node
     target = node.attr 'target'
     type = (::File.extname target)[1..-1]
+    id_attr = node.id ? %( id="#{node.id}") : ''
     img_attrs = [%(alt="#{node.attr 'alt'}")]
     case type
     when 'svg'
       img_attrs << %(style="width: #{node.attr 'scaledwidth', '100%'}")
       # TODO make this a convenience method on document
-      epub_properties = (node.document.attr 'epub-properties') || []
-      unless epub_properties.include? 'svg'
-        epub_properties << 'svg'
-        node.document.attributes['epub-properties'] = epub_properties
-      end
+      epub_properties = (node.document.attributes['epub-properties'] ||= [])
+      epub_properties << 'svg' unless epub_properties.include? 'svg'
     else
       if node.attr? 'scaledwidth'
         img_attrs << %(style="width: #{node.attr 'scaledwidth'}")
@@ -657,7 +656,7 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       end
     end
 =end
-    %(<figure class="image">
+    %(<figure#{id_attr} class="image#{prepend_space node.role}">
 <div class="content">
 <img src="#{node.image_uri node.attr('target')}" #{img_attrs * ' '}/>
 </div>#{node.title? ? %[
@@ -692,8 +691,11 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         id_attr = nil unless @xrefs_seen.add? refid
         refdoc = doc.references[:spine_items].find {|it| refdoc_id == (it.id || (it.attr 'docname')) }
         if refdoc
-          if (reftext = refdoc.references[:ids][refdoc_refid])
-            text ||= reftext
+          # QUESTION should we invoke xreftext for references in other documents?
+          if (refs = refdoc.references[:refs]) && ::Asciidoctor::Document === (ref = refs[refdoc_refid])
+            text ||= (ref.attr 'docreftext') || ref.doctitle
+          elsif (xreftext = refdoc.references[:ids][refdoc_refid])
+            text ||= xreftext
           else
             warn %(asciidoctor: WARNING: #{::File.basename(doc.attr 'docfile')}: invalid reference to unknown anchor in #{refdoc_id} chapter: #{refdoc_refid})
           end
@@ -702,10 +704,18 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
         end
       else
         id_attr = (@xrefs_seen.add? refid) ? %( id="xref-#{refid}") : nil
-        if (reftext = doc.references[:ids][refid])
-          text ||= reftext
+        if (refs = doc.references[:refs])
+          if ::Asciidoctor::AbstractNode === (ref = refs[refid])
+            xreftext = text || ref.xreftext((@xrefstyle ||= (doc.attr 'xrefstyle')))
+          end
         else
-          # FIXME we get false negatives for reference to bibref
+          xreftext = doc.references[:ids][refid]
+        end
+
+        if xreftext
+          text ||= xreftext
+        else
+          # FIXME we get false negatives for reference to bibref when using Asciidoctor < 1.5.6
           warn %(asciidoctor: WARNING: #{::File.basename(doc.attr 'docfile')}: invalid reference to unknown local anchor (or valid bibref): #{refid})
         end
       end
@@ -757,8 +767,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
       %(<i class="#{i_classes * ' '}"></i>)
     else
       target = node.image_uri node.target
-      class_attr = %( class="#{node.role}") if node.role?
-      %(<img src="#{target}" alt="#{node.attr 'alt'}"#{class_attr}/>)
+      img_attrs = [%(alt="#{node.attr 'alt'}"), %(class="inline#{node.role? ? " #{node.role}" : ''}")]
+      if target.end_with? '.svg'
+        img_attrs << %(style="width: #{node.attr 'scaledwidth', '100%'}")
+        # TODO make this a convenience method on document
+        epub_properties = (node.document.attributes['epub-properties'] ||= [])
+        epub_properties << 'svg' unless epub_properties.include? 'svg'
+      elsif node.attr? 'scaledwidth'
+        img_attrs << %(style="width: #{node.attr 'scaledwidth'}")
+      end
+      %(<img src="#{target}" #{img_attrs * ' '}/>)
     end
   end
 
@@ -839,11 +857,16 @@ document.addEventListener('DOMContentLoaded', function(event, reader) {
     end
     nil
   end
+
+  # Prepend a space to the value if it's non-nil, otherwise return empty string.
+  def prepend_space value
+    value ? %( #{value}) : ''
+  end
 end
 
 class DocumentIdGenerator
   ReservedIds = %w(cover nav ncx)
-  CharRefRx = /&(?:([a-zA-Z]{2,})|#(\d{2,6})|#x([a-fA-F0-9]{2,5}));/
+  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}/

data/lib/asciidoctor-epub3/packager.rb

@@ -94,7 +94,19 @@ module GepubBuilderMixin
 </platform>
 </display_options>'.to_ios unless format == :kf8
 
-        with_media_type 'application/x-font-ttf' do
+        # https://github.com/asciidoctor/asciidoctor-epub3/issues/120
+        #
+        # 'application/x-font-ttf' causes warnings in epubcheck 4.0.2,
+        # "non-standard font type". Discussion:
+        # https://www.mobileread.com/forums/showthread.php?t=231272
+        #
+        # 3.1 spec recommends 'application/font-sfnt', but epubcheck doesn't
+        # implement that yet (warnings). https://idpf.github.io/epub-cmt/v3/
+        #
+        # 3.0 spec recommends 'application/vnd.ms-opentype', this works without
+        # warnings.
+        # http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-core-media-types
+        with_media_type 'application/vnd.ms-opentype' do
           font_files.each do |font_file|
             file font_file => ::File.join(DATA_DIR, font_file)
           end
@@ -123,7 +135,7 @@ module GepubBuilderMixin
           width, height = 1050, 1600
         end
       else
-        warn %(asciidoctor: ERROR: front cover image not found or readable: #{image_path})
+        warn %(asciidoctor: ERROR: #{::File.basename(doc.attr 'docfile')}: front cover image not found or readable: #{::File.expand_path image_path, workdir})
         image_path = nil
       end
     end
@@ -210,7 +222,6 @@ body > svg {
     nil
   end
 
-  # FIXME add inline images
   def add_content_images doc, images
     docimagesdir = (doc.attr 'imagesdir', '.').chomp '/'
     docimagesdir = (docimagesdir == '.' ? nil : %(#{docimagesdir}/))
@@ -218,15 +229,12 @@ body > svg {
     workdir = (workdir = doc.attr 'docdir').nil_or_empty? ? '.' : workdir
     resources workdir: workdir do
       images.each do |image|
-        imagesdir = (image.document.attr 'imagesdir', '.').chomp '/'
-        imagesdir = (imagesdir == '.' ? nil : %(#{imagesdir}/))
-        image_path = %(#{imagesdir}#{image.attr 'target'})
-        if image_path.start_with? %(#{docimagesdir}jacket/cover.)
+        if (image_path = image[:path]).start_with? %(#{docimagesdir}jacket/cover.)
           warn %(asciidoctor: WARNING: image path is reserved for cover artwork: #{image_path}; skipping image found in content)
         elsif ::File.readable? image_path
           file image_path
         else
-          warn %(asciidoctor: ERROR: image not found or not readable: #{image_path})
+          warn %(asciidoctor: ERROR: #{::File.basename image[:docfile]}: image not found or not readable: #{::File.expand_path image_path, workdir})
         end
       end
     end
@@ -266,7 +274,7 @@ body > svg {
   end
 
   def add_content doc
-    builder, spine, format = self, @spine, @format
+    builder, spine, format, images = self, @spine, @format, {}
     workdir = (doc.attr 'docdir').nil_or_empty? ? '.' : workdir
     resources workdir: workdir do
       extend GepubResourceBuilderMixin
@@ -277,13 +285,21 @@ body > svg {
         builder.add_cover_page doc, self, @book.manifest unless format == :kf8
         builder.add_front_matter_page doc, self
         spine.each_with_index do |item, i|
+          docfile = item.attr 'docfile'
+          imagesdir = (item.attr 'imagesdir', '.').chomp '/'
+          imagesdir = (imagesdir == '.' ? '' : %(#{imagesdir}/))
           file %(#{item.id || (item.attr 'docname')}.xhtml) => (builder.postprocess_xhtml item.convert, format)
           add_property 'svg' if ((item.attr 'epub-properties') || []).include? 'svg'
+          # QUESTION should we pass the document itself?
+          item.references[:images].each do |target|
+            images[image_path = %(#{imagesdir}#{target})] ||= { docfile: docfile, path: image_path }
+          end
           # QUESTION reenable?
           #linear 'yes' if i == 0
         end
       end
     end
+    add_content_images doc, images.values
     nil
   end
 
@@ -407,7 +423,12 @@ body > svg {
   def select_fonts filename, scripts = 'latin'
     font_css = ::File.read(filename)
     font_css = font_css.gsub(/(?<=-)latin(?=\.ttf\))/, scripts) unless scripts == 'latin'
-    font_list = font_css.scan(/url\(\.\.\/(.+\.ttf)\);$/).flatten
+
+    # 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
+
     return [font_list, font_css.to_ios]
   end
 
@@ -476,11 +497,9 @@ class Packager
     target = options[:target]
     dest = File.dirname target
 
-    images = spine.map {|item| item.find_by context: :image }.compact.flatten
-        .uniq {|img| %(#{(img.document.attr 'imagesdir', '.').chomp '/'}/#{img.attr 'target'}) }
     # FIXME authors should be aggregated already on parent document
     authors = if doc.attr? 'authors'
-      (doc.attr 'authors').split(GepubBuilderMixin::CsvDelimiterRx).concat(spine.map {|item| item.attr 'author' }).uniq
+      (doc.attr 'authors').split(GepubBuilderMixin::CsvDelimiterRx).concat(spine.map {|item| item.attr 'author' }.compact).uniq
     else
       []
     end
@@ -569,8 +588,6 @@ class Packager
         usernames = spine.map {|item| item.attr 'username' }.compact.uniq
         add_profile_images doc, usernames
       end
-      # QUESTION move add_content_images to add_content method?
-      add_content_images doc, images
       add_content doc
     end
 

data/lib/asciidoctor-epub3/spine_item_processor.rb

@@ -16,13 +16,17 @@ class SpineItemProcessor < Extensions::IncludeProcessor
     inherited_attrs = spine_doc.attributes.dup
     # QUESTION should we keep backend-epub3 for convenience?
     %w(backend-epub3 backend-epub3-doctype-book docdir docfile docname doctitle outfilesuffix spine).each {|key| inherited_attrs.delete key }
+    if (leveloffset = inherited_attrs['leveloffset'])
+      leveloffset = inherited_attrs['leveloffset'] = %(#{leveloffset}@) unless leveloffset.end_with? '@'
+    end
 
     # parse header to get author information
     spine_item_doc_meta = ::Asciidoctor.load_file include_file,
         safe: spine_doc.safe,
         backend: 'epub3-xhtml5',
         doctype: :article,
-        parse_header_only: true
+        parse_header_only: true,
+        attributes: leveloffset ? { 'leveloffset' => leveloffset } : nil
 
     # blank out author information if present in sub-document
     # FIXME this is a huge hack...we need a cleaner way to do this; perhaps an API method that retrieves all the author attribute names
@@ -51,6 +55,7 @@ class SpineItemProcessor < Extensions::IncludeProcessor
         backend: 'epub3-xhtml5',
         doctype: :article,
         header_footer: true,
+        catalog_assets: true,
         attributes: inherited_attrs
 
     # restore attributes to those defined in the document header

data/lib/asciidoctor-epub3/version.rb

@@ -1,5 +1,5 @@
 module Asciidoctor
 module Epub3
-  VERSION = '1.5.0.alpha.7'
+  VERSION = '1.5.0.alpha.8'
 end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-epub3
 version: !ruby/object:Gem::Version
-  version: 1.5.0.alpha.7
+  version: 1.5.0.alpha.8
 platform: ruby
 authors:
 - Dan Allen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-18 00:00:00.000000000 Z
+date: 2018-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -67,10 +67,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.3.6
-description: 'An extension for Asciidoctor that converts AsciiDoc documents to EPUB3
-  and KF8/MOBI (Kindle) e-book archives.
-
-'
+description: |
+  An extension for Asciidoctor that converts AsciiDoc documents to EPUB3 and KF8/MOBI (Kindle) e-book archives.
 email: dan@opendevise.com
 executables:
 - asciidoctor-epub3
@@ -168,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Converts AsciiDoc documents to EPUB3 and KF8/MOBI (Kindle) e-book formats