bindery 0.0.2

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*_gen
+*.epub
+rspec.txt
+coverage

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/README.md

@@ -0,0 +1,126 @@
+# Bindery
+
+[Bindery][] is a [Ruby][] library for packaging ebooks.
+
+Electronic book formats are typically rather simple.
+An EPUB book, for example, is just HTML, CSS, and some image files packed into a single zip file along with various bits of metadata.
+But there are numerous tricky details, and a lot of redundancy in the metadata.
+Bindery aims to simplify the process.
+
+To use Bindery, you write a simple Ruby program that describes the book's structure and important metadata.
+This program is also responsible for identifying the HTML files that correspond to the book's chapters; those files might already exist, but the program can generate them on the fly as well.
+Then, you simply run that program to generate the book.
+
+Initially, Bindery will support generating the [EPUB][] format.
+I'll work to add support for other formats when EPUB support is working well.
+
+## Example
+
+Here is a quick example of a Bindery program.
+
+```ruby
+require 'bindery'
+require 'active_support'
+require 'maruku'
+
+Bindery.book do |b|
+  b.output 'anthology'
+  b.format :epub
+  
+  b.title "The Great Elbonian Novel"
+  b.language 'en'
+  b.url 'http://glv.github.com/bindery/books/example'
+  b.author 'Glenn Vanderburg'
+  
+  b.frontmatter 'Preface', 'pref.xhtml'
+  
+  b.chapter 'Introduction', 'intro.xhtml' 
+  
+  # process a collection of files called "chapter_1.md"
+  Dir['*.md'].sort.each do |file_name|
+    stem = file_name.sub(/\.md$/, '')
+    output_file_name = "#{stem}.xhtml_gen"
+    system %{markdown <#{file_name} >#{output_file_name}}
+    b.chapter stem.humanize, output_file_name
+  end
+  
+  # an alternative way to process chapters, assuming the chapters use
+  # Maruku's metadata support and contain the chapter title.  (Maruku
+  # is a Ruby Markdown library that supports numerous common extensions
+  # to the basic Markdown syntax.)
+  Dir['*.maruku'].sort.each do |file_name|
+    b.chapter do
+      output_file_name = file_name.sub(/\.maruku$/, '.xhtml_gen')
+      doc = Maruku.new(IO.read(file_name))
+      open(output_file_name, "w") {|os| os.write(doc.to_html)}
+      # return a hash with title and file info:
+      { :title => doc.attributes[:title], :file => output_file_name }
+    end
+  end
+  
+  b.backmatter 'Colophon' # filename assumed to be colophon.xhtml
+end
+```
+    
+## Status
+
+Bindery is currently limited to generating EPUB books that do not contain images or other non-textual content.
+
+It is also in a very early stage.
+It's capable of generating very simple books, but many features (including the frontmatter and backmatter methods in the example above) do not work yet.
+Additionally, validation is sketchy, so it's quite likely that the books you build using Bindery will not be valid EPUB files.
+But the basics are there, and contributions are welcome.
+
+Planned features include:
+
+* options for sections (with and without section title pages) rather than just a flat chapter structure.
+* additional metadata including all of [Dublin Core][].
+* support for images
+* support for multiple stylesheets
+* support for generating Mobipocket books
+
+## When to use Bindery
+
+There are other systems for generating ebooks; [git-scribe][] is one of the best.
+However most ebook generation systems prescribe a particular authoring format or tool.
+For example, git-scribe assumes you will be using [AsciiDoc][] and [Git][], and is additionally optimized for use on [GitHub][].
+Other systems are designed to work with proprietary tools such as [Microsoft Word][] or [Adobe InDesign][].
+Each such format or tool has strengths and weaknesses.
+For example, while AsciiDoc is an excellent tool for writing technical books, it's less well suited for novels, memoirs, or poetry.
+For such tasks (and depending on your personal preferences) it may be better to write in [Markdown][] or [Textile][].
+
+More importantly, requiring a specific format makes an ebook system difficult to use for a book that includes existing material being republished or repurposed.
+
+Imagine that, like [Joel Spolsky][], you want to publish an anthology of [your best blog posts][joel on software], or a collection of the [best software writing from around the web][best software writing].
+Or, like [Steven Johnson][], you write carefully researched books that weave together threads from many fields and disciplines, so you write and collect research in a sophisticated research management tool like [DEVONthink][] (Johnson has written [two][johnson dt1] [articles][johnson dt2] describing his research and writing methods).
+Or perhaps you simply want to read through the [SproutCore Guides][], but your spare time is fragmented (and usually occurs when you're on an airplane) so you want to convert them to an ebook format so they're always available and your ebook reader will keep track of how far you've read.
+(For that matter, if you're part of an effort like [SproutCore][] and have great online material like that, Bindery might be the easiest way to package it up into a handy offline format.)
+
+In any of those cases, the writing will exist in a format that probably doesn't match what existing ebook generation systems expect, and in some cases it will already be in the HTML format that all popular ebook formats are based on.
+
+Bindery is designed to support those use cases, not just brand new books written with a particular toolchain in mind.
+If you want to publish in both electronic and paper formats, Bindery is probably not for you.
+Bindery is targeted at electronic books only.
+
+[adobe indesign]: http://www.adobe.com/products/indesign.html
+[asciidoc]: http://www.methods.co.nz/asciidoc/
+[best software writing]: http://www.apress.com/9781590595008
+[Bindery]: http://github.com/glv/bindery
+[devonthink]: http://www.devon-technologies.com/products/devonthink/index.html
+[dublin core]: http://dublincore.org/sm
+[epub]: http://idpf.org/epub
+[git]: http://git-scm.com/
+[github]: http://github.com/
+[git-scribe]: http://github.com/schacon/git-scribe
+[joel on software]: http://www.apress.com/9781590593899
+[joel spolsky]: http://www.joelonsoftware.com/AboutMe.html
+[johnson dt1]: http://www.nytimes.com/2005/01/30/books/review/30JOHNSON.html?_r=1&oref=login
+[johnson dt2]: http://boingboing.net/2009/01/27/diy-how-to-write-a-b.html
+[markdown]: http://daringfireball.net/projects/markdown/
+[microsoft word]: http://office.microsoft.com/word/
+[rake]: http://rake.rubyforge.org/
+[ruby]: http://ruby-lang.org/
+[sproutcore]: http://www.sproutcore.com/
+[sproutcore guides]: http://guides.sproutcore.com/
+[steven johnson]: http://www.stevenberlinjohnson.com/
+[textile]: http://www.textism.com/tools/textile/

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO.taskpaper

@@ -0,0 +1,14 @@
+- Flesh out validation
+	Consider moving details to format modules.
+	Investigate Mobi validity constraints to see whether that makes sense.
+- Add more metadata support
+	- subtitle
+	- different kinds of authors
+- Title page
+- Title image
+- Image support
+- A basic CSS file
+- Support for alternative CSS files
+- Frontmatter
+- Nested chapter structures
+- Generate Mobi files

data/bindery.gemspec

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "bindery/version"
+
+Gem::Specification.new do |s|
+  s.name        = "bindery"
+  s.version     = Bindery::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Glenn Vanderburg"]
+  s.email       = ["glv@vanderburg.org"]
+  s.homepage    = "http://github.com/glv/bindery"
+  s.summary     = %q{Easy ebook packaging with Ruby}
+  s.description = %q{Bindery is a Ruby library for easy packaging of ebooks.
+You supply the chapter content (in HTML format) and explain the book's structure to bindery,
+and bindery generates the various other files required by ebook formats and assembles them
+into a completed book suitable for installation on an ebook reader.}
+
+  s.rubyforge_project = "bindery"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  add_runtime_dependency = if s.respond_to?(:specification_version) && Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+                             :add_runtime_dependency
+                           else
+                             :add_dependency
+                           end
+  s.send(add_runtime_dependency, 'builder')
+  s.send(add_runtime_dependency, 'nokogiri')
+  s.send(add_runtime_dependency, 'zip')
+  
+  s.add_development_dependency 'mocha'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', ['~> 2.0']
+end

data/examples/ashtray/book.rb

@@ -0,0 +1,58 @@
+require 'bindery'
+require 'open-uri'
+require 'nokogiri'
+require 'tidy_ffi'
+
+# In March, 2011, Errol Morris published on the New York Times website
+# a five-part reminiscence of a long-ago encounter with famed philosopher
+# Thomas Kuhn.  It's a perfect example of the kind of thing Bindery was
+# designed for.  You could always use Instapaper to allow you to read it
+# later, but the fact that it's in five pieces means that it wouldn't
+# appear as a single piece of writing in the Instapaper apps; additionally,
+# it's long enough that you might well have to stop reading in the middle
+# of one of the articles, and Instapaper doesn't remember your stopping 
+# point or synch it between devices. (Not to mention that it doesn't let
+# you highlight or make notes.) An ebook is simply a better format for some
+# kinds of writing.
+#
+# Note: I occasionally write Bindery scripts like this to bundle writing
+# from the web into a more convenient form for my own personal use.  In
+# that respect, I find it no different (as a matter of copyright) than
+# using a service like Instapaper.  However, it would definitely be a
+# violation of Morris' and the New York Times' copyrights to distribute
+# the resulting ebook to others.  Don't do that!
+
+PARTS = [
+  'http://opinionator.blogs.nytimes.com/2011/03/06/the-ashtray-the-ultimatum-part-1/',
+  'http://opinionator.blogs.nytimes.com/2011/03/07/the-ashtray-shifting-paradigms-part-2/',
+  'http://opinionator.blogs.nytimes.com/2011/03/08/the-ashtray-hippasus-of-metapontum-part-3/',
+  'http://opinionator.blogs.nytimes.com/2011/03/09/the-ashtray-the-author-of-the-quixote-part-4/',
+  'http://opinionator.blogs.nytimes.com/2011/03/10/the-ashtray-this-contest-of-interpretation-part-5/'
+]
+
+def process_part(url, i)
+  file_name = "chapter_#{i+1}.xhtml_gen"
+  doc = Nokogiri::HTML(open(url))
+  #puts doc
+  title = doc.at_css('h1.entry-title').text.sub(/^.*?: (.*) \(Part \d\)\s*$/, '\\1')
+  open(file_name, 'w') do |os|
+    content = doc.at_css('div.entry-content')
+    content.children[0..1].each{|c| c.remove}
+    os.write content.serialize
+  end
+  { :title => title, :file => file_name }
+end
+
+Bindery.book do |b|
+  b.output 'the_ashtray'
+  b.format :epub
+  
+  b.title "The Ashtray"
+  b.author 'Errol Morris'
+  b.url 'http://glenn.mp/book/the_ashtray'
+  b.language 'en'
+  
+  PARTS.each_with_index do |url, i|
+    b.chapter { process_part(url, i) }
+  end
+end

data/examples/trivial/book.rb

@@ -0,0 +1,27 @@
+require 'bindery'
+
+Bindery.book do |b|
+  b.output 'trivial'
+  b.format :epub
+  
+  b.title "A Trivial Bindery Example"
+  b.author 'Glenn Vanderburg'
+  b.url 'http://glenn.mp/book/trivial_example'
+  b.language 'en'
+  
+  b.chapter "Chapter 1", 'chapter_1.xhtml'
+  b.chapter "Chapter 2", 'chapter_2.xhtml', :body_only => false
+  b.chapter "Chapter 3" do
+    # It's good practice to have a way to distinguish source files from
+    # those generated as part of the build, so you can have a Rake task
+    # or something to clean up the intermediate files.
+    "chapter_3.xhtml_gen".tap do |filename|
+      File.open(filename, "w") do |os|
+        os.write %{
+          <p>Let's just write this chapter in line, shall we?</p>
+          <p>It seems easier that way, when the chapters are so short.</p>
+        }
+      end
+    end
+  end
+end

data/examples/trivial/chapter_1.xhtml

@@ -0,0 +1,3 @@
+<h2>Chapter 1</h2>
+
+<p>This chapter is a bit short. (The same is true for the entire book, for that matter.)</p>

data/examples/trivial/chapter_2.xhtml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
+  <title>Chapter 2</title>
+  <link rel="stylesheet" href="css/book.css" type="text/css" />
+</head>
+<body>
+<h2>Chapter 2</h2>
+
+<p>Unlike Chapter 1, this chapter's source file is a full, valid XHTML file, not just the body.</p>
+</body>
+</html>

data/lib/bindery.rb

@@ -0,0 +1,10 @@
+require 'bindery/extensions/string'
+require 'bindery/extensions/file'
+
+require 'bindery/version'
+require 'bindery/bindery'
+require 'bindery/book'
+require 'bindery/book_builder'
+require 'bindery/chapter'
+
+require 'bindery/formats/epub'

data/lib/bindery/bindery.rb

@@ -0,0 +1,9 @@
+module Bindery
+  
+  def self.book
+    builder = ::Bindery::BookBuilder.new
+    yield builder
+    builder.book.generate if builder.book.valid?
+  end
+  
+end

data/lib/bindery/book.rb

@@ -0,0 +1,45 @@
+module Bindery
+  class Book
+    attr_accessor :output, :url, :isbn, :title, :language, :author, :subtitle
+    
+    def formats
+      @formats ||= []
+    end
+    
+    def chapters
+      @chapters ||= []
+    end
+    
+    def full_title
+      title + (subtitle ? ": #{subtitle}" : '')
+    end
+    
+    def valid?
+      configuration_valid? && metadata_valid? && chapters_valid?
+    end
+    
+    def configuration_valid?
+      true
+      # formats specified or correctly defaulted
+      # ouput specified
+      # at least one chapter
+    end
+    
+    def metadata_valid?
+      true
+      # everything required has been specified (must find out what that is)
+      # what is there is correct
+    end
+    
+    def chapters_valid?
+      chapters.all?{|chapter| chapter.valid?} # && chapter file names are unique
+    end
+    
+    def generate
+      formats.each do |format|
+        require "bindery/formats/#{format}"
+        ::Bindery::Formats.const_get(format.to_s.capitalize).new(self).generate
+      end
+    end
+  end
+end

data/lib/bindery/book_builder.rb

@@ -0,0 +1,101 @@
+module Bindery
+  
+  class BookBuilder
+    attr_accessor :book
+    
+    def initialize
+      self.book = ::Bindery::Book.new
+    end
+    
+    def format(fmt)
+      raise "unsupported format :#{fmt}" unless [:epub].include?(fmt)
+      book.formats << fmt
+    end
+    
+    def output(basename)
+      raise "output already set to #{book.output}" unless book.output.nil?
+      book.output = basename.to_s
+    end
+    
+    def url(url)
+      book.url = url
+    end
+    
+    def isbn(isbn)
+      book.isbn = isbn
+    end
+    
+    def title(title)
+      book.title = title
+    end
+    
+    def subtitle(subtitle)
+      book.subtitle = subtitle
+    end
+    
+    def language(language)
+      book.language = language
+    end
+    
+    def author(author)
+      book.author = author
+    end
+    
+    # :call-seq:
+    #   chapter(title, filename, options={})
+    #   chapter(title, options={}) { ... }
+    #   chapter(options={}) { ... }
+    #
+    # Add a chapter to the book.
+    #
+    # If called with a title and a filename, the chapter's content should
+    # be found in the named file.
+    #
+    # If called with a title and a block, the block should generate or
+    # retrieve the chapter's content, write it to a file, and return the
+    # file name.
+    #
+    # If called with no parameters and a block, the block should generate
+    # or retrieve the chapter's content, write it to a file, and return a
+    # hash with the following keys:
+    # [:title] the chapter title (required)
+    # [:file]  the name of the file containing the chapter content (required)
+    #
+    # An options hash parameter is always allowed, and the following 
+    # options are supported:
+    # [:body_only] the file contains only the body of the XHTML document,
+    #              and Bindery should wrap it to create a valid document.
+    #              Defaults to true.
+    def chapter(*args)
+      default_options = {:body_only => true}
+      options = default_options.merge(args.last.kind_of?(Hash) ? args.pop : {})
+      if block_given?
+        chapter_dynamic(options, *args){yield}
+      else
+        chapter_static(options, *args)
+      end
+    end
+    
+    protected
+    
+    def chapter_static(options, *args)
+      title, file = args
+      raise ArgumentError, "title not specified" if title.nil?
+      raise ArgumentError, "file not specified" if file.nil?
+      book.chapters << Chapter.new(title, file, options)
+    end
+    
+    def chapter_dynamic(options, title=nil)
+      if title
+        file = yield
+        raise "expected the block to return a filename string" unless file.kind_of?(String)
+        chapter_static(options, title, yield)
+      else
+        info = yield
+        raise "expected the block to return a hash containing :title, :file, etc." unless info.kind_of?(Hash)
+        chapter_static(options, info[:title], info[:file])
+      end
+    end
+  end
+  
+end

data/lib/bindery/chapter.rb

@@ -0,0 +1,28 @@
+module Bindery
+  class Chapter
+    attr_accessor :file
+    attr_accessor :title
+    attr_accessor :options
+    
+    def initialize(title, file, options)
+      self.title = title
+      self.file = file
+      self.options = options
+    end
+    
+    def valid?
+      true
+      # title specified
+      # file exists, readable
+      # file content properly formed?  Does that matter?  Can we verify it?
+    end
+    
+    def body_only?
+      options.fetch(:body_only, true)
+    end
+    
+    def include_images?
+      options.fetch(:include_images, true)
+    end
+  end
+end

data/lib/bindery/extensions/file.rb

@@ -0,0 +1,16 @@
+module Bindery
+  module Extensions
+    module FileClassMethods
+      def base_parts(fn)
+        ext = File.extname(fn)
+        [File.basename(fn, ext), ext]
+      end
+      
+      def stemname(fn)
+        base_parts(fn)[0]
+      end
+    end
+  end
+end
+
+File.extend(Bindery::Extensions::FileClassMethods)

data/lib/bindery/extensions/string.rb

@@ -0,0 +1,12 @@
+module Bindery
+  module Extensions
+    module StringExtensions
+      # stolen from Scala
+      def strip_margin
+        gsub(/^\s*\|/m, '')
+      end
+    end
+  end
+end
+
+String.send(:include, Bindery::Extensions::StringExtensions)

data/lib/bindery/extensions/zip_file.rb

@@ -0,0 +1,28 @@
+require 'zip'
+
+module Bindery
+  module Extensions
+    module ZipFileExtensions
+      def write_file(entry, contents)
+        get_output_stream(entry){|os| os.write(contents) }
+      end
+      
+      def write_uncompressed_file(entry_name, contents)
+        entry = Zip::ZipEntry.new(@name, entry_name.to_s)
+        entry.compression_method = Zip::ZipEntry::STORED
+        write_file(entry, contents)
+      end
+    end
+    
+    module ZipStreamableStreamExtensions
+      def kind_of?(thing)
+        # ZipStreamableStream is a ZipEntry, but through delegation, not inheritance.
+        return true if thing == ::Zip::ZipEntry
+        super
+      end
+    end
+  end
+end
+
+Zip::ZipFile.send(:include, Bindery::Extensions::ZipFileExtensions)
+Zip::ZipStreamableStream.send(:include, Bindery::Extensions::ZipStreamableStreamExtensions)

data/lib/bindery/formats/epub.rb

@@ -0,0 +1,317 @@
+require 'builder'
+require 'zip'
+require 'bindery/extensions/zip_file'
+require 'nokogiri'
+
+module Bindery
+  module Formats
+    
+    # Builds an EPUB book file from the book description.
+    #
+    # The {EPUB Wikipedia entry}[http://en.wikipedia.org/wiki/EPUB] provides a nice, concise overview of the EPUB format.
+    #
+    # For more precise details:
+    # * The overall structure of an EPUB file is documented in
+    #   {Open Container Format (OCF) 2.0.1 - Recommended Specification}[http://idpf.org/epub/20/spec/OCF_2.0.1_draft.doc].
+    # * The format of the OPF file is documented in
+    #   {Open Packaging Format (OPF) 2.0.1 - Recommended Specification}[http://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm].
+    # * The format of the NCX file is documented in
+    #   {Section 8 of "Specifications for the Digital Talking Book"}[http://www.niso.org/workrooms/daisy/Z39-86-2005.html#NCX].
+    # * Details of the format of other files allowed in EPUB documents are found in
+    #   {Open Publication Structure (OPS) 2.0.1 - Recommended Specification}[http://idpf.org/epub/20/spec/OPS_2.0.1_draft.htm].
+    class Epub
+      
+      MimeTypes = {
+        '.jpg' => 'image/jpeg',
+        '.png' => 'image/png',
+        '.gif' => 'image/gif',
+      }
+      
+      class ManifestEntry < Struct.new(:file_name, :xml_id, :mime_type)
+      end
+      
+      attr_accessor :book, :manifest_entries
+      
+      def initialize(book)
+        self.book = book
+        book.extend BookMethods
+        book.chapters.each{|chapter| chapter.extend ChapterMethods}
+        self.manifest_entries = []
+      end
+      
+      def generate
+        File.delete(book.epub_output_file) if File.exist?(book.epub_output_file)
+        Zip::ZipFile.open(book.epub_output_file, Zip::ZipFile::CREATE) do |zipfile|
+          # FIXME: The mimetype file is supposed to be the first one in the Zip directory, but that doesn't seem to be happening.
+          zipfile.write_uncompressed_file 'mimetype', mimetype
+          zipfile.mkdir 'META-INF'
+          zipfile.write_file 'META-INF/container.xml', container
+          
+          # also frontmatter, backmatter
+          book.chapters.each do |chapter|
+            write_chapter(chapter, zipfile)
+          end
+          
+          zipfile.mkdir 'css'
+          zipfile.write_file 'css/book.css', stylesheet
+
+          zipfile.write_file 'book.opf', opf
+          zipfile.write_file 'book.ncx', ncx
+        end
+      end
+            
+      def mimetype
+        # the mimetype file must be the first file in the archive
+        # it must be ASCII, uncompressed, and unencrypted
+        'application/epub+zip'
+      end
+      
+      def container
+        %q{|<?xml version="1.0" encoding="UTF-8" ?>
+           |<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+           |  <rootfiles>
+           |    <rootfile full-path="book.opf" media-type="application/oebps-package+xml"/>
+           |  </rootfiles>
+           |</container>
+           |}.strip_margin
+      end
+      
+      def opf
+        xm = Builder::XmlMarkup.new(:indent => 2)
+        xm.instruct!
+        xm.package('version'=>'2.0', 'xmlns'=>'http://www.idpf.org/2007/opf', 'unique-identifier'=>'BookId') {
+          
+          xm.metadata('xmlns:dc'=>'http://purl.org/dc/elements/1.1/', 'xmlns:opf'=>'http://www.idpf.org/2007/opf') {
+            # required elements
+            xm.dc :title, book.full_title
+            xm.dc :language, book.language
+            xm.dc :identifier, book.url, ident_options('opf:scheme'=>'URL') if book.url
+            xm.dc :identifier, book.isbn, ident_options('opf:scheme'=>'ISBN') if book.isbn            
+            
+            # optional elements
+            xm.dc :creator, book.author, 'opf:role'=>'aut' if book.author
+          }
+          
+          xm.manifest {
+            book.chapters.each{|chapter| xm.item 'id'=>chapter.epub_id, 'href'=>chapter.epub_output_file, 'media-type'=>'application/xhtml+xml'}
+            # also frontmatter, backmatter
+            xm.item 'id'=>'stylesheet', 'href'=>'css/book.css', 'media-type'=>'text/css'
+            manifest_entries.each do |entry|
+              xm.item 'id'=>entry.xml_id, 'href'=>entry.file_name, 'media-type'=>entry.mime_type
+            end
+            # xm.item 'id'=>'myfont', 'href'=>'css/myfont.otf', 'media-type'=>'application/x-font-opentype'
+            xm.item 'id'=>'ncx', 'href'=>'book.ncx', 'media-type'=>'application/x-dtbncx+xml'
+          }
+          
+          xm.spine('toc'=>'ncx') {
+            book.chapters.each{|chapter| xm.itemref 'idref'=>chapter.epub_id}
+          }
+          
+          # xm.guide {
+          #   xm.reference 'type'='loi', 'title'=>'List of Illustrations', 'href'=>'appendix.html#figures'
+          # }
+        }
+      end
+      
+      def ncx
+        xm = Builder::XmlMarkup.new(:indent => 2)
+        xm.instruct!
+        xm.declare!(:DOCTYPE, :ncx, :PUBLIC, '-//NISO//DTD ncx 2005-1//EN', 'http://www.daisy.org/z3986/2005/ncx-2005-1.dtd')
+        xm.ncx('version'=>'2005-1', 'xml:lang'=>'en', 'xmlns'=>'http://www.daisy.org/z3986/2005/ncx/') {
+          xm.head {
+            xm.meta 'name'=>'dtb:uid', 'content'=>book.ident
+            xm.meta 'name'=>'dtb:depth', 'content'=>book.depth
+            xm.meta 'name'=>'dtb:totalPageCount', 'content'=>0
+            xm.meta 'name'=>'dtb:maxPageNumber', 'content'=>0
+          }
+          
+          xm.docTitle {
+            xm.text book.full_title
+          }
+          
+          xm.docAuthor {
+            xm.text book.author
+          }
+          
+          xm.navMap {
+            play_order = 1
+            
+            # also frontmatter, backmatter
+            book.chapters.each do |chapter|
+              xm.navPoint('class'=>'chapter', 'id'=>chapter.epub_id, 'playOrder'=>play_order) {
+                xm.navLabel {
+                  xm.text chapter.title
+                }
+                xm.content 'src'=>chapter.epub_output_file
+              }
+              play_order += 1
+            end
+          }
+        }
+      end
+      
+      def write_chapter(chapter, zipfile)
+        save_options = Nokogiri::XML::Node::SaveOptions
+        File.open(chapter.file, 'r:UTF-8') do |ch_in|
+          doc = Nokogiri.HTML(ch_in.read)
+          include_images(doc, zipfile) if chapter.include_images?
+          zipfile.get_output_stream(chapter.epub_output_file) do |ch_out|
+            if chapter.body_only?
+              # FIXME: must HTML-escape the chapter title
+              ch_out.write %{|<?xml version="1.0" encoding="UTF-8" ?>
+                             |<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+                             |<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+                             |<head>
+                             |  <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
+                             |  <title>#{chapter.title}</title>
+                             |  <link rel="stylesheet" href="css/book.css" type="text/css" />
+                             |</head>
+                             |}.strip_margin
+              ch_out.write doc.at('body').serialize(:save_with => (save_options::AS_XHTML | save_options::NO_DECLARATION))
+              ch_out.write %{|</html>
+                             |}.strip_margin
+            else
+              ch_out.write doc.serialize(:save_with => save_options::AS_XHTML)
+            end
+          end
+        end
+      end
+      
+      def include_images(doc, zipfile)
+        # TODO: where else can images appear? Style sheets?
+        zipfile.mkdir('images') unless zip_dir_exists?(zipfile, 'images')
+        doc.css('img').each do |img|
+          url = img['src']
+          img_fn = make_image_file_name(zipfile, url)
+          # TODO: These images should be cached somewhere for multi-format runs
+          open(url, 'r') do |is|
+            zipfile.get_output_stream(img_fn) do |os|
+              os.write is.read
+            end
+          end
+          add_manifest_entry(img_fn)
+          img['src'] = img_fn
+        end
+      end
+      
+      def add_manifest_entry(file_name)
+        xml_id, ext = File.base_parts(file_name.gsub('/', '-'))
+        manifest_entries << ManifestEntry.new(file_name, xml_id, MimeTypes[ext])
+      end
+      
+      def cover
+        xm = Builder::XmlMarkup.new(:indent => 2)
+        xm.instruct!
+        xm.declare!(:DOCTYPE, :html, :PUBLIC, '-//W3C//DTD XHTML 1.1//END', 'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd')
+        xm.html('xmlns'=>'http://www.w3.org/1999/xhtml') { # ??? xml:lang attribute?
+          xm.head {
+            xm.title "#{book.title}: Cover"
+            xm.meta('http-equiv'=>'Content-Type', 'content'=>'application/xhtml+xml; charset=utf-8')
+          }
+          xm.body {
+            xm.div('style'=>'text-align: center; page-break-after: always;') {
+              if book.cover
+                xm.img('src'=>"images/#{book.cover}", 'alt'=>book.title, 'style'=>'height: 100%; max-width: 100%;')
+              else
+                xm.h1 book.title
+                xm.h2 book.subtitle if book.subtitle
+                xm.h3 "by #{book.author}" if book.author
+              end
+            }
+          }
+        }
+      end
+      
+      def stylesheet
+        # This is a start, but needs work.
+        %q{|@page {
+           |  margin-top: 0.8em;
+           |  margin-bottom: 0.8em;}
+           |
+           |body {
+           |  margin-left: 1em;
+           |  margin-right: 1em;
+           |  padding: 0;}
+           |
+           |h2 {
+           |  padding-top:0;
+           |  display:block;}
+           |
+           |p {
+           |  margin-top: 0.3em;
+           |  margin-bottom: 0.3em;
+           |  text-indent: 1.0em;
+           |  text-align: justify;}
+           |
+           |body > p:first-child {text-indent: 0}
+           |div.text p:first-child {text-indent: 0}
+           |
+           |blockquote p, li p {
+           |  text-indent: 0.0em;
+           |  text-align: left;}
+           |
+           |div.chapter {padding-top: 3.0em;}
+           |div.part {padding-top: 3.0em;}
+           |h3.section_title {text-align: center;}
+           |}.strip_margin
+      end
+      
+      def ident_options(opts)
+        if book.isbn
+          return opts.merge('id'=>'BookId') if opts['opf:scheme'] == 'ISBN'
+        else
+          return opts.merge('id'=>'BookId') if opts['opf:scheme'] == 'URL'
+        end
+        opts
+      end
+      
+      def zip_dir_exists?(zipfile, dirname)
+        dirname = "#{dirname}/" unless dirname =~ %r{/$}
+        zipfile.entries.any?{|e| e.directory? && e.name == dirname}
+      end
+            
+      def zip_file_exists?(zipfile, filename)
+        zipfile.entries.any?{|e| e.name == filename}
+      end
+            
+      def make_image_file_name(zipfile, url)
+        stem, ext = File.base_parts(url)
+        filename = "images/#{stem}#{ext}"
+        n = 0
+        while zip_file_exists?(zipfile, filename)
+          n += 1
+          filename = "#{stem}_#{n}#{ext}"
+        end
+        filename
+      end
+      
+      module BookMethods
+        def epub_output_file
+          @epub_output_file ||= "#{output}.epub"
+        end
+        
+        def depth
+          1
+        end
+        
+        def ident
+          isbn || url
+        end
+      end
+      
+      module ChapterMethods
+        def epub_id
+          @epub_id ||= File.stemname(file)
+        end
+        
+        def epub_output_file
+          @epub_output_file ||= "#{epub_id}.xhtml"
+        end
+      end
+    end
+  end
+end
+
+# Notes:
+# cover image file: in manifest, then in metadata as <meta name="cover" content="manifest-entry-id"/>
+# cover: xhtml file, in manifest, also in spine as <itemref idref="manifest-entry-id" linear="no"/>, also in guide as <reference type="cover" title="Cover" href="cover.xhtml"/> (why does that use a direct href instead of an id ref?)

data/lib/bindery/version.rb

@@ -0,0 +1,3 @@
+module Bindery
+  VERSION = "0.0.2"
+end

data/spec/bindery/bindery_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe Bindery do
+  describe ".book" do
+    it "yields a new BookBuilder object to the block" do
+      Bindery.book do |b|
+        b.should be_kind_of Bindery::BookBuilder
+      end
+    end
+    
+    it "generates the book after the block returns if the book is valid" do
+      Bindery.book do |b|
+        b.book.expects(:valid?).once.returns(true)
+        b.book.expects(:generate).once
+      end
+    end
+    
+    it "does not generate the book if the book is not valid" do
+      Bindery.book do |b|
+        b.book.expects(:valid?).once.returns(false)
+        b.book.expects(:generate).never
+      end
+    end
+  end
+end

data/spec/bindery/book_builder_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+describe Bindery::BookBuilder do
+  let(:book) { subject.book }
+  
+  describe "#book" do
+    it "returns the configured Book instance" do
+      book.should be_kind_of(Bindery::Book)
+    end
+  end
+  
+  describe "#output" do
+    it "stores the filename to use (minus suffix) for output book files" do
+      subject.output 'foo'
+      book.output.should == 'foo'
+    end
+    
+    it "converts its argument to a string before storing it" do
+      subject.output :foo
+      book.output.should == 'foo'
+    end
+    
+    it "raises an error if the output has already been set" do
+      subject.output 'bar'
+      expect { subject.output 'foo' }.to raise_error
+    end
+  end
+  
+  describe "#format" do
+    it "raises an exception if the supplied format is unsupported" do
+      expect { subject.format :interpress }.to raise_error
+      expect { subject.format :mobi }.to raise_error
+    end
+    
+    it "adds the supplied format to the list of formats to generate for this book" do
+      subject.format :epub
+      book.formats.should =~ [:epub]
+    end
+  end
+  
+  describe "#chapter" do
+    
+    context "when called without a block" do
+      it "raises an exception if title or filename are not supplied" do
+        expect { subject.chapter }.to raise_error(ArgumentError, "title not specified")
+        expect { subject.chapter "A" }.to raise_error(ArgumentError, "file not specified")
+      end
+      
+      it "stores a new chapter with the supplied options" do
+        subject.chapter "Foo", "bar.xhtml"
+        book.chapters.should have(1).elements
+        book.chapters.first.title.should == "Foo"
+        book.chapters.first.file.should == "bar.xhtml"
+      end
+    end
+    
+    context "when called with a block" do
+      
+      context "and title is supplied as an argument" do
+        it "expects the block to result in a filename string" do
+          expect { subject.chapter("Foo"){ 3 } }.to raise_error
+        end
+        
+        it "stores the title and the filename as a new chapter" do
+          subject.chapter("Foo"){ 'bar.xhtml' }
+          book.chapters.should have(1).elements
+          book.chapters.first.title.should == "Foo"
+          book.chapters.first.file.should == "bar.xhtml"
+        end
+      end
+      
+      context "and title is not supplied as an argument" do
+        it "expects the block to result in a hash with :title and :file options" do
+          expect { subject.chapter{ "Invalid" } }.to raise_error
+          expect { subject.chapter{ {:title => 'Foo'} } }.to raise_error
+          expect { subject.chapter{ {:file => 'bar.xhtml'} } }.to raise_error
+        end
+        
+        it "stores the title and the filename as a new chapter" do
+          subject.chapter { {:title => 'Foo', :file => 'bar.xhtml'} }
+          book.chapters.should have(1).elements
+          book.chapters.first.title.should == "Foo"
+          book.chapters.first.file.should == "bar.xhtml"
+        end
+      end
+      
+    end
+    
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require 'rspec/core'
+
+require 'bindery'
+
+Dir['./spec/support/**/*.rb'].map {|f| require f}
+
+def in_editor?
+  ENV.has_key?('TM_MODE') || ENV.has_key?('EMACS') || ENV.has_key?('VIM')
+end
+
+RSpec.configure do |c|
+  c.color_enabled = !in_editor?
+  c.filter_run :focus => true
+  c.mock_with :mocha
+  c.run_all_when_everything_filtered = true
+  c.add_formatter :progress
+  c.add_formatter :documentation, 'rspec.txt'
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification 
+name: bindery
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Glenn Vanderburg
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-18 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: builder
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: zip
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rake
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.0"
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+description: |-
+  Bindery is a Ruby library for easy packaging of ebooks.
+  You supply the chapter content (in HTML format) and explain the book's structure to bindery,
+  and bindery generates the various other files required by ebook formats and assembles them
+  into a completed book suitable for installation on an ebook reader.
+email: 
+- glv@vanderburg.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- TODO.taskpaper
+- bindery.gemspec
+- examples/ashtray/book.rb
+- examples/trivial/book.rb
+- examples/trivial/chapter_1.xhtml
+- examples/trivial/chapter_2.xhtml
+- lib/bindery.rb
+- lib/bindery/bindery.rb
+- lib/bindery/book.rb
+- lib/bindery/book_builder.rb
+- lib/bindery/chapter.rb
+- lib/bindery/extensions/file.rb
+- lib/bindery/extensions/string.rb
+- lib/bindery/extensions/zip_file.rb
+- lib/bindery/formats/epub.rb
+- lib/bindery/version.rb
+- spec/bindery/bindery_spec.rb
+- spec/bindery/book_builder_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/glv/bindery
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -3490394669822348887
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -3490394669822348887
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: bindery
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Easy ebook packaging with Ruby
+test_files: 
+- spec/bindery/bindery_spec.rb
+- spec/bindery/book_builder_spec.rb
+- spec/spec_helper.rb