bb-epub 0.0.1

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

@@ -0,0 +1,87 @@
+# See: http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-opf-metadata-identifiers-pid
+#
+# "To redress this problem of identifying minor modifications and releases
+# without changing the Unique Identifier, this specification defines the
+# semantics for a Package Identifier, or means of distinguishing and
+# sequentially ordering Publications with the same Unique Identifier. The
+# Package Identifier is not an actual property in the package metadata section,
+# but is a value that can be obtained from two required pieces of metadata: the
+# Unique Identifier and the last modification date of the Publication.
+#
+# "When the taken together, the combined value represents a unique identity that
+# can be used to distinguish any particular version of an EPUB Manifestation
+# from another. To ensure that a Package Identifier can be constructed, the
+# Publication must include exactly one `modified` property containing
+# the last modification date (see meta)."
+#
+class BbEPUB::Transform::PackageIdentifier < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::Metadata, BbEPUB::Transform::NCX]
+  end
+
+
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+
+    # Unique identifier
+    unless id_hashes = package.map['metadata']['identifier']
+      package.warn('No identifiers found in package metadata')
+    end
+    if id_hashes && uid_id = opf_doc.root['unique-identifier']
+      uid_hash = id_hashes.detect { |id_hash|
+        id_hash['id'] && id_hash['id']['@'] == uid_id
+      }
+    else
+      package.warn('OPF root "unique-identifier" attribute not found')
+    end
+    if uid_hash
+      id_hashes.delete(uid_hash)
+      package.map['metadata'].delete('identifier')  if id_hashes.empty?
+      package.map['unique-identifier'] = uid_hash['@']
+    else
+      package.warn('OPF metadata for required "unique-identifier" not found')
+    end
+
+    # Modified
+    begin
+      mod_hash = package.map['metadata'].delete('dcterms:modified').first
+      timestamp = Time.parse(mod_hash['@'])
+    rescue
+      package.warn('OPF metadata for "modified" not found - using now()')
+      timestamp = Time.now
+    end
+    package.map['modified'] = timestamp.utc.iso8601
+  end
+
+
+  def from_map(package)
+    map_uid = package.map['unique-identifier']
+    map_mod = package.map['modified']
+    opf_doc = package.file(:opf).document
+    metadata_tag = opf_doc.find('opf|metadata')
+
+    # Unique identifier
+    opf_doc.root['unique-identifier'] = 'unique-identifier'
+    opf_doc.new_node('dc:identifier', :append => metadata_tag) { |uid_tag|
+      uid_tag['id'] = 'unique-identifier'
+      uid_tag.content = map_uid
+    }
+
+    # Add the unique identifier to the NCX as well, because too
+    # much data redundancy is never enough.
+    package.if_file(:ncx) { |ncx_file|
+      ncx_file.document.new_node('meta', :append => 'ncx|head') { |uid_meta_tag|
+        uid_meta_tag['name'] = 'dtb:uid'
+        uid_meta_tag['content'] = map_uid
+      }
+    }
+
+    # Modified
+    opf_doc.new_node('meta', :append => metadata_tag) { |mod_tag|
+      mod_tag['property'] = 'dcterms:modified'
+      mod_tag.content = map_mod
+    }
+  end
+
+end

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

