bookbinder 0.2.0

data/lib/bookbinder/transform/epub/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 Bookbinder::Transform::EPUB_AudioSoundtrack < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_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/bookbinder/transform/epub/contributor.rb

@@ -0,0 +1,11 @@
+require 'bookbinder/transform/epub/creator'
+
+class Bookbinder::Transform::EPUB_Contributor < Bookbinder::Transform::EPUB_Creator
+
+  protected
+
+    def actor_type
+      'contributor'
+    end
+
+end

data/lib/bookbinder/transform/epub/cover_image.rb

@@ -0,0 +1,80 @@
+# 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 Bookbinder::Transform::EPUB_CoverImage < Bookbinder::Transform
+
+  def dependencies
+    [
+      Bookbinder::Transform::EPUB_Resources,
+      Bookbinder::Transform::EPUB_Metadata
+    ]
+  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)
+    opf_doc = package.file(:opf).document('r')
+    cover_item = opf_doc.find('opf|manifest > opf|item[properties~="cover-image"]')
+    cover_item ||= opf_doc.find('opf|manifest > opf|item[id="cover-image"]')
+    cover_item ||= opf_doc.find('opf|manifest > opf|item[id="cover_image"]')
+    cover_meta_props = (package.map['metadata'] || {}).delete('cover')
+    if !cover_item && cover_meta_props && cover_meta_props.any?
+      cover_image_id = cover_meta_props.first['content']['@']
+      cover_item = opf_doc.find('opf|manifest > opf|item[id="'+cover_image_id+'"]')
+    end
+    covers = {}
+    if cover_item
+      rsrc = package.map['resources'].detect { |r|
+        r['id'] == cover_item['id']
+      }
+      covers.update("front" => package.map['resources'].delete(rsrc))
+    end
+    package.map['cover'] = covers
+  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
+
+end

data/lib/bookbinder/transform/epub/cover_page.rb

@@ -0,0 +1,148 @@
+class Bookbinder::Transform::EPUB_CoverPage < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_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_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
+
+
+    # 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)
+      if cover_page_file = package.file(cover_page_path)
+        if doc = cover_page_file.document('r')
+          unless page_title
+            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
+    end
+
+end

data/lib/bookbinder/transform/epub/creator.rb

@@ -0,0 +1,67 @@
+class Bookbinder::Transform::EPUB_Creator < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Metadata]
+  end
+
+
+  def to_map(package)
+    return  unless package.map['metadata']
+    return  unless metadata_array = package.map['metadata'][actor_type]
+    actors = []
+    actor_data = metadata_array.sort { |a, b|
+      if a['display-seq'] && b['display-seq']
+        a['display-seq']['@'].to_i <=> b['display-seq']['@'].to_i
+      else
+        0
+      end
+    }
+    actor_data.each { |cdata|
+      actor = {
+        'name' => cdata['@'],
+        'role' => cdata['role'] ? cdata['role']['@'] : 'aut',
+      }
+      actor['file-as'] = cdata['file-as']['@']  if cdata['file-as']
+      # Eh, 'alternate-script' is too messy for now.
+
+      metadata_array.delete(cdata)
+      actors.push(actor)
+    }
+    package.map['metadata'].delete(actor_type)  if metadata_array.empty?
+    package.map[actor_type] = actors
+  end
+
+
+  def from_map(package)
+    return  unless actors = package.map[actor_type]
+    opf_doc = package.file(:opf).document
+    metadata_tag = opf_doc.find('opf|metadata')
+    actors.each_with_index { |actor, seq|
+      actor_tag = opf_doc.new_node('dc:'+actor_type, :append => metadata_tag)
+      actor_tag.content = actor['name']
+      if actors.length > 1
+        seq += 1
+        actor_id = "dc-#{actor_type}-metadata-#{seq}"
+        actor_tag['id'] = actor_id
+        opf_doc.new_node('meta', :append => metadata_tag) { |role_meta_tag|
+          role_meta_tag.content = actor['role']
+          role_meta_tag['property'] = 'role'
+          role_meta_tag['refines'] = '#'+actor_id
+        }
+        opf_doc.new_node('meta', :append => metadata_tag) { |seq_meta_tag|
+          seq_meta_tag.content = seq
+          seq_meta_tag['property'] = 'display-seq'
+          seq_meta_tag['refines'] = '#'+actor_id
+        }
+      end
+    }
+  end
+
+
+  protected
+
+    def actor_type
+      'creator'
+    end
+
+end

