gepub 0.6.4.6 → 0.6.5.1

data/gepub.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rspec", ">= 2"
-  s.add_runtime_dependency "nokogiri", ">= 1.5.0"
-  s.add_runtime_dependency "rubyzip", ">= 0.9.6"
+  s.add_development_dependency "rspec", "~> 2"
+  s.add_runtime_dependency "nokogiri", "~> 1.5.0"
+  s.add_runtime_dependency "rubyzip", "= 0.9.6.1"
 end

data/lib/gepub/book.rb

@@ -7,19 +7,23 @@ require 'fileutils'
 # = GEPUB 
 # Author:: KOJIMA Satoshi
 # namespace for gepub library.
-# GEPUB::Book for parsing/generating, GEPUB::Builder for generating.
-# GEPUB::Item holds data of resources like xhtml text, css, scripts, images, videos, etc.
+# The core class is GEPUB::Book. It holds metadata and contents of EPUB file. metadata and contents can be accessed
+# through GEPUB::Meta and GEPUB::Item.
+# For generating EPUB file,  use GEPUB::Builder.
+# GEPUB::Item holds information and data  of resources like xhtml text, css, scripts, images, videos, etc.
 # GEPUB::Meta holds metadata(title, creator, publisher, etc.) with its information (alternate script, display sequence, etc.)
 
 module GEPUB
-  # Book is the basic class to hold data in EPUB files.
+  # Book is the class to hold data in EPUB files.
   # 
-  # It can generate and parse EPUB2/EPUB3 files. For generating a new EPUB file,
-  # consider to use GEPUB::Builder. Builder is specialized for generating EPUB, 
-  # very easy to use and can handle almost every metadata of EPUB3.
+  # It can generate and parse EPUB2/EPUB3 files.
+  #
+  # If you want to generate a new EPUB file, consider using GEPUB::Builder instead
+  # of using Book directly.
+  # Builder is a wrapper class of Book specialized for generating EPUB.
   # 
   # Book delegates many methods to objects in other class, so you can't find
-  # them in Book#methods or in ri/rdoc documentation. Their description is below.
+  # them in Book#methods or in ri/rdoc documentation. Their descriptions are below.
   #
   # == \Package Attributes
   # === Book#version (delegated to Package#version)
@@ -133,7 +137,7 @@ module GEPUB
           end
         }
         book = Book.new(package.path)
-        book.instance_eval { @package = package; @stray_files = files }
+        book.instance_eval { @package = package; @optional_files = files }
         book
       }
     end
@@ -150,6 +154,22 @@ module GEPUB
       yield book if block_given?
     end
 
+
+    # Get optional(not required in EPUB specification) files in the container.
+    def optional_files
+      @optional_files || {}
+    end
+
+    # Add an optional file to the container
+    def add_optional_file(path, io_or_filename)
+      io = io_or_filename
+      if io_or_filename.class == String
+        io = File.new(io_or_filename)
+      end
+      io.binmode
+      (@optional_files ||= {})[path] = io.read
+    end
+    
     # add navigation text (which will appear on navigation document or table of contents) to an item.
     # DEPRECATED: please use Item#toc_text or Item#toc_text_with_id, or Builder#heading
 
@@ -236,22 +256,30 @@ module GEPUB
     end
 
     # write EPUB to stream specified by the argument.
-    def write_to_epub_container(epub) 
+    def write_to_epub_container(epub)
       epub.put_next_entry('mimetype', '', '', Zip::ZipEntry::STORED)
       epub << "application/epub+zip"
-      epub.put_next_entry('META-INF/container.xml')
-      epub << container_xml.force_to_bin
 
-      epub.put_next_entry(@package.path)
-      epub << opf_xml.force_to_bin
+      entries = {}
+      optional_files.each {
+        |k, content|
+        entries[k] = content
+      }
 
+      entries['META-INF/container.xml'] = container_xml
+      entries[@package.path] = opf_xml
       @package.manifest.item_list.each {
         |k, item|
         if item.content != nil
-          epub.put_next_entry(@package.contents_prefix + item.href)
-           epub << item.content.force_to_bin
+          entries[@package.contents_prefix + item.href] = item.content
         end
       }
+
+      entries.sort_by { |k,v| k }.each {
+        |k,v|
+        epub.put_next_entry(k)
+        epub << v.force_to_bin
+      }
     end
 
     # generates and returns StringIO contains EPUB.

