skoji / gepub Goto Github PK

View Code? Open in Web Editor NEW

240.0 15.0 42.0 28.34 MB

a generic EPUB library for Ruby : supports EPUB 3

License: Other

Ruby 100.00%

gepub's Introduction

gepub

https://rubydoc.info/github/skoji/gepub

DESCRIPTION:

a generic EPUB parser/generator library.

FEATURES/PROBLEMS:

GEPUB::Book provides functionality to create EPUB files and parse EPUB files
Handle every metadata in EPUB2/EPUB3.
See issues for known problems.

If you are using GEPUB::Builder and do not like its behavior (e.g., GEPUB::Builder evaluates the block as inside the Builder instance), consider using GEPUB::Book directly.

SYNOPSIS:

Example

require 'rubygems'
require 'gepub'

book = GEPUB::Book.new
book.primary_identifier('http://example.jp/bookid_in_url', 'BookID', 'URL')
book.language = 'ja'

book.add_title 'GEPUBサンプル文書', 
               title_type: GEPUB::TITLE_TYPE::MAIN,
               lang: 'ja',
               file_as: 'GEPUB Sample Book',
               display_seq: 1,
               alternates: {
                       'en' => 'GEPUB Sample Book (Japanese)',
                       'el' => 'GEPUB δείγμα (Ιαπωνικά)',
                       'th' => 'GEPUB ตัวอย่าง (ญี่ปุ่น)' }
               
# you can do the same thing using method chain
book.add_title('これはあくまでサンプルです', title_type: GEPUB::TITLE_TYPE::SUBTITLE).display_seq(1).add_alternates('en' => 'this book is just a sample.')

# use arguments
book.add_creator '小嶋智', 
                 display_seq:1, 
                 alternates: { 'en' => 'KOJIMA Satoshi' } 
book.add_contributor '電書部',
                     display_seq: 1,
                     alternates: {'en' => 'Denshobu'}
book.add_contributor 'アサガヤデンショ',
                     display_seq: 2, 
                     alternates: {'en' => 'Asagaya Densho'}
# you can also use method chain
book.add_contributor('湘南電書鼎談').display_seq(3).add_alternates('en' => 'Shonan Densho Teidan')
book.add_contributor('電子雑誌トルタル').display_seq(4).add_alternates('en' => 'eMagazine Torutaru')

imgfile = File.join(File.dirname(__FILE__),  'image1.jpg')
File.open(imgfile) do
  |io|
  book.add_item('img/image1.jpg',content: io).cover_image
end

# within ordered block, add_item will be added to spine.
book.ordered {
  book.add_item('text/cover.xhtml',
                content: StringIO.new(<<-COVER)).landmark(type: 'cover', title: 'cover page')
                <html xmlns="http://www.w3.org/1999/xhtml">
                <head>
                  <title>cover page</title>
                </head>
                <body>
                <h1>The Book</h1>
                <img src="../img/image1.jpg" />
                </body></html>
  COVER
  book.add_item('text/chap1.xhtml').add_content(StringIO.new(<<-CHAP_ONE)).toc_text('Chapter 1').landmark(type: 'bodymatter', title: '本文')
  <html xmlns="http://www.w3.org/1999/xhtml">
  <head><title>c1</title></head>
  <body><p>the first page</p></body></html>
  CHAP_ONE
  book.add_item('text/chap1-1.xhtml').add_content(StringIO.new(<<-SEC_ONE_ONE)) # do not appear on table of contents
  <html xmlns="http://www.w3.org/1999/xhtml">
  <head><title>c2</title></head>
  <body><p>the second page</p></body></html>
  SEC_ONE_ONE
  book.add_item('text/chap2.xhtml').add_content(StringIO.new(<<-CHAP_TWO)).toc_text('Chapter 2')
  <html xmlns="http://www.w3.org/1999/xhtml">
  <head><title>c3</title></head>
  <body><p>the third page</p></body></html>
  CHAP_TWO
  # to add nav file:
  # book.add_item('path/to/nav').add_content(nav_html_content).add_property('nav')
}
epubname = File.join(File.dirname(__FILE__), 'example_test.epub')

# if you do not specify a nav document with add_item, 
# generate_epub will generate simple navigation text.
# auto-generated nav file will not appear on the spine.
book.generate_epub(epubname)

