bb-epub 0.0.1

data/README.md

@@ -0,0 +1,14 @@
+# BbEPUB
+
+
+EPUB 2 and EPUB 3 package support for Bookbinder.
+
+
+## HOWTO
+
+    $ bundle
+
+    $ bundle exec irb -rbookbinder -rbb-epub
+
+    >> puts Bookbinder::Operations.map('tmp/book.epub')
+

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new { |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/unit/**/test*.rb']
+  t.verbose = true
+}
+
+desc('Run tests')
+task(:default => :test)

data/lib/bb-epub/package.rb

@@ -0,0 +1,64 @@
+class BbEPUB::Package < Bookbinder::Package
+
+  require_transforms(File.join(File.dirname(__FILE__), 'transform'))
+
+  DEFAULT_TRANSFORMS = [
+    BbEPUB::Transform::PackageIdentifier,
+    BbEPUB::Transform::Title,
+    BbEPUB::Transform::Creator,
+    BbEPUB::Transform::Contributor,
+    BbEPUB::Transform::Language,
+    BbEPUB::Transform::CoverImage,
+    BbEPUB::Transform::Description,
+    BbEPUB::Transform::Version,
+    BbEPUB::Transform::Spine,
+    BbEPUB::Transform::Resources,
+    BbEPUB::Transform::NavToc,
+    BbEPUB::Transform::CoverPage,
+    BbEPUB::Transform::Rendition,
+    BbEPUB::Transform::AudioOverlay,
+    Bookbinder::Transform::Organizer,
+    Bookbinder::Transform::Generator
+  ]
+
+  DEFAULT_CONTENT_ROOT = 'EPUB'
+
+
+  def self.recognize(path)
+    return (
+      File.extname(path).downcase == '.epub' ||
+      File.directory?(File.join(path, 'META-INF'))
+    )
+  end
+
+
+  def self.transforms
+    @transforms ||= DEFAULT_TRANSFORMS
+  end
+
+
+  def make_id(path)
+    path.gsub(/[^\w]/, '-')
+  end
+
+
+  def make_path(href)
+    CGI.unescape(href)
+  end
+
+
+  def make_href(path)
+    CGI.escape(path)
+  end
+
+
+  protected
+
+    # Overriding this Package method to inject EPUB's mimetype file.
+    #
+    def write_to_file_system(dest_file_system)
+      dest_file_system.write('mimetype', 'application/epub+zip')
+      super
+    end
+
+end

data/lib/bb-epub/transform/audio_overlay.rb