data/lib/gepub/builder.rb

@@ -1,4 +1,152 @@
+# -*- coding: utf-8 -*-
 module GEPUB
+  #
+  # Builder is a wrapper class of Book. It provides DSL to create new EPUB file.
+  #
+  # = Synopsys
+  #      # -*- coding: utf-8 -*-
+  #      # GEPUB::Builder example.
+  #      require 'ruby gem'
+  #      require 'gepub'
+  #
+  #      builder = GEPUB::Builder.new {
+  #        # In the root block, you can define metadata.
+  #        # You can define title, creator(s), contributor(s), publisher(s), date, unique_identifier, identifier, language.
+  #        # Title can be specified with title, subtitle, collection, short_title, expanded_title, edition. 
+  #        # You can also define description, format, relation, right, source, subject, type.
+  #        # You can 'refine' last-defined metadata by refiner/attributes methods
+  #        # Refiner methods contains : file_as, alt 
+  #        
+  #
+  #        language 'ja'
+  #
+  #        title 'タイトル'
+  #        alt 'en' => 'main title'
+  #        file_as 'main title'
+  #
+  #        subtitle 'サブタイトル'  
+  #        alt 'en' => 'subtitle'
+  #
+  #        # collection title and position in the collection:
+  #        collection 'gepub sample book series', 2
+  #
+  #        #specifying creator
+  #        creator 'author1','aut'
+  #        alt 'ja' =>'日本語名' ,'en' =>'english name for author1'
+  #        id 'the_first_author'
+  #
+  #        #specifying multiple creator
+  #        creators 'author1', 'author2', ['editor1', 'edt']
+  #
+  #        contributor 'contributor'
+  #        contributors 'contributor1', 'contributor2'
+  #        # easy way to write alt {'ja' =>'日本語 for contributor1'}, {'ja' => '日本語 for contributor2'}
+  #        alts 'ja' => ['日本語 for contributor1','日本語 for contributor2'] 
+  #
+  #        publisher '出版社'
+  #        alt 'en' => 'ThePublisher'
+  #        
+  #        date '2012-02-21T00:00:00Z'
+  #
+  #        unique_identifier 'the_unique_id_in_uuid', 'uuid'
+  #        identifier 'http://other_id','url'
+  #        identifier 'http://another_id','url'
+  #
+  #        # in resources block, you can define resources by its relative path and datasource.
+  #        # item creator methods are: files, file.
+  #        resources(:workdir => '~/epub_source') {
+  #          # Reads from file. in EPUB container, they are placed at the same path.
+  #          file 'img/image0.jpg'
+  #          files('img/image.jpg','img/image2.jpg')
+  #          glob 'img/*.jpg' # means files(Dir.glob('img/*.jpg'))
+  #
+  #          # Reads from file. will be placed at path indicated by key.
+  #          files('img/image.jpg' => 'imgage.jpg')
+  #
+  #          # Read from IO object.
+  #          files('img/image.png' => supplied_io, 'img/image2.png' => supplied_io2)
+  #
+  #          # this will be end in error:
+  #          # files(io1, io2)
+  #
+  #          # specify remote resource.
+  #          # only referenced from the EPUB package.
+  #          file 'http://example.com/video/remote_video.qt'
+  #          media_type('video/quicktime')
+  #
+  #          # specify media type. 
+  #          file 'resources/pv.mp4'
+  #          media_type('video/mp4')
+  #
+  #          files('audio/voice1.mp4','audio/music1.mp4')
+  #          media_type('audio/mp4')  # applied to all items in the line above.
+  #
+  #          # media_type to some file
+  #          with_media_type('video/mp4') {
+  #            file 'resources/v1.mp4'
+  #            file 'resources/v2.mp4'
+  #            file 'resources/v3.mp4'
+  #          }
+  #
+  #          # with_media_type and media_type 
+  #          with_media_type('video/mp4') {
+  #            file 'resources/v1.mp4'
+  #            file 'resources/v2.mp4'
+  #            file 'resources/a4.mp4'
+  #            media_type 'audio/mp4' # override with_media_type
+  #          }
+  #
+  #          # Read from IO object: loop
+  #          # supplied_IOs = { 'path' => io, 'path' => io... }
+  #          supplied_IOs.each {
+  #            |name, io|
+  #            file name => io
+  #          }
+  #
+  #          file 'css/default.css'
+  #
+  #          # indicate property.
+  #          # this is cover image.
+  #          cover_image 'img/cover.jpg'
+  #
+  #          # this is navigation document.
+  #          nav 'text/toc.xhtml'
+  #
+  #          # ordered item. will be added to spine.
+  #          ordered {
+  #            # specify texts on table of contents for auto-generated toc.
+  #            # (if you supply navigation document with method 'nav',  'heading' has no effect.)
+  #            file('text/chap1.xhtml')
+  #            heading 'Chapter 1'
+  #            file 'text/chap2.xhtml'
+  #            
+  #            # fallback chain: style 1
+  #            fallback_group {
+  #              file 'chap3_docbook.xhtml'
+  #              mimetype('application/docbook+xml')
+  #              file 'chap3.xml'
+  #              mimetype "application/z3986-auth+xml"
+  #              file 'chap3.xhtml'
+  #            }
+  #
+  #            # fallback chain: style 2
+  #            fallback_chain_files 'chap4_docbook.xhtml', 'chap4.xml', 'chap4.xhtml'
+  #            mimetype('application/docbook+xml','application/z3986-auth+xml' 'application/xhtml+xml')
+  #
+  #            # fallback chain: style 3 + with_mimetype
+  #            with_mimetype('application/docbook+xml','application/z3986-auth+xml' 'application/xhtml+xml') {
+  #              fallback_chain_files 'chap5_docbook.xhtml', 'chap5.xml', 'chap5.xhtml' 
+  #              fallback_chain_files 'chap6_docbook.xhtml', 'chap6.xml', 'chap6.xhtml' 
+  #              fallback_chain_files 'chap7_docbook.xhtml', 'chap7.xml', 'chap7.xhtml' 
+  #            }
+  #
+  #          }
+  #        }
+  #      }
+  #
+  #      builder.generate_epub('sample.epub')
+
+
   class Builder
     include BuilderMixin
     class MetaItem