@@ -0,0 +1,273 @@
+# For the original Apple extension to EPUB 2, see any version of the iBooks
+# Asset Guide prior to version 5. Here's a link to version 4.7:
+#
+#   http://www.mobileread.com/forums/attachment.php?attachmentid=74234
+#
+# In particular, see the section titled "Configuring Display Options"
+#
+# For the EPUB 3 Fixed Layout specification (actually a Mixed Layout
+# specification), see:
+#
+#   http://www.idpf.org/epub/301/spec/epub-publications.html#sec-package-metadata-fxl
+#
+# NOTE: a potential gotcha. The EPUB3 properties are 'rendition:...',
+# with a colon, whereas the Openbook form follows the dash convention
+# for property names, ie 'rendition-...'.
+#
+class BbEPUB::Transform::Rendition < Bookbinder::Transform
+
+  RENDITION_DEFAULT_PROPERTIES = {
+    'rendition:flow' => 'paginated',
+    'rendition:layout' => 'reflowable',
+    'rendition:spread' => 'auto',
+    'rendition:orientation' => 'auto',
+    'rendition:viewport' => nil
+  }
+  APPLE_FXL_PATH = 'META-INF/com.apple.ibooks.display-options.xml'
+
+
+  def dependencies
+    [BbEPUB::Transform::Spine, BbEPUB::Transform::Metadata]
+  end
+
+
+  def to_map(package)
+    package.map['rendition-format'] = 'ebook'
+    book_properties = book_properties_from_apple_display_options(package)
+    book_properties.update(book_properties_from_opf(package))
+    component_rendition_properties_from_opf(package, book_properties)
+  end
+
+
+  def from_map(package)
+    first_cmpt = package.map['spine'][0]
+    book_properties = {
+      'rendition:flow' => first_cmpt['rendition-flow'],
+      'rendition:layout' => first_cmpt['rendition-layout'],
+      'rendition:spread' => first_cmpt['rendition-spread'],
+      'rendition:orientation' => first_cmpt['rendition-orientation'],
+      'rendition:viewport' => first_cmpt['rendition-viewport']
+    }
+    opf_doc = package.file(:opf).document
+    opf_doc.add_prefix('rendition')
+    book_properties.each_pair { |prop, content|
+      if content && RENDITION_DEFAULT_PROPERTIES[prop] != content
+        book_meta_tag(opf_doc, prop, content)
+      end
+    }
+    opf_doc.each('opf|spine > opf|itemref') { |itemref|
+      # Update the itemref properties attribute.
+      cmpt = component_for_itemref(package, itemref)
+      props = (itemref['properties'] || '').split
+      book_properties.each_pair { |prop, book_content|
+        key = prop.gsub(':', '-')
+        if cmpt[key] != book_content
+          cmpt_content = cmpt[key] || RENDITION_DEFAULT_PROPERTIES[prop]
+          props.push("#{prop}-#{cmpt_content}")
+        end
+      }
+      if ['left', 'right'].include?(cmpt['rendition-position'])
+        props.push('page-spread-'+cmpt['rendition-position'])
+      elsif cmpt['rendition-position'] == 'center'
+        props.push('rendition:page-spread-center')
+      end
+      if cmpt['rendition-align-x-center']
+        props.push('rendition:align-x-center')
+      end
+      itemref['properties'] = props.join(' ')  if props.any?
+
+      # Update the viewport/viewBox attribute in the component file.
+      add_icb_to_component(
+        package.file(cmpt['path']),
+        cmpt['rendition-viewport']
+      ) if cmpt['rendition-viewport']
+    }
+  end
+
+
+  protected
+
+    # Inspects Apple's display-options file in META-INF for some
+    # option values that we can convert to EPUB3 equivalents.
+    # Returns a hash with zero or more rendition:* properties.
+    #
+    def book_properties_from_apple_display_options(package)
+      {}.tap { |book_properties|
+        package.if_file(APPLE_FXL_PATH, false) { |apple_file|
+          apple_options = apple_file.document('r').search(
+            'display_options > platform[name="*"] > option'
+          )
+          apple_hash = apple_options.inject({}) { |acc, apple_option|
+            acc.update(apple_option['name'] => apple_option.content.strip)
+          }
+
+          if apple_hash['fixed-layout'] == 'true'
+            book_properties['rendition-layout'] = 'pre-paginated'
+          end
+
+          if apple_hash['orientation-lock'] == 'landscape-only'
+            book_properties['rendition-orientation'] = 'landscape'
+          elsif apple_hash['orientation-lock'] == 'portrait-only'
+            book_properties['rendition-orientation'] = 'portrait'
+          end
+
+          # FIXME: not really a 1-to-1 mapping - should we ignore this option?
+          # UPDATE: yes, disabled for now.
+          # if apple_hash['open-to-spread'] == 'true'
+          #   book_properties['rendition-spread'] = 'both'
+          # end
+        }
+      }
+    end
+
+
+    # Looks for book rendition properties in the OPF <metadata>
+    # tag, returning a hash with zero or more such properties.
+    #
+    # Book-level rendition properties are:
+    #
+    #   <meta property="rendition:layout">reflowable</meta>
+    #   <meta property="rendition:spread">auto</meta>
+    #   <meta property="rendition:orientation">landscape</meta>
+    #
+    def book_properties_from_opf(package)
+      {}.tap { |book_properties|
+        spent = []
+        package.map['metadata'].each_pair { |key, value|
+          if RENDITION_DEFAULT_PROPERTIES.keys.include?(key)
+            book_properties.update(key.sub(':', '-') => value.first['@'])
+            spent.push(key)
+          end
+        }
+        spent.each { |key| package.map['metadata'].delete(key) }
+        if vpt_str = book_properties['rendition-viewport']
+          if vpt = parse_viewport_string(vpt_str)
+            book_properties['rendition-viewport'] = vpt
+          else
+            package.warn("Viewport string unparseable: #{vpt_str}")
+          end
+        end
+      }
+    end
+
+
+    # Iterates over each spine component looking for component-specific
+    # rendition properties, which are merged over the top of the default
+    # book-level properties, then applied directly to the map's component.
+    #
+    def component_rendition_properties_from_opf(package, book_properties)
+      opf_doc = package.file(:opf).document('r')
+      opf_doc.each('opf|spine opf|itemref') { |itemref|
+        cmpt = component_for_itemref(package, itemref)
+        cmpt_properties = book_properties.clone
+        (itemref['properties'] || '').split.each { |itemref_prop|
+          if match = itemref_prop.match(/^rendition:flow-(.+)/)
+            cmpt_properties['rendition-flow'] = match[1]
+          end
+          if match = itemref_prop.match(/^rendition:layout-(.+)/)
+            cmpt_properties['rendition-layout'] = match[1]
+          end
+          if match = itemref_prop.match(/^rendition:spread-(.+)/)
+            cmpt_properties['rendition-spread'] = match[1]
+          end
+          if match = itemref_prop.match(/^rendition:orientation-(.+)/)
+            cmpt_properties['rendition-spread'] = match[1]
+          end
+          if match = itemref_prop.match(/^(rendition:)?page-spread-(\w+)/)
+            cmpt_properties['rendition-position'] = match[2]
+          end
+          if match = itemref_prop.match(/^rendition:align-x-center$/)
+            cmpt_properties['rendition-align-x-center'] = true
+          end
+        }
+
+        # The rendition:viewport should ONLY be set on the component if
+        # it is pre-paginated, and we should prefer the values in the
+        # HTML file itself over anything we find in the OPF.
+        book_vpt = cmpt_properties.delete('rendition-viewport')
+        if cmpt_properties['rendition-layout'] == 'pre-paginated'
+          cmpt_vpt = retrieve_icb_from_component(package.file(cmpt['path']))
+          if cmpt_vpt || book_vpt
+            cmpt_properties['rendition-viewport'] = cmpt_vpt || book_vpt
+          else
+            package.warn("Pre-paginated: viewport not found: #{cmpt['path']}")
+            puts("Expected viewport, found nothing")
+            cmpt_properties.delete('rendition-layout')
+          end
+        end
+        cmpt.update(cmpt_properties)
+      }
+    end
+
+
+    # Given an itemref tag, finds the map's component hash that
+    # corresponds to it. (Look-up is performed using href, via
+    # the manifest item tag.)
+    #
+    def component_for_itemref(package, itemref)
+      package.map['spine'].detect { |cmpt|
+        cmpt['id'] == itemref['idref']
+      }
+    end
+
+
+    # Finds the "initial containing block" (in EPUB3 parlance) for
+    # the given component document. This is either the SVG viewBox
+    # attribute, or the HTML <meta name="viewport"> content attribute.
+    #
+    def retrieve_icb_from_component(cmpt_file)
+      cmpt_doc = cmpt_file.document('r')
+      if cmpt_file.media_type.match(/svg/)
+        icb = cmpt_doc.root['viewBox'].split
+        { 'width' => icb[0], 'height' => icb[1] }
+      elsif viewport_meta = cmpt_doc.find('meta[name="viewport"]')
+        parse_viewport_string(viewport_meta['content'])
+      end
+    end
+
+
+    def parse_viewport_string(icb)
+      {
+        'width' => icb.match(/width\s*=\s*(\d+)/)[1].to_i,
+        'height' => icb.match(/height\s*=\s*(\d+)/)[1].to_i
+      }
+    rescue
+      # package.warn("Viewport string unparseable: #{icb}")
+      nil
+    end
+
+
+    # Creates a book-level meta tag for the given rendition:* property,
+    # inserting it into the OPF document.
+    #
+    def book_meta_tag(opf_doc, property, content)
+      opf_doc.new_node('meta', :append => 'opf|metadata') { |meta_tag|
+        meta_tag['property'] = property
+        meta_tag.content = content
+      }
+    end
+
+
+    # Updates the viewBox or meta-viewport declaration in the
+    # component document (SVG or HTML respectively), creating
+    # tags/attributes as necessary.
+    #
+    def add_icb_to_component(cmpt_file, icb)
+      cmpt_doc = cmpt_file.document
+      if cmpt_file.media_type.match(/svg/)
+        cmpt_doc.root['viewBox'] = icb.join(' ')
+      elsif viewport_meta = cmpt_doc.find('meta[name="viewport"]')
+        vpc = viewport_meta['content']
+        vpc.gsub!(/width\s*=\s*\d+/, "width=#{icb['width']}")
+        vpc.gsub!(/height\s*=\s*\d+/, "height=#{icb['height']}")
+        viewport_meta['content'] = vpc
+      else
+        cmpt_doc.new_node('meta', :append => 'head') { |viewport_meta_tag|
+          viewport_meta_tag['name'] = 'viewport'
+          viewport_meta_tag['content'] =
+            "width=#{icb['width']},height=#{icb['height']}"
+        }
+      end
+    end
+
+end

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