@@ -0,0 +1,227 @@
+# EPUB 3 only. Spec:
+#
+#   http://www.idpf.org/epub/301/spec/epub-mediaoverlays.html#sec-package-metadata
+#
+# Each spine item's manifest item may have a media-overlay attribute, which
+# is an idref pointing at a SMIL manifest item.
+#
+# Other properties to manage:
+#
+#   <meta property="media:active-class">-epub-media-overlay-active</meta>
+#   <meta property="media:playback-active-class">-epub-media-overlay-playing</meta>
+#   <meta property="media:duration" refines="#ch1_audio">0:32:29</meta>
+#   <meta property="media:duration">1:36:20</meta>
+#   <meta property="media:narrator">Bill Speaker</meta>
+#
+# Note: "The Package Document must include the duration of each
+# Media Overlay as well as of the entire Publication."
+#
+class BbEPUB::Transform::AudioOverlay < Bookbinder::Transform
+
+  def dependencies
+    [
+      BbEPUB::Transform::Metadata,
+      BbEPUB::Transform::Resources,
+      BbEPUB::Transform::Spine
+    ]
+  end
+
+
+  def to_map(package)
+    meta_to_prop(
+      package,
+      'media:active-class',
+      'audio-overlay-active-class'
+    )
+    meta_to_prop(
+      package,
+      'media:playback-active-class',
+      'audio-overlay-playback-active-class'
+    )
+    book_overlay_duration = meta_to_prop(
+      package,
+      'media:duration',
+      'audio-overlay-duration'
+    ) { |hashes|
+      hashes.detect { |hash|
+        unless hash.has_key?('refines')
+          hash['@'] = smil_clock_value_to_seconds(hash['@'])
+          true
+        end
+      }
+    }
+    # TODO: check that book does have a duration if there are any overlays.
+    meta_to_prop(
+      package,
+      'media:narrator',
+      'audio-overlay-narrator'
+    ) { |hashes|
+      hashes.detect { |hash| !hash.has_key?('refines') }
+    }
+    # Find each manifest item (SI) with media-overlay attribute:
+    #
+    #   - find the map['resources'] item that matches the media-overlay id
+    #   - find the map['spine'] item that matches the SI id
+    #     - set 'audio-overlay' to the AO path
+    #     - set 'audio-overlay-duration' to the refined duration
+    #     - set 'audio-overlay-narrator' to the refined narrator
+    #
+    opf_doc = package.file(:opf).document('r')
+    opf_doc.each('opf|manifest > opf|item[media-overlay]') { |cmpt_item|
+      cmpt_id = cmpt_item['id']
+      cmpt = package.map['spine'].detect { |c| c['id'] == cmpt_id }
+      # TODO: nil check cmpt
+      ao_id = cmpt_item['media-overlay']
+      rsrc = package.map['resources'].detect { |r| r['id'] == ao_id }
+      # TODO: nil check rsrc
+      cmpt['audio-overlay'] = rsrc['path']
+      cmpt_overlay_duration = meta_to_prop(
+        package,
+        'media:duration',
+        'audio-overlay-duration',
+        cmpt
+      ) { |hashes|
+        hashes.detect { |hash|
+          if hash['refines']['@'] == '#'+ao_id
+            hash['@'] = smil_clock_value_to_seconds(hash['@'])
+            true
+          end
+        }
+      }
+      # TODO: nil check cmpt_overlay_duration
+      meta_to_prop(
+        package,
+        'media:narrator',
+        'audio-overlay-narrator',
+        cmpt
+      ) { |hashes|
+        hash['refines']['@'] == '#'+ao_id
+      }
+    }
+  end
+
+
+  # Create a meta tag for:
+  #   audio-overlay-active-class => media:active-class
+  #   audio-overlay-playback-active-class => media:playback-active-class
+  #   audio-overlay-duration => media:duration
+  #   audio-overlay-narrator => media:narrator
+  #
+  # For each spine item with a 'media-overlay' key:
+  #
+  #   Find the corresponding map resource
+  #   Find the corresponding manifest item for component:
+  #     - set 'media-overlay' to rsrc['id']
+  #   Create a top-level meta tag:
+  #     cmpt['audio-overlay-duration'] => meta[property='media:duration'][refines='rsrc["id"]]
+  #   Also create a top-level meta tag for media:narrator if cmpt has 'audio-overlay-narrator'
+  #
+  def from_map(package)
+    opf_doc = package.file(:opf).document
+    metadata_tag = opf_doc.find('opf|metadata')
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-active-class',
+      'media:active-class'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-playback-active-class',
+      'media:playback-active-class'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-duration',
+      'media:duration'
+    )
+    prop_to_meta(
+      package.map,
+      metadata_tag,
+      'audio-overlay-narrator',
+      'media:narrator'
+    )
+    package.map['spine'].each { |cmpt|
+      next  unless cmpt['audio-overlay']
+      rsrc = package.map['resources'].detect { |r|
+        r['path'] == cmpt['audio-overlay']
+      }
+      cmpt_manifest_item = opf_doc.find("opf|manifest > opf|item##{cmpt['id']}")
+      cmpt_manifest_item['media-overlay'] = rsrc['id']
+      duration_meta_tag = prop_to_meta(
+        cmpt,
+        metadata_tag,
+        'audio-overlay-duration',
+        'media:duration'
+      )
+      duration_meta_tag['refines'] = '#'+rsrc['id']
+      narrator_meta_tag = prop_to_meta(
+        cmpt,
+        metadata_tag,
+        'audio-overlay-narrator',
+        'media:narrator'
+      )
+      narrator_meta_tag['refines'] = '#'+rsrc['id']  if narrator_meta_tag
+    }
+  end
+
+
+  protected
+
+    def meta_to_prop(package, meta_name, prop_name, target = nil)
+      return  unless package.map['metadata']
+      hashes = package.map['metadata'][meta_name]
+      return  unless hashes && hashes.any?
+      hash = block_given? ? yield(hashes) : hashes.first
+      if hash
+        hashes.delete(hash)
+        package.map['metadata'].delete(meta_name)  if hashes.empty?
+        (target || package.map)[prop_name] = hash['@']
+      end
+    end
+
+
+    # 5:34:31.396 = 5 hours, 34 minutes, 31 seconds and 396 milliseconds
+    # 124:59:36 = 124 hours, 59 minutes and 36 seconds
+    # 0:05:01.2 = 5 minutes, 1 second and 200 milliseconds
+    # 0:00:04 = 4 seconds
+    # 09:58 = 9 minutes and 58 seconds
+    # 00:56.78 = 56 seconds and 780 milliseconds
+    # 76.2s = 76.2 seconds = 76 seconds and 200 milliseconds
+    # 7.75h = 7.75 hours = 7 hours and 45 minutes
+    # 13min = 13 minutes
+    # 2345ms = 2345 milliseconds
+    # 12.345 = 12 seconds and 345 milliseconds
+    def smil_clock_value_to_seconds(clock)
+      return clock.to_f  if clock.kind_of?(Numeric)
+      clock = clock.to_s
+      if match = clock.match(/(\d+:)?(\d+:)(\d+\.?\d*)/)
+        h = match[1].to_s.to_f
+        m = match[2].to_s.to_f
+        s = match[3].to_s.to_f
+        h*60*60 + m*60 + s
+      elsif match = clock.match(/^(\d+\.?\d*)h$/)
+        match[1].to_f*60*60
+      elsif match = clock.match(/^(\d+\.?\d*)min$/)
+        match[1].to_f*60
+      elsif match = clock.match(/^(\d+\.?\d*)s?$/)
+        clock.to_f
+      elsif match = clock.match(/^(\d+\.?\d*)ms$/)
+        clock.to_f / 1000.0
+      end
+    end
+
+
+    def prop_to_meta(scope, metadata_tag, prop_name, meta_name)
+      if scope[prop_name]
+        meta_tag = Nokogiri::XML::Node.new('meta', metadata_tag)
+        meta_tag['property'] = meta_name
+        meta_tag.content = scope[prop_name]
+        metadata_tag.add_child(meta_tag)
+        return meta_tag
+      end
+    end
+
+end

