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.
 Normal text is easy.
 Some specials following now...

 =for image /path/to/camel.jpg This is a nice animal.

 =begin html

 <p>Some <i>HTML</i> junks.</p>

 =end html

 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 pagebreak 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::Converter

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

Note: =head0 is not part of the official POD standard. You will create invalid POD if you use this syntax. However I find it usefull for processing existing docs. You have been warned.

SPECIAL SYNTAX FOR IMAGES

POD does not support images. However you can add images with some special markup.

 =for image /path/to/image.jpg And some description here.

Note: This version marks the old style of adding images as DEPRECATED. Please DON'T use this markup anymore:

 # DEPRECATED, will not be supported in next version
 =image /path/to/image.jpg And some description here.

EMPEDDING HTML IN YOUR POD

This module can detect HTML in your POD. It will directly put it "as is" into the MOBI format, which should always work fine for simple stuff. You have to use =begin and =end commands to mark your HTML recognisable. =for is not supported.

 =begin html
 
 <p>Some stuff in <i>HTML</i>...</p>

 =end html

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>

cpanm EBook::MOBI

perl -MCPAN -e shell
install EBook::MOBI