asciidoctor-epub3 1.0.0.alpha.1

data/Rakefile

@@ -0,0 +1,78 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path '../lib/asciidoctor-epub3/version', __FILE__
+
+require 'rake/clean'
+
+default_tasks = []
+
+begin
+  require 'bundler/gem_tasks'
+
+  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
+
+begin
+  require 'rdoc/task'
+  Rake::RDocTask.new do |t|
+    t.rdoc_dir = 'rdoc'
+    t.title = %(Asciidoctor EPUB3 #{Asciidoctor::Epub3::VERSION})
+    t.main = %(README.adoc)
+    t.rdoc_files.include 'README.adoc', 'LICENSE.adoc', 'NOTICE.adoc', 'lib/**/*.rb', 'bin/**/*'
+  end
+rescue LoadError
+end
+
+=begin NOT CURRENTLY IN USE
+begin
+  require 'rake/testtask'
+  Rake::TestTask.new do |t|
+    t.libs << 'test'
+    t.pattern = 'test/**/*_test.rb'
+    t.verbose = true
+    t.warning = true
+    if RUBY_VERSION >= '2'
+      t.options = '--tty=no'
+    end
+  end
+  default_tasks << :test
+rescue LoadError
+end
+
+begin
+  require 'cucumber'
+  require 'cucumber/rake/task'
+  CUKE_RESULTS_FILE = 'feature-results.html'
+  ARUBA_TMP_DIR = 'tmp'
+  CLEAN << CUKE_RESULTS_FILE if File.file? CUKE_RESULTS_FILE
+  CLEAN << ARUBA_TMP_DIR if File.directory? ARUBA_TMP_DIR
+  desc 'Run features'
+  Cucumber::Rake::Task.new :features do |t|
+    opts = %(features --format html -o #{CUKE_RESULTS_FILE} --format progress -x --tags ~@pending)
+    opts = %(#{opts} --tags #{ENV['TAGS']}) if ENV['TAGS']
+    t.cucumber_opts = opts
+    t.fork = false
+  end
+
+  desc 'Run features tagged as work-in-progress (@wip)'
+  Cucumber::Rake::Task.new 'features:wip'  do |t|
+    #t.cucumber_opts = %(features --format html -o #{CUKE_RESULTS_FILE} --format pretty -x -s --tags @wip)
+    t.cucumber_opts = %(features --format html -o #{CUKE_RESULTS_FILE} --format progress -x --tags @wip)
+    t.fork = false
+  end
+
+  default_tasks << :features
+  task :cucumber => :features
+  task 'cucumber:wip' => 'features:wip'
+  task :wip => 'features:wip'
+rescue LoadError
+end
+=end
+
+task :default => default_tasks unless default_tasks.empty?

data/bin/adb-push-ebook

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+ADB = ENV['ADB'] || 'adb'
+
+unless ::File.executable? ADB
+  warn %(adb-push-ebook: `adb` not found.\nPlease set the ADB environment variable or add `adb` to your PATH.)
+  exit 1
+end
+
+require 'open3'
+require 'shellwords'
+
+docname = ARGV[0] || '_output/sample-book'
+
+targets = {
+  'epub' => '/sdcard/',
+  'mobi' => '/sdcard/Android/data/com.amazon.kindle/files/'
+}
+
+targets.each {|(ext, target)|
+  file = %(#{docname}.#{ext})
+  Open3.popen2e(Shellwords.join [ADB, 'push', file, target]) {|input, output, wait_thr|
+    output.each {|line| puts line }
+  } if File.file? file
+}

data/bin/asciidoctor-epub3

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require File.join File.dirname(__FILE__), '../lib/asciidoctor-epub3'
+require 'asciidoctor/cli'
+
+options = Asciidoctor::Cli::Options.new backend: 'epub3'
+# FIXME This is a really bizarre API. Please make me simpler.
+if (options.parse! ARGV) == 0
+  exit 0
+else
+  invoker = Asciidoctor::Cli::Invoker.new options
+  GC.start
+  invoker.invoke!
+  exit invoker.code
+end

data/data/images/default-avatar.svg

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="125"
+   height="125"
+   id="svg3896"
+   version="1.1"
+   inkscape:version="0.48.4 r9939"
+   sodipodi:docname="default-avatar.svg">
+  <defs
+     id="defs3898" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.4385429"
+     inkscape:cx="57.476305"
+     inkscape:cy="126.28564"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="2560"
+     inkscape:window-height="1337"
+     inkscape:window-x="0"
+     inkscape:window-y="49"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata3901">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-927.36218)">
+    <text
+       xml:space="preserve"
+       style="font-size:144px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#242422;fill-opacity:1;stroke:none;font-family:FontAwesome;-inkscape-font-specification:FontAwesome"
+       x="5.9285712"
+       y="1041.2908"
+       id="text3904"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3906"
+         x="5.9285712"
+         y="1041.2908"></tspan></text>
+  </g>
+</svg>

data/data/images/default-cover.svg

@@ -0,0 +1,53 @@
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" viewBox="0 0 1050 1600">
+ <defs>
+  <filter id="filter3874" color-interpolation-filters="sRGB">
+   <feGaussianBlur stdDeviation="0.01 5" in="SourceGraphic"/>
+  </filter>
+  <filter id="filter4056" color-interpolation-filters="sRGB">
+   <feGaussianBlur in="SourceGraphic" stdDeviation="3" result="result6"/>
+   <feColorMatrix in="SourceGraphic" values="1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 " result="result7"/>
+   <feComposite operator="in" result="fbSourceGraphic" in2="result7" in="result6"/>
+   <feColorMatrix values="0 0 0 -1 0 0 0 0 -1 0 0 0 0 -1 0 0 0 0 1 0" result="fbSourceGraphicAlpha" in="fbSourceGraphic"/>
+   <feGaussianBlur in="fbSourceGraphic" stdDeviation="3" result="result6"/>
+   <feColorMatrix in="fbSourceGraphic" values="1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 " result="result7"/>
+   <feComposite operator="in" in2="result7" in="result6"/>
+  </filter>
+  <filter id="filter4098" color-interpolation-filters="sRGB">
+   <feGaussianBlur in="SourceGraphic" stdDeviation="3" result="result6"/>
+   <feColorMatrix in="SourceGraphic" values="1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 " result="result7"/>
+   <feComposite operator="in" result="fbSourceGraphic" in2="result7" in="result6"/>
+   <feColorMatrix values="0 0 0 -1 0 0 0 0 -1 0 0 0 0 -1 0 0 0 0 1 0" result="fbSourceGraphicAlpha" in="fbSourceGraphic"/>
+   <feGaussianBlur in="fbSourceGraphic" stdDeviation="3" result="result6"/>
+   <feColorMatrix in="fbSourceGraphic" values="1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 " result="result7"/>
+   <feComposite operator="in" in2="result7" in="result6"/>
+  </filter>
+ </defs>
+ <metadata>
+  <rdf:RDF>
+   <cc:Work rdf:about="">
+    <dc:format>image/svg+xml</dc:format>
+    <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+    <dc:title/>
+   </cc:Work>
+  </rdf:RDF>
+ </metadata>
+ <rect style="enable-background:accumulate;fill-rule:nonzero;color:#000000;fill:#333332;" height="1600" width="1050" y="0" x="0"/>
+ <rect style="enable-background:accumulate;fill-rule:nonzero;color:#000000;fill:#264e2e;" height="20" width="1050" y="468" x="0"/>
+ <path style="filter:url(#filter4056);fill:#264e2e;" d="m525,349.3-495,25c127.6,50,67.95,230,40,240l455-10,455,10c-27.95-10-87.65-190,40-240l-495-25z"/>
+ <path style="filter:url(#filter4098);fill:#57ad68;" d="m525,379.3-460,5c93.17,34.67,55,190,40,205h420,420c-15-15-53.17-170.3,40-205l-460-5z"/>
+ <path style="fill:#333332;" d="m95,394.3c55.42,25.11,45.36,131.3,35,165l395,15,395-15c-10.36-33.66-20.42-139.9,35-165l-430,5-430-5z"/>
+ <rect style="enable-background:accumulate;fill-rule:nonzero;color:#000000;filter:url(#filter3874);fill:#264e2e;" height="169.5" width="1050" y="1435" x="0"/>
+ <rect style="enable-background:accumulate;fill-rule:nonzero;color:#000000;fill:#57ad68;" height="6" width="1050" y="1453" x="0"/>
+ <g transform="translate(1.2573242e-5,-10)">
+  <text style="font-size:86px;stroke-width:3;writing-mode:lr-tb;fill:#b3b3b1;letter-spacing:-4px;text-anchor:start;line-height:100%;word-spacing:0px;stroke:#b3b3b1;font-stretch:normal;stroke-miterlimit:4;font-family:&apos;M+ 1p&apos;;font-variant:normal;stroke-dasharray:none;font-weight:bold;font-style:normal;text-align:start;" y="529.82001" x="162.99142" xml:space="preserve"><tspan y="529.82001" x="162.99142">Asciidoctor</tspan></text>
+  <text style="font-size:86px;stroke-width:3;writing-mode:lr-tb;fill:#b3b3b1;letter-spacing:-4px;text-anchor:start;line-height:100%;word-spacing:0px;stroke:#b3b3b1;font-stretch:normal;stroke-miterlimit:4;font-family:&apos;M+ 1p&apos;;font-variant:normal;stroke-dasharray:none;font-weight:bold;font-style:normal;text-align:start;" xml:space="preserve" y="529.82001" x="632.99139"><tspan x="632.99139" y="529.82001">EPUB3</tspan></text>
+ </g>
+ <g transform="translate(1.2573242e-5,-10)">
+  <text style="font-size:86px;font-family:&apos;M+ 1p&apos;;writing-mode:lr-tb;fill:#ffffff;letter-spacing:-4px;text-anchor:start;line-height:100%;word-spacing:0px;font-stretch:normal;font-variant:normal;font-weight:bold;font-style:normal;text-align:start;" xml:space="preserve" y="529.82001" x="162.99142"><tspan x="162.99142" y="529.82001">Asciidoctor</tspan></text>
+  <text style="font-size:86px;font-family:&apos;M+ 1p&apos;;writing-mode:lr-tb;fill:#ffffff;letter-spacing:-4px;text-anchor:start;line-height:100%;word-spacing:0px;font-stretch:normal;font-variant:normal;font-weight:bold;font-style:normal;text-align:start;" y="529.82001" x="632.99139" xml:space="preserve"><tspan y="529.82001" x="632.99139">EPUB3</tspan></text>
+ </g>
+ <g transform="translate(0,547.6378)">
+  <path style="stroke-linejoin:miter;stroke:#122616;stroke-linecap:square;stroke-miterlimit:4;stroke-dasharray:none;stroke-width:32;fill:none;" d="m11.87,3098,1021,0"/>
+ </g>
+</svg>

data/data/samples/asciidoctor-epub3-readme.adoc

@@ -0,0 +1,744 @@
+= Asciidoctor EPUB3: 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
+ifdef::env-github[]
+:base-uri: link:
+endif::[]
+ifndef::env-github[]
+:base-uri: {project-repo-uri}/blob/master/
+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.
+
+== 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_*.
+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.
+image::screenshots/text.png[]
+endif::[]
+
+=== Project Mission
+
+The {project-name} project aims to produce EPUB3 documents that meet the following objectives:
+
+[itemized,subject-stop=.]
+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:
+  - 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::
+  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.
+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.
+Of course, there's always room for improvement, so we'll continue to work with you to achieve and maintain this goal.
+
+=== Notable Features
+
+* Direct AsciiDoc to EPUB3 conversion
+* Direct AsciiDoc to KF8/MOBI conversion
+* Highly-aesthetic and readable styles with optimized text legibility
+* EPUB3 metadata, manifest and spine (assembled by Gepub)
+* Document metadata (title, authors, subject, keywords, etc.)
+* 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 reader)
+* Orphan section titles avoided (so much as it's supported by the reader)
+* Table border settings honored
+* Support for SVG images in the content
+
+=== Project Status
+
+CAUTION: {project-name} is currently _alpha_ software.
+Use accordingly.
+Although the bulk of AsciiDoc content is rendered, there's still work needed to fill in gaps where rendering is incomplete or unstyled.
+Once it's battle tested, the project will be moved into the Asciidoctor organization on GitHub.
+
+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.
+
+=== Planned Features and Work In Progress
+
+See {worklog-uri}[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} can then produce a KF8/MOBI, the file 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].
+
+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.
+
+=== 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.
+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.
+
+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.
+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).
+
+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.
+
+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.
+
+== Prerequisites
+
+All that's needed to use {project-name} is Ruby 1.9.3 or better and a few RubyGems, which we'll explain how to install in the next section.
+
+To check if you have Ruby available, use the `ruby` command to query the version installed:
+
+ $ ruby --version
+
+If you're using {rvm-uri}[RVM], we recommend creating a new gemset to work with {project-name}:
+
+ $ rvm use @asciidoctor-epub3 --create
+
+We like RVM because it keeps the dependencies required by various projects isolated ;)
+
+== Getting Started
+
+{project-name} isn't yet published as a RubyGem itself, so you'll need to get the source code.
+
+=== Retrieve the project
+
+You can retrieve {project-name} in one of two ways:
+
+. Clone the git repository
+. Download a zip archive of the repository
+
+==== 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:
+
+ $ git clone https://github.com/asciidoctor/asciidoctor-epub3
+
+Next, change to the project directory:
+
+ $ cd asciidoctor-epub3
+
+==== Option 2: Download the Archive
+
+If you want to download a zip archive, click on the btn:[icon:cloud-download[\] Download Zip] button on the right-hand side of the repository page on GitHub.
+Once the download finishes, extract the archive, open a console and change to that directory.
+
+We'll now leverage the project configuration to install the necessary dependencies.
+
+=== Install the Dependencies
+
+The dependencies needed to use {project-name} are defined in the [file]_Gemfile_ at the root of the project.
+We can use Bundler to install the dependencies for us.
+
+To check if you have Bundler available, use the `bundle` command to query the version installed:
+
+ $ bundle --version
+
+If it's not installed, use the `gem` command to install it.
+
+ $ gem install bundle
+
+Then use the `bundle` command to install the project dependencies:
+
+ $ bundle install
+
+=== Build and Install the Gem
+
+Now that the dependencies are installed, you can build and install the Gem.
+
+Use the Rake build tool to build the Gem:
+
+ $ rake build
+
+The build will report that it built the Gem into the [path]_pkg_ directory.
+
+Finally, install the Gem.
+
+ $ gem install pkg/asciidoctor-epub3-1.0.0.dev.gem
+
+You're now ready to use {project-name}!
+Let's get an AsciiDoc document ready to convert to EPUB3.
+
+=== Prepare an AsciiDoc Document
+
+If you don't already have an AsciiDoc document, you can use the [file]_sample-book.adoc_ file and its chapters found in the [path]_data/samples_ directory of this project.
+
+.Master file named sample-book.adoc
+```asciidoc
+= Asciidoctor EPUB3: Sample Book
+Author Name
+v1.0, 2014-04-15
+:doctype: book
+:producer: Asciidoctor
+:keywords: Asciidoctor, samples, e-book, EPUB3, KF8, MOBI, Asciidoctor.js
+:copyright: CC-BY-SA 3.0
+:imagesdir: images
+
+\include::asciidoctor-epub3-readme.adoc[]
+
+\include::sample-content.adoc[]
+
+\include::asciidoctor-js-introduction.adoc[]
+
+\include::asciidoctor-js-extension.adoc[]
+```
+
+=== EPUB-related AsciiDoc Attributes
+
+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].
+
+.AsciiDoc attributes that control the EPUB3 metadata (i.e., package.opf)
+[cols="1m,3"]
+|===
+|Name |Description
+
+|id
+|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. 
+
+|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)
+
+|revdate
+|Populates the publication date (`<dc:date>`) in the package metadata.
+The date should be specified in a parsable format, such as `2014-01-01`.
+
+|doctitle
+|Populates the title (`<dc:title>`) in the package metadata.
+The title is added to the metadata in plain text format.
+
+|author
+|Populates the contributors (`<dc:contributor>`) in the package metadata.
+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}.png$$_, 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.
+
+|description
+|Populates the description (`<dc:description>`) in the package metadata.
+
+|keywords
+|Populates the subjects (i.e., `<dc:subject>`) in the package metadata.
+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.
+Using the inline image macro is preferred as it allows the height and width to be specified.
+
+|copyright
+|Populates the rights statement (`<dc:rights>`) in the package metadata.
+
+|source
+|Populates the source reference (`<dc:source>`) in the package metadata.
+The recommended practice is to identify the referenced resource by means of a string or number conforming to a formal identification system.
+
+|epub-properties
+|An optional override of the properties attribute for this document's item in the manifest.
+_Only applies to a chapter document._
+
+|doctype
+|Effectively ignored.
+The master document is assumed to be a book and each chapter an 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`.
+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:
+
+----
+\ifdef::ebook-format-kf8[Hello Kindle reader!]
+----
+
+With that out of the way, it's time to convert the AsciiDoc document directly to EPUB3.
+
+== Performing the Conversion
+
+You can convert AsciiDoc documents to EPUB3 and KF8/MOBI from the commandline using the `asciidoctor-epub3` script provided with the {project-name} project.
+
+=== Convert AsciiDoc to EPUB3
+
+Converting an AsciiDoc document to EPUB3 is as simple as passing your document to the `asciidoctor-epub3` command.
+This command should be available on your PATH if you installed the `asciidoctor-epub3` gem.
+Otherwise, you can find the command in the [path]_bin_ folder of the project.
+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.
+
+Below are several screenshots of this sample book as it appears on an Android phone.
+
+.An example of a chapter title and abstract shown side-by-side in Day and Night mode
+image::screenshots/chapter-title.png[]
+
+.An example of a section title followed by paragraph text separated by a literal block
+image::screenshots/section-title-paragraph.png[]
+
+.An example of a figure and an admonition
+image::screenshots/figure-admonition.png[]
+
+.An example of a sidebar
+image::screenshots/sidebar.png[]
+
+.An example of a table
+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].
+
+=== Validate the EPUB3 Archive
+
+Next, let's validate the EPUB3 archive to ensure it built correctly.
+
+.EPUB3 with validation
+ $ asciidoctor-epub3 -D output -a ebook-validate data/samples/sample-book.adoc
+
+.Validation success
+----
+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.
+
+An EPUB3 archive contains:
+
+* a package document (metadata, file manifest, spine)
+* a navigation document (table of contents)
+* one or more content documents
+* assets (images, fonts, stylesheets, etc.)
+
+The IDPF also supports {epubcheck-uri}[EpubCheck].
+EpubCheck parses and validates the file against the EPUB schema.
+****
+
+If you want to browse the contents of the EPUB3 file that is generated, or preview the XHTML files in a regular web browser, add the `-a ebook-extract` flag to the `asciidoctor-epub3` command.
+The EPUB3 file will be extracted to a directory adjacent to the generated file, but without the file extension.
+
+ $ asciidoctor-epub3 -D output -a ebook-extract data/samples/sample-book.adoc
+
+In this example, the contents of the EPUB3 will be extracted to the [path]_output/sample-book_ directory.
+
+=== Convert AsciiDoc to KF8/MOBI
+
+Creating a KF8/MOBI archive directly from an AsciiDoc document is done with the same generation script (`asciidoctor-epub3`).
+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_ 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?
+****
+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].
+
+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.
+****
+
+=== Command Arguments
+
+*-h, --help* ::
+  Show the usage message
+
+*-D, --destination-dir* ::
+  Writes files to specified directory (defaults to the current directory)
+
+*-a ebook-extract* ::
+  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)
+
+*-a ebook-validate* ::
+  Runs Epubcheck 3.0.1 to validate output file against the EPUB3 specification
+
+*-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.
+
+....
+META-INF/
+  container.xml
+OEBPS/
+  fonts/
+    font-awesome.ttf
+    font-icons.ttf
+    mplus-1mn-latin-bold.ttf
+    mplus-1mn-latin-light.ttf
+    mplus-1mn-latin-medium.ttf
+    mplus-1mn-latin-regular.ttf
+    mplus-1p-latin-bold.ttf
+    mplus-1p-latin-light.ttf
+    mplus-1p-latin-regular.ttf
+    noto-serif-bold-italic.ttf
+    noto-serif-bold.ttf
+    noto-serif-italic.ttf
+    noto-serif-regular.ttf
+  images/
+    avatars/
+      default.png
+    figure-01.png
+    figure-02.png
+  styles/
+    epub3-css3-only.css
+    epub3.css
+  chapter-01.xhtml
+  chapter-02.xhtml
+  ...
+  cover.xhtml
+  nav.xhtml
+  package.opf
+  toc.ncx
+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.
+
+The sample book contains placeholder images for an author avatar and a book cover.
+
+// TODO explain the avatar and book cover images
+
+=== Changing the Cover Image
+
+E-book readers 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.
+
+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.
+
+----
+:front-cover-image: image:cover.png[width=1050,height=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.
+
+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.
+
+== 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.
+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's CSS files are located in the [path]_data/style_ directory.
+
+IMPORTANT: {project-name} only provides one theme, and, at this time, you can not replace it with a custom theme using the `stylesheet` attribute.
+
+=== Fonts
+
+{project-name} embeds a set of fonts and font icons.
+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.
+
+// TODO document command to generate the M+ 1p latin fonts
+
+=== The 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.
+
+One of the bugs in WebKit causes rich text to be justified incorrectly.
+In particular, 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</stong> <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 absymal, 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.
+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.
+
+,===
+Reader,body class name
+
+Gitden,gitden-reader
+Namo PubTreeViewer,namo-epub-library
+Readium,epub-js-viewer
+iBooks,ibooks
+Google Books,gb-reader-container (div)
+,===
+
+== Pushing to Android
+
+While it's certainly possible to view the EPUB3 on your desktop/laptop, you'll probably want to test it where it's most likely going to be read--on a reading device such as a smartphone or a tablet.
+Assuming you have an Android device available, transferring the EPUB3 to the device is easy once you get a bit of setup out of the way.
+
+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
+. 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
+
+ $ export ADB=~/apps/android-sdk/platform-tools/adb
+
+Now you can use the `adb-push-ebook` script provided by {project-name} to push the EPUB3 and KF8/MOBI files to your Android device.
+
+.Publish both EPUB3 and KF8 files to Android device
+ $ adb-push-ebook output/sample-book
+
+IMPORTANT: Don't include the file extension since the script will check for both the .epub and .mobi files.
+
+The `adb-push-ebook` script copies the files to the following locations on the device:
+
+,===
+File type,Destination on Android device
+
+*.epub,/sdcard/
+*.mobi,/sdcard/Android/data/com.amazon.kindle/files/
+,===
+
+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.
+ 
+== 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:
+
+* http://www.amazon.com/gp/feature.html?docId=1000493771[Amazon Kindle] (most platforms)
+* http://gitden.com/gitdenreader[Gitden] (Android and iOS)
+* http://www.apple.com/ibooks[iBooks] (iOS, OSX)
+* 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)
+
+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.
+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.
+
+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.
+Most of these obstacles were addressed using media queries or explicit classes.
+Some we haven't conquered. 
+Yet.
+
+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
+* overrules margins and line heights like a medieval tyrant
+* `font-family` can't be set on `<body>`
+* requires `!important` on text-decoration
+* `position: relative` isn't permitted
+* strips (or unwraps) `<header>` tags
+* `@page` isn't supported
+* `page-break: avoid` isn't supported
+* `max-width` isn't supported
+* `widows` are left in the cold
+* won't style footers without an explicit class
+
+////
+head-stop (default '.')
+stack-head role (run-in is default)
+signature role (sets hardbreaks option)
+
+subject-stop (default ':')
+////
+
+////
+== Device and Application Testing
+
+{project-name} has been tested on the following devices and applications.
+
+.Computers
+|===
+|Device |OS |Resolution |ppi |Browsers |Readium |Gitden |Kindle 
+
+|Asus
+|Fedora 17
+|no x no
+|
+|Chrome x
+|Readium
+
+Asus, Fedora 20, display resolution, Chrome x, Readium
+Ideapad Y460  |Fedora 20 |1366 x 768 (16:9) |
+PC, Windows X, 
+|===
+
+.Tablets
+|===
+Asus Transformer, Android x, display resolution, Aldiko, Kindle, Readium, Readmill
+Nexus,
+|===
+
+.Phones
+|===
+HTC Sensation, Android x, display resolution, xxxx 
+Nexus , 
+|===
+
+////
+
+== Contributing
+
+In the spirit of free software, _everyone_ is encouraged to help improve this project.
+
+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.
+
+== Authors
+
+{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise on behalf of the Asciidoctor Project.
+
+== Copyright
+
+Copyright (C) 2014 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.
+
+////
+== Additional Points of Note
+
+* uppercase chapter titles to work around line-height limitation in Kindle (1.4 minimum)
+* 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)
+////