data/lib/bb-epub/transform/audio_soundtrack.rb

@@ -0,0 +1,73 @@
+# For the specification, see the iBooks Asset Guide, specifically the
+# section titled "Ambient Soundtrack" in version 5.1:
+#
+#   https://itunesconnect.apple.com/docs/iBooksAssetGuide5.1Revision2.pdf
+#
+#
+class BbEPUB::Transform::AudioSoundtrack < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::Spine]
+  end
+
+
+  # Iterate through each spine item, looking for
+  #
+  #   <audio epub:type="ibooks:soundtrack" src="..." />
+  #
+  def to_map(package)
+    package.map['spine'].each { |cmpt|
+      find_soundtrack_in_component(cmpt, package.file(cmpt['path']))
+    }
+  end
+
+
+  # Iterate through each spine item, adding an audio tag to components
+  # that don't have one, or setting the src if the audio tag exists.
+  #
+  def from_map(package)
+    package.map['spine'].each { |cmpt|
+      if cmpt['audio-soundtrack']
+        add_soundtrack_to_component(cmpt, package.file(cmpt['path']))
+      end
+    }
+  end
+
+
+  protected
+
+    def find_soundtrack_in_component(cmpt, cmpt_file)
+      soundtrack_tag = soundtrack_tag_in_document(cmpt_file.document)
+      cmpt['audio-soundtrack'] = soundtrack_tag ? soundtrack_tag['src'] : nil
+    end
+
+
+    def add_soundtrack_to_component(cmpt, cmpt_file)
+      cmpt_doc = cmpt_file.document
+      unless soundtrack_tag = soundtrack_tag_in_document(cmpt_doc)
+        cmpt_doc.add_namespace('epub')
+        cmpt_doc.add_prefix('ibooks', 'epub:prefix')
+
+        soundtrack_tag = cmpt_doc.new_node('audio', :append => 'body')
+        soundtrack_tag['epub:type'] = 'ibooks:soundtrack'
+
+        cmpt_doc.new_node('style', :append => 'head') { |style_tag|
+          style_tag['type'] = 'text/css'
+          style_tag['id'] = 'BB_HIDE_AUDIO_SOUNDTRACK'
+          style_tag.content = [
+            'audio[epub|type="ibooks:soundtrack"] {',
+              'position: absolute;',
+              'top: -100px;',
+            '}'
+          ].join
+        }
+      end
+      soundtrack_tag['src'] = cmpt['audio-soundtrack']
+    end
+
+
+    def soundtrack_tag_in_document(cmpt_doc)
+      cmpt_doc.find('audio[epub|type="ibooks:soundtrack"]')
+    end
+
+end

