<html><head><title>EBook::MOBI</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI - create an ebook in the MOBI format.</p>
<p>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).</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<p>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.</p>
<p>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.</p>
<pre> use utf8;</pre>
<p>Then we create an object and set some information about the book.</p>
<pre> # 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)');</pre>
<p>Input can be done in several ways. You can always work directly with the format itself. See <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3AConverter" class="podlinkpod"
>EBook::MOBI::Converter</a> for more information about this format.</p>
<pre> # lets create our own title page!
$book->add_mhtml_content(
" <h1>This is my Book</h1>
<p>Read my wisdome.</p>"
);
$book->add_pagebreak();</pre>
<p>To help you with the format there is also a module. The above could also be coded with the help of that.</p>
<pre> 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() );</pre>
<p>At any point in the book you can insert a table of content.</p>
<pre> # insert a table of contents after the titlepage
$book->add_toc_once();
$book->add_pagebreak();</pre>
<p>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.</p>
<pre> # 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},
);</pre>
<p>After that, some small final steps are needed and the book is ready.</p>
<pre> # 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</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_(set_meta_data)"
>METHODS (set meta data)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_title"
>set_title</a></h2>
<p>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.</p>
<pre> $book->set_title('Read my Wisdome');</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_author"
>set_author</a></h2>
<p>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.</p>
<pre> $book->set_author('Alfred Beispiel');</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_filename"
>set_filename</a></h2>
<p>The book will be stored under the name and location you pass here. When calling the save() method the file will be created.</p>
<pre> $book->set_filename('./data/my_ebook.mobi');</pre>
<p>If you don't use this method, the default name will be 'book.mobi'.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_encoding"
>set_encoding</a></h2>
<p>If you don't set anything here, <code>:encoding(UTF-8)</code> will be default. As far as I know, only CP1252 (Win Latin1) und UTF-8 are supported by popular readers.</p>
<pre> $book->set_encoding(':encoding(UTF-8)');</pre>
<p>Please see <a href="http://perldoc.perl.org/functions/binmode.html" class="podlinkurl"
>http://perldoc.perl.org/functions/binmode.html</a> for the syntax of your encoding keyword. If you use use hardcoded strings in your program, <code>use utf8;</code> should be helping.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_(adding_content)"
>METHODS (adding content)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="add_mhtml_content"
>add_mhtml_content</a></h2>
<p>'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.</p>
<p>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.</p>
<pre> $book->add_mhtml_content(
" <h1>This is my Book</h1>
<p>Read my wisdome.</p>"
);</pre>
<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.</p>
<p>There is a module <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3AConverter" class="podlinkpod"
>EBook::MOBI::Converter</a> which helps you in creating this format. See it's documentation for more information.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="add_content"
>add_content</a></h2>
<p>Use this method if you have your content in a specific markup format. See below for details to the arguments supported by this method.</p>
<pre> $book->add_content( data => $data_as_string,
driver => $driver_name,
driver_options => {plugin_option => $value}
);</pre>
<p>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 <code>EBook::MOBI::Driver::$yourMarkup</code>.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="data"
>data</a></h3>
<p>A string, containing your text for the ebook.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="driver"
>driver</a></h3>
<p>The name of the module which parses your data. If this value is not set, the default is <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3ADriver%3A%3APOD" class="podlinkpod"
>EBook::MOBI::Driver::POD</a>. You are welcome to add your own driver for your markup of choice!</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="driver_options"
>driver_options</a></h3>
<p>Pass a hash ref here, with options for the plugin. This options may be different for each plugin.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="add_pagebreak"
>add_pagebreak</a></h2>
<p>Use this method to seperate content and give some structure to your book.</p>
<pre> $book->add_pagebreak();</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="add_toc_once"
>add_toc_once</a></h2>
<p>Use this method to place a table of contents into your book. You will <b>need to</b> call the make() method later, <b>after</b> 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.</p>
<pre> $book->add_toc_once();</pre>
<p>By default, the toc is called 'Table of Contents'. You can change that label by passing it as a parameter:</p>
<pre> $book->add_toc_once( 'Summary' );</pre>
<p>This method can only be called once. If you call it twice, the second call will not do anything.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_(finishing)"
>METHODS (finishing)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="make"
>make</a></h2>
<p>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.</p>
<pre> $book->make();</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="print_mhtml"
>print_mhtml</a></h2>
<p>If you are curious how the mobi-specific HTML looks like, take a look!</p>
<p>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.</p>
<pre> # print to stdout
$book->print_mhtml();
# or get the result into a variable
$mhtml_data = $book->print_mhtml('result to var');</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="save"
>save</a></h2>
<p>Put the whole thing together as an ebook. This will create a file, with the name and location you gave with set_filename().</p>
<pre> $book->save();</pre>
<p>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.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_(debugging)"
>METHODS (debugging)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="reset"
>reset</a></h2>
<p>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)</p>
<pre> $book->reset();</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_on"
>debug_on</a></h2>
<p>You can just ignore this method if you are not interested in debuging! Pass a reference to a debug subroutine and enable debug messages.</p>
<pre> sub debug {
my ($package, $filename, $line) = caller;
print "$package\t$_[0]\n";
}
$book->debug_on(\&debug);</pre>
<p>Or shorter:</p>
<pre> $book->debug_on(sub { print @_; print "\n" });</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_off"
>debug_off</a></h2>
<p>Stop debug messages and erease the reference to the subroutine.</p>
<pre> $book->debug_off();</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="PLUGINS_/_DRIVERS"
>PLUGINS / DRIVERS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="POD"
>POD</a></h2>
<p><a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3ADriver%3A%3APOD" class="podlinkpod"
>EBook::MOBI::Driver::POD</a> is a plugin for Perls markup language POD. Please see its docs for more information and options.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Example"
>Example</a></h2>
<p><a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3ADriver%3A%3AExample" class="podlinkpod"
>EBook::MOBI::Driver::Example</a> 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.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<ul>
<li><a href="https://github.com/borisdaeppen/EBook--MOBI" class="podlinkurl"
>Github</a> for participating and also for <a href="https://github.com/borisdaeppen/EBook--MOBI/issues" class="podlinkurl"
>bugreports</a>.</li>
<li><a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3AConverter" class="podlinkpod"
>EBook::MOBI::Converter</a> - look up what I mean by saying MHTML.</li>
<li>Everything in the namespace <code>EBook::MOBI::MobiPerl</code> is coming from MobiPerl. For information about this code, please visit <a href="https://dev.mobileread.com/trac/mobiperl" class="podlinkurl"
>https://dev.mobileread.com/trac/mobiperl</a></li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="THANKS_TO"
>THANKS TO</a></h1>
<ul>
<li>Renée Bäcker and <a href="http://www.perl-services.de/" class="podlinkurl"
>Perl-Services.de</a> for the idea, patches and making this module possible.</li>
<li><a href="http://perl-magazin.de/" class="podlinkurl"
>Perl-Magazin</a> for publishing an article in autumn 2012.</li>
<li><a href="http://shop.linuxnewmedia.de/eh20194.html" class="podlinkurl"
>Linux-Magazin</a> for mentioning the module in the Perl-Snapshots. The article is also available <a href="http://www.linux-magazin.de/content/view/full/69651" class="podlinkurl"
>online</a> and as <a href="http://www.linux-magazin.de/plus/2012/08/Perl-Snapshot-Linux-Magazin-2012-08" class="podlinkurl"
>podcast</a>.</li>
<li>Tompe for developing MobiPerl.</li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="CONTRIBUTORS"
>CONTRIBUTORS</a></h1>
<ul>
<li><a href="https://metacpan.org/author/GARU" class="podlinkurl"
>Garu</a></li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2012 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Driver::Example</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Driver::Example - Example plugin implementation.</p>
<p>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.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS_(for_users)"
>SYNOPSIS (for users)</a></h1>
<p>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 <b>just an example</b> for a markup which is not actually existing.</p>
<pre> 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',
);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS_(for_developers)"
>SYNOPSIS (for developers)</a></h1>
<p>Here you can see how the plugin will be called by <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI" class="podlinkpod"
>EBook::MOBI</a>:</p>
<pre> 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);</pre>
<p>Please check the source code of this module if you are interested in writing a plugin. It will be a good and simple example.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Methods"
>Methods</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="parse"
>parse</a></h2>
<p>This is the method each plugin should provide! It takes the input format as a string and returns MHTML.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="inherited_methods"
>inherited methods</a></h2>
<p>See <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3ADriver" class="podlinkpod"
>EBook::MOBI::Driver</a> for usefull inherited methods. You can use the debug methods from this module for example.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2012 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Driver::POD</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Driver::POD - Create HTML,
flavoured for the MOBI format,
out of POD.</p>
<p>This module extends <a href="http://search.cpan.org/perldoc?Pod%3A%3AParser" class="podlinkpod"
>Pod::Parser</a> for parsing capabilities.
The module <a href="http://search.cpan.org/perldoc?HTML%3A%3AEntities" class="podlinkpod"
>HTML::Entities</a> is used to translate chars to HTML entities.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS_(for_users)"
>SYNOPSIS (for users)</a></h1>
<p>The plugin is called like this while using <code>EBook::MOBI</code>:</p>
<pre> 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 }
);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS_(for_developers)"
>SYNOPSIS (for developers)</a></h1>
<p>This module is a plugin for <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI" class="podlinkpod"
>EBook::MOBI</a>. You probably don't need to access this module directly, unless you are a developer for <code>EBook::MOBI</code>.</p>
<pre> use EBook::MOBI::Driver::POD;
my $plugin = new EBook::MOBI::Driver::POD;
my $mobi_format = $plugin->parse($pod);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="parse"
>parse</a></h2>
<p>This is the method each plugin should provide! It takes the input format as a string and returns MHTML.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="OPTIONS_(POD_plugin_specific)"
>OPTIONS (POD plugin specific)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_options"
>set_options</a></h2>
<p>This method is provided by all plugins. This module supports the following options:</p>
<pre> $plugin->set_options(pagemode => 1, head0_mode => 1);</pre>
<p>See description below for more details of the options.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="pagemode"
>pagemode</a></h3>
<p>Pass any true value to enable <code>pagemode</code>. 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 <code>h1</code> chapter at a new page.</p>
<p>Default is to not add any pagebreak.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="head0_mode"
>head0_mode</a></h3>
<p>Pass any true value to enable <code>head0_mode</code>. The effect will be, that you are allowed to use a <code>=head0</code> command in your POD.</p>
<p>Pod can now look like this:</p>
<pre> =head0 Module EBook::MOBI
=head1 NAME
=head1 SYNOPSIS
=head0 Module EBook::MOBI::Pod2Mhtml
=head1 NAME
=head1 SYNOPSIS
=cut</pre>
<p>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.</p>
<p>Default is to ignore any <code>=head0</code> command.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2011,2012 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Driver</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Driver - Interface for plugins.</p>
<p>Thid module helps you to write an input plugin for <code>EBook::MOBI</code>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<p>Some example code snippets are provided here.
For a complete example,
please have a look at <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3ADriver%3A%3AExample" class="podlinkpod"
>EBook::MOBI::Driver::Example</a>.</p>
<pre> # 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
}
}
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="IMPLEMENTED_METHODS"
>IMPLEMENTED METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="new"
>new</a></h2>
<p>Saves a plugin the need to write this one.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_on"
>debug_on</a></h2>
<p>Enable debugging by passing a sub.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_off"
>debug_off</a></h2>
<p>Stop debug messages.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_msg"
>debug_msg</a></h2>
<p>Write a debug message.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="EMPTY_METHODS"
>EMPTY METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="parse"
>parse</a></h2>
<p>Should be implemented by the plugin! Takes a string, returns a string.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="set_options"
>set_options</a></h2>
<p>Should be implemented by the plugin! Takes a hash ref with arguments.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2012 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Converter</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Converter - Tool to create MHTML.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> 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( );</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="WHAT_IS_MHTML?"
>WHAT IS MHTML?</a></h1>
<p>'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.</p>
<p>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.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Simple_Text"
>Simple Text</a></h2>
<p>Most simple HTML tags will just work.</p>
<pre> <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></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="TOC_and_Hyperlinks"
>TOC and Hyperlinks</a></h2>
<p>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.</p>
<pre> <h1>Table of Contents</h1>
<ul>
<li><a filepos="00000458">CHAPTER ONE</a></li>
<li><a filepos="00000510">CHAPTER TWO</a></li>
</ul></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Images"
>Images</a></h2>
<p>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:</p>
<pre> <img recindex="0004"></pre>
<p>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 <code>recindex="1"</code> and it will be fine!</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="New_Page"
>New Page</a></h2>
<p>If you want to enforce a new page at the ebook-reader you can use a MOBI specific tag:</p>
<pre> <mbp:pagebreak /></pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="new"
>new</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="text"
>text</a></h2>
<p>Returns your normal text (without markup) encoded for MHTML, which means, HTML special chars get replaced with HTML entities.</p>
<p>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.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS_(for_tags)"
>METHODS (for tags)</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="title"
>title</a></h2>
<p>Returns your text formated as a title. Takes 3 arguments:</p>
<pre> 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)
);</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="paragraph"
>paragraph</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="newline"
>newline</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="pagebreak"
>pagebreak</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="italic"
>italic</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="bold"
>bold</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="code"
>code</a></h2>
<pre> $mhtml = $c->code(
'for my $i (@a) {
print $_;
print "the end\n";
}
');</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="small"
>small</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="big"
>big</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="emphasize"
>emphasize</a></h2>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="list"
>list</a></h2>
<p>Create a very simple list.</p>
<pre> my $mhtml = $c->list( ['A', 'B', 'C', 'D'], 'ul' );</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="table"
>table</a></h2>
<p>Create a very simple table.</p>
<pre> $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'
);</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="image"
>image</a></h2>
<p>Add a picture to the data.</p>
<pre> $mhtml = $c->image('/path/to/pic.jpg', 'This is a picture');</pre>
<p>Image must remain on the path at disc, until ebook is created! This method just adds the path, not the data.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Possible_Tags"
>Possible Tags</a></h1>
<p>According to <a href="http://www.mobipocket.com/dev/article.asp?BaseFolder=prcgen&File=TagRef_OEB.htm" class="podlinkurl"
>mobipocket.com</a> the following tags are supported in Mobipocket. Not all are implemented in the methods mentioned above.</p>
<pre> <?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></pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2012 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Picture</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Picture - Make sure that pictures cope with the MOBI standards.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> use EBook::MOBI::Picture;
my $p = EBook::MOBI::Picture->new();
my $img_path_small = $p->rescale_dimensions($img_path_big);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="new"
>new</a></h2>
<p>The code is meant to be used in object oriented style, so you are asked to create an object before using.</p>
<pre> my $p = EBook::MOBI::Picture->new();</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="rescale_dimensions"
>rescale_dimensions</a></h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_on"
>debug_on</a></h2>
<p>You can just ignore this method if you are not interested in debuging!</p>
<p>Pass a reference to a debug subroutine and enable debug messages.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="debug_off"
>debug_off</a></h2>
<p>Stop debug messages and erease the reference to the subroutine.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="TODO"
>TODO</a></h1>
<p>A method to 'clean up' and also to change the maximum values would be nice.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2011 Boris Däppen, all rights reserved.</p>
<p>This program is free software; you can redistribute it and/or modify it under the same terms of Artistic License 2.0.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />
<html><head><title>EBook::MOBI::Mhtml2Mobi- Create a Mobi ebook by packing MOBI-ready HTML.</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Fri Aug 24 08:55:28 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>EBook::MOBI::Mhtml2Mobi- Create a Mobi ebook by packing MOBI-ready HTML.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> use EBook::MOBI::Mhtml2Mobi;
my $mobi = EBook::MOBI::Mhtml2Mobi->new();
$mobi->pack($mhtml, $out_filename, $author, $title);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="pack"
>pack</a></h2>
<p>The input parameters are the following:</p>
<pre> $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</pre>
<p>Call the method like this:</p>
<pre> $mobi->pack($mhtml, $filename, $author, $title);</pre>
<p>After the method call, a Mobi ebook should be found at the path you specified in $filename.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="Handling_of_Images"
>Handling of Images</a></h3>
<p>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 <a href="http://search.cpan.org/perldoc?EBook%3A%3AMOBI%3A%3APicture" class="podlinkpod"
>EBook::MOBI::Picture</a>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_&_LICENSE"
>COPYRIGHT & LICENSE</a></h1>
<p>Copyright 2012 Boris Däppen, all rights reserved.</p>
<p>Parts of this code are coming from MobiPerl.</p>
<p>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.</p>
<p>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.</p>
<p>You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Boris Däppen <boris_daeppen@bluewin.ch></p>
<!-- end doc -->
</body></html>
<hr />