epub-parser 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f7e1c88df88ae747c9119ab1a7a5978da200d977ffa0a97b33f2c5c2d398cb8
-  data.tar.gz: b554ff75c8641a4f8edc3cf0a4801671440b605aa493a50d95498d278c9e49b7
+  metadata.gz: 4ac4cf6d94841545616b908ef95b0028d8ba6e6ad266b48b1a616c67f18c881b
+  data.tar.gz: 630f88dbacaba24a28364a5cb87d98b6778fdb1504eba785b470495cb8823bda
 SHA512:
-  metadata.gz: 8a102404b9a0a7257e7899f43c08002e4ce55b29ed56df6bead42d2eef0d316b9b63ee4494627777fba1aa3849389fd2754caccc5409a9d7c7a5761243ca3367
-  data.tar.gz: f12125b9970efaa46bd24d71f6e32b6fe9d95d7ceb07c20f0b65124be6c3832044941c28fd46ed79722408ab0a449e6431442cfd519981a786606550fd34bfde
+  metadata.gz: 827f7b42fedec851ee5f3146bba19477cb80b457fdb2c98c69dff872772175bb70a877d686e851eb90744b1cf14974de46300494c5a810fcf7d9c873e2b537b1
+  data.tar.gz: 6607c5d2a5cbd63c4d9bca7eecaa7b71dfc5be49c828f0d8fdc44fd3cb4e3ee825bbb5e2adb5b06023b54ff2900ef9624cd2a3625a3f77376db12c762f3b42a0

data/.gitlab-ci.yml

@@ -2,16 +2,66 @@ before_script:
   - ruby -v
   - which ruby
   - gem install bundler --no-document
-  - bundle install --jobs=$(nproc) "${FLAGS[@]}"
+  - bundle install --jobs=$(nproc) --path=deps "${FLAGS[@]}"
+  - bundle clean
 
 test:2.3:
   image: ruby:2.3
   script: bundle exec rake test
+  except:
+    - tags
+  cache:
+    key: ruby:2.3
+    paths:
+      - deps
 
 test:2.4:
   image: ruby:2.4
   script: bundle exec rake test
+  except:
+    - tags
+  cache:
+    key: ruby:2.4
+    paths:
+      - deps
 
 test:2.5:
   image: ruby:2.5
   script: bundle exec rake test
+  except:
+    - tags
+  artifacts:
+    paths:
+      - coverage
+  cache:
+    key: ruby:2.5
+    paths:
+      - deps
+
+test:2.6:
+  image: ruby:2.6-rc
+  script: bundle exec rake test
+  except:
+    - tags
+  cache:
+    key: ruby:2.6
+    paths:
+      - deps
+
+pages:
+  stage: deploy
+  dependencies:
+    - test:2.5
+  script:
+    - rake doc:yard
+    - mv doc public
+    - mv coverage public/
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
+  cache:
+    key: ruby:2.5
+    paths:
+      - deps

data/.yardopts

@@ -1,18 +1,20 @@
 --load docs/yard-forwardable_def_delegators_handler.rb
 -
-CHANGELOG.markdown
+CHANGELOG.adoc
 MIT-LICENSE
-docs/Home.markdown
+docs/Home.adoc
 docs/Publication.markdown
 docs/Item.markdown
 docs/FixedLayout.markdown
 docs/Epubinfo.markdown
 docs/EpubOpen.markdown
+docs/EpubCover.adoc
 docs/Navigation.markdown
-docs/Searcher.markdown
+docs/Searcher.adoc
 docs/UnpackedArchive.markdown
 docs/AggregateContentsFromWeb.markdown
 docs/MultipleRenditions.markdown
+docs/Examples.adoc
 examples/aggregate-contents-from-web.rb
 examples/exctract-content-using-cfi.rb
 examples/find-elements-and-cfis.rb

data/{CHANGELOG.markdown → CHANGELOG.adoc}

