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).

# 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.

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 there is also a module. The above could also be coded with the help of that.

     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.

     # 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. As far as I know, only CP1252 (Win Latin1) und UTF-8 are supported by popular readers.

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

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.

## 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`.

### 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();

## print_mhtml

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 debuging! 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.

# SEE ALSO

- Github for participating and also for bugreports.
- EBook::MOBI::Converter - look up what I mean by saying MHTML.
- Everything in the namespace `EBook::MOBI::MobiPerl` is coming from MobiPerl. For information about this code, please visit https://dev.mobileread.com/trac/mobiperl

# 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

- Garu

# COPYRIGHT & LICENSE

Copyright 2012 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Driver::Example

# NAME

EBook::MOBI::Driver::Example - Example plugin implementation.

This module is just for demonstration. I invented a very simple markup, which works only line by line, to show how a plugin can be created.

# SYNOPSIS (for users)

If you wan't to run this as a plugin, use this code. But I can't imagine any situation where this might be the case for real, since this is just an example for a markup which is not actually existing.

     use EBook::MOBI;
     my $book = EBook::MOBI->new();

     my $foomarkup= <<FOOMARKUP;
     !h! This is a Title
     ! ! A normal text line.
     !i! An italic text line.
     ! ! This is just a very simple example of markup.
     !b! Guess what. This is a bold line.

     typo : this is ignored
     !U! unknown command
     FOOMARKUP

     $book->add_content( data   => $foomarkup,
                         driver => 'EBook::MOBI::Driver::Example',
                       );

# SYNOPSIS (for developers)

Here you can see how the plugin will be called by EBook::MOBI:

     use EBook::MOBI::Driver::Example;

     my $plugin = EBook::MOBI::Driver::Example->new();

     my $format= <<FOOMARKUP;
     !h! This is a Title
     ! ! A normal text line.
     !i! An italic text line.
     ! ! This is just a very simple example of markup.
     !b! Guess what. This is a bold line.

     typo : this is ignored
     !U! unknown command
     FOOMARKUP

     my $mobi_format = $plugin->parse($format);

Please check the source code of this module if you are interested in writing a plugin. It will be a good and simple example.

# Methods

## parse

This is the method each plugin should provide! It takes the input format as a string and returns MHTML.

## inherited methods

See EBook::MOBI::Driver for usefull inherited methods. You can use the debug methods from this module for example.

# COPYRIGHT & LICENSE

Copyright 2012 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Driver::POD

# NAME

EBook::MOBI::Driver::POD - Create HTML, flavoured for the MOBI format, out of POD.

This module extends Pod::Parser for parsing capabilities. The module HTML::Entities is used to translate chars to HTML entities.

# SYNOPSIS (for users)

The plugin is called like this while using `EBook::MOBI`:

     use EBook::MOBI;
     my $book = EBook::MOBI->new();

     my $POD_in = <<END;
     =head1 SOME POD

     Just an example.

     END

     $book->add_content( data           => $POD_in,
                         driver         => 'EBook::MOBI::Driver::POD',
                         driver_options => { pagemode => 1, head0_mode => 0 }
                       );

# SYNOPSIS (for developers)

This module is a plugin for EBook::MOBI. You probably don't need to access this module directly, unless you are a developer for `EBook::MOBI`.

     use EBook::MOBI::Driver::POD;
     my $plugin = new EBook::MOBI::Driver::POD;

     my $mobi_format = $plugin->parse($pod);

# METHODS

## parse

This is the method each plugin should provide! It takes the input format as a string and returns MHTML.

# OPTIONS (POD plugin specific)

## set_options

This method is provided by all plugins. This module supports the following options:

     $plugin->set_options(pagemode => 1, head0_mode => 1);

See description below for more details of the options.

### pagemode

Pass any true value to enable `pagemode`. The effect will be, that before every - but the first - title on highest level there will be a peagebreak inserted. This means: The resulting ebook will start each `h1` chapter at a new page.

Default is to not add any pagebreak.

### head0_mode

Pass any true value to enable `head0_mode`. The effect will be, that you are allowed to use a `=head0` command in your POD.

Pod can now look like this:

      =head0 Module EBook::MOBI

      =head1 NAME

      =head1 SYNOPSIS

      =head0 Module EBook::MOBI::Pod2Mhtml

      =head1 NAME

      =head1 SYNOPSIS

      =cut

