/ 
EBook-MOBI-0.72
River stage one • 2 direct dependents • 2 total dependents
/ EBook::MOBI

NAME

EBook::MOBI - create an ebook in the MOBI format.

You are at the right place here if you want to create an ebook in the so called MOBI format (somethimes also called PRC format or Mobipocket).

This is a software library for the perl programming language.

SYNOPSIS

If you plan to create a typical ebook you probably will need most of the methods provided by this module. So it might be a good idea to read all the descriptions in the methods section, and also have a look at this example here.

Minimalistic Example

Paste and run.

use EBook::MOBI;
my $book = EBook::MOBI->new();
$book->add_mhtml_content("hello world");
$book->make();
$book->save();

You should then find a file book.mobi in your current directory.

Detailed Example

Because the input in this example is from the same file as the code, and this text-file is utf-8, we enable utf-8 and we will have no problems.

use utf8;

Then we create an object and set some information about the book.

# Create an object of a book
use EBook::MOBI;
my $book = EBook::MOBI->new();

# give some meta information about this book
$book->set_filename('./data/my_ebook.mobi');
$book->set_title   ('Read my Wisdome');
$book->set_author  ('Alfred Beispiel');
$book->set_encoding(':encoding(UTF-8)');

Input can be done in several ways. You can always work directly with the format itself. See EBook::MOBI::Converter for more information about this format.

# lets create our own title page!
$book->add_mhtml_content(
    " <h1>This is my Book</h1>
     <p>Read my wisdome.</p>"
);
$book->add_pagebreak();

To help you with the format use EBook::MOBI::Converter. The above would then look like this:

my $c = EBook::MOBI::Converter->new();
$book->add_mhtml_content( $c->title('This is my Book', 1, 0) );
$book->add_mhtml_content( $c->paragraph('Read my wisdome')   );
$book->add_mhtml_content( $c->pagebreak()                    );

At any point in the book you can insert a table of content.

# insert a table of contents after the titlepage
$book->add_toc_once();
$book->add_pagebreak();

The preferred way for your normal input should be the add_content() method. It makes use of plugins, so you should make sure there is a plugin for your input markup.

my $POD_in = "=head1 Title\n\nSome text.\n\n";  

# add the books text, which is e.g. in the POD format
$book->add_content( data           => $POD_in,
                    driver         => 'EBook::MOBI::Driver::POD',
                    driver_options => { pagemode => 1},
                  );

After that, some small final steps are needed and the book is ready.

# prepare the book (e.g. calculate the references for the TOC)
$book->make();

# let me see how this mobi-format looks like
$book->print_mhtml();

# ok, give me that mobi-book as a file!
$book->save();

# done

METHODS (set meta data)

set_title

Give a string which will appear in the meta data of the format. This will be used e.g. by ebook-readers to determine the books name.

$book->set_title('Read my Wisdome');

set_author

Give a string which will appear in the meta data of the format. This will be used e.g. by ebook-readers to determine the books author.

$book->set_author('Alfred Beispiel');

set_filename

The book will be stored under the name and location you pass here. When calling the save() method the file will be created.

$book->set_filename('./data/my_ebook.mobi');

If you don't use this method, the default name will be 'book.mobi'.

set_encoding

If you don't set anything here, :encoding(UTF-8) will be default.

$book->set_encoding(':encoding(UTF-8)');

Only two encodings are supported by the mobiperl driver: UTF-8 or ISO-8859-1. ASCII is treated the same as ISO-8859-1. If any other encodings are passed in, the module will raise an error.

Please see http://perldoc.perl.org/functions/binmode.html for the syntax of your encoding keyword. If you use use hardcoded strings in your program, use utf8; should be helping.

METHODS (adding content)

add_mhtml_content

'mhtml' stands for mobi-html, which means: it is actually HTML but some things are different. I invented this term myself, so it is probably not a good idea to search the web or ask other people about it. If you are looking for more information about this format you might search the web for 'mobipocket file format' or something similar.

If you stick to the most basic HTML tags it should be perfect mhtml 'compatible'. This way you can add your own content directly. If this is to tricky, have a look at the add_content() method.

$book->add_mhtml_content(
    " <h1>This is my Book</h1>
     <p>Read my wisdome.</p>"
);

If you indent the 'h1' tag with any whitespace, it will not appear in the TOC (only 'h1' tags directly starting and ending with a newline are marked for the TOC). This may be usefull if you want to design a title page.

There is a module EBook::MOBI::Converter which helps you in creating this format. See it's documentation for more information.