@@ -112,6 +260,21 @@ module GEPUB
       MetaItem.new(@book.add_contributor(val, nil, role))
     end
 
+    # set optional file.
+    # val should be String or Hash.
+    # if val is String, file is read from the File specified by string and stored in EPUB to the path specified by string.
+    # if val is Hash, file is read from the value and stored in EPUB to the path specified by the key.
+    def optional_file(val)
+      path = val
+      io = val if String === val
+      if Hash === val
+        raise 'argument to optional_file should be length 1' if val.size != 1
+        path = val.first[0]
+        io = val.first[1]
+      end
+      @book.add_optional_file(path, io)
+    end
+    
     def generate_epub(path_to_epub)
       @book.generate_epub(path_to_epub)
     end

data/lib/gepub/item.rb

@@ -1,4 +1,10 @@
 module GEPUB
+  #
+  # an Object to hold metadata and content of item in manifest.
+  #
+  # following methods are created dynamically.
+  # #id, #id=, #set_id, #href, #href=, #set_href, #media_type, #media_type=, #set_media_type,
+  # #fallback, #fallback=, #set_fallback, #media_overlay, #media_overlay=, #set_media_overlay
   class Item
     attr_accessor :content
     def self.create(parent, attributes = {})
@@ -6,6 +12,12 @@ module GEPUB
                attributes.reject { |k,v| ['id','href','media-type'].member?(k) })
     end
 
+    #
+    # create Item.
+    # 
+    # if mediatype is not specified, it will be guessed from extension name.
+    # Item can't guess media type for videos and  audios, so you should specify one.
+    # 
     def initialize(itemid, itemhref, itemmediatype = nil, parent = nil, attributes = {})
       if attributes['properties'].class == String
         attributes['properties'] = attributes['properties'].split(' ')
@@ -14,7 +26,6 @@ module GEPUB
       @attributes['media-type'] =  guess_mediatype if media_type.nil?
       @parent = parent
       @parent.register_item(self) unless @parent.nil?
-      @content_callback = []
       self
     end
 
@@ -25,14 +36,16 @@ module GEPUB
       define_method(methodbase) { @attributes[name] }
     }
 
+    # get item's id
     def itemid
       id
     end
 
+    # get mediatype of the item.
     def mediatype
       media_type
     end
-    
+
     def [](x)
       @attributes[x]
     end
@@ -40,28 +53,61 @@ module GEPUB
     def []=(x,y)
       @attributes[x] = y
     end
-    
+
+    # add value to properties attribute.
     def add_property(property)
       (@attributes['properties'] ||=[]) << property
       self
     end
 