data/lib/bb-epub/transform/contributor.rb

@@ -0,0 +1,11 @@
+require(File.join(File.dirname(__FILE__), 'creator.rb'))
+
+class BbEPUB::Transform::Contributor < BbEPUB::Transform::Creator
+
+  protected
+
+    def actor_type
+      'contributor'
+    end
+
+end

data/lib/bb-epub/transform/cover_image.rb

@@ -0,0 +1,123 @@
+# The best source of information about wading through the EPUB
+# cover image quagmire has always been Keith's article on the
+# Threepress blog:
+#
+#   http://blog.safaribooksonline.com/2009/11/20/best-practices-in-epub-cover-images/
+#
+# He added an update for EPUB3, which follows the spec but is
+# a bit easier to grok:
+#
+#   http://blog.safaribooksonline.com/2011/05/26/covers-in-epub3/
+#
+class BbEPUB::Transform::CoverImage < Bookbinder::Transform
+
+  def dependencies
+    [
+      BbEPUB::Transform::Metadata,
+      BbEPUB::Transform::CoverPage
+    ]
+  end
+
+
+  # If it's EPUB3, the cover will be in the 'properties' attribute
+  # of the manifest item: 'cover-image'
+  #
+  # Otherwise, look for a manifest item with an 'id' of 'cover-image'.
+  #
+  # Or, look for a meta tag with a 'name' of 'cover', then find the
+  # manifest item that has the 'id' that matches meta's 'content'.
+  #
+  # Set map['cover'] to this item (and remove it from map['resources']).
+  #
+  def to_map(package)
+    package.map['cover'] = {}
+    opf_doc = package.file(:opf).document('r')
+    cover_item = cover_item_from_manifest(package, opf_doc) ||
+      cover_item_from_metadata(package, opf_doc) ||
+      cover_item_from_cover_page(package)
+    if cover_resource = cover_resource_from_item(package, cover_item)
+      package.map['resources'].delete(cover_resource)
+      package.map['cover'].update("front" => cover_resource)
+    end
+  end
+
+
+  # Belt and braces: give the manifest item a property of
+  # 'cover-image', an 'id' of 'cover-image' (updating any
+  # idrefs) and create a meta tag with 'name'='cover' and
+  # 'content'='cover-image'.
+  #
+  def from_map(package)
+    return  unless package.map['cover'] && cover = package.map['cover']['front']
+    opf_doc = package.file(:opf).document
+
+    opf_doc.new_node('item', :append => 'opf|manifest') { |manifest_item_tag|
+      manifest_item_tag['href'] = package.make_href(cover['path'])
+      manifest_item_tag['media-type'] = cover['media-type']
+      manifest_item_tag['id'] = 'cover-image'
+      manifest_item_tag['properties'] = 'cover-image'
+    }
+
+    cover_id = package.make_id(cover['path'])
+    opf_doc.each('[idref="'+cover_id+'"]') { |idref|
+      idref['idref'] = cover_id
+    }
+
+    opf_doc.new_node('meta', :append => 'opf|metadata') { |cover_meta_tag|
+      cover_meta_tag['name'] = 'cover'
+      cover_meta_tag['content'] = 'cover-image'
+    }
+  end
+
+
+  def cover_item_from_manifest(package, opf_doc)
+    opf_doc.find('opf|manifest > opf|item[properties~="cover-image"]') ||
+      opf_doc.find('opf|manifest > opf|item[id="cover-image"]') ||
+      opf_doc.find('opf|manifest > opf|item[id="cover_image"]')
+  end
+
+
+  def cover_item_from_metadata(package, opf_doc)
+    cover_meta_props = (package.map['metadata'] || {}).delete('cover')
+    if cover_meta_props && cover_meta_props.any?
+      cover_image_id = cover_meta_props.first['content']['@']
+      opf_doc.find('opf|manifest > opf|item[id="'+cover_image_id+'"]')
+    end
+  end
+
+
+  def cover_item_from_cover_page(package)
+    if (nav = package.map['nav']) && (landmarks = nav['landmarks'])
+      if landmark = landmarks.detect { |it| it['type'] == 'cover' }
+        return package.map['spine'].detect { |c| c['path'] == landmark['path'] }
+      end
+    end
+  end
+
+
+  # TODO: support SVG images too.
+  #
+  def cover_item_from_component(package, cmpt)
+    package.if_file(cmpt['path']) { |cmpt_file|
+      return  unless cmpt_doc = cmpt_file.document('r')
+      return  unless img_tag = cmpt_doc.find('body img')
+      opf_doc = package.file(:opf).document('r')
+      opf_doc.find('opf|manifest > opf|item[href="'+img_tag['src']+'"]')
+    }
+  rescue
+    nil
+  end
+
+
+  def cover_resource_from_item(package, cover_item)
+    return nil  unless cover_item && cover_item['id']
+    if cmpt = package.map['spine'].detect { |c| c['id'] == cover_item['id'] }
+      unless cover_item = cover_item_from_component(package, cmpt)
+        package.warn("Did not discover cover image in #{cmpt['path']}. SVG?")
+        return nil
+      end
+    end
+    package.map['resources'].detect { |r| r['id'] == cover_item['id'] }
+  end
+
+end

