rpub 0.3.0 → 0.4.0

data/.rspec

@@ -1,5 +1,6 @@
 --format progress
 --color
+--order rand
 -Ilib
 -Ispec
 -r spec_helper

data/.yardopts

@@ -1,6 +1,8 @@
 --no-private
 --title "Rpub, a simple ePub generator library in Ruby"
 --readme README.md
+--markup markdown
+--markup-provider kramdown
 -
 HISTORY.md
 LICENSE

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rpub (0.3.0)
+    rpub (0.4.0)
       builder
       kramdown
       nokogiri
@@ -17,35 +17,43 @@ GEM
     diff-lcs (1.1.3)
     ffi (1.0.11)
     growl (1.0.3)
-    guard (1.0.1)
-      ffi (>= 0.5.0)
-      thor (~> 0.14.6)
-    guard-rspec (0.7.0)
-      guard (>= 0.10.0)
-    kramdown (0.13.5)
-    multi_json (1.3.2)
-    nokogiri (1.5.2)
+    guard (1.1.1)
+      listen (>= 0.4.2)
+      thor (>= 0.14.6)
+    guard-rspec (1.0.0)
+      guard (>= 1.1)
+    kramdown (0.13.7)
+    listen (0.4.3)
+      rb-fchange (~> 0.0.5)
+      rb-fsevent (~> 0.9.1)
+      rb-inotify (~> 0.8.8)
+    multi_json (1.3.6)
+    nokogiri (1.5.3)
     rake (0.9.2.2)
+    rb-fchange (0.0.5)
+      ffi
     rb-fsevent (0.9.1)
-    rspec (2.9.0)
-      rspec-core (~> 2.9.0)
-      rspec-expectations (~> 2.9.0)
-      rspec-mocks (~> 2.9.0)
-    rspec-core (2.9.0)
-    rspec-expectations (2.9.1)
+    rb-inotify (0.8.8)
+      ffi (>= 0.5.0)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.9.0)
+    rspec-mocks (2.10.1)
     rubypants (0.2.0)
     rubyzip (0.9.8)
-    simplecov (0.6.2)
-      multi_json (~> 1.3)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
       simplecov-html (~> 0.5.3)
     simplecov-html (0.5.3)
     textstats (0.0.2)
-    thor (0.14.6)
+    thor (0.15.2)
     typogruby (1.0.15)
       rubypants
-    yard (0.7.5)
+    yard (0.8.2)
 
 PLATFORMS
   ruby

data/HISTORY.md

@@ -1,5 +1,11 @@
 # History
 
+## 0.4.0
+
+* Generate ePub table of contents from markdown headings
+* Expanded documentation with configuration reference
+* Enhanced .mobi compatibility (convert your .epub with kindlegen)
+
 ## 0.3.0
 
 * Only run simplecov on demand

data/README.md

@@ -1,4 +1,4 @@
-# Rpub -- an ePub generator in Ruby [![Build Status](https://secure.travis-ci.org/avdgaag/rpub.png?branch=master)](http://travis-ci.org/avdgaag/rpub)
+# Rpub -- an ePub generator in Ruby [![Build Status](https://secure.travis-ci.org/avdgaag/rpub.png?branch=master)](http://travis-ci.org/avdgaag/rpub) [![Gemnasium dependency status](https://gemnasium.com/avdgaag/rpub.png)](https://gemnasium.com/avdgaag/rpub)
 
 ## Introduction
 
@@ -10,6 +10,7 @@ make working with ePub files a little easier:
 * Packaging your eBook in an archive with additional README file
 * Embedding fonts
 * Easy previewing as you write
+* .mobi compatibility
 
 ## Installation
 
@@ -53,7 +54,8 @@ in a special configuration file called `config.yml`:
     title: My new book
     version: 0.1.0
 