@@ -0,0 +1,38 @@
+class BbEPUB::Transform::Resources < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::OPF]
+  end
+
+
+  # Find all the items in the manifest -- except all spine items, the NCX,
+  # and the NAV.
+  #
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+    items = opf_doc.search('opf|manifest > opf|item')
+    package.map['resources'] = items.collect { |item|
+      path = package.make_path(item['href'])
+      {
+        'path' => path,
+        'media-type' => item['media-type'],
+        'id' => item['id'] || package.make_id(path)
+      }
+    }
+  end
+
+
+  def from_map(package)
+    return  unless package.map['resources']
+    opf_doc = package.file(:opf).document
+    manifest_tag = opf_doc.find('opf|manifest')
+    package.map['resources'].each { |rsrc|
+      opf_doc.new_node('item', :append => manifest_tag) { |manifest_item_tag|
+        manifest_item_tag['href'] = package.make_href(rsrc['path'])
+        manifest_item_tag['media-type'] = rsrc['media-type']
+        manifest_item_tag['id'] = rsrc['id']
+      }
+    }
+  end
+
+end

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

@@ -0,0 +1,79 @@
+class BbEPUB::Transform::Spine < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::Resources]
+  end
+
+
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+    itemrefs = opf_doc.search('opf|spine > opf|itemref')
+    package.map['spine'] = itemrefs.collect { |itemref|
+      cmpt = package.map['resources'].detect { |r| r['id'] == itemref['idref'] }
+      if cmpt
+        package.map['resources'].delete(cmpt)
+        cmpt['linear'] = itemref['linear'] == 'no' ? false : true
+        cmpt
+      else
+        package.warn("No manifest item for spine idref: #{itemref['idref']}")
+      end
+    }.compact
+  end
+
+
+  def from_map(package)
+    opf_doc = package.file(:opf).document
+
+    package.map['spine'].each { |cmpt|
+      # Convert component to valid XHTML
+      cmpt_file = package.file(cmpt['path'])
+      cmpt_doc = cmpt_file.document
+      # Add the EPUB namespace:
+      # FIXME: only add the EPUB namespace if there are any epub:* attrs?
+      cmpt_doc.add_namespace('epub')
+
+      # Update the OPF manifest
+      opf_doc.new_node('item', :append => 'opf|manifest') { |manifest_item_tag|
+        manifest_item_tag['href'] = package.make_href(cmpt['path'])
+        manifest_item_tag['id'] = cmpt['id']
+        manifest_item_tag['media-type'] = cmpt['media-type']
+        props = component_properties(cmpt, cmpt_doc)
+        manifest_item_tag['properties'] = props.join(' ')  if props.any?
+      }
+
+      # Update the OPF spine
+      opf_doc.new_node('itemref', :append => 'opf|spine') { |spine_item_tag|
+        spine_item_tag['idref'] = cmpt['id']
+        spine_item_tag['linear'] = 'no'  unless cmpt['linear']
+      }
+    }
+  end
+
+
+  protected
+
+    # Assemble the component properties by inspecting the HTML...
+    # because some reading systems can't do this themselves, I guess.
+    #
+    # NB: the 'cover-image' and 'nav' properties will be set in
+    # other tranforms.
+    #
+    def component_properties(cmpt, cmpt_doc)
+      [].tap { |props|
+        # 'scripted': check whether there are any script tags in the component.
+        props.push('scripted')  if cmpt_doc.find('script')
+
+        # 'mathml': look for a math element
+        props.push('mathml')  if cmpt_doc.find('math, mathml:math')
+
+        # 'remote-resources': TODO
+
+        # 'svg': look for an svg element
+        props.push('svg')  if cmpt_doc.find('svg, svg:svg')
+
+        # 'switch': look for an epub:switch element
+        props.push('switch')  if cmpt_doc.find('epub|switch')
+      }
+    end
+
+end

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