data/lib/bb-epub/transform/cover_page.rb

@@ -0,0 +1,158 @@
+class BbEPUB::Transform::CoverPage < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::Spine]
+  end
+
+
+  # A: look in the Nav (if it exists) for a landmark li with an
+  # epub:type of 'cover', and find the spine item with that href.
+  #
+  # B: look for an OPF <guide><reference type="cover"> and find
+  # the spine item with the same href.
+  #
+  # C: look at the first spine item:
+  #   - is it have /cover/ in the filename?
+  #   - no? does it have an image and no body text?
+  #   - no? does it have an svg and no body text?
+  #
+  # -> If found, add to map['nav']['landmarks'] with a 'type'
+  # of 'cover'.
+  #
+  def to_map(package)
+    cover_page_item =
+      cover_page_item_from_nav(package) ||
+      cover_page_item_from_opf_guide(package) ||
+      cover_page_item_from_id(package) ||
+      cover_page_item_from_first_spine_item(package)
+
+    if cover_page_item
+      package.map['nav'] ||= {}
+      package.map['nav']['landmarks'] ||= []
+      package.map['nav']['landmarks'].unshift(cover_page_item)
+      package.map['spine'].each { |item|
+        if item['path'] == cover_page_item['path']
+          item['linear'] = false
+        end
+      }
+    end
+  end
+
+
+  # Do nothing unless we have a map['nav']['landmark'] type='cover'.
+  #
+  # In the Nav (if it exists), create a landmark with an
+  # epub:type of 'cover'. Actually, don't -- let the landmarks feature
+  # handle this.
+  #
+  # In the OPF, create a <guide> element if it doesn't exist,
+  # and create a <reference type="cover" title="Cover" href="..."> tag
+  # within it.
+  #
+  def from_map(package)
+    return  unless package.map['nav'] && package.map['nav']['landmarks']
+    cover_page_item = package.map['nav']['landmarks'].detect { |item|
+      item['type'] == 'cover'
+    }
+    return  unless cover_page_item
+
+    opf_doc = package.file(:opf).document
+    unless guide_tag = opf_doc.find('opf|guide')
+      guide_tag = opf_doc.new_node('guide', :append => opf_doc.root)
+    end
+
+    opf_doc.new_node('reference', :append => guide_tag) { |ref_tag|
+      ref_tag['type'] = 'cover'
+      ref_tag['href'] = package.make_href(cover_page_item['path'])
+      ref_tag['title'] = cover_page_item['title']
+    }
+  end
+
+
+  protected
+
+    # Look for an EPUB3 landmark with type 'cover'.
+    #
+    def cover_page_item_from_nav(package)
+      return  unless nav_file = package.file(:nav)
+      nav_doc = nav_file.document('r')
+      if li = nav_doc.find('nav[epub|type="landmark"] li[epub|type="cover"]')
+        href_to_cover_page_item(
+          package,
+          li['href'],
+          li['title'] || li.content.strip
+        )
+      end
+    end
+
+
+    # Look for a guide reference with type 'cover' in the OPF.
+    #
+    def cover_page_item_from_opf_guide(package)
+      opf_doc = package.file(:opf).document('r')
+      if guide_ref_tag = opf_doc.find('opf|guide > opf|reference[type="cover"]')
+        href_to_cover_page_item(package, guide_ref_tag['href'])
+      end
+    end
+
+
+    def cover_page_item_from_id(package)
+      opf_doc = package.file(:opf).document('r')
+      if manifest_tag = opf_doc.find('opf|manifest > opf|item[id^="cover"]')
+        if manifest_tag['media-type'].match(/ml$/)
+          href_to_cover_page_item(package, manifest_tag['href'])
+        end
+      end
+    end
+
+
+    # Investigate whether the first spine item is a cover page.
+    #
+    def cover_page_item_from_first_spine_item(package)
+      spine = package.map['spine']
+      if spine.any? && file_path = package.map['spine'].first['path']
+        file_href = package.make_href(file_path)
+        if file_path.match(/cover/)
+          return href_to_cover_page_item(package, file_href)
+        end
+        package.if_file(file_path) { |cmpt_file|
+          if cmpt_doc = cmpt_file.document('r')
+            body = cmpt_doc.find('body')
+            nodes = body.xpath('.//text()[normalize-space()]')
+            # If the body has no text...
+            if nodes.empty?
+              # ...and it has an <img> or an <svg>...
+              if cmpt_doc.find('body img') || cmpt_doc.find('body svg')
+                # ...we'll treat it as a cover page.
+                return href_to_cover_page_item(package, file_href)
+              end
+            end
+          end
+        }
+      end
+    end
+
+
+    # Given a href for a cover page, create the cover page item
+    # that will go into the landmarks array in the package map.
+    #
+    def href_to_cover_page_item(package, cover_href, page_title = nil)
+      cover_href = cover_href.sub(/#.*$/, '')
+      cover_page_path = package.make_path(cover_href)
+      package.if_file(cover_page_path) { |cover_page_file|
+        return  unless doc = cover_page_file.document('r')
+        if page_title.nil? || page_title.empty?
+          title_tag = cover_page_file.document('r').find('head > title')
+          page_title = title_tag ? title_tag.content.strip : 'Cover page'
+        end
+        {
+          'type' => 'cover',
+          'path' => cover_page_path,
+          'title' => page_title,
+          # FIXME: acquire the real media-type from manifest item?
+          'media-type' => cover_page_file.media_type
+        }
+      }
+    end
+
+end