+    # set 'cover-image' property to the Item.
+    # On generating EPUB, EPUB2-style cover image meta item will be added.
     def cover_image
       add_property('cover-image')
     end
 
+    # set 'nav' property to the Item.
     def nav
       add_property('nav')
     end
 
-    def add_raw_content(data)
-      @content = data
+    # guess and set content property from contents.
+    def guess_content_property
+      if File.extname(self.href) =~ /.x?html/
+        @attributes['properties'] = (@attributes['properties'] || []).reject {
+          |x| x == 'svg' || x == 'mathml' || x == 'switch' || x == 'remote-resources'
+        }
+        parsed = Nokogiri::XML::Document.parse(@content)
+        ns_prefix =  parsed.namespaces.invert['http://www.w3.org/1999/xhtml']
+        if ns_prefix.nil?
+          prefix = ''
+        else
+          prefix = "#{ns_prefix}:"
+        end
+        videos = parsed.xpath("//#{prefix}video[starts-with(@src,'http')]")
+        audios = parsed.xpath("//#{prefix}audio[starts-with(@src,'http')]")
+        if videos.size > 0 || audios.size > 0
+          self.add_property('remote-resources')
+        end
+        if parsed.xpath("//p:math", { 'p' => 'http://www.w3.org/1998/Math/MathML' }).size > 0
+          self.add_property('mathml')
+        end
+        if parsed.xpath("//s:svg", { 's' => 'http://www.w3.org/2000/svg' }).size > 0
+          self.add_property('svg')
+        end
+        if parsed.xpath("//epub:switch", { 'epub' => 'http://www.idpf.org/2007/ops' }).size > 0
+          self.add_property('switch')
+        end
+      end
     end
 
-    def push_content_callback(&block)
-      @content_callback << block
+    # add content data to the item.
+    def add_raw_content(data)
+      @content = data
+      guess_content_property
     end
 
+    # add content form io or file to the item
     def add_content(io_or_filename)
       io = io_or_filename
       if io_or_filename.class == String
@@ -69,23 +115,11 @@ module GEPUB
       end
       io.binmode
       @content = io.read
-      if File.extname(self.href) =~ /.x?html/
-        parsed = Nokogiri::XML::Document.parse(@content)
-        ns_prefix =  parsed.namespaces.invert['http://www.w3.org/1999/xhtml']
-          if ns_prefix.nil?
-            prefix = ''
-          else
-            prefix = "#{ns_prefix}:"
-          end
-          videos = parsed.xpath("//#{prefix}video[starts-with(@src,'http')]")
-          audios = parsed.xpath("//#{prefix}audio[starts-with(@src,'http')]")
-          if videos.size > 0 || audios.size > 0
-            self.add_property('remote-resources')
-          end
-      end
+      guess_content_property
       self
     end
 
+    # generate xml to supplied Nokogiri builder.
     def to_xml(builder, opf_version = '3.0')
       attr = @attributes.dup
       if opf_version.to_f < 3.0
@@ -93,6 +127,9 @@ module GEPUB
       end
       if !attr['properties'].nil?
         attr['properties'] = attr['properties'].join(' ')
+        if attr['properties'].size == 0
+          attr.delete 'properties'
+        end
       end
       builder.item(attr)
     end

data/lib/gepub/rubyzip_patch.rb

@@ -0,0 +1,11 @@
+require 'zip/zip'
+
+module Zip
+  class ZipCentralDirectory
+    def write_to_stream(io)  #:nodoc:
+      offset = io.tell
+      @entrySet.each { |entry| entry.write_c_dir_entry(io) }
+      write_e_o_c_d(io, offset)
+    end
+  end
+end

data/lib/gepub/version.rb

@@ -1,3 +1,4 @@
 module GEPUB
-  VERSION = "0.6.4.6"
+  # GEPUB gem version 
+  VERSION = "0.6.5.1"
 end

data/lib/gepub.rb

@@ -18,7 +18,7 @@ else
   end
 end
 
-
+require 'gepub/rubyzip_patch'
 require 'gepub/version'
 require 'gepub/xml_util'
 require 'gepub/meta'

data/spec/builder_spec.rb

@@ -437,5 +437,65 @@ describe GEPUB::Builder do
       }
       # this should not raise 'No such file or directory'
     end