If you are passing your own text to add_mhtml_content rather than using a converter you will need to: a) encode the text according to your chosen encoding, eg call Encode::encode_utf8; b) ensure that any HTML entities such as '<' in your text are replaced, eg by calling HTML::Entities::encode_entities.

add_content

Use this method if you have your content in a specific markup format. See below for details to the arguments supported by this method.

$book->add_content( data           => $data_as_string,
                    driver         => $driver_name,
                    driver_options => {plugin_option => $value}
                  );

The method uses a plugin system to transform your format into an ebook. If you don't find a plugin for your markup please write one and release it under the namespace EBook::MOBI::Driver::$YourMarkup.

Details for the options of this method:

data

A string, containing your text for the ebook.

driver

The name of the module which parses your data. If this value is not set, the default is EBook::MOBI::Driver::POD. You are welcome to add your own driver for your markup of choice!

driver_options

Pass a hash ref here, with options for the plugin. This options may be different for each plugin.

add_pagebreak

Use this method to seperate content and give some structure to your book.

$book->add_pagebreak();

add_toc_once

Use this method to place a table of contents into your book. You will need to call the make() method later, after you added all your content to the book. This is, because we need all the content - to be able to calculate the references where the TOC is pointing to. Only 'h1' tags starting and ending with a newline char will enter the TOC.

$book->add_toc_once();

By default, the toc is called 'Table of Contents'. You can change that label by passing it as a parameter:

$book->add_toc_once( 'Summary' );

This method can only be called once. If you call it twice, the second call will not do anything.

METHODS (finishing)

make

You only need to call this one before saving, if you have used the add_toc_once() method. This will calculate the references, pointing from the TOC into the content.

$book->make();

If you are curious how the mobi-specific HTML looks like, take a look!

If you call the method it will print to standard output. You can change this behaviour by passing any true argument. The content will then be returned, so that you can store it in a variable.

# print to stdout
$book->print_mhtml();

# or get the result into a variable
$mhtml_data = $book->print_mhtml('result to var');

save

Put the whole thing together as an ebook. This will create a file, with the name and location you gave with set_filename().

$book->save();

In this process it will also read images and store them into the ebook. So it is important, that the images are readable at the path you provided before.

METHODS (debugging)

reset

Reset the object, so that all the content is purged. Helpful if you like to make a new book, but are to lazy to create a new object. (e.g. for testing)

$book->reset();

debug_on

You can just ignore this method if you are not interested in debugging! Pass a reference to a debug subroutine and enable debug messages.

sub debug {
    my ($package, $filename, $line) = caller;
    print "$package\t$_[0]\n";
}

$book->debug_on(\&debug);

Or shorter:

$book->debug_on(sub { print @_; print "\n" });

debug_off

Stop debug messages and erease the reference to the subroutine.

$book->debug_off();

PLUGINS / DRIVERS

POD

EBook::MOBI::Driver::POD is a plugin for Perls markup language POD. Please see its docs for more information and options.

Example

EBook::MOBI::Driver::Example is an example implementation of a simple plugin. It is only useful for plugin writers, as an example. Please see its docs for more information and options.

IMAGES

Since v0.56 there is a change to the image behaviour. If you like to include images or pictures into your ebook you now should install the module EBook::MOBI::Image. This code is no more with the main module, to reduce dependencies to image libraries (not everybody need to add images). It depends on your input plugin, how you can add images to your book. For POD, see the special syntax described in EBook::MOBI::Driver::POD. For adding manually in MHTML, see EBook::MOBI::Converter.

Shortcut for lazy guys: The conclusion of reading EBook::MOBI::Driver::POD will be that you can add images via the POD-driver as following:

$book->add_content( data   => '=for image /my/camel.jpg This is a Camel.',
                    driver => 'EBook::MOBI::Driver::POD',
                    driver_options => { pagemode => 0, head0_mode => 0 }
                  );

If you don't want to use the POD driver for adding images then you should read the section WHAT IS MHTML? in the module EBook::MOBI::Converter (as said already). But this needs some effort.

SEE ALSO

THANKS TO

  • Renée Bäcker and Perl-Services.de for the idea, patches and making this module possible.

  • Perl-Magazin for publishing an article in autumn 2012.

  • Linux-Magazin for mentioning the module in the Perl-Snapshots. The article is also available online and as podcast.

  • Tompe for developing MobiPerl.

CONTRIBUTORS

COPYRIGHT & LICENSE

Copyright 2015 Boris Däppen, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.

AUTHOR

Boris Däppen <bdaeppen.perl@gmail.com>