bookbinder 0.2.0

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

@@ -0,0 +1,177 @@
+class Bookbinder::Transform::EPUB_NavToc < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Nav, Bookbinder::Transform::EPUB_NCX]
+  end
+
+
+  def to_map(package)
+    toc = []
+    package.if_file(:nav) { |nav_file|
+      nav_doc = nav_file.document('r')
+      base_path = content_rooted_path(package.content_root, nav_file.path)
+      nav_doc.each('nav[epub|type="toc"] > ol > li') { |li|
+        toc.push(extract_nav_chapter(nav_doc, li, base_path))
+      }
+    }
+    unless toc.any?
+      package.if_file(:ncx) { |ncx_file|
+        ncx_doc = ncx_file.document
+        base_path = content_rooted_path(package.content_root, ncx_file.path)
+        ncx_doc.each('ncx|navMap > ncx|navPoint') { |point|
+          toc.push(extract_ncx_chapter(ncx_doc, point, base_path))
+        }
+      }
+    end
+    if toc.any?
+      package.map['nav'] ||= {}
+      package.map['nav']['toc'] = toc
+    end
+  end
+
+
+  def from_map(package)
+    package.if_file(:ncx) { |ncx_file|
+      @max_depth = 0
+      @chapter_count = 0
+      toc = (package.map['nav'] || {})['toc'] || []
+      build_ncx_map(ncx_file.document, toc)
+      build_ncx_depth_meta(ncx_file.document, @max_depth)
+    }
+    package.if_file(:nav) { |nav_file|
+      toc = (package.map['nav'] || {})['toc'] || []
+      build_nav_tag(nav_file.document, toc)
+    }
+  end
+
+
+  protected
+
+    # NAV to_map
+
+    def extract_nav_chapter(doc, li, base_path)
+      {}.tap { |chp|
+        content_node = doc.find_within(li, '> a, span')
+        chp['title'] = content_node['title'] || content_node.content.strip
+        if content_node.node_name.downcase == 'a'
+          chp['path'] = resolved_path(base_path, content_node['href'])
+        end
+        children = doc.search_within(li, '> li')
+        if children.any?
+          chp['contents'] = children.collect { |child|
+            extract_nav_chapter(doc, child, base_path)
+          }
+        end
+      }
+    end
+
+
+    # NCX to_map
+
+    def extract_ncx_chapter(doc, point, base_path)
+      {
+        'title' => doc.find_within(point, 'text').text,
+        'path' => resolved_path(
+          base_path,
+          doc.find_within(point, 'content')['src']
+        )
+      }.tap { |out|
+        children = doc.search_within(point, '> navPoint')
+        if children.any?
+          out['contents'] = children.collect { |pt|
+            extract_ncx_chapter(doc, pt, base_path)
+          }
+        end
+      }
+    end
+
+
+    # NAV from_map
+
+    def build_nav_tag(nav_doc, toc)
+      nav_tag_frag = Nokogiri::XML::DocumentFragment.parse('')
+      Nokogiri::XML::Builder.with(nav_tag_frag) { |x|
+        x.nav('epub:type' => 'toc') { build_nav_ol_for_chapters(x, toc) }
+      }
+      nav_doc.find('body').add_child(nav_tag_frag)
+    end
+
+
+    def build_nav_ol_for_chapters(x, chapters)
+      x.ol {
+        chapters.each { |chp|
+          x.li {
+            atts = { 'href' => chp['path'] }
+            x.a(chp['title'], atts)
+            build_nav_ol_for_chapters(x, chp['contents'])  if chp['contents']
+          }
+        }
+      }
+    end
+
+
+    # NCX from_map
+
+    def build_ncx_map(ncx_doc, toc)
+      nav_map_frag = Nokogiri::XML::DocumentFragment.parse('')
+      Nokogiri::XML::Builder.with(nav_map_frag) { |x|
+        x.navMap {
+          toc.each { |chp| build_ncx_point_for_chapter(x, chp, 0) }
+        }
+      }
+      ncx_doc.root.add_child(nav_map_frag)
+    end
+
+
+    def build_ncx_depth_meta(ncx_doc, max_depth)
+      ncx_doc.new_node('meta', :append => 'ncx|head') { |depth_meta_tag|
+        depth_meta_tag['name'] = 'dtb:depth'
+        depth_meta_tag['content'] = max_depth
+      }
+    end
+
+
+    def build_ncx_point_for_chapter(x, chp, depth)
+      @chapter_count += 1
+      depth += 1
+      @max_depth = depth  if depth > @max_depth
+      x.navPoint(
+        'id' => "toc-#{@chapter_count}",
+        'class' => 'chapter',
+        'playOrder' => @chapter_count
+      ) {
+        x.navLabel { x.text_(chp['title']) }
+        x.content('src' => chp['path'])
+        if chp['children']
+          chp['children'].each { |chd|
+            build_ncx_point_for_chapter(x, chd, depth)
+          }
+        end
+      }
+    end
+
+
+    # Utilities
+    def content_rooted_path(content_root, path)
+      File.dirname(path).sub(/^#{content_root}\/?/, '').sub(/^\.$/, '')
+    end
+
+
+    def resolved_path(base_path, path)
+      relative_path = File.join(base_path, path).sub(/^\//, '')
+      relative_parts = relative_path.split('/')
+      resolved_parts = []
+      while relative_parts.any?
+        part = relative_parts.shift
+        if part == '.'
+          # do nothing
+        elsif part == '..'
+          resolved_parts.pop
+        else
+          resolved_parts.push(part)
+        end
+      end
+      File.join(resolved_parts)
+    end
+
+end

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

@@ -0,0 +1,63 @@
+class Bookbinder::Transform::EPUB_NCX < Bookbinder::Transform
+
+  DEFAULT_FILE_NAME = 'book.ncx'
+
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_Resources]
+  end
+
+
+  def to_map(package)
+    opf_doc = package.file(:opf).document('r')
+    spine = opf_doc.find('opf|spine')
+    if spine && ncx_id = spine['toc']
+      ncx_item = opf_doc.find('opf|manifest > opf|item[id="'+ncx_id+'"]')
+      ncx_path = package.make_path(ncx_item['href'])
+      package.file_aliases[:ncx] = ncx_path
+      package.map['resources'].delete_if { |rsrc|
+        package.file_path(rsrc['path']) == ncx_path
+      }
+    end
+  end
+
+
+  def from_map(package)
+    if package.options['ncx_file'] != false
+      stub_ncx(package)
+      add_to_opf_manifest(package)
+    end
+  end
+
+
+  protected
+
+    def stub_ncx(package)
+      package.file_aliases[:ncx] = DEFAULT_FILE_NAME
+      package.file(:ncx).new_xml_document { |doc, x|
+        x.ncx('version' => '2005-1', 'xml:lang' => 'en') {
+          doc.add_node_namespace(x.parent, 'ncx', true)
+          x.head {
+            x.meta(
+              'name' => 'dtb:generator',
+              'content' => "Bookbinder #{Bookbinder::VERSION}"
+            )
+          }
+        }
+      }
+    end
+
+
+    def add_to_opf_manifest(package)
+      opf_file = package.file(:opf)
+      ncx_file = package.file(:ncx)
+      ncx_id = package.make_id(DEFAULT_FILE_NAME)
+      opf_file.document.new_node('item', :append => 'opf|manifest') { |item_tag|
+        item_tag['href'] = package.make_href(DEFAULT_FILE_NAME)
+        item_tag['media-type'] = ncx_file.media_type
+        item_tag['id'] = ncx_id
+      }
+      opf_file.document.find('opf|spine')['toc'] = ncx_id
+    end
+
+end

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

@@ -0,0 +1,33 @@
+class Bookbinder::Transform::EPUB_OCF < Bookbinder::Transform
+
+  OCF_PATH = 'META-INF/container.xml'
+
+  # No dependencies! Something has to have no dependencies, after all.
+
+  def to_map(package)
+    package.file_aliases[:ocf] = OCF_PATH
+    ocf = package.file(:ocf, false)
+    opf_path = ocf.document('r').find('ocf|rootfile')['full-path']
+    package.file_aliases[:opf] = File.basename(opf_path)
+    package.content_root = File.dirname(opf_path).sub(/^\./, '')
+  end
+
+
+  def from_map(package)
+    package.file_aliases[:ocf] = OCF_PATH
+    package.file_aliases[:opf] = 'book.opf'
+    opf_file = package.file(:opf)
+    package.file(:ocf, false).new_xml_document { |doc, x|
+      x.container('version' => '1.0') {
+        doc.add_node_namespace(x.parent, 'ocf', true)
+        x.rootfiles {
+          x.rootfile(
+            'full-path' => opf_file.path,
+            'media-type' => opf_file.media_type
+          )
+        }
+      }
+    }
+  end
+
+end

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

@@ -0,0 +1,22 @@
+class Bookbinder::Transform::EPUB_OPF < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_OCF]
+  end
+
+
+  def from_map(package)
+    package.file(:opf).new_xml_document { |opf_doc, x|
+      x.package('version' => '3.0') {
+        opf_doc.add_node_namespace(x.parent, 'opf', true)
+        x.metadata {
+          opf_doc.add_node_namespace(x.parent, 'dc')
+          opf_doc.add_node_namespace(x.parent, 'dcterms')
+        }
+        x.manifest
+        x.spine
+      }
+    }
+  end
+
+end

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

@@ -0,0 +1,265 @@
+# 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 Bookbinder::Transform::EPUB_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
+    [Bookbinder::Transform::EPUB_Spine, Bookbinder::Transform::EPUB_Metadata]
+  end
+
+
+  def to_map(package)
+    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 = book_properties['rendition-viewport']
+          book_properties['rendition-viewport'] = parse_viewport_string(vpt)
+        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
+      }
+    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/bookbinder/transform/epub/resources.rb

@@ -0,0 +1,38 @@
+class Bookbinder::Transform::EPUB_Resources < Bookbinder::Transform
+
+  def dependencies
+    [Bookbinder::Transform::EPUB_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