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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53cfac0ce0da69c5ac8b1b2a207ab0ff89cfd187
-  data.tar.gz: 069bcd8227164ddc01bc2cd161b65ae7b3fe0c2e
+  metadata.gz: e374c40b52ce88330f2a960fd7430768ca178120
+  data.tar.gz: 732c8b6ae36689da969cab15eebd75536b6f6124
 SHA512:
-  metadata.gz: 0d6f85f5787589c0015ff134ad61ec92ae70fff3d2a4a3ec14f7298e76b6ef198eda072e638d86373569a8b725578afaddba2505e491d3b4a7b647fe496dfbdc
-  data.tar.gz: 6c3f1e30f7aef5b2d858834eb36c215681ef6f9a1feb48c5f108ba05c439eae4ee06665208f5780dc8f409d98dd6ba3b7b47d446255dfdf3efcb9d60d22e1305
+  metadata.gz: 34ec853c27180fce39c6be6bae2ddc084b524c624d588e65551ae8cfb8a491ea38fc08419344be87dbb0aebe69d5312b0c5a71a70e9a8786c58f5633fd9a169f
+  data.tar.gz: 93eb3c8919c0799573b0e107ebf6f1ebc8ee0b79cf4f3628fd543bebfd2e1e019e1180ea753ef7e6fa6a5b8e50342fb4854e4a7a048e8ba3a3ba8bcf2a4bc335

data/LICENSE.adoc

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

data/NOTICE.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor EPUB3
 
-Copyright (C) 2014-2015 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project.
 
 Please visit the Asciidoctor project site for more information:
 

data/README.adoc

@@ -1,6 +1,5 @@
 = Asciidoctor EPUB3: A _native_ EPUB3 converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.5, 2015-11-01
 :project-name: Asciidoctor EPUB3
 :project-handle: asciidoctor-epub3
 :project-uri: https://github.com/asciidoctor/{project-handle}
@@ -67,9 +66,10 @@ Of course, there's always room for improvement, so we'll continue to work with y
 * Direct AsciiDoc to EPUB3 conversion
 * Direct AsciiDoc to KF8/MOBI conversion
 * Highly-aesthetic and readable styles with optimized text legibility
+* Respects font settings (if supported by the reader) without altering headings, code or icons
 * EPUB3 metadata, manifest and spine (assembled by Gepub)
 * Document metadata (title, authors, subject, keywords, etc.)
-* Internal cross reference links
+* 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)
@@ -81,8 +81,7 @@ Of course, there's always room for improvement, so we'll continue to work with y
 
 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.
+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.
@@ -94,7 +93,7 @@ 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.
+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.
@@ -105,6 +104,8 @@ 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.
@@ -113,85 +114,82 @@ You can think of the master document as the spine of the book and the include di
 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.
+Here's an example showing the structure of a spine document:
 
-Eventually, we envision introducing a dedicated block macro to represent a spine item so that we don't overload the meaning of the include directive.
-However, for the time being, the include directive will suit this purpose.
-
-== 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
+----
+= Book Title
+Author Name
+:doctype: book
+:imagesdir: images
+//...and so on
+\ifndef::ebook-format[:leveloffset: 1]
 
-You can retrieve {project-name} in one of two ways:
+\include::chapter-one.adoc[]
 
-. Clone the git repository
-. Download a zip archive of the repository
+\include::chapter-two.adoc[]
 
-==== 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:
+\include::chapter-three.adoc[]
+----
 
- $ git clone https://github.com/asciidoctor/asciidoctor-epub3
+Here's an example showing the structure of a chapter document:
 
-Next, change to the project directory:
+----
+[[chapter-one]]
+= Chapter One
 
- $ cd asciidoctor-epub3
+chapter content
+----
 
-==== Option 2: Download the Archive
+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 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.
+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]).
 
-We'll now leverage the project configuration to install the necessary dependencies.
+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.
 
-=== Install the Dependencies
+== Prerequisites
 
-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.
+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 Bundler available, use the `bundle` command to query the version installed:
+To check if you have Ruby available, use the `ruby` command to query the installed version:
 
- $ bundle --version
+ $ ruby --version
 
-If it's not installed, use the `gem` command to install it.
+== Getting Started
 
- $ gem install bundle
+You can get {project-name} by <<_install_the_published_gem,installing the published gem>> or <<_development,running the code from source>>.
 
-Then use the `bundle` command to install the project dependencies:
+=== Install the Published Gem
 
- $ bundle install
+{project-name} is published as a pre-release on RubyGems.org.
+You can install the published gem using the following command:
 
-=== Build and Install the Gem
+ $ 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:
 
-Now that the dependencies are installed, you can build and install the Gem.
+.CodeRay
+ $ gem install coderay
 
-Use the Rake build tool to build the Gem:
+.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):
 
- $ rake build
+[source,asciidoc]
+----
+:source-highlighter: coderay 
+----
 
-The build will report that it built the Gem into the [path]_pkg_ directory.
+NOTE: At the moment, Pygments is automatically used if it's available.
 
-Finally, install the Gem.
+Assuming all the required gems install properly, verify you can run the `asciidoctor-epub3` script:
 
- $ gem install pkg/asciidoctor-epub3-1.5.0.dev.gem
+ $ asciidoctor-epub3 -v
 
-You're now ready to use {project-name}!
+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
@@ -231,7 +229,7 @@ The `dc` namespace prefix is in reference to the http://dublincore.org/documents
 |===
 |Name |Description
 
-|id
+|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. 
@@ -256,7 +254,7 @@ The authors in each chapter document are aggregated together with the authors in
 
 |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
+The avatar image should be located at the path _$${imagesdir}/avatars/{username}.jpg$$_, where
 `{username}` is the value of this attribute.
 
 |producer
@@ -290,6 +288,9 @@ The recommended practice is to identify the referenced resource by means of a st
 |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.
@@ -390,7 +391,7 @@ You just need to specify the format (`-a ebook-format`) as `kf8`.
 
  $ asciidoctor-epub3 -D output -a ebook-format=kf8 data/samples/sample-book.adoc
 
-When the script completes, you'll see the file [file]_sample-book.mobi_ appear in the [path]_output_ directory.
+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.
 
@@ -469,6 +470,8 @@ mimetype
 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
@@ -507,6 +510,7 @@ The theme maintains readability regardless of the e-book reader's background mod
 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
 
@@ -520,14 +524,14 @@ Refer to the {notice-uri}[NOTICE.adoc] file for further information about the fo
 
 // TODO document command to generate the M+ 1p latin fonts
 
-=== The text justification hack
+=== 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.
+It also brings along the same set of bugs present in browsers that are based on it.
 
-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.
+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
@@ -545,28 +549,28 @@ 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>
+<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>`).
+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;`).
+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;`).
+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.
+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.
+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._
@@ -584,15 +588,18 @@ 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)
+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.
@@ -670,6 +677,15 @@ To see all of the workarounds and why we chose certain style options, check out
 * `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 '.')
@@ -722,13 +738,101 @@ To contribute code, simply fork the project on GitHub, hack away and send a pull
 
 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-2015 OpenDevise Inc. and the Asciidoctor Project.
+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.