@@ -0,0 +1,92 @@
+# EPUB2 spec:
+#
+#   http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm#Section2.2.1
+#
+# EPUB3 spec:
+#
+#   http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-opf-dctitle
+#
+# On title types:
+#
+# "When the title-type value is drawn from a code list or other formal
+# enumeration, the scheme attribute should be attached to identify its source.
+# When a scheme is not specified, Reading Systems should recognize the
+# following title type values: main, subtitle, short, collection, edition
+# and expanded."
+#
+class BbEPUB::Transform::Title < Bookbinder::Transform
+
+  TITLE_TYPES = %w[main subtitle short collection edition expanded]
+
+
+  def dependencies
+    [BbEPUB::Transform::Metadata, BbEPUB::Transform::NCX]
+  end
+
+
+  def to_map(package)
+    package.map['title'] = titles = {}
+    return  unless package.map['metadata']
+    return  unless metadata_array = package.map['metadata']['title']
+    title_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
+    }
+    title_data.each { |tdata|
+      t = tdata['@']
+      type = tdata['title-type'] ? tdata['title-type']['@'] : 'main'
+      next  unless TITLE_TYPES.include?(type)
+      if titles[type]
+        package.warn("Existing title for '#{type}' - discarding '#{t}'")
+      else
+        titles[type] = t
+        metadata_array.delete(tdata)
+      end
+    }
+    # Now that we have "used" the raw metadata for titles, remove it.
+    package.map['metadata'].delete('title')  if metadata_array.empty?
+  end
+
+
+  def from_map(package)
+    titles = package.map['title']
+    opf_doc = package.file(:opf).document
+    metadata_tag = opf_doc.find('opf|metadata')
+    seq = 0
+    titles.each_pair { |type, title|
+      title_tag = opf_doc.new_node('dc:title', :append => metadata_tag)
+      title_tag.content = title
+      if titles.length > 1
+        seq += 1
+        title_id = "dc-title-metadata-#{seq}"
+        title_tag['id'] = title_id
+        opf_doc.new_node('meta', :append => metadata_tag) { |type_meta_tag|
+          type_meta_tag.content = type
+          type_meta_tag['property'] = 'title-type'
+          type_meta_tag['refines'] = '#'+title_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'] = '#'+title_id
+        }
+      end
+    }
+
+    # Add it to the NCX if that file exists in the package
+    package.if_file(:ncx) { |ncx_file|
+      ncx_title = [titles['main'], titles['subtitle']].compact.join(': ')
+      ncx_doc = ncx_file.document
+      ncx_doc.new_node('docTitle') { |doc_title_tag|
+        ncx_doc.new_node('text', :append => doc_title_tag) { |text_tag|
+          text_tag.content = ncx_title
+        }
+        ncx_doc.find('ncx|head').add_next_sibling(doc_title_tag)
+      }
+    }
+  end
+
+end

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