-This file is written in [YAML](http://yaml.org) and sets basic properties of your book project.
+This file is written in [YAML](http://yaml.org) and sets basic properties of
+your book project.
 
 Since regenerating your ePub file and opening it in a suitable reader
 application is cumbersome, Rpub can generate a simple preview document for you:
@@ -67,6 +69,24 @@ easy viewing in any browser.
 [Markdown]: http://daringfireball.net/projects/markdown
 [John gruber]: http://daringfireball.net
 
+### Generating a .mobi file
+
+Since the ePub and Mobipocket file formats are very (_very_) similar it is
+quite easy to create a `.mobi` version of your book, suitable for reading on
+Amazon's Kindle. To do so, you will need to install the [kindlegen program
+Amazon provides][kindlegen].
+
+Here's how it works:
+
+1. Install `kindlegen` ([download it here][kindlegen])
+2. Compile your book as usual using `rpub compile`
+3. Compile `my-book.epub` to `my-book.mobi`: `kindlegen my-book.epub`.
+
+Optionally, include your `my-book.mobi` in your package by adding it to your
+list of packaged files (see "Packaging for distribution").
+
+[kindlegen]: http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211
+
 ### Advanced features
 
 #### Packaging for distribution
@@ -104,6 +124,15 @@ configuration to your `config.yml` file:
 
     toc: true
 
+Note that this only affects the human-readable table of contents, represented
+as a page in your book. Rpub will alway generate the .epub table of contents
+for you, which contains the machine-readable references to your chapters. It
+will, by default, reference all chapter titles and subheadings for you, but
+you can customize the number of levels that will be included using the
+following in your `config.yml` file:
+
+    max_level: 3
+
 #### Custom layout and styles
 
 When you compile a set of Markdown files to an ePub file, rpub uses a default
@@ -113,15 +142,22 @@ inclined.
 
 Simply define a `layout.html` and/or `styles.css` in your project directory.
 Your HTML file will be parsed with Erb, an so you can include your writing
-using the `yield` method:
+using the `@body` instance variable:
 
     <html>
     <body>
-      <%= yield %>
+      <%= @body %>
     </body>
     </html>
 
-**Note**: despite the name 'html' and `.html` extension, your file actually has
+**Note 1**: this feature is actually provided by the [Kramdown gem][kramdown],
+so have a look at [the standard Kramdown document template][doc] to see some
+nifty tricks.
+
+[kramdown]: http://kramdown.rubyforge.org
+[doc]:      https://github.com/gettalong/kramdown/blob/master/data/kramdown/document.html
+
+**Note 2**: despite the name 'html' and `.html` extension, your file actually has
 to be XHTML-compliant.
 
 You can also provide custom layouts or styles to use when invoking the `compile`
@@ -136,16 +172,66 @@ those files into your project using the `generate` subcommand:
 
 ### Command reference
 
-* `rpub compile` -- generate .epub file
-* `rpub package` -- create zip file with compiled book and other listed files
-* `rpub preview` -- generate preview HTML file
-* `rpub generate` -- copy default layout.html, styles.css and config.yml
-* `rpub help` -- get help on subcommands
-* `rpub clean` -- remove generated files
+`rpub compile`
+: generate .epub file
+
+`rpub package`
+: create zip file with compiled book and other listed files
+
+`rpub preview`
+: generate preview HTML file
+
+`rpub generate`
+: copy default layout.html, styles.css and config.yml
+
+`rpub help`
+: get help on subcommands
+
+`rpub clean`
+: remove generated files
+
+### Configuration reference
+
+`title`
+: the book title (string)
+
+`descrption`
+: one-line summary of the book (string)
+
+`creator`
+: author name (string)
+
+`publisher`
+: publisher name (string)
+
+`subject`
+: book subject/category (string)
+
+`language`
+: language code of the book contents, e.g. 'en' (string)
+
+`rights`
+: copyright line (string)
+
+`version`
+: version number of the book to include in the .epub filename (string)
+
+`toc`
+: whether to generate a table of contents as book page (boolean, default false)
+
+`max_level`
+: the maximum depth of the .epub table of contents (number, default 2)
+
+`ignore`
+: list of files not to include in the epub, that otherwise would (array)
+
+`package`
+: list of files to be included in the archive created by the package task (array)
+
 
 ### Examples
 
-See the [examples directory](https://github.com/avdgaag/rpub/example) for two example projects.
+See the [examples directory](https://github.com/avdgaag/rpub/tree/master/example) for two example projects.
 
 ### Documentation
 
@@ -171,7 +257,7 @@ tracker](https://github.com/avdgaag/rpub/issues).
 
 ### What has changed?
 
-See the [HISTORY](https://github.com/avdgaag/rpub/HISTORY) file for a detailed changelog.
+See the [HISTORY](https://github.com/avdgaag/rpub/blob/master/HISTORY.md) file for a detailed changelog.
 
 ### Credits
 

data/lib/rpub/chapter.rb

@@ -17,6 +17,11 @@ module Rpub
       @content, @number, @layout = content, number, layout
       @document = Kramdown::Document.new(content, KRAMDOWN_OPTIONS.merge(:template => layout))
     end
+    
+    # @return [Kramdown::Element] Toc elements hierarchy
+    def toc
+      Kramdown::Converter::Toc.convert(@document.root).first
+    end
 
     # @return [String] Unique identifier for this chapter.
     def uid

data/lib/rpub/epub/content.rb

@@ -71,9 +71,14 @@ module Rpub
             end
           end
 
-          if book.has_cover?
+          if book.has_cover? || book.has_toc?
             xml.guide do
-              xml.reference :type => 'cover', :title => 'Cover', :href => 'cover.html'
+              if book.has_cover?
+                xml.reference :type => 'cover', :title => 'Cover', :href => 'cover.html'
+              end
+              if book.has_toc?
+                xml.reference :type => 'toc',   :title => 'Table of Contents', :href => 'toc.html'
+              end
             end
           end
         end

data/lib/rpub/epub/toc.rb

@@ -4,7 +4,9 @@ module Rpub
       attr_reader :book
 
       def initialize(book)
-        @book = book
+        @book       = book
+        @play_order = -1
+        @max_level  = book.config.fetch(:max_level) { 2 }
         super()
       end
 
@@ -13,23 +15,45 @@ module Rpub
         xml.declare! :DOCTYPE, :ncx, :PUBLIC, "-//W3C//DTD XHTML 1.1//EN", 'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd'
         xml.ncx :xmlns => 'http://www.daisy.org/z3986/2005/ncx/', :version => '2005-1' do
           xml.head do
-            xml.meta :name => 'dtb:uid', :content => book.uid
-            xml.meta :name => 'dtb:depth', :content => '1'
+            xml.meta :name => 'dtb:uid',            :content => book.uid
+            xml.meta :name => 'dtb:depth',          :content => @max_level
             xml.meta :name => 'dtb:totalPageCount', :content => '0'
-            xml.meta :name => 'dtb:maxPageNumber', :content => '0'
+            xml.meta :name => 'dtb:maxPageNumber',  :content => '0'
           end
           xml.docTitle { xml.text book.title }
           xml.navMap do
-            book.chapters.each_with_index do |chapter, n|
-              xml.navPoint :id => chapter.xml_id, :playOrder => n do
-                xml.navLabel { xml.text chapter.title }
-                xml.content :src => chapter.filename
-              end
+            book.chapters.each do |chapter|
+              nav_points_nested_by_level chapter.toc, chapter.filename
             end
           end
         end
       end
+
+      private
+
+      def next_play_order
+        @play_order += 1
+      end
+
+      def nav_points_nested_by_level(heading, filename, level = 1)
+        heading.children.each do |heading|
+          html_id = heading.attr[:id]
+          source = filename+'#'+html_id
+          if heading.value.options[:level] <= @max_level
+            nav_point html_id, next_play_order, heading.value.options[:raw_text], source do
+                nav_points_nested_by_level heading, filename, level + 1
+            end
+          end
+        end
+      end
+
+      def nav_point(id, play_order, text, filename)
+        xml.navPoint :id => id, :playOrder => play_order do
+          xml.navLabel { xml.text text }
+          xml.content :src => filename
+          yield if block_given?
+        end
+      end
     end
   end
 end
-

data/lib/rpub/version.rb

@@ -1,3 +1,3 @@
 module Rpub
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/spec/rpub/epub/content_spec.rb

@@ -58,6 +58,7 @@ describe Rpub::Epub::Content do
   context 'when the book has a ToC' do
     before { book.stub! :has_toc? => true }
     it { should have_xpath('/xmlns:package/xmlns:manifest/xmlns:item[@id="toc"][@href="toc.html"][@media-type="application/xhtml+xml"]') }
+    it { should have_xpath('/xmlns:package/xmlns:guide/xmlns:reference[@type="toc"][@title="Table of Contents"][@href="toc.html"]') }
   end
 
   context 'when the book has images' do

data/spec/rpub/epub/toc_spec.rb

@@ -2,12 +2,13 @@ require 'spec_helper'
 
 describe Rpub::Epub::Toc do
   let(:chapters) { [] }
-  let(:book)     { double('book', :uid => 'foo', :title => 'title', :chapters => chapters) }
+  let(:config)   { {} }
+  let(:book)     { double('book', :uid => 'foo', :title => 'title', :chapters => chapters, :config => config) }
   let(:subject)  { described_class.new(book).render }
 
   it { should have_xpath('/xmlns:ncx') }
   it { should have_xpath('/xmlns:ncx/xmlns:head/xmlns:meta[@name="dtb:uid"][@content="foo"]') }
-  it { should have_xpath('/xmlns:ncx/xmlns:head/xmlns:meta[@name="dtb:depth"][@content="1"]') }
+  it { should have_xpath('/xmlns:ncx/xmlns:head/xmlns:meta[@name="dtb:depth"][@content="2"]') }
   it { should have_xpath('/xmlns:ncx/xmlns:head/xmlns:meta[@name="dtb:totalPageCount"][@content="0"]') }
   it { should have_xpath('/xmlns:ncx/xmlns:head/xmlns:meta[@name="dtb:maxPageNumber"][@content="0"]') }
   it { should have_xpath('/xmlns:ncx/xmlns:docTitle/xmlns:text[text()="title"]') }
@@ -17,9 +18,23 @@ describe Rpub::Epub::Toc do
   end
 
   context 'with chapters' do
-    let(:chapters) { [double('chapter', :title => 'chapter title', :filename => 'filename', :xml_id => 'id')] }
-    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint[@id="id"]') }
+    let(:heading1) { double('heading', :children => [heading2], :value => double('value', :options => { :level => 1, :raw_text => 'chapter title'  }), :attr => { :id => 'foo' }) }
+    let(:heading2) { double('heading', :children => [], :value => double('value', :options => { :level => 2, :raw_text => 'chapter title 2' }), :attr => { :id => 'bar' }) }
+    let(:toc)      { double('toc', :children => [heading1])}
+    let(:chapters) { [double('chapter', :title => 'chapter title', :filename => 'filename', :xml_id => 'id', :toc => toc)] }
+    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint[@id="foo"]') }
     it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navLabel/xmlns:text[text()="chapter title"]') }
-    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:content[@src="filename"]') }
+    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:content[@src="filename#foo"]') }
+    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navPoint[@id="bar"]') }
+    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navPoint/xmlns:navLabel/xmlns:text[text()="chapter title 2"]') }
+    it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navPoint/xmlns:content[@src="filename#bar"]') }
+
+    context 'with low max_level' do
+      let(:config) { { :max_level => 1 } }
+      it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint[@id="foo"]') }
+      it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navLabel/xmlns:text[text()="chapter title"]') }
+      it { should have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:content[@src="filename#foo"]') }
+      it { should_not have_xpath('/xmlns:ncx/xmlns:navMap/xmlns:navPoint/xmlns:navPoint') }
+    end
   end
 end

data/support/config.yml

@@ -8,6 +8,7 @@ language:    'en'
 rights:      'public comain'
 version:     '0.0.0'
 toc:         true
+max_level:   2
 ignore:
  - README.md
 package:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rpub
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-06 00:00:00.000000000 Z
+date: 2012-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typogruby
@@ -349,7 +349,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 883141922978996594
+      hash: 2837060171432617966
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -358,10 +358,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 883141922978996594
+      hash: 2837060171432617966
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: ! 'rPub is a command-line tool that generates a collection of plain text