data/lib/bookbinder/transform/epub/description.rb

@@ -0,0 +1,43 @@
+class Bookbinder::Transform::EPUB_Description < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Metadata]
+  end
+
+
+  def to_map(package)
+    desc_hashes = package.map['metadata'].delete('description')
+    descs = []
+    if desc_hashes && desc_hashes.any?
+      descs = desc_hashes.collect { |dh| dh['@'] }
+      descs.sort! { |a, b| a.length <=> b.length }
+      full = descs.shift
+      if full && !full.empty?
+        short = descs.shift || first_sentence(full)
+        desc = { 'full' => full }
+        desc['short'] = short  if short
+        package.map['description'] = desc
+      end
+    end
+  end
+
+
+  def from_map(package)
+    if desc = package.map['description']
+      opf_doc = package.file(:opf).document
+      opf_doc.new_node('dc:description', :append => 'opf|metadata') { |desc_tag|
+        desc_tag.content = desc['full']
+      }
+    end
+  end
+
+
+  protected
+
+    def first_sentence(str)
+      str = Nokogiri::HTML(str).text
+      sentences = str.split(/\./)
+      sentences.first+'.'  if sentences.any?
+    end
+
+end

data/lib/bookbinder/transform/epub/language.rb

@@ -0,0 +1,29 @@
+class Bookbinder::Transform::EPUB_Language < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Metadata]
+  end
+
+
+  def to_map(package)
+    lang_hashes = package.map['metadata'].delete('language')
+    if lang_hashes && lang_hashes.any?
+      package.map['language'] = lang_hashes.collect { |lh| lh['@'] }
+    else
+      package.warn('No <dc:language> found in OPF metadata')
+    end
+  end
+
+
+  def from_map(package)
+    if langs = package.map['language']
+      opf_doc = package.file(:opf).document
+      langs.each { |lang|
+        opf_doc.new_node('dc:language', :append => 'opf|metadata') { |lang_tag|
+          lang_tag.content = lang
+        }
+      }
+    end
+  end
+
+end

data/lib/bookbinder/transform/epub/metadata.rb