@@ -1,71 +1,64 @@
-CHANGELOG
-=========
+= CHANGELOG
+
+== 0.3.7
+
+* Strip leading and trailing white spaces from identifiers. See http://www.idpf.org/epub/31/spec/epub-packages.html#sec-opf-dcidentifier for details.
+* Change home page and documentation from rubydoc.info to GitLab Pages
+* Parse `package/metadata/meta@name` and `@content` to allow EPUB 2 meta info
+* Add {EPUB::Metadata#cover_image Metadata#cover_image}
+* Make {EPUB::Book::Features#cover_image Book::Features#cover_image} return EPUB 2 cover image if EPUB 3's not available
+* Add `epub-cover` command-line tool. See {file:docs/EpubCover.adoc} for details.
+
+== 0.3.6
 
-0.3.6
------
 * [BUG FIX]Ignore fragment when find item by relative IRI
-* Enable [PrettyBacktrace][] only when specified by env var for testing performance
+* Enable https://github.com/ko1/pretty_backtrace[PrettyBacktrace] only when specified by env var for testing performance
 
-[PrettyBacktrace]: https://github.com/ko1/pretty_backtrace
+== 0.3.5
 
-0.3.5
------
-* [BUG FIX]Fix a bug that {EPUB::ContentDocument::Navigation::Item#item} is `nil` when `href` includes double dots(`..`)(Thanks [aelkiss][]!)
+* [BUG FIX]Fix a bug that {EPUB::ContentDocument::Navigation::Item#item} is `nil` when `href` includes double dots(`..`)(Thanks https://gitlab.com/aelkiss[aelkiss]!)
 
-0.3.4
------
+== 0.3.4
 
 * Add {EPUB::Publication::Package#full_path} and {EPUB::Publication::Package#rootfile}
-* [BUG FIX]Fix a bug that {EPUB::ContentDocument::Navigation::Item#item} doesn't return correct {EPUB::Publication::Package::Manifest::Item Item}(Thanks [aelkiss][]!)
+* [BUG FIX]Fix a bug that {EPUB::ContentDocument::Navigation::Item#item} doesn't return correct {EPUB::Publication::Package::Manifest::Item Item}(Thanks https://gitlab.com/aelkiss[aelkiss]!)
 
-[aelkiss]: https://gitlab.com/aelkiss
-
-0.3.3
------
+== 0.3.3
 
 * [BUG FIX]Use UnpackedURI adapter for URI
 * [BREAKING CHANGE]Remove deprecated second argument from `EPUB::Parser::Publication#initialize`
 * Add `detect_encoding` keyword argument to `Publication::Package::Manifest::Item#read` and `ContentDocument::XHTML#read`
 
-0.3.2
------
+== 0.3.2
 
 * Use epub-cfi gem for EPUB CFI
 
-0.3.1
------
+== 0.3.1
 
 * Load epub/parser.rb in epub/parser/cfi.rb to allow to use Parser::CFI independently
 * Make `CFI` comparable. Now can call `CFI#==`
 * Include `Publication::Package::Spine::Itemref` in `Searcher.search_element`'s result
 
-0.3.0
------
+== 0.3.0
 
 * Wrong release. I'm sorry.
 
-0.2.9
------
+== 0.2.9
 
 * Fix a bug that `Searcher.search_element` returns wrong CFI
 * Add `Searcher.search_by_cfi`
 
-0.2.8
------
+== 0.2.8
 
 * Change Searcher API: #search -> #search_text
 * Add Searcher.search_element
 
-0.2.7
------
+== 0.2.7
 
 * Add `EPUB::Metadata#children` to keep all child emements to count them on CFI search
-* Allow class including `EPUB` to intialize with extra arguments(Thanks, [skukx][]!)
-
-[skukx]: https://github.com/skukx
+* Allow class including `EPUB` to intialize with extra arguments(Thanks, https://github.com/skukx[skukx]!)
 
-0.2.6
------
+== 0.2.6
 
 * Add `EPUB::Publication::Package::Metadata#package_identifier` as alias of `#release_identifier`, which is defined in EPUB Publication 3.0 spec
 * [BUG FIX]Metadata#modified returns modified with no refiners
@@ -76,16 +69,14 @@ CHANGELOG
 
 [multi-rendition]: http://www.idpf.org/epub/renditions/multiple/
 
-0.2.5
------
+== 0.2.5
 
 * [BUG FIX]Don't load Zip/Ruby if unneccessary
 * Raise error when PhysicalContainer::ArchiveZip fails find entry
 * Remove unused files in schemas directory
 * Add `EPUB::CFI::PhysicalContainer.find_adapter`
 
-0.2.4
------
+== 0.2.4
 
 * Bug fix for `EPUB::CFI::Location#<=>`
 * Change default physical container adapter from `EPUB::OCF::PhysicalContainer::ZipRuby` to `EPUB::OCF::PhysicalContainer::ArchiveZip`
@@ -93,72 +84,57 @@ CHANGELOG
 * Change attribute name: `EPUB::CFI::Step#step` -> `EPUB::CFI::Step#value`, `EPUB::CFI::CharacterOffset#offset` -> `EPUB::CFI::CharacterOffset#value`
 * Show modified on `epubinfo` command
 
-0.2.3
------
+== 0.2.3
 
 * Change the name of physical container adapter for file system: :File -> :UnpackedDirectory
 * Add `EPUB::Publication::Package::Manifest::Item#full_path`
 * Make #href= acceptable String
 * Implement `EPUB::CFI` and `EPUB::Parser::CFI`
-* Remove [nokogumbo][] from dependencies. It ommits `head` and `body` elements
+* Remove https://github.com/rubys/nokogumbo/[nokogumbo] from dependencies. It ommits `head` and `body` elements
 * Remove Cucumber and Cucumber features
 * Add `EPUB::Publication::Package::Metadata#modified` and `EPUB::Book::Features#modified`
 * Add `EPUB::Book::Features#release_identifier`
 
-0.2.2
------
+== 0.2.2
 
 * [BUGFIX]Item#entry_name returns normalized IRI
 
-0.2.1
------
+== 0.2.1
 
 * Remove deprecated `EPUB::Constants::MediaType::UnsupportedError`. Use `UnsupportedMediatType` instead.
-* Make it possible to use [archive-zip][] gem to extract contents from EPUB package via `EPUB::OCF::PhysicalContainer::ArchiveZip`
+* Make it possible to use https://github.com/javanthropus/archive-zip[archive-zip] gem to extract contents from EPUB package via `EPUB::OCF::PhysicalContainer::ArchiveZip`
 * Add warning about default physical container adapter change
 * Make it possible to extract contents from the web via `EPUB::OCF::PhysicalContainer::UnpackedURI`. See {file:ExtractContentsFromWeb.markdown} for details.
 
-[archive-zip]: https://github.com/javanthropus/archive-zip
-
-0.2.0
------
+== 0.2.0
 
 * Introduce abstraction layer for OCF physical container
 * Add `EPUB::OCF::PhysicalContainer::File` and make it possible to parse file system directory as an EPUB file. See {file:docs/UnpackedArchive.markdown} for details.
 * Remove `EPUB::Parser::OCF::CONTAINER_FILE` and other constants
 
-0.1.9
------
+== 0.1.9
 
-* Introduce [Nokogumbo][] for XHTML Content Documents
+* Introduce https://github.com/rubys/nokogumbo/[Nokogumbo] for XHTML Content Documents
 * Stop support for Ruby 1.9
 * Remove `EPUB.included` method. Now including `EPUB` module empowers nothing of EPUB features. Include `EPUB::Book::Features` instead.
 * Add `EPUB::Searcher::XHTML::Seamless` and make it default searcher
 * Add `EPUB::Publication::Package::Manifest#each_nav`
 * Stop to use enumerabler gem
 
-[nokogumbo]: https://github.com/rubys/nokogumbo/
+== 0.1.8
 
-0.1.8
------
+* Explicity #close each zip member file that has been opened via #fopen(Thanks, https://github.com/xunker[xunker]!)
 
-* Explicity #close each zip member file that has been opened via #fopen(Thanks, [xunker][]!)
-
-[xunker]: https://github.com/xunker
-
-0.1.7.1
--------
+== 0.1.7.1
 
 * Don't set encoding when content is not text
 
-0.1.7
------
+== 0.1.7
 
 * [Experimental]Add `EPUB::Searcher` module. See {file:Searcher.markdown} for details
 * Detect and set character encoding in `EPUB::Publication::Package::Item#read`
 
-0.1.6
------
+== 0.1.6
 * Remove `EPUB.parse` method
 * Remove `EPUB::Publication::Package::Metadata#to_hash`
 * Add `EPUB::Publication::Package::Metadata::Identifier` for ad-hoc `scheme` attribute and `#isbn?` method
@@ -168,15 +144,12 @@ CHANGELOG
 * Add exception class `EPUB::Constants::MediaType::UnsupportedMediaType`
 * Make `EPUB::Constants::MediaType::UnsupportedError` deprecated. Use `UnsupportedMediatType` instead
 * Add `EPUB::Publication::Package::Item#cover_image?`
-* Add `EPUB::Book::Features` module and move methods of `EPUB` module to it(Thanks, [takahashim][]!)
+* Add `EPUB::Book::Features` module and move methods of `EPUB` module to it(Thanks, https://github.com/takahashim[takahashim]!)
 * Make including `EPUB` deprecated
 * Parse `hidden` attribute of `nav` elements
 * [Experimental]Add `EPUB::ContentDocument::Navigation::Item#traverse`
 
-[takahashim]: https://github.com/takahashim
-
-0.1.5
------
+== 0.1.5
 * Add `ContentDocument::XHTML#title`
 * Add `Manifest::Item#xhtml?`
 * Add `--words` and `--chars` options to `epubinfo` command which count words and charactors of XHTMLs in EPUB file
@@ -185,33 +158,25 @@ CHANGELOG
 * Add `ContentDocument::XHTML#nokogiri` which returns document as `Nokogiri::XML::Document` object
 * Inspect more readbly
 
-0.1.4
------
-* [Fixed-Layout Documents][fixed-layout] support
+== 0.1.4
+* http://www.idpf.org/epub/fxl/[Fixed-Layout Documents] support
 * Define `ContentDocument::XHTML#top_level?`
 * Define `Spine::Itemref#page_spread` and `#page_spread=`
 * Define some utility methods around `Manifest::Item` and `Spine::Itemref`
   * `Manifest::Item#itemref`
   * `Spine::Itemref#item=`
 
-[fixed-layout]: http://www.idpf.org/epub/fxl/
-
-0.1.3
------
+== 0.1.3
 * Add `EPUB::Parser::Utils` module
 * Add a command-line tool `epub-open`
 * Add support for XHTML Navigation Document
 * Make `EPUB::Publication::Package::Metadata#to_hash` obsolete. Use `#to_h` instead
 * Add utility methods `EPUB#description`, `EPUB#date` and `EPUB#unique_identifier`
 
-0.1.2
------
-* Fix a bug that `Item#read` couldn't read file when `href` is percent-encoded(Thanks, [gambhiro][]!)
-
-[gambhiro]: https://github.com/gambhiro
+== 0.1.2
+* Fix a bug that `Item#read` couldn't read file when `href` is percent-encoded(Thanks, https://github.com/gambhiro[gambhiro]!)
 
-0.1.1
------
+== 0.1.1
 * Parse package@prefix and attach it as `Package#prefix`
 * `Manifest::Item#iri` was removed. It have existed for files in unzipped epub books but now EPUB Parser retrieves files from zip archive directly. `#href` now returns `Addressable::URI` object.
 * `Metadata::Link#iri`: ditto.

data/README.adoc

@@ -0,0 +1,228 @@
+= EPUB Parser
+
+= {doctitle}
+
+image:https://gitlab.com/KitaitiMakoto/epub-parser/badges/master/build.svg[link="https://gitlab.com/KitaitiMakoto/epub-parser/commits/master", title="pipeline status"]
+image:https://gemnasium.com/KitaitiMakoto/epub-parser.png[link="https://gitlab.com/KitaitiMakoto/epub-parser/commits/master",title="Dependency Status"]
+image:https://badge.fury.io/rb/epub-parser.svg[link="https://gemnasium.com/KitaitiMakoto/epub-parser",title="Gem Version"]
+image:https://gitlab.com/KitaitiMakoto/epub-parser/badges/master/coverage.svg[link="https://kitaitimakoto.gitlab.io/epub-parser/coverage/",title="coverage report"]
+
+* https://kitaitimakoto.gitlab.io/epub-parser/file.Home.html[Homepage]
+* https://kitaitimakoto.gitlab.io/epub-parser/[Documentation]
+* https://gitlab.com/KitaitiMakoto/epub-parser[Source Code]
+* https://kitaitimakoto.gitlab.io/epub-parser/coverage/[Test Coverage]
+
+== INSTALLATION
+
+----
+gem install epub-parser
+----
+
+== USAGE
+
+=== As a library
+
+----
+require 'epub/parser'
+
+book = EPUB::Parser.parse('book.epub')
+book.metadata.titles # => Array of EPUB::Publication::Package::Metadata::Title. Main title, subtitle, etc...
+book.metadata.title # => Title string including all titles
+book.metadata.creators # => Creators(authors)
+book.each_page_on_spine do |page|
+  page.media_type # => "application/xhtml+xml"
+  page.entry_name # => "OPS/nav.xhtml" entry name in EPUB package(zip archive)
+  page.read # => raw content document
+  page.content_document.nokogiri # => Nokogiri::XML::Document. The same to Nokogiri.XML(page.read)
+  # do something more
+  #    :
+end
+book.cover_image # => EPUB::Publication::Package::Manifest::Item which represents cover image file
+----
+
+See document's {file:docs/Home.markdown} or https://kitaitimakoto.gitlab.io/epub-parser/[API Documentation] for more info.
+
+=== `epubinfo` command-line tool
+
+`epubinfo` tool extracts and shows the metadata of specified EPUB book.
+
+----
+$ epubinfo ~/Documebts/Books/build_awesome_command_line_applications_in_ruby.epub
+Title:              Build Awesome Command-Line Applications in Ruby (for KITAITI MAKOTO)
+Identifiers:        978-1-934356-91-3
+Titles:             Build Awesome Command-Line Applications in Ruby (for KITAITI MAKOTO)
+Languages:          en
+Contributors:       
+Coverages:          
+Creators:           David Bryant Copeland
+Dates:              
+Descriptions:       
+Formats:            
+Publishers:         The Pragmatic Bookshelf, LLC (338304)
+Relations:          
+Rights:             Copyright © 2012 Pragmatic Programmers, LLC
+Sources:            
+Subjects:           Pragmatic Bookshelf
+Types:              
+Unique identifier:  978-1-934356-91-3
+Epub version:       2.0
+----
+
+See {file:docs/Epubinfo.markdown} for more info.
+
+=== `epub-open` command-line tool
+
+`epub-open` tool provides interactive shell(IRB) which helps you research about EPUB book.
+
+----
+epub-open path/to/book.epub
+----
+
+IRB starts. `self` becomes the EPUB book and can access to methods of `EPUB`.
+
+----
+title
+=> "Title of the book"
+metadata.creators
+=> [Author 1, Author2, ...]
+resources.first.properties
+=> #<Set: {"nav"}> # You know that first resource of this book is nav document
+nav = resources.first
+=> ...
+nav.href
+=> #<Addressable::URI:0x15ce350 URI:nav.xhtml>
+nav.media_type
+=> "application/xhtml+xml"
+puts nav.read
+<?xml version="1.0"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
+    :
+    :
+    :
+</html>
+=> nil
+exit # Enter "exit" when exit the session
+----
+
+See {file:docs/EpubOpen.markdown} for more info.
+
+=== `epub-cover` command-line tool
+
+`epub-cover` tool extract cover image from EPUB book.
+
+----
+% epub-cover childrens-literature.epub
+Cover image output to cover.png
+----
+
+See {file:docs/EpubCover.adoc} for details.
+
+== DOCUMENTATION
+
+Documentation is available in https://kitaitimakoto.gitlab.io/epub-parser/file.Home.html[homepage].
+
+If you installed EPUB Parser by gem command, you can also generate documentaiton yourself(https://rubygems.org/gems/rubygems-yardoc[rubygems-yardoc] gem is needed):
+
+----
+$ gem install epub-parser
+$ gem yardoc epub-parser
+...
+Files:          33
+Modules:        20 (   20 undocumented)
+Classes:        45 (   44 undocumented)
+Constants:      31 (   31 undocumented)
+Methods:       292 (   88 undocumented)
+52.84% documented
+YARD documentation is generated to:
+/path/to/gempath/ruby/2.2.0/doc/epub-parser-0.2.0/yardoc
+----
+
+It will show you path to generated documentation(`/path/to/gempath/ruby/2.2.0/doc/epub-parser-0.2.0/yardoc` here) at the end.
+
+Or, generating by yardoc command is possible, too:
+
+----
+$ git clone https://gitlab.com/KitaitiMakoto/epub-parser.git
+$ cd epub-parser
+$ bundle install --path=deps
+$ bundle exec rake doc:yard
+...
+Files:          33
+Modules:        20 (   20 undocumented)
+Classes:        45 (   44 undocumented)
+Constants:      31 (   31 undocumented)
+Methods:       292 (   88 undocumented)
+52.84% documented
+----
+
+Then documentation will be available in `doc` directory.
+
+== REQUIREMENTS
+
+* Ruby 2.3.0 or later
+* `patch` command to install Nokogiri
+* C compiler to compile Nokogiri
+
+== SIMILAR EFFORTS
+
+* https://github.com/skoji/gepub[gepub] - a generic EPUB library for Ruby
+* https://github.com/chdorner/epubinfo[epubinfo] - Extracts metadata information from EPUB files. Supports EPUB2 and EPUB3 formats.
+* https://github.com/kmuto/review[ReVIEW] - ReVIEW is a easy-to-use digital publishing system for books and ebooks.
+* https://github.com/takahashim/epzip[epzip] - epzip is EPUB packing tool. It's just only doing 'zip.' :)
+* https://github.com/jugyo/eeepub[eeepub] - EeePub is a Ruby ePub generator
+* https://gitlab.com/KitaitiMakoto/epub-maker[epub-maker] - This library supports making and editing EPUB books based on this EPUB Parser library
+* https://gitlab.com/KitaitiMakoto/epub-cfi[epub-cfi] - EPUB CFI library extracted this EPUB Parser library.
+
+If you find other gems, please tell me or request a pull request.
+
+== RECENT CHANGES
+
+=== 0.3.7
+
+* Strip leading and trailing white spaces from identifiers
+* Change home page and documentation from rubydoc.info to GitLab Pages
+* Make {EPUB::Book::Features#cover_image Book::Features#cover_image} return EPUB 2 cover image if EPUB 3's not available
+* Add `epub-cover` command-line tool. See {file:docs/EpubCover.adoc} for details.
+
+=== 0.3.6
+
+* [BUG FIX]Ignore fragment when find item by relative IRI
+* Disable https://github.com/ko1/pretty_backtrace[PrettyBacktrace] by default
+
+=== 0.3.5
+
+* [BUG FIX]Fix a bug that {EPUB::ContentDocument::Navigation::Item#item} is `nil` when `href` includes double dots(`..`)(Thanks https://gitlab.com/aelkiss[aelkiss]!)
+
+See {file:CHANGELOG.adoc} for older changelogs and details.
+
+== TODOS
+
+* Consider to implement IRI feature instead of to use Addressable
+* EPUB 3.0.1
+* EPUB 3.1
+* Help features for `epub-open` tool
+* Vocabulary Association Mechanisms
+* Implementing navigation document and so on
+* Media Overlays
+* Content Document
+* Digital Signature
+* Using SAX on parsing
+* Abstraction of XML parser(making it possible to use REXML, standard bundled XML library of Ruby)
+* Handle with encodings other than UTF-8
+
+== DONE
+
+* Simple inspect for `epub-open` tool
+* Using zip library instead of `unzip` command, which has security issue
+* Modify methods around fallback to see `bindings` element in the package
+* Content Document(only for Navigation Documents)
+* Fixed Layout
+* Vocabulary Association Mechanisms(only for itemref)
+* Archive library abstraction
+* Extracting and organizing common behavior from some classes to modules
+* Multiple rootfiles
+
+== LICENSE
+
+This library is distribuetd under the term of the MIT License.
+See {file:MIT-LICENSE} file for more info.