examples in this repository

INSTALL:

gem install gepub

DONATE:

Bitcoin Address: 1M69AwoxpgPZsp5KStLUEjP7so5dHVfDTH

gepub's People

Contributors

Stargazers

Watchers

Forkers

tinyfive xunker k0tbegem0t mamarjan vnorguet takuan-osho hogelog mike-bourgeous benkoerber ankkho gitter-badger mbchandar chrisauclair mlberns ompugao thenotary pauloabner toroidal-code zzet solomon ccutrer jirutka gambhiro takahashim v-kolesnikov olleolleolle slonopotamus chloerei apayu lulalala shivtej1505 dyet92k andyroberts washu standardgalactic elebow ahsanziauddin 00mjk brandondrew aef edjefferson

gepub's Issues

GEPUB::Builder fallback items will appear on spine

if you write code like this

GEPUB::Builder.new {
# define metadata
#...
  resources {
     ordered {
         fallback_chain_items('file.xml', 'file2.xml', 'file3.xhtml')
         media_type('application/unknown1', 'application/unknown2', 'application/xhtml+xml'
     }
  }
}.generate_epub('epubfile.epub')

file.xml, file2.xml and file3.xhtml appears on spine. only file.xml should appear on spine.

parse epub 2 file error[version = 0.6.6]

When I parse a epub 2 book, it raise an error : undefined namespace prefix: opf:meta[not(@refines) and not(@Property)]
the problem occured at metadata.rb method parse_opf2_meta, do you forget to set the namesapce param for xpath?

support to parse existing EPUB file

Rendition at manifest level setup

Feature request
There's no way to add at manifest level rendition properties (current realization supports only spine)

    <meta property="rendition:layout">pre-paginated</meta>
    <meta property="rendition:orientation">portrait</meta>
    <meta property="rendition:spread">none</meta>

By the way, looks like current iBooks fails to read rendition set via properties in spine and works only with meta-section. And there's no need in setting up custom ibooks com.apple.blah-blah properties file in META-INF.
Checkout this example http://files.infogridpacific.com/fxl-tb/fxl-portrait-locked-16x9.epub

Smart autofix features

What about some «clever features»:

auto add xml declaration if does not exist
<?xml version="1.0" encoding="utf-8"?>
auto fix if <html> to valid <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="ru-RU" lang="en-EN">
set valid xml notation via applying nokogiri preparsing to enpacked xhtml (will quickfix forgotten /> etc)

Write spec for examples

support epubcfi

support EPUB fixed layouts metadata

Support EPUB 3 Fixed Layout Metadata Standard, and hopefully Apple's proprietary extension to EPUB 2

support EPUB3

create kindlegen-ready EPUB file

e.g. opf contains element for indicating table of contents.

a file added by add_optional_file is not written into generated EPUB

support for landmark

http://www.idpf.org/epub/301/spec/epub-contentdocs.html#sec-xhtml-nav-def-types-landmarks

EPUBCheck v4.2.0 gives a warning for generated nav

WARNING(RSC-017): path/to/epub/OEBPS/nav.xhtml(3,9): Warning while parsing file: The 'head' element should have a 'title' child element.

Maybe a title element should be added to head for automatically generated nav file?

support navigation document template

currently, gepub generated nav document is in fixed format, without css.

better traversing interface

gepub API for traversing parsed EPUB data is poor.

For example, if you want to access 1st item on spine from book, you should write code something like this:

   book.instance_eval {
        @package.manifest.item_list[@package.spine.itemref_list[0].idref];
   }

travarsing API seems too complecated

need cleanup

position of mimitype in the container is not valid

will be fixed on next release of rubyzip (version > 0.9.6.1)

.parse support not working as of a3f8a3c55b

Have the added this code to book_spec.rb

context 'on parsing existing book' do
    describe '.parse' do
     context 'IO Object' do
      it 'loads book and returns GEPUB::Book object' do
       filehandle = File.new('/Users/mnielsen/work/gepub/spec/fixtures/test_book.epub')
       book = GEPUB::Book.parse(filehandle)
       expect(book).to be_instance_of GEPUB::Book
      end
     end
    end
  end

It passes in commit 85b18b9 but fails in a3f8a3c.

I would like to help and add more tests to this project, should I add them to the working commit or wait until this code works on the Master branch?

allow `nil` value (and ignore it)

The script below generates valid EPUB file, but without comment of publisher, it's non-valid EPUB file.

require 'gepub'

book = GEPUB::Book.new
book.identifier = 'http://example.jp/bookid_in_url'
book.title = 'GEPUB Sample Book'
book.creator = 'KOJIMA Satoshi'
book.language = 'ja'
## book.publisher = nil

book.ordered do
  item = book.add_item('name.xhtml')
  item.add_content StringIO.new('<html xmlns="http://www.w3.org/1999/xhtml"><head><title>c1</title></head><body><p>the first page</p></body></html>')
end

book.generate_epub("test.epub")

I hope nil value is simply ignored.

LCP feature request

What about such a core feature like http://idpf.org/epub-content-protection ?

Release new version

Please release a new version on RubyGems containing #59.

Invalid nav.xhtml is created on EPUB 3 mode when @toc is empty

Epubcheck validation of nav.html failed: Anchors within nav elements must contain text as far as <a href="index.html"/> is not valid.

extending `Book#add_item` and other `add_xxx` methods

IMHO, some examples, such as book.add_item('foo.xhtml').add_content(bar).toc_text(buz) or book.add_contributor(foo).display_seq(1).add_alternates('en' => 'buz') seems a bit complicated.

How about shortcut methods like book.add_item('foo.xhtml', content: bar, toc: buz) or book.add_contributor(foo, display_seq: 1, alternatives: "en" => 'buz') ?

Or, if targets ruby versions are not so old, we can use keyword arguments like book.insert_item(name: 'foo.xhtml', content: bar, toc: buz). (I'd like to use the name add_item, but its API compatibilities are broken...)

add mathml,svg,switch property to item automatically

On adding content to item, set property to item automatically by parsing content.

Can't modify table of contents of GEPUB::Book generated by Book.parse

How to add images into epub without spine section?

I trying to create ePub like in example

    book.ordered {
      @pages.drop(1).each_with_index do |img, index|
        book.add_item("Text/chap#{index + 1}.xhtml").add_content(StringIO.new(page_with_image img)).toc_text("#{@page_name_prefix} #{index + 1}")
        book.add_item("Images/#{basename_image(img)}").add_content(img)
      end
    }

but after building end i see all pages is duplicated because <spine> section contain chapters with images:

<spine toc="ncx">
    <itemref  idref="item_chap0"/>
    <itemref  idref="item_picture_00001"/>
    <itemref  idref="item_chap1"/>
    <itemref  idref="item_picture_00002"/>
    <itemref  idref="item_chap2"/>
 </spine>

As i thing it happened because book.add_item("Images/#{basename_image(img)}").add_content(img). How i can add images by right way?

better spine itemref's properties attribute handling

Spine itemref element's properties attribute holds data like page-spread or rendition setting in fixed layout data.
Gepub supports to read and write properties attribute of itemref elements as raw string, so a client should parse the string manually.

support EPUB 3.0.1

should change Meta#to_s(locale) to Meta#to_str(locale)

refactor test

Don't bundle the test suite

The test suite is inflating the size of gem. As of the 1.0.2 release, the gem is over 10MB. There's no reason to publish the test suite with the gem since it isn't used at runtime. It's better just to keep the test suite in the git repository (available for a release via a tag).

missing support for <binding> in OPF

GEPub::Book.parse().generate_epub won't work.

autoinclude and manifest all files in project dir

is a feature request )

better metadata handling

need documentation

support properties attribute in item-ref

Get and set date metadata with ruby Time object

Benchmarks/Compare features with KitaitiMakoto/epub-parser

https://gitlab.com/KitaitiMakoto/epub-parser

better DSL design

The design goal of GEPUB::Builder API is "easy to learn for non-programmers".

But actually, GEPUB::Builder is

Not easy to learn for non programmers
Awful for ruby programmers

Besides, I found that non-programmers do not want to write XHTML contents and EPUB DSL separately.
Then just want to write (markuped) texts with some metadata and convert it directly into EPUB.

So we should give up original goal and redesign DSL for ruby programmer.

GEPUB::Builder.new {
     resources {
          file '01.xhtml' # which has video tag referencing external video
          remote_resources

          remote_file 'http://example.com/external_video_resource.mp4'
          media_type 'video/mp4'
     }
}