@@ -0,0 +1,140 @@
+# Takes all the elements in the <metadata> tag of the OPF file and
+# generates a clean hash of the data. Other transforms will pick and
+# choose from this hash. What's left over is mostly just for
+# preserving EPUB's guff.
+#
+# So this:
+#
+#    <metadata>
+#      <dc:identifier id="isbn-id">
+#        urn:isbn:9780101010101
+#      </dc:identifier>
+#      <meta
+#        refines="#isbn-id"
+#        property="identifier-type"
+#        scheme="onix:codelist5"
+#      >
+#        15
+#      </meta>
+#      <dc:source id="src-id">
+#        urn:isbn:9780375704024
+#      </dc:source>
+#      <meta
+#        refines="#src-id"
+#        property="identifier-type"
+#        scheme="onix:codelist5"
+#      >
+#        15
+#      </meta>
+#    </metadata>
+#
+# ... becomes this:
+#
+#    "metadata": {
+#      "identifier": [{
+#        "@": "urn:isbn:9780101010101",
+#        "identifier-type": {
+#          "@": 15,
+#          "scheme": {
+#            "@": "onix-codelist5"
+#          }
+#        }
+#      }],
+#      "source": [{
+#        "@": "urn:isbn:9780375704024",
+#        "identifier-type": {
+#          "@": 15,
+#          "scheme": {
+#            "@": "onix-codelist5"
+#          }
+#        }
+#      }]
+#    }
+#
+# You can nest properties arbitrarily deep in the map's "metadata" structure.
+#
+#     "metadata": {
+#       "some-property": [{
+#         "@": "value-of-some-property",
+#         "some-property-property": {
+#           "@": "value-of-some-property-property",
+#           "some-property-property-property": {
+#             "@": "value-of-etc"
+#           }
+#         }
+#       }],
+#       "other-property": [
+#         { "@": "other-property-first-value" },
+#         { "@": "other-property-second-value" }
+#       ]
+#     }
+#
+class Bookbinder::Transform::EPUB_Metadata < Bookbinder::Transform
+
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_OPF]
+  end
+
+
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+    md = {}
+    opf_doc.each('opf|metadata > *') { |tag|
+      # If this tag refines another metadata tag, we can skip it
+      next if tag['refines'] && opf_doc.find('opf|metadata > '+tag['refines'])
+
+      # Find the basic name and value of the meta tag
+      name = tag.node_name
+      value = { '@' => tag.content.strip }
+      # If the meta tag has attributes, add them to the value
+      # (but note that these are deprecated in EPUB3 in favor
+      # of refinements).
+      tag.attributes.each_pair { |key, attr|
+        value[key] = { '@' => attr.value }
+        value[key]['deprecated'] = true  unless key == 'id' || key == 'refines'
+      }
+      if name == 'meta'
+        if tag['property']
+          name = tag['property']
+          value.delete('property')
+        elsif tag['name']
+          # Note that <meta name="" content=""> is deprecated in EPUB3.
+          name = tag['name']
+          value['@'] = tag['content']
+          value['deprecated'] = true
+          value.delete('name')
+        end
+      end
+      # If the meta tag is refined by another meta tag, add the
+      # refinements to our value hash.
+      if tag['id']
+        refines = opf_doc.search(
+          'opf|metadata > opf|meta[refines="#'+tag['id']+'"]'
+        )
+        refines.each { |refinement|
+          refine_value = { '@' => refinement.content.strip }
+          refinement.attributes.each_pair { |key, attr|
+            refine_value[key] = attr.value
+          }
+          value[refinement['property']] = refine_value
+        }
+      end
+      # Add the name and value to our metadata hash
+      add_to_hash(md, name, value)
+    }
+    package.map['metadata'] = md
+  end
+
+
+  def from_map(package)
+  end
+
+
+  protected
+
+    def add_to_hash(hash, key, val)
+      hash[key] = [hash[key], val].flatten.compact
+    end
+
+end

data/lib/bookbinder/transform/epub/nav.rb

@@ -0,0 +1,60 @@
+class Bookbinder::Transform::EPUB_Nav < Bookbinder::Transform
+
+  DEFAULT_FILE_NAME = 'book-nav.xhtml'
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Resources]
+  end
+
+
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+    if nav_item = opf_doc.find('opf|manifest > opf|item[properties~="nav"]')
+      nav_path = package.make_path(nav_item['href'])
+      package.file_aliases[:nav] = nav_path
+      package.map['resources'].delete_if { |rsrc|
+        package.file_path(rsrc['path']) == nav_path
+      }
+    end
+  end
+
+
+  def from_map(package)
+    if package.options['nav_file'] != false
+      stub_nav(package)
+      add_to_opf_manifest(package)
+    end
+  end
+
+
+  protected
+
+    def stub_nav(package)
+      package.file_aliases[:nav] = DEFAULT_FILE_NAME
+      package.file(:nav).new_xml_document { |doc, x|
+        x.doc.create_internal_subset('html', nil, nil)
+        x.html {
+          doc.add_node_namespace(x.parent, 'xhtml', true)
+          doc.add_node_namespace(x.parent, 'epub')
+          x.head {
+            x.meta('charset' => 'utf-8')
+            x.style('ol { list-style: none; }')
+          }
+          x.body
+        }
+      }
+    end
+
+
+    def add_to_opf_manifest(package)
+      opf_file = package.file(:opf)
+      nav_file = package.file(:nav)
+      opf_file.document.new_node('item', :append => 'opf|manifest') { |item_tag|
+        item_tag['href'] = package.make_href(DEFAULT_FILE_NAME)
+        item_tag['id'] = package.make_id(DEFAULT_FILE_NAME)
+        item_tag['properties'] = 'nav'
+        item_tag['media-type'] = nav_file.media_type
+      }
+    end
+
+end