+
+    it 'should handle mathml' do
+      builder = GEPUB::Builder.new {
+        unique_identifier 'uid'
+        resources {
+          file 'mathml.xhtml' => StringIO.new('<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"><head></head><body><div><p><math xmlns="http://www.w3.org/1998/Math/MathML"></math></p></div></body></html>')
+        }
+      }
+      builder.instance_eval {
+        @book.item_by_href('mathml.xhtml').properties[0].should == 'mathml'
+      }
+    end
+
+    it 'should handle svg' do
+      builder = GEPUB::Builder.new {
+        unique_identifier 'uid'
+        resources {
+          file 'svg.xhtml' => StringIO.new('<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"><head></head><body><div><p><svg xmlns="http://www.w3.org/2000/svg"></svg></p></div></body></html>')
+        }
+      }
+      builder.instance_eval {
+        @book.item_by_href('svg.xhtml').properties[0].should == 'svg'
+      }
+    end
+
+    it 'should handle epub:switch' do
+      builder = GEPUB::Builder.new {
+        unique_identifier 'uid'
+        resources {
+          file 'switch.xhtml' => StringIO.new('<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"><head></head><body><div><p>
+<epub:switch>
+   <epub:case required-namespace="http://www.xml-cml.org/schema">
+      <cml xmlns="http://www.xml-cml.org/schema">
+         <molecule id="sulfuric-acid">
+            <formula id="f1" concise="H 2 S 1 O 4"/>
+         </molecule>
+      </cml>
+   </epub:case>
+   <epub:default>
+      <p>H<sub>2</sub>SO<sub>4</sub></p>
+   </epub:default>
+</epub:switch></p></div></body></html>')
+        }
+      }
+      builder.instance_eval {
+        @book.item_by_href('switch.xhtml').properties[0].should == 'switch'
+      }
+    end
+
+    it 'should handle optional file' do
+      builder = GEPUB::Builder.new {
+        optional_file 'META-INF/test.xml' => StringIO.new('<test></test>')
+      }
+      builder.instance_eval {
+        @book.optional_files.size.should == 1
+      }
+      builder.instance_eval {      
+        @book.optional_files['META-INF/test.xml']
+      }.should_not be_nil
+    end
   end
 end

data/spec/gepub_spec.rb

@@ -189,6 +189,12 @@ EOF
     jar = File.join(File.dirname(__FILE__), 'fixtures/epubcheck-3.0b4/epubcheck-3.0b4.jar')
     system 'java', '-jar', jar, epubname
   end
-
+  it 'should generate epub with extra file' do
+    epubname = File.join(File.dirname(__FILE__), 'testepub3.epub')
+    @book.add_optional_file('META-INF/foobar.xml', StringIO.new('<foo></foo>'))
+    @book.generate_epub(epubname)
+    jar = File.join(File.dirname(__FILE__), 'fixtures/epubcheck-3.0b4/epubcheck-3.0b4.jar')
+    system 'java', '-jar', jar, epubname
+  end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gepub
 version: !ruby/object:Gem::Version
-  version: 0.6.4.6
+  version: 0.6.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,41 +9,41 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-04 00:00:00.000000000 Z
+date: 2012-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70096651811060 !ruby/object:Gem::Requirement
+  requirement: &70119775057080 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '2'
   type: :development
   prerelease: false
-  version_requirements: *70096651811060
+  version_requirements: *70119775057080
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70096651810400 !ruby/object:Gem::Requirement
+  requirement: &70119775056340 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: 1.5.0
   type: :runtime
   prerelease: false
-  version_requirements: *70096651810400
+  version_requirements: *70119775056340
 - !ruby/object:Gem::Dependency
   name: rubyzip
-  requirement: &70096651809700 !ruby/object:Gem::Requirement
+  requirement: &70119775055860 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - =
       - !ruby/object:Gem::Version
-        version: 0.9.6
+        version: 0.9.6.1
   type: :runtime
   prerelease: false
-  version_requirements: *70096651809700
+  version_requirements: *70119775055860
 description: gepub is a generic EPUB parser/generator. Generates and parse EPUB2 and
   EPUB3
 email:
@@ -76,6 +76,7 @@ files:
 - lib/gepub/metadata.rb
 - lib/gepub/package.rb
 - lib/gepub/resource_builder.rb
+- lib/gepub/rubyzip_patch.rb
 - lib/gepub/spine.rb
 - lib/gepub/version.rb
 - lib/gepub/xml_util.rb