@@ -0,0 +1,39 @@
+# See https://itunesconnect.apple.com/docs/iBooksAssetGuide5.1Revision2.pdf
+# pages 22 and 23.
+#
+# "The version of your book is specified within a `meta` element
+# in the Package Document. The `meta` element has a property value
+# of `ibooks:version':
+#
+#   <meta property="ibooks:version">1.1.2</meta>
+#
+class BbEPUB::Transform::Version < Bookbinder::Transform
+
+  def dependencies
+    [BbEPUB::Transform::Metadata]
+  end
+
+
+  def to_map(package)
+    ver_hashes = package.map['metadata'].delete('ibooks:version')
+    if ver_hashes && ver_hashes.any?
+      package.map['version'] = ver_hashes.first['@']
+    end
+  end
+
+
+  def from_map(package)
+    if package.map['version']
+      # Add the ibooks prefix to the package root.
+      opf_doc = package.file(:opf).document
+      opf_doc.add_prefix('ibooks')
+
+      # Create the meta node and append it to <metadata>
+      opf_doc.new_node('meta', :append => 'opf|metadata') { |ver_tag|
+        ver_tag['property'] = 'ibooks:version'
+        ver_tag.content = package.map['version']
+      }
+    end
+  end
+
+end

data/lib/bb-epub/version.rb

@@ -0,0 +1,5 @@
+module BbEPUB
+
+  VERSION = "0.0.1"
+
+end

data/lib/bb-epub.rb

@@ -0,0 +1,10 @@
+require 'bookbinder'
+
+module BbEPUB
+end
+
+module BbEPUB::Transform
+end
+
+require 'bb-epub/version'
+require 'bb-epub/package'