This feature is useful if you want to have the documentation of several modules in Perl in one ebook. You then can add a higher level of titles, so that the TOC does not only contain several NAME and SYNOPSIS entries.

Default is to ignore any `=head0` command.

# COPYRIGHT & LICENSE

Copyright 2011,2012 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Driver

# NAME

EBook::MOBI::Driver - Interface for plugins.

Thid module helps you to write an input plugin for `EBook::MOBI`.

# SYNOPSIS

Some example code snippets are provided here. For a complete example, please have a look at EBook::MOBI::Driver::Example.

     # Plugin for EBook::MOBI
     use EBook::MOBI::Driver;
     our @ISA = ('EBook::MOBI::Driver');

     sub parse {
         my ($self, $input) = @_;

         # your code to convert input to output

         return $output;
     }

     sub set_options {
         my $self = shift;
         my $args = shift;

         # call the args like this
         if (ref($args) eq "HASH") {
             if ($args->{YOUR_ARG_NAME}) {
                 # do your stuff
             }
         }
     }

# IMPLEMENTED METHODS

## new

Saves a plugin the need to write this one.

## debug_on

Enable debugging by passing a sub.

## debug_off

Stop debug messages.

## debug_msg

Write a debug message.

# EMPTY METHODS

## parse

Should be implemented by the plugin! Takes a string, returns a string.

## set_options

Should be implemented by the plugin! Takes a hash ref with arguments.

# COPYRIGHT & LICENSE

Copyright 2012 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Converter

# NAME

EBook::MOBI::Converter - Tool to create MHTML.

# SYNOPSIS

      use EBook::MOBI::Converter;
      my $c = EBook::MOBI::Converter->new();

      my $mhtml_text = '';

      $mhtml_text .= $c->title(     $c->text('This is my Book') , 1, 0);
      $mhtml_text .= $c->paragraph( $c->text('Read my wisdome')       );
      $mhtml_text .= $c->pagebreak(                                   );

# WHAT IS MHTML?

'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 this term. 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'. So if you want to 'write a book' or something similar you can just use basic HTML for markup. The ebook readers using the MOBI format actually just display plain HTML. But sadly that's not the whole truth - you can't stick to the official HTML standards. Since I did some research on how to do things, I'd like to share my knowledge.

## Simple Text

Most simple HTML tags will just work.

      <h1>My Book</h1>
      <p>
      This is my first book.
      I want to show the world <b>my</b> mind!
      <br />&nbsp; -- the author
      </p>

## TOC and Hyperlinks

Hyperlinks pointing to the WWW are working just like in HTML. But if you want to point into your own file, e.g. for a table of contents, it will not work. You then have to declare an attribute called 'filepos' which points to the char where you whant to jump to.

      <h1>Table of Contents</h1>
      <ul>
      <li><a filepos="00000458">CHAPTER ONE</a></li>
      <li><a filepos="00000510">CHAPTER TWO</a></li>
      </ul>

## Images

Images are handled slightly different than in standard HTML, since all the data is not on a normal filesystem - it is packed into the MOBI format. Since there are no such thing as filenames in the MOBI format (at least as far as I know) you can't point to an image over it's name. Images are stored in seperat format-intern containers, which have a count. You can then adress to an image with the number of it's container. The syntax is like this:

      <img recindex="0004">

Attention! If you have a lot of text, it will fill up more than one container. But even then... images always start counting from recindex one! So this count seems to be relative, not absolute. Just start counting with `recindex="1"` and it will be fine!

## New Page

If you want to enforce a new page at the ebook-reader you can use a MOBI specific tag:

      <mbp:pagebreak />

# METHODS

## new

## text

Returns your normal text (without markup) encoded for MHTML, which means, HTML special chars get replaced with HTML entities.

This method gets not called autmotically by the other methods. So you need to call this every time, also when using other methods, if you want to ensure that special chars are converted.

# METHODS (for tags)

## title

Returns your text formated as a title. Takes 3 arguments:

     my $mobi_title = $converter->title(

        # Arguments:

            $text, # your title

            $level,# title level form 1 to 6
                   # (default: 1)

            $toc   # pass false if it should not appear in the TOC
                   # (default: true)
     );

## paragraph

## newline

## pagebreak

## italic

## bold

## code

     $mhtml = $c->code(
     'for my $i (@a) {
         print $_;
         print "the end\n";
     }
     ');

## small

## big

## emphasize

## list

Create a very simple list.

     my $mhtml = $c->list( ['A', 'B', 'C', 'D'], 'ul' );

## table

Create a very simple table.

     $mhtml = $c->table(   th =>   ['A', 'B', 'C'],
                             td => [
                                    ['1', '2', '3'],
                                    ['10', '20', '30'],
                                    ['100', '200', '300']
                                   ],
                             caption     => 'This is a table',
                             border      => '8',
                             cellspacing => '10',
                             cellpadding => '20'
                         );

## image

Add a picture to the data.

     $mhtml = $c->image('/path/to/pic.jpg', 'This is a picture');

Image must remain on the path at disc, until ebook is created! This method just adds the path, not the data.

# Possible Tags

According to mobipocket.com the following tags are supported in Mobipocket. Not all are implemented in the methods mentioned above.

      <?xml?>
      <?xml-stylesheet?>
      <!--
      <!doctype>
      <a>
      <area>
      <b>
      <base>
      <big>
      <blockquote>
      <body>
      <br
      <caption>
      <center>
      <cite>
      <code>
      <dd>
      <del>
      <dfn>
      <dir>
      <div>
      <dl>
      <dt>
      <em>
      <font>
      <head>
      <h1
      <hr
      <html>
      <i>
      <img
      <ins>
      <kbd>
      <li>
      <link
      <listing>
      <map>
      <menu>
      <meta>
      <object>
      <ol>
      <p>
      <param>
      <plaintext>
      <pre>
      <q>
      <s>
      <samp>
      <small>
      <span>
      <strike>
      <strong>
      <style>
      <sub>
      <sup>
      <table>
      <td>
      <th>
      <title>
      <tr>
      <tt>
      <u>
      <ul>
      <var>
      <xmp>

# COPYRIGHT & LICENSE

Copyright 2012 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Picture

# NAME

EBook::MOBI::Picture - Make sure that pictures cope with the MOBI standards.

# SYNOPSIS

      use EBook::MOBI::Picture;
      my $p = EBook::MOBI::Picture->new();

      my $img_path_small = $p->rescale_dimensions($img_path_big);

# METHODS

## new

The code is meant to be used in object oriented style, so you are asked to create an object before using.

      my $p = EBook::MOBI::Picture->new();

## rescale_dimensions

According to my own research at the web, it is a good idea to have a maximum size for images of 520 x 622. And this is what this method does, it ensures that this maximum is kept.

Pass a path to an image as the first argument, you will then get back the path of a rescaled image. The image is only rescaled if necessary.

Attention: All pictures, no matter what size will be converted to JPG. In my tests, the Kindle-Reader failed to display PNG, that is why I convert everything - to go safe.

## debug_on

You can just ignore this method if you are not interested in debuging!

Pass a reference to a debug subroutine and enable debug messages.

## debug_off

Stop debug messages and erease the reference to the subroutine.

# TODO

A method to 'clean up' and also to change the maximum values would be nice.

# COPYRIGHT & LICENSE

Copyright 2011 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 <boris_daeppen@bluewin.ch>

EBook::MOBI::Mhtml2Mobi- Create a Mobi ebook by packing MOBI-ready HTML.

# NAME

EBook::MOBI::Mhtml2Mobi- Create a Mobi ebook by packing MOBI-ready HTML.

# SYNOPSIS

      use EBook::MOBI::Mhtml2Mobi;
      my $mobi = EBook::MOBI::Mhtml2Mobi->new();
      $mobi->pack($mhtml, $out_filename, $author, $title);

# METHODS

## pack

The input parameters are the following:

      $mhtml     # data to put in the mobi ebook
      $filename  # filename (with path) of the desired ebook
      $author    # author of the ebook
      $title     # title of the ebook

Call the method like this:

      $mobi->pack($mhtml, $filename, $author, $title);

After the method call, a Mobi ebook should be found at the path you specified in $filename.

### Handling of Images

If your input data ($mhtml) contains <img> tags which are pointing to images on the filesystem, these images will be stored and linked into the MOBI datafile. The images will be rescaled if necessary, according to EBook::MOBI::Picture.

# COPYRIGHT & LICENSE

Copyright 2012 Boris Däppen, all rights reserved.

Parts of this code are coming from MobiPerl.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

# AUTHOR

Boris Däppen <boris_daeppen@bluewin.ch>