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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e374c40b52ce88330f2a960fd7430768ca178120
-  data.tar.gz: 732c8b6ae36689da969cab15eebd75536b6f6124
+  metadata.gz: d837e7c36f6d2e47ee9f436d1a7327e42b304aad
+  data.tar.gz: '02679c6c564034d4fefd752cd26ee1611ac8c3cc'
 SHA512:
-  metadata.gz: 34ec853c27180fce39c6be6bae2ddc084b524c624d588e65551ae8cfb8a491ea38fc08419344be87dbb0aebe69d5312b0c5a71a70e9a8786c58f5633fd9a169f
-  data.tar.gz: 93eb3c8919c0799573b0e107ebf6f1ebc8ee0b79cf4f3628fd543bebfd2e1e019e1180ea753ef7e6fa6a5b8e50342fb4854e4a7a048e8ba3a3ba8bcf2a4bc335
+  metadata.gz: 2d1284f2bca9f66a2a64d8625d812c83ccd29caac1cabd68c834376429632f0f41e0b443e40ebd03394e3ba846480ee092f8c13130061d50da3270d4d0c9ac29
+  data.tar.gz: ff5db3ebee66a7cafafc0ec294355c422c8cac597ec991d1db49166e064db59e7b81314b58c17adcda0926676358864fa0508b78a429e84f195366131a1bee7c

data/CHANGELOG.adoc

@@ -0,0 +1,134 @@
+= {project-name} Changelog
+:project-name: Asciidoctor EPUB3
+:uri-repo: https://github.com/asciidoctor/asciidoctor-epub3
+
+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.7 (2017-04-18) - @mojavelinux
+
+* generate TOC levels in navigation document based on toclevels attribute (#90)
+* automatically resolve title of reference between documents (#87)
+* fix xref between chapter files (#27)
+* don't include byline in chapter header if the value of the publication-type attribute is book (#86)
+* don't include avatars if value of publication-type attribute is book (#53)
+* make a stronger statement in the README about the dangers of the “Send to Kindle” tool
+* add ebook-compress flag to enable huffdic compression in kindlegen
+* implement embedded to handle AsciiDoc table cell content (#69)
+* go into more depth about how to structure the document in README (#45)
+* explain how to adjust section level of chapters if they use level-2 headings
+* don't add content image to archive more than once (#76)
+* warn when xref cannot be resolved and text is provided (#103)
+* built-in avatar location should respect imagesdir (#2)
+* change admonition icons (#72) (@PrimaryFeather)
+* fix broken refs in bibliography (#19)
+* remove text justification hack (#92)
+* reset @page for CSS3-capable readers
+* detect Calibre, set class attribute on body to calibre-desktop, add page margins
+* force preformatted text to wrap in Gitden
+* add svg property to front matter only if reference to SVG is detected
+* switch from word-wrap to standard overflow-wrap property in stylesheet
+* loosen letter spacing in quote attribute context
+* adjust font size and margins on Gitden; force margins to be set
+* document in README that using vw units causes Aldiko to crash
+* drop trailing semi-colon in value of inline style attributes
+* use standard format (from core) for warning and error messages
+* update terminology in README; use ebook instead of e-book; refer to application as ereader
+* allow front-cover-image to be specified using block image macro (#3)
+* clean auto-generated file names for chapters (#46)
+* register chapter ID in references
+* only wrap open block content in div if id or role is defined (@rvolz)
+* link to EPUB 3.1 spec from README
+* set ebook-format-kf8 attribute when ebook-format is specified as mobi
+* document the front-cover-image attribute properly
+* update adb-push-book script to honor file extension if specified
+* document limitations of applying page-break-* property on Kindle
+* document that Asciidoctor is added as creator if creator attribute is not specified (#68)
+* group optional gems in the :optional group; remove from gemspec
+* upgrade kindlegen gem to 3.0.3
+* upgrade Pygments to 1.1.1 and allow JRuby to install it
+* document that Pygments bw style is used by default
+* honor explicit table width even when autowidth option is set
+* use method_defined? instead of respond_to? to check if method is already defined
+* fix README typo, strong tag misspelled (@neontapir)
+* fix name of bundler gem; add NOKOGIRI_USE_SYSTEM_LIBRARIES to install command
+* state in README that the spine document must only have include directives as content
+
+== 1.5.0.alpha.6 (2016-01-05) - @mojavelinux
+
+* disable text-rendering: optimizeLegibility on Kindle devices (#58)
+* proxy CSS in KF8 format to work around KDP removing font-related CSS rules
+* don't append source when generating mobi file
+* disable -webkit-hyphens to prevent Kindle for Mac from crashing (#26)
+* don't explicitly enable hyphenation
+* disable hyphens in preformatted text
+* don't fail if source block is empty
+* hide style element in body from Aldiko
+* enable Original (Publisher) font option in iBooks client
+* preserve heading & monospaced fonts in Kindle Paperwhite/Voyage
+* force left justification in listings (fix for Namo)
+* fix documentation regarding uuid attribute (@chkal)
+* add note that currently images must be placed in a directory called images (@chkal)
+* fix file type of avatar image in docs (@chkal)
+* document how to install the pre-release gem (#38)
+* use built-in font names for mobi7 (#56)
+* document the epub3-stylesdir attribute
+* prevent ellipsis from being used in inline code
+* don't include scoped icon CSS in KF8 format
+* remove link color hack for Gitden since its already covered
+* override heading and monospace fonts for non-Kindle epub3 readers
+* wrap simple dd content in span to allow font to be controlled in iBooks
+* enforce use of monospace font for preformatted elements
+* upgrade kindlegen
+* don't allow UI button to wrap
+* remove amzn-mobi from media query in CSS3-only file
+* use CSS property word-wrap instead of word-break
+* remove charset declaration from CSS
+* switch samples to modern AsciiDoc syntax
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.6[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.6[git tag]
+
+== 1.5.0.alpha.5 (2015-11-01) - @mojavelinux
+
+* implement -o flag (output file) (#31) (@chloerei)
+* implement the converter method for floating_title (#36)
+* don't print kindlegen output if -q flag is used (#34)
+* CLI now identifies as asciidoctor-epub3 (#32)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.5[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.5[git tag]
+
+== 1.5.0.alpha.4 (2014-11-28) - @mojavelinux
+
+* set ebook-format-epub3 attribute (#16)
+* add box drawing symbols to M+ 1mn font
+* switch version to 1.5.0.x to align with core
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.4[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.4[git tag]
+
+== 1.0.0.alpha.3 (2014-08-17) - @mojavelinux
+
+* don't attempt to chdir to DATA_DIR; use full path; for compatibility with AsciidoctorJ
+* fix BOM regexp in JRuby (again)
+* switch sample png avatars to jpg
+* don't install pygments.rb on JRuby
+
+{uri-repo}/releases/tag/v1.0.0.alpha.4[git tag]
+
+== 1.0.0.alpha.2 (2014-08-15) - @mojavelinux
+
+* upgrade to Asciidoctor 1.5.0
+* use new functionality of doctitle method for splitting up doctitle
+* don't put units on line-height in stylesheet
+* use regexp to match the BOM character (used to fix text justification) in JRuby
+
+{uri-repo}/releases/tag/v1.0.0.alpha.2[git tag]
+
+== 1.0.0.alpha.1 (2014-07-29) - @mojavelinux
+
+* initial pre-release
+
+{uri-repo}/issues?q=milestone%3Av1.0.0.alpha.1[issues resolved] |
+{uri-repo}/releases/tag/v1.0.0.alpha.1[git tag]

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Look in asciidoctor-epub3.gemspec for runtime and development dependencies.
+gemspec
+
+group :optional do
+  gem 'pygments.rb', '1.1.1'
+  gem 'kindlegen', '3.0.3'
+  gem 'epubcheck', '3.0.1'
+end

data/README.adoc

@@ -1,37 +1,57 @@
-= Asciidoctor EPUB3: A _native_ EPUB3 converter for AsciiDoc
+= {project-name}: A _native_ EPUB3 converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-:project-name: Asciidoctor EPUB3
-:project-handle: asciidoctor-epub3
-:project-uri: https://github.com/asciidoctor/{project-handle}
-:project-repo-uri: {project-uri}
-:project-issues-uri: {project-repo-uri}/issues
-:rvm-uri: http://rvm.io
-:asciidoctor-uri: http://asciidoctor.org
-:idpf-uri: http://www.idpf.org/
-:epub-uri: http://www.idpf.org/epub/30/spec/epub30-overview.html
-:epubcheck-uri: https://github.com/idpf/epubcheck
+v1.5.0.alpha.7, 2017-04-18
+// Settings:
+:experimental:
+:idprefix:
+:idseparator: -
+:imagesdir: data/samples/images
+ifdef::env-github,env-browser[]
+:toc: preamble
+:toclevels: 1
+endif::[]
 ifdef::env-github[]
-:base-uri: link:
+:status:
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
 endif::[]
 ifndef::env-github[]
-:base-uri: {project-repo-uri}/blob/master/
+:icons: font
+endif::[]
+// Aliases:
+:project-name: Asciidoctor EPUB3
+:project-handle: asciidoctor-epub3
+// URIs:
+:uri-project: https://github.com/asciidoctor/{project-handle}
+:uri-gem: http://rubygems.org/gems/asciidoctor-epub3
+:uri-repo: {uri-project}
+:uri-issues: {uri-repo}/issues
+:uri-discuss: http://discuss.asciidoctor.org
+:uri-rvm: https://rvm.io
+:uri-asciidoctor: http://asciidoctor.org
+: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
+
+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::[]
-:notice-uri: {base-uri}NOTICE.adoc
-:license-uri: {base-uri}LICENSE.adoc
-:worklog-uri: {base-uri}WORKLOG.adoc
-:imagesdir: data/samples/images
-:experimental:
 
-{project-name} is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI e-book formats.
+{project-name} is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI ebook 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_ 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 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.
 
 ifdef::env-github[]
-.An excerpt from an e-book produced by {project-name} shown in Day, Night and Sepia mode.
+.An excerpt from an ebook produced by {project-name} shown in Day, Night and Sepia mode.
 image::screenshots/text.png[]
 endif::[]
 
@@ -54,11 +74,11 @@ Exceptional Readability::
 Complete & 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+) readers and respond to any size screen.
+  Render consistently across a broad range of EPUB3 (and select EPUB2+) ereading platforms and respond to any size screen.
 Polish, Polish & More Polish::
   Add polish to the final product such as font-based icons and callout numbers.
 
-We believe that the e-books produced by {project-name} are the _very best_ output you can expect to find in digital publishing today.
+We believe that the ebooks 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
@@ -66,14 +86,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 reader) without altering headings, code or icons
+* Respects font settings (if supported by the ereader) 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)
 * 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 reader)
-* Orphan section titles avoided (so much as it's supported by the reader)
+* 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)
 * Table border settings honored
 * Support for SVG images in the content
 
@@ -88,41 +108,96 @@ We may explore the use of fixed layout documents in the future if the need arise
 
 === Planned Features and Work In Progress
 
-See {worklog-uri}[WORKLOG.adoc].
+See <<WORKLOG#,WORKLOG.adoc>>.
 
 == Converter Workflow
 
-{project-name} takes a single, logical AsciiDoc document as input and converts it to an EPUB3 publication archive (often described as a “website in a box”).
-Using the EPUB3 publication as the “digital master”, {project-name} then produces a KF8/MOBI file, the format required by Amazon Kindle.
-The conversion to KF8/MOBI is performed by sending the EPUB3 through http://www.amazon.com/gp/feature.html?docId=1000765211[KindleGen].
+{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”).
 
-An EPUB3 archive is typically structured with the contents of each “chapter” in a separate XHTML file.
-The converter must therefore “chunk” the source document into multiple XHTML files to put in the EPUB3 archive.
-Other converters tend to handle this task by automatically slicing up the XHTML output at predetermined heading levels.
-Asciidoctor takes a different approach.
+{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.
+
+== Structuring your Manuscript
+
+An EPUB3 archive is composed of multiple files. The content of each “chapter” is typically stored in a dedicated XHTML file.
+Therefore, the {project-name} converter “chunks” the AsciiDoc source document into multiple XHTML files to add to the EPUB3 archive.
+While other converters handle this chunking task by automatically slicing up the XHTML output at predetermined heading levels, this converter takes a different approach, outlined next.
+
+=== Composition Rules
+
+There are several rules you must follow to successfully convert your AsciiDoc source documents into an EPUB3 publication archive.
+These rules may be loosened in the future, but they are mandatory at the moment.
+
+Rule 1::
+Each chapter must begin in a dedicated file that resides at the root of the project.
+It must be included into the main document using the AsciiDoc include directive.
+The main document, which we call the “spine”, may only contain a document header and a sequence of include directives.
+See <<Declaring the Spine>> for details.
++
+TIP: The include directive may be used in the chapter files to include other files (even files in other folders).
+
+Rule 2::
+Each chapter must start with a document title (i.e., level-0 heading).
+The document header must declare an ID that matches the chapter filename (minus its file extension).
+
+Rule 3::
+No sections in a chapter may have the same ID as the chapter ID.
+
+Rule 4::
+The cross reference (i.e., xref) from one chapter to another must be in the format `+xref:chapter-id#chapter-id[optional reftext]+` (or `+<<chapter-id#chapter-id,optional reftext>>+`).
+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: 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.
+
+The next section goes into more detail about how to set up the spine document and include the chapter files.
 
 === Declaring the Spine
 
-Asciidoctor relies on top-level include directives (i.e., include directives in the master document) to indicate where the chapter splits should occur.
-Each chapter must start with a single-line, level-0 section.
-The section title becomes the chapter title and TOC entry and the section id determines the chapter file name in the EPUB3 archive.
-In other words, you must be explicit.
-Asciidoctor will not try to guess.
-If your AsciiDoc document is not structured in this way, you'll need to change it to use the {project-name} converter properly.
+The spine (or master document) must be well-formed.
+Otherwise, {project-name} will not convert the document properly.
+If your AsciiDoc documents are not structured as explained in this section, you'll need to change them.
+
+Asciidoctor uses top-level include directives (i.e., include directives in the master document) to indicate where each chapter split should occur.
+The chapter files should begin with an AsciiDoc document header, which consists of an ID, a document title (i.e., level-0 heading), an author name, and a set of attribute entries.
+Only the document title is required.
+
+The document title in the chapter file is used as the chapter title and the label for the chapter in the TOC.
+The chapter ID, combined with the _.xhtml_ suffix, is used as the filename of the chapter inside the EPUB3 archive (though this could change in the future).
+We recommend that you base the filename of the chapter on the chapter ID.
+
+If you don't specify an ID for a chapter, one will be generated automatically from the document title.
+The rules for generating a chapter ID from the document title are as follows:
+
+* apply inline formatting, then remove XML elements
+* remove the `\&#8217;` character reference (so `John\&#8217;s` becomes `Johns`)
+* replace `\&amp;` with the word `and` (so `John \&amp; Jane` becomes `John and Jane`)
+* expand all other character references
+* lowercase all characters
+* replace illegal ID characters with the character defined by the `idseparator` attribute
+* prepend the value of the `idprefix` attribute
+* 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 being passed down from the master to ensure consistent behavior.
+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.
 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:
 
+[source,asciidoc]
 ----
 = Book Title
 Author Name
 :doctype: book
 :imagesdir: images
-//...and so on
 \ifndef::ebook-format[:leveloffset: 1]
+//...and so on
 
 \include::chapter-one.adoc[]
 
@@ -131,22 +206,32 @@ Author Name
 \include::chapter-three.adoc[]
 ----
 
+IMPORTANT: The spine document cannot contain any content other than include directives.
+
 Here's an example showing the structure of a chapter document:
 
+[source,asciidoc]
 ----
-[[chapter-one]]
+[#chapter-one]
 = Chapter One
 
 chapter content
 ----
 
-CAUTION: Although an explicit ID over the chapter title is not required, it is recommended.
-See issue https://github.com/asciidoctor/asciidoctor-epub3/issues/46[#46] for details.
+CAUTION: Although an explicit ID over the chapter title is not required, it's recommended for stability.
 
-If the master document does not contain any include directives, then the converter treats the document as the sole chapter in the EPUB3 archive and automatically produces a navigation file that references it. (Currently broken. See issue https://github.com/asciidoctor/asciidoctor-epub3/issues/47[#47]).
+If your chapter files start with a level-1 section instead of a level-2 section, you need to make the opposite adjustment in the header of the spine document:
 
-Eventually, we envision introducing a dedicated block macro to represent a spine item so that we don't overload the meaning of the include directive.
-However, for the time being, the include directive will suit this purpose.
+[source,asciidoc]
+----
+\ifndef::ebook-format[:leveloffset: -1]
+----
+
+If the master document does not contain any include directives, then the converter treats the document as the sole chapter in the EPUB3 archive and automatically produces a navigation file that references it.
+(Currently broken. See issue {uri-issues}/47[#47]).
+
+NOTE: Eventually, we envision introducing a dedicated block macro to represent a spine item so that we don't overload the meaning of the include directive.
+However, for the time being, the include directive fills this role.
 
 == Prerequisites
 
@@ -158,15 +243,15 @@ 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>> or <<Development,running the code from source>>.
 
 === Install the Published Gem
 
 {project-name} is published as a pre-release on RubyGems.org.
 You can install the published gem using the following command:
 
- $ gem install asciidoctor-epub3 --pre
- 
+ $ NOKOGIRI_USE_SYSTEM_LIBRARIES=1 gem install asciidoctor-epub3 --pre
+
 If you want to syntax highlight source listings, you'll also want to install CodeRay or Pygments.
 Choose one (or more) of the following:
 
@@ -175,15 +260,18 @@ Choose one (or more) of the following:
 
 .Pygments
  $ gem install pygments.rb
- 
+
 You then activate syntax highlighting for a given document by adding the `source-highlighter` attribute to the document header (CodeRay shown):
 
 [source,asciidoc]
 ----
-:source-highlighter: coderay 
+:source-highlighter: coderay
 ----
 
 NOTE: At the moment, Pygments is automatically used if it's available.
+If a style is not specified, the black and white theme (i.e., bw) is used.
+This default is used so that the syntax highlighting is legibile regardless of which reading mode the reader selects (white, black, sepia, etc).
+To override this default, you must pass a valid Pygments style name to the `pygments-style` attribute when invoking the `asciidoctor-epub3` script (e.g., `-a pygments-style=pastie`).
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-epub3` script:
 
@@ -202,8 +290,9 @@ If you don't already have an AsciiDoc document, you can use the [file]_sample-bo
 Author Name
 v1.0, 2014-04-15
 :doctype: book
+:creator: {author}
 :producer: Asciidoctor
-:keywords: Asciidoctor, samples, e-book, EPUB3, KF8, MOBI, Asciidoctor.js
+:keywords: Asciidoctor, samples, ebook, EPUB3, KF8, MOBI, Asciidoctor.js
 :copyright: CC-BY-SA 3.0
 :imagesdir: images
 
@@ -232,13 +321,14 @@ The `dc` namespace prefix is in reference to the http://dublincore.org/documents
 |uuid
 |Populates the *required* unique identifier (`<dc:identifier>`) in the package metadata.
 An id will be generated automatically from the doctitle if not specified.
-The recommended practice is to identify the document by means of a string or number conforming to a formal identification system. 
+The recommended practice is to identify the document by means of a string or number conforming to a formal identification system.
 
 |lang
 |Populates the content language / locale (`<dc:language>`) in the package metadata.
 
 |scripts
-|Controls the font subsets that are selected based on the specified scripts (e.g., alphabets). (values: *latin*, latin-ext, latin-cyrillic or multilingual)
+|Controls the font subsets that are selected based on the specified scripts (e.g., alphabets).
+(values: *latin*, latin-ext, latin-cyrillic or multilingual)
 
 |revdate
 |Populates the publication date (`<dc:date>`) in the package metadata.
@@ -253,16 +343,15 @@ 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 an avatar for the author that is displayed in the header of a chapter.
-The avatar image should be located at the path _$${imagesdir}/avatars/{username}.jpg$$_, where
-`{username}` is the value of this attribute.
+|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`.
+The avatar image should be located at the path _\{imagesdir}/avatars/\{username}.jpg_, where `\{username}` is the value of this attribute.
 
 |producer
 |Populates the publisher (`<dc:publisher>`) in the package metadata.
 
 |creator
 |Populates the creator (`<dc:creator>`) in the package metadata.
-If the creator is not specified, the value of the producer attribute is used.
+*If the creator is not specified, Asciidoctor is added as the creator with the role "mfr" (an abbreviation for manufacturer).*
 
 |description
 |Populates the description (`<dc:description>`) in the package metadata.
@@ -273,8 +362,8 @@ 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 e-book archive.
-May be specified as a path or inline image macro.
+The image is also added to the ebook 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.
 
 |copyright
@@ -294,12 +383,18 @@ _Only applies to a chapter document._
 |doctype
 |Effectively ignored.
 The master document is assumed to be a book and each chapter an article.
+
+|publication-type
+|Used to control the inclusion of special content in the generated HTML.
+If set to a value other than book, the byline information (author and avatar) is included below the chapter header.
+Suggested values include: book (default), anthology, magazine, journal, article.
 |===
 
-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`.
+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`.
 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:
 
+[source,asciidoc]
 ----
 \ifdef::ebook-format-kf8[Hello Kindle reader!]
 ----
@@ -320,7 +415,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 EPUB3 reader to view the result.
+Open that file with an EPUB reader (aka ereader) to view the result.
 
 Below are several screenshots of this sample book as it appears on an Android phone.
 
@@ -352,19 +447,20 @@ Next, let's validate the EPUB3 archive to ensure it built correctly.
  $ asciidoctor-epub3 -D output -a ebook-validate data/samples/sample-book.adoc
 
 .Validation success
-----
+[.output]
+....
 Epubcheck Version 3.0.1
 
 Validating against EPUB version 3.0
 No errors or warnings detected.
-----
+....
 
 If the EPUB3 archive contains any errors, they will be output in your terminal.
 
 .EPUB Standard & Validator
 ****
-The electronic publication (EPUB) standard is developed by the {idpf-uri}[International Digital Publishing Forum (IDPF)].
-{epub-uri}[EPUB 3.0], released in October 2011, is the latest version of this standard.
+The electronic publication (EPUB) standard is developed by the {uri-idpf}[International Digital Publishing Forum (IDPF)].
+{uri-epub}[EPUB 3.1], released in January 2017, is the latest version of this standard.
 
 An EPUB3 archive contains:
 
@@ -373,7 +469,7 @@ An EPUB3 archive contains:
 * one or more content documents
 * assets (images, fonts, stylesheets, etc.)
 
-The IDPF also supports {epubcheck-uri}[EpubCheck].
+The IDPF also supports {uri-epubcheck}[EpubCheck].
 EpubCheck parses and validates the file against the EPUB schema.
 ****
 
@@ -392,7 +488,7 @@ You just need to specify the format (`-a ebook-format`) as `kf8`.
  $ asciidoctor-epub3 -D output -a ebook-format=kf8 data/samples/sample-book.adoc
 
 When the script completes, you'll see the file [file]_sample-book.mobi_ as well as [file]_sample-book-kf8.epub_ (the precursor) appear in the [path]_output_ directory.
- 
+
 KindleGen does mandatory validation so you don't need to run the `validate` command after converting to KF8/MOBI.
 
 .What is KF8?
@@ -417,17 +513,20 @@ That's why we refer to the format in this project as KF8/MOBI.
   Extracts the EPUB3 to a folder in the destination directory after the file is generated
 
 *-a ebook-format=<format>* ::
-  Specifies the e-book format to generate (epub3 or kf8, default: epub3)
+  Specifies the ebook format to generate (epub3 or kf8, default: epub3)
 
 *-a ebook-validate* ::
   Runs Epubcheck 3.0.1 to validate output file against the EPUB3 specification
 
+*-a ebook-compress=<0|1|2|none|standard|huffdic>* ::
+  Controls the compression type used by kindlegen (0=none [default if unset], 1=standard [default if empty], 2=huffdic)
+
 *-v, --version* ::
   Display the program version
 
 === EPUB3 Archive Structure
 
-Here's a sample manifest of files found in an EPUB3 document produced by Asciidoctor EPUB3.
+Here's a sample manifest of files found in an EPUB3 document produced by {project-name}.
 
 ....
 META-INF/
@@ -467,10 +566,17 @@ mimetype
 
 == Working with Images
 
-Images that your AsciiDoc document references should be saved in the directory defined in the `imagesdir` attribute, which defaults to the directory of the document.
-{project-name} will discover all local image references and insert the images into the EPUB3 archive at the same relative path.
+Images referenced in your AsciiDoc document must be stored in the images catalog.
+The images catalog is defined by the `imagesdir` attribute.
+If set, the value of this attribute is resolved relative to the spine document and must be at or below (i.e., within) the directory of that document.
+(In other words, it cannot point to a location outside the document directory).
+If this attribute is not set, the images catalog defaults to the directory of the spine document.
+{project-name} will discover all local image references and insert those images into the EPUB3 archive at the same relative path.
+
+WARNING: {project-name} does not currently discover and package inline images.
+See issue {uri-issues}/30[#30].
 
-WARNING: Currently including images only works correctly if you set `imagesdir` to the directory `images` like in the example shown above. This will be fixed in future versions.
+=== Default Images
 
 The sample book contains placeholder images for an author avatar and a book cover.
 
@@ -478,34 +584,49 @@ The sample book contains placeholder images for an author avatar and a book cove
 
 === Changing the Cover Image
 
-E-book readers have different image resolution and file size limits regarding a book's cover.
+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 application you're targeting.
+To ensure your cover displays correctly, you'll want to review the documentation or publisher guidelines for the 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.
 
 Feel free to use the SVG of the sample cover in the [path]_data/images_ folder as a template for creating your own cover.
 Once your image is ready, you can replace the placeholder cover image by defining the `front-cover-image` attribute in the header of the master document.
 
+[source,asciidoc]
 ----
-:front-cover-image: image:cover.png[width=1050,height=1600]
+:front-cover-image: image:cover.png[Front Cover,1050,1600]
 ----
 
-The image is resolved relative to the directory specified in the `imagesdir` attribute, which defaults to the document directory.
-The image can be in any format, though we recommend using PNG or JPG as they are the most portable formats.
+The image is resolved relative to the directory specified in the `imagesdir` attribute, which defaults to the directory of the spine document.
+The image can be in any format, though we recommend using PNG, JPG, or SVG as they are the most portable formats.
 
-IMPORTANT: You should always specify the dimensions of the cover image.
+IMPORTANT: *You should always specify the dimensions of the cover image.*
 This ensures the viewer will preserve the aspect ratio if it needs to be scaled to fit the screen.
 If you don't specify a width and height, then the dimensions are assumed to be 1050x1600.
 
+=== How to Organize Images by Chapter
+
+You can set the `imagesdir` attribute per chapter (as long as the attribute is not overridden by the API).
+To do so, use an attribute entry to set the value of the `imagesdir` attribute on the line above the include directive for a chapter.
+
+[source,asciidoc]
+----
+:imagesdir: chapter-one/images
+\include::chapter-one.adoc[]
+
+:imagesdir: chapter-two/images
+\include::chapter-two.adoc[]
+----
+
 == About the Theme
 
 EPUB3 and KF8/MOBI files are styled using CSS3.
-However, each e-book reader honors a reduced set of CSS3 styles, and the styles they allow and how they implement them are rarely documented.
+However, each ereading 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 reader applications and to degrade gracefully in select EPUB2 readers. 
-The theme maintains readability regardless of the e-book reader's background mode (i.e., day, night or sepia) or the display device's pixel density and screen resolution.
+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.
+The theme maintains readability regardless of the reading mode (i.e., day, night or sepia) or the display device's pixel density and screen resolution.
 
 The theme's CSS files are located in the [path]_data/style_ directory.
 
@@ -520,66 +641,10 @@ The theme's fonts are located in the [path]_data/fonts_ directory.
 The M+ Outline fonts are used for titles, headings, literal (monospace) text, and annotation numbers.
 The body text uses Noto Serif.
 Admonition icons and the end-of-chapter mark are from the Font Awesome icon font.
-Refer to the {notice-uri}[NOTICE.adoc] file for further information about the fonts.
+Refer to the <<NOTICE#,NOTICE>> file for further information about the fonts.
 
 // TODO document command to generate the M+ 1p latin fonts
 
-=== Text Justification Hack
-
-Many of the EPUB3 readers use the http://webkit.org[WebKit browser engine] to render the content and apply the CSS formatting and styles.
-Generally speaking, WebKit is a great engine that brings a lot of consistency and power to the e-book reader landscape.
-It also brings along the same set of bugs present in browsers that are based on it.
-
-One particular bug in WebKit causes rich text to be justified incorrectly.
-Specifically, when the value of the `text-align` property is `justify`, WebKit drops the space between formatted text (bold, italic, hyperlink, etc) and non-formatted text, causing the words to be unevenly spaced across the line.
-You can see an example of this problem in the screenshot below.
-
-.WebKit justifying rich text incorrectly
-image::incorrect-text-justification.png[]
-
-It's not terrible, but just enough to disrupt a reader's flow.
-Here's how we expect the text to look:
-
-.WebKit justifying rich text correctly after the “word joiner hack” is applied
-image::correct-text-justification.png[]
-
-After some time in the tech lab and some dumb luck, we found a way to trick WebKit into justifying the text correctly!
-We call it the “word joiner hack”.
-
-Here's the HTML source of the first sentence from the screenshots:
-
-```xml
-<strong><a href="...">Fork</a> the repository</srtong> <span>and clone it locally.</span>
-```
-
-WebKit treats the space following an inline element as insignificant and thus fails to account for it when justifying the text.
-
-At first glance, you might think to add a normal space character before the closing tag of the inline element (e.g., `+<a href="...">Fork </a>+`).
-However, that would cause any underline beneath links to extend past the end of the word.
-
-At second glance, you might think to add a zero-width space character immediately following the element (e.g., `+<a href="...">Fork</a>&#x200b;+`).
-However, that's problematic if the next character is a period or other punctuation because it introduces a wrap opportunity where there shouldn't be one.
-
-Reflecting on the problem of the zero-width space brings us to either the http://www.fileformat.info/info/unicode/char/FEFF/index.htm[zero-width no-break space] character (e.g., `+<a href="...">Fork</a>&#xfeff+`) or the http://www.fileformat.info/info/unicode/char/2060/index.htm[word joiner] character (e.g., `+<a href="...">Fork</a>&#x2060;+`).
-Like the zero-width space, these characters occupy no space.
-However, instead of introducing a wrap opportunity, they prevent one.
-
-But here's the clincher.
-If the character following a zero-width non-break space or a word joiner is a normal space (e.g., `+<a href="...">Fork</a>&#xfeff; the+`), then it behaves just like a regular space.
-We've covered all the scenarios!
-Hey WebKit, you've been Unicode punked!
-
-*UPDATE:* The zero-width no-break space was deprecated in favor of the word joiner.
-However, as we've discovered, font support for the word joiner is abysmal, whereas the zero-width no-break space is supported everywhere we've checked.
-Therefore, we've decided to go with the zero-width no-break space to avoid nasty rectangle outlines from font bombing your content.
-
-_By adding the +++<del>word joiner</del>+++ zero-width no-break space character immediately after any inline element, we can trick WebKit into justifying the text properly, as shown in the second screenshot above._
-
-NOTE: You won't see `&#xfeff;` anywhere in the HTML source.
-That's because we use the actual Unicode character so that any regular expressions being applied to the text still work as expected.
-
-Although the fix may seem minor enhancement, it plays an important role in reaching one of the core objectives of this converter: to make the text in the EPUB3 as readable as possible.
-
 === 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.
@@ -632,12 +697,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 reader application of choice.
- 
+You'll have to manually import the EPUB3 into your ereader of choice.
+
 == E-book Reader Recommendations and Quirks
 
-EPUB3 readers will provide the best reading experience when viewing the book generated by {project-name}.
-Here's a list of some of the readers we know to have good EPUB3 support and the systems on which they run:
+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:
 
 * http://www.amazon.com/gp/feature.html?docId=1000493771[Amazon Kindle] (most platforms)
 * http://gitden.com/gitdenreader[Gitden] (Android and iOS)
@@ -647,25 +712,25 @@ Here's a list of some of the readers we know to have good EPUB3 support and the
 * 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)
 
-IMPORTANT: To get the full experience, ensure that the reader is configured to use the publisher's styles.
-Different readers word this setting in different ways.
+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.
 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 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 readers, 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 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.
 
-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 readers, despite the different CSS implementation rules and limitations unique to each e-book 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 ereaders, despite the different CSS implementation rules and limitations unique to each ebook application.
 Most of these obstacles were addressed using media queries or explicit classes.
-Some we haven't conquered. 
+Some we haven't conquered.
 Yet.
 
-The <<_kindle_quirks,Kindle quirks list>> shows you just a few of the constraints we encountered.
+The <<kindle-quirks,Kindle quirks list>> shows you just a few of the constraints we encountered.
 To see all of the workarounds and why we chose certain style options, check out the code and comments in the [file]_epub3.css_ and [file]_epub3-css-only.css_ files.
 
 // TODO add http://www.namo.com/site/namo/menu/5074.do[Namo PubTreeViewer] (iOS, Android & Windows) and http://www.kobo.com/apps[Kobo] (iOS, Android, OSX & Windows)
 
-[[_kindle_quirks]]
+[#kindle-quirks]
 .Kindle Quirks
 * overrules margins and line heights like a medieval tyrant
 * `font-family` can't be set on `<body>`
@@ -674,6 +739,7 @@ To see all of the workarounds and why we chose certain style options, check out
 * strips (or unwraps) `<header>` tags
 * `@page` isn't supported
 * `page-break: avoid` isn't supported
+* `page-break-*` cannot be applied using a compound or nested CSS selector; must be a simple ID or class
 * `max-width` isn't supported
 * `widows` are left in the cold
 * won't style footers without an explicit class
@@ -683,9 +749,16 @@ To see all of the workarounds and why we chose certain style options, check out
 
 === Send to Kindle
 
-The “Send to Kindle” feature, used for transferring a MOBI file to a Kindle device, is known to strip out all the font files.
-Therefore, if you use this feature, don't be surprised to see default fonts and missing font-based icons.
-We recommend that you transfer the file using other means, such as a USB cable or a sync service like Dropbox.
+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.
+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.
+
+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.
+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).
 
 ////
 head-stop (default '.')
@@ -702,7 +775,7 @@ subject-stop (default ':')
 
 .Computers
 |===
-|Device |OS |Resolution |ppi |Browsers |Readium |Gitden |Kindle 
+|Device |OS |Resolution |ppi |Browsers |Readium |Gitden |Kindle
 
 |Asus
 |Fedora 17
@@ -713,7 +786,7 @@ subject-stop (default ':')
 
 Asus, Fedora 20, display resolution, Chrome x, Readium
 Ideapad Y460  |Fedora 20 |1366 x 768 (16:9) |
-PC, Windows X, 
+PC, Windows X,
 |===
 
 .Tablets
@@ -724,8 +797,8 @@ Nexus,
 
 .Phones
 |===
-HTC Sensation, Android x, display resolution, xxxx 
-Nexus , 
+HTC Sensation, Android x, display resolution, xxxx
+Nexus ,
 |===
 
 ////
@@ -736,11 +809,11 @@ In the spirit of free software, _everyone_ is encouraged to help improve this pr
 
 To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
 
-Feel free to use the {project-issues-uri}[issue tracker] or http://discuss.asciidoctor.org[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
+Feel free to use the {uri-issues}[issue tracker] or {uri-discuss}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
 
 == Development
 
-To help develop Asciidoctor EPUB3, or to simply test drive the development version, you need to get the source from GitHub.
+To help develop {project-name}, or to simply test drive the development version, you need to get the source from GitHub.
 Follow the instructions below to learn how to clone the source and run it from your local copy.
 
 === Retrieve the Source Code
@@ -752,13 +825,15 @@ You can retrieve {project-name} in one of two ways:
 
 ==== Option 1: Fetch Using `git clone`
 
-If you want to clone the git repository, simply copy the {project-repo-uri}[GitHub repository URL] and pass it to the `git clone` command:
+If you want to clone the git repository, simply copy the {uri-repo}[GitHub repository URL] and pass it to the `git clone` command:
 
- $ git clone https://github.com/asciidoctor/asciidoctor-epub3
+[subs=attributes+]
+ $ git clone {uri-repo}
 
 Next, change to the project directory:
 
- $ cd asciidoctor-epub3
+[subs=attributes+]
+ $ cd {project-handle}
 
 ==== Option 2: Download the Archive
 
@@ -771,7 +846,7 @@ We'll leverage the project configuration to install the necessary dependencies.
 
 === Prepare RVM (optional step)
 
-If you're using {rvm-uri}[RVM], we recommend creating a new gemset to work with {project-name}:
+If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
 
  $ rvm use 2.2@asciidoctor-epub3-dev --create
 
@@ -788,7 +863,7 @@ To check if you have Bundler available, use the `bundle` command to query the ve
 
 If it's not installed, use the `gem` command to install it.
 
- $ gem install bundle
+ $ gem install bundler
 
 Then use the `bundle` command to install the project dependencies:
 
@@ -832,18 +907,19 @@ Jump back to <<Getting Started>> to learn how to create an AsciiDoc document and
 
 == Copyright
 
-Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2017 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-uri}[LICENSE.adoc] file.
-Refer to the {notice-uri}[NOTICE.adoc] file for information about third-party Open Source software in use.
+For the full text of the license, see the <<LICENSE#,LICENSE>> file.
+Refer to the <<NOTICE#,NOTICE>> file for information about third-party Open Source software in use.
 
 ////
 == Additional Points of Note
 
 * uppercase chapter titles to work around line-height limitation in Kindle (1.4 minimum)
+* using vw units crashes Aldiko
 * circled numbers from M+ 1mn for annotation numbers in listing blocks
 * avatars for authors
 * document command to generate the M+ 1p latin fonts
-* recommended readers (Readium, Gitden, Kindle, etc)
+* recommended ereaders (Readium, Gitden, Kindle, etc)
 ////