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

data/lib/asciidoctor-epub3/spine_item_processor.rb

@@ -8,35 +8,39 @@ class SpineItemProcessor < Extensions::IncludeProcessor
   # NOTE only fires for includes in spine document if registered directly on the instance of the spine document
   def process doc, reader, target, attributes
     spine_doc = doc
-    unless ::File.exist?(include_file = (spine_doc.normalize_system_path target, reader.dir, nil, target_name: 'include file'))
+    # TODO allow URI value
+    unless ::File.file?(include_file = (spine_doc.normalize_system_path target, reader.dir, nil, target_name: 'include file'))
       warn %(asciidoctor: WARNING: #{reader.line_info}: include file not found: #{include_file})
       return
     end
-    inherited_attributes = spine_doc.attributes.dup
-    %w(spine doctitle docfile docdir docname).each {|key| inherited_attributes.delete key }
+    inherited_attrs = spine_doc.attributes.dup
+    # QUESTION should we keep backend-epub3 for convenience?
+    %w(backend-epub3 backend-epub3-doctype-book docdir docfile docname doctitle outfilesuffix spine).each {|key| inherited_attrs.delete key }
 
     # parse header to get author information
     spine_item_doc_meta = ::Asciidoctor.load_file include_file,
         safe: spine_doc.safe,
         backend: 'epub3-xhtml5',
         doctype: :article,
-        parse_header_only: true 
+        parse_header_only: true
 
     # blank out author information if present in sub-document
     # FIXME this is a huge hack...we need a cleaner way to do this; perhaps an API method that retrieves all the author attribute names
     if spine_item_doc_meta.attr? 'author'
-      %w(author firstname lastname email authorinitials authors authorcount).each {|key| inherited_attributes.delete key }
+      %w(author firstname lastname email authorinitials authors authorcount).each {|key| inherited_attrs.delete key }
       idx = 1
-      while inherited_attributes.key? %(author_#{idx})
-        %W(author_#{idx} firstname_#{idx} lastname_#{idx} email_#{idx} authorinitials_#{idx}).each {|key| inherited_attributes.delete key }
+      while inherited_attrs.key? %(author_#{idx})
+        %W(author_#{idx} firstname_#{idx} lastname_#{idx} email_#{idx} authorinitials_#{idx}).each {|key| inherited_attrs.delete key }
         idx += 1
       end
     end
 
     # REVIEW reaching into converter to resolve document id feels like a hack; should happen in Asciidoctor parser
     # also, strange that "id" doesn't work here
-    inherited_attributes['css-signature'] = DocumentIdGenerator.generate_id spine_item_doc_meta
-    inherited_attributes['docreldir'] = ::File.dirname target
+    idprefix = (spine_doc.attr 'idprefix') || (spine_item_doc_meta.attr 'idprefix')
+    idseparator = (spine_doc.attr 'idseparator') || (spine_item_doc_meta.attr 'idseparator')
+    inherited_attrs['css-signature'] = DocumentIdGenerator.generate_id spine_item_doc_meta, idprefix, idseparator
+    inherited_attrs['docreldir'] = ::File.dirname target
 
     # NOTE can't assign spine document as parent since there's too many assumptions in the Asciidoctor processor
     spine_item_doc = ::Asciidoctor.load_file include_file,
@@ -47,15 +51,22 @@ class SpineItemProcessor < Extensions::IncludeProcessor
         backend: 'epub3-xhtml5',
         doctype: :article,
         header_footer: true,
-        attributes: inherited_attributes
+        attributes: inherited_attrs
 
     # restore attributes to those defined in the document header
     spine_item_doc.restore_attributes
 
-    (spine_doc.references[:spine_items] ||= []) << spine_item_doc
+    # FIXME core should register document ID if specified
+    unless (refs = spine_item_doc.references)[:ids].include? spine_item_doc.id
+      spine_item_doc.register :ids, [spine_item_doc.id, (spine_item_doc.attr 'docreftext') || spine_item_doc.doctitle]
+    end
+
+    refs[:spine] = spine_doc
+    refs[:spine_items] = ((spine_doc.references[:spine_items] ||= []) << spine_item_doc)
     # NOTE if there are attribute assignments between the include directives,
     # then this ordered list is not continguous, so bailing on the idea
     #reader.replace_line %(. link:#{::File.basename(spine_item_doc.attr 'outfile')}[#{spine_item_doc.doctitle}])
+    nil
   end
 
   # handles? should get the attributes on include directive as the second argument

data/lib/asciidoctor-epub3/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-epub3
 version: !ruby/object:Gem::Version
-  version: 1.5.0.alpha.6
+  version: 1.5.0.alpha.7
 platform: ruby
 authors:
 - Dan Allen
@@ -9,22 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-05 00:00:00.000000000 Z
+date: 2017-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: asciidoctor
   requirement: !ruby/object:Gem::Requirement
@@ -59,30 +59,36 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.5
-description: |
-  An extension for Asciidoctor that converts AsciiDoc documents to EPUB3 and KF8/MOBI (Kindle) e-book archives.
-email: dan@opendevise.io
+        version: 0.3.6
+description: 'An extension for Asciidoctor that converts AsciiDoc documents to EPUB3
+  and KF8/MOBI (Kindle) e-book archives.
+
+'
+email: dan@opendevise.com
 executables:
 - asciidoctor-epub3
 - adb-push-ebook
 extensions: []
 extra_rdoc_files:
-- README.adoc
+- CHANGELOG.adoc
 - LICENSE.adoc
 - NOTICE.adoc
+- README.adoc
 files:
+- CHANGELOG.adoc
+- Gemfile
 - LICENSE.adoc
 - NOTICE.adoc
 - README.adoc
 - Rakefile
+- asciidoctor-epub3.gemspec
 - bin/adb-push-ebook
 - bin/asciidoctor-epub3
 - data/fonts/assorted-icons.ttf
@@ -127,25 +133,6 @@ files:
 - data/images/default-cover.svg
 - data/images/default-headshot.jpg
 - data/images/default-headshot.png
-- data/samples/asciidoctor-epub3-readme.adoc
-- data/samples/asciidoctor-js-browser-extension.adoc
-- data/samples/asciidoctor-js-introduction.adoc
-- data/samples/i18n.adoc
-- data/samples/images/asciidoctor-js-chrome-extension.png
-- data/samples/images/avatars/graphitefriction.jpg
-- data/samples/images/avatars/mogztter.jpg
-- data/samples/images/avatars/mojavelinux.jpg
-- data/samples/images/correct-text-justification.png
-- data/samples/images/incorrect-text-justification.png
-- data/samples/images/screenshots/chapter-title-day.png
-- data/samples/images/screenshots/chapter-title.png
-- data/samples/images/screenshots/figure-admonition.png
-- data/samples/images/screenshots/section-title-paragraph.png
-- data/samples/images/screenshots/sidebar.png
-- data/samples/images/screenshots/table.png
-- data/samples/images/screenshots/text.png
-- data/samples/sample-book.adoc
-- data/samples/sample-content.adoc
 - data/styles/color-palette.css
 - data/styles/epub3-css3-only.css
 - data/styles/epub3-fonts.css
@@ -157,21 +144,23 @@ files:
 - lib/asciidoctor-epub3/packager.rb
 - lib/asciidoctor-epub3/spine_item_processor.rb
 - lib/asciidoctor-epub3/version.rb
-- scripts/generate-font-subsets.pe
 homepage: https://github.com/asciidoctor/asciidoctor-epub3
 licenses:
 - MIT
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --charset=UTF-8 --title="Asciidoctor EPUB3" --main=README.adoc -ri
+- "--charset=UTF-8"
+- --title="Asciidoctor EPUB3"
+- "--main=README.adoc"
+- "-ri"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '1.9'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
@@ -179,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Converts AsciiDoc documents to EPUB3 and KF8/MOBI (Kindle) e-book formats

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

@@ -1,849 +0,0 @@
-= 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
-* Respects font settings (if supported by the reader) without altering headings, code or icons
-* EPUB3 metadata, manifest and spine (assembled by Gepub)
-* Document metadata (title, authors, subject, keywords, etc.)
-* Internal cross reference links (not yet between chapters)
-* 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 converted, there's still work needed to fill in gaps where conversion is incomplete or unstyled.
-
-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} 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].
-
-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.
-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.
-
-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).
-
-Here's an example showing the structure of a spine document:
-
-----
-= Book Title
-Author Name
-:doctype: book
-:imagesdir: images
-//...and so on
-\ifndef::ebook-format[:leveloffset: 1]
-
-\include::chapter-one.adoc[]
-
-\include::chapter-two.adoc[]
-
-\include::chapter-three.adoc[]
-----
-
-Here's an example showing the structure of a chapter document:
-
-----
-[[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.
-
-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]).
-
-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 above; 2.2.x recommended) and a few Ruby gems, 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 installed version:
-
- $ ruby --version
-
-== Getting Started
-
-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
- 
-If you want to syntax highlight source listings, you'll also want to install CodeRay or Pygments.
-Choose one (or more) of the following:
-
-.CodeRay
- $ gem install coderay
-
-.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 
-----
-
-NOTE: At the moment, Pygments is automatically used if it's available.
-
-Assuming all the required gems install properly, verify you can run the `asciidoctor-epub3` script:
-
- $ asciidoctor-epub3 -v
-
-If you see the version of {project-name} printed, you're 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
-
-|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. 
-
-|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}.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.
-
-|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._
-
-|epub3-stylesdir
-|The path to a directory that contains alternate epub3.css and epub3-css3-only.css files to customize the look and feel.
-
-|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_ 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?
-****
-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.
-
-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.
-
-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.
-However, you can use your own [path]_epub3.css_ and [path]_epub3-css3-only.css_ files by specifying the directory where they are located using the `epub3-stylesdir` 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
-
-=== 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.
-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,HTML Element,CSS Class Name
-
-Gitden,body,gitden-reader
-Namo PubTreeViewer,body,namo-epub-library
-Readium,body,readium-js-viewer
-iBooks,body,ibooks
-Adobe RMSDK >= 11,body,rmsdk
-Google Books,div,gb-reader-container
-,===
-
-NOTE: Kobo does not support the epubReadingSystem JavaScript object, despite the fact that it does support JavaScript.
-
-== 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
-* `-webkit-hyphens: auto` causes Kindle for Mac (and perhaps others) to crash
-* `text-rendering: optimizeLegibility` causes file to be rejected by KFP (and causes the text to disappear in some previewers)
-* Kindle Direct Publishing (KDP) strips out select font-related CSS rules (e.g., `font-family`) under certain conditions (for reasons that have proved nearly impossible to reverse engineer); the known workaround is to add a layer of indirection by using `@import` to hide the CSS files from the script
-
-=== 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.
-
-////
-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.
-
-== Development
-
-To help develop Asciidoctor EPUB3, 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
-
-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.
-
-TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your `PATH` environment variable.
-
-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}:
-
- $ rvm use 2.2@asciidoctor-epub3-dev --create
-
-We like RVM because it keeps the dependencies required by various projects isolated.
-
-=== 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
-
-NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.
-
-=== 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 and install the gem (into the current RVM gemset or into the system if not using RVM):
-
- $ rake install:local
-
-The build will report that it built the gem into the [path]_pkg_ directory and that it installed the gem.
-
-Once the development version of the gem is installed, you can run {project-name} by invoking the `asciidoctor-epub3` script:
-
- $ asciidoctor-epub3 -v
-
-If you see the version of {project-name} printed to your console, you're ready to use {project-name}!
-
-=== Shortcut: Run the Launch Script Directly
-
-Assuming all the required gems install properly, you can run the `asciidoctor-epub3` script directly out of the project folder using either:
-
- $ bin/asciidoctor-epub3 -v
-
-or
-
- $ bundle exec bin/asciidoctor-epub3 -v
-
-You're now ready to test drive the development version of {project-name}!
-
-Jump back to <<Getting Started>> to learn how to create an AsciiDoc document and convert it to EPUB3.
-
-== 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-2016 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)
-////