EBook::EPUB(3)

📦
version 0.6 · 2 versions
, in fedora 43

💖 EBook::EPUB 💖

okay so bestie, welcome to EBook::EPUB — the Perl module that literally generates EPUB documents for you. it's from the User Contributed Perl Documentation corner of the universe and it's lowkey iconic. ✨

✨ NAME ✨

EBook::EPUB — module for generating EPUB documents 🎀

🌸 VERSION 🌸

Version 0.6

🦋 SYNOPSIS 🦋

here's the whole vibe, fr fr — no cap, this is the entire flow from "empty object" to "actual ebook file":

use EBook::EPUB;

# Create EPUB object
my $epub = EBook::EPUB->new;

# Set metadata: title/author/language/id
$epub->add_title('Three Men in a Boat');
$epub->add_author('Jerome K. Jerome');
$epub->add_language('en');
$epub->add_identifier('1440465908', 'ISBN');

# Add package content: stylesheet, font, xhtml and cover
$epub->copy_stylesheet('/path/to/style.css', 'style.css');
$epub->copy_file('/path/to/figure1.png',
    'figure1.png', 'image/png');
$epub->encrypt_file('/path/to/CharisSILB.ttf',
    'CharisSILB.ttf', 'application/x-font-ttf');
my $chapter_id = $epub->copy_xhtml('/path/to/page1.xhtml',
    'page1.xhtml');
$epub->copy_xhtml('/path/to/notes.xhtml', 'notes.xhtml',
    linear => 'no'
);

# Add top-level nav-point
my $navpoint = $epub->add_navpoint(
        label       => "Chapter 1",
        id          => $chapter_id,
        content     => 'page1.xhtml',
        play_order  => 1 # should always start with 1
);

# Add cover image
# Not actual epub standart but does the trick for iBooks
my $cover_id = $epub->copy_image('/path/to/cover.jpg', 'cover.jpg');
$epub->add_meta_item('cover', $cover_id);

# Generate resulting ebook
$epub->pack_zip('/path/to/three_men_in_a_boat.epub');

like… look at that. she's doing it all. metadata, stylesheets, fonts, xhtml, nav points, a cover for iBooks, and then the whole thing gets zipped up into a real .epub. periodt. 💅

👑 SUBROUTINES/METHODS 👑

🌈 the constructor

  • new([$params]) — Create an EBook::EPUB object 🫶

🎀 metadata girlies

  • add_title($title) — Set the title of the book. yes, the actual name of the thing. you need this. 📖
  • add_identifier($id, [$scheme]) — Set a unique identifier for the book, such as its ISBN or a URL. the $scheme is optional, but like… specify it. it's giving organized. 🔖
  • add_author($name, [$formal_name]) — Add author of the document. for the deets, go check add_contributor. ✍️
  • add_creator($name, [fileas => $formal_name, role => $role]) — Add primary creator or author of the publication of the publication. (yes, the original really says it twice, we love a dramatic entrance 💀) See add_contributor for details.
  • add_contributor($name, [fileas => $formal_name, role =>]) — Add person/organization that contributed to publication. $name is the name in human-readable form, e.g. "Arthur Conan Doyle", $formal_name is in form, suitable for machine processing, e.g. "Doyle, Arthur Conan". $role reflects kind of contribution to document. See Section 2.2.6 of OPF specification for list of possible values: http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html#Section2.2.6 🌟
  • add_coverage($coverage) — The extent or scope of the content of the resource. 🗺️
  • add_date($date, [$event]) — Date of publication, in the format defined by "Date and Time Formats" at http://www.w3.org/TR/NOTE-datetime and by ISO 8601 on which it is based. In particular, dates without times are represented in the form YYYY[-MM[-DD]]: a required 4-digit year, an optional 2-digit month, and if the month is given, an optional 2-digit day of month. $event is an optional description of event that date refers to. Possible values may include: creation, publication, and modification. 📅
  • add_description($description) — Add description of the publication content. spill the tea about what's inside. 🍵
  • add_format($format) — The media type or dimensions of the resource. Best practice is to use a value from a controlled vocabulary (e.g. MIME media types). 💾
  • add_language($lang) — Add language of the content of the publication. $lang must comply with RFC 3066 (see http://www.ietf.org/rfc/rfc3066.txt). 🌍
  • add_publisher($publisher) — An entity responsible for making the resource available. 🏢
  • add_relation($relation) — An identifier of an auxiliary resource and its relationship to the publication. 🔗
  • add_rights($rights) — A statement about rights, or a reference to one. In this specification, the copyright notice and any further rights description should appear directly. ⚖️
  • add_source($source) — Information regarding a prior resource from which the publication was derived. 📚
  • add_subject($subject) — Add subject of the publication. tag it, bestie. 🏷️
  • add_translator($name, [$formal_name]) — Add translator of the document. $name is in human-readable form, e.g. "Arthur Conan Doyle", $formal_name is in form, suitable for machine processing, e.g. "Doyle, Arthur Conan". 🫶
  • add_type($type) — type includes terms describing general categories, functions, genres, or aggregation levels for content. The advised best practice is to select a value from a controlled vocabulary. 🎭
  • add_navpoint(%opts) — Add refrence to an OPS Content Document that is a part of publication. %opts is an anonymous hash, for possible key values see EBook::EPUB::NCX::NavPoint. Method returns created EBook::EPUB::NCX::NavPoint object that could be used later for adding subsections. 🧭
  • add_meta_item($name, $value) — Add non-standard item to metadata e.g. metadata from source documetn that is not described in Doublin Core spec. (typos are part of the canon, we respect them 💜)

🌸 adding content by hand

  • add_xhtml($filename, $data, %opts) — Add xhtml data $data to $filename in package. Returns id of newly added entry.
    • %opts is an anonymous hash array of parameters:
      • linear — 'yes' or 'no'
  • add_stylesheet($filename, $data) — Add stylesheet data $data as $filename in package. Returns id of newly added entry. 🎨
  • add_image($filename, $data, $type) — Add image data $data as $filename in package with content type $type (e.g. image/jpeg). Returns id of newly added entry. 🖼️

🧚 copying content from disk

  • copy_xhtml($source_file, $filename, %opts) — Add existing xhtml file $source_file as $filename in package. Returns id of newly added entry.
    • %opts is an anonymous hash array of parameters:
      • linear — 'yes' or 'no'
  • copy_stylesheet($source_file, $filename) — Add existing css file $source_file as $filename in package. Returns id of newly added entry. 💅
  • copy_image($source_file, $filename, $type) — Add existing image file $source_file as $filename in package and set its content type to $type (e.g. image/jpeg). Returns id of newly added entry. 📸
  • copy_file($source_file, $filename, $type) — Add existing file $source_file as $filename in package and set its content type to $type (e.g. text/plain). Returns id of newly created entry. Returns id of newly added entry. (she said it twice, she's thorough 😭) 📁
  • copy_file($source_file, $filename, $type) — same energy as above, because that's literally how it's listed, and we don't skip entries in this house. 🫡
  • encrypt_file($source_file, $filename, $type) — Add existing file $source_file as $filename in package and set its content type to $type (e.g. text/plain) Apply Adobe copy protection scheme to this file using book UUID as a key. Function croaks if key has not been set previously using. Returns id of newly added entry. 🔐
⚠️ heads up bestie — encrypt_file will croak at you if the key hasn't been set previously using [the thing the original sentence trails off on]. the original text ends there, so that's exactly where we end too. no invented details, no cap.
  • pack_zip($filename) — Generate OCF Zip container with contents of current package. this is the finale, the main character moment, the actual file on disk. 🎉

🎀 AUTHOR 🎀

Oleksandr Tymoshenko, <gonzo@bluezbox.com> 💖

🙈 BUGS 🙈

Please report any bugs or feature requests to <gonzo@bluezbox.com>. be nice, be specific, include the deets. 🐛

Copyright 2009, 2010 Oleksandr Tymoshenko.

http://bluezbox.com

This module is free software; you can redistribute it and/or modify it under the terms of the BSD license. See the LICENSE file included with this distribution.

okay that's the whole page, bestie. you're officially fluent in EBook::EPUB. go make a book, you absolute icon. 👑✨

this lil tour was brought to you by perl v5.42.0, dated 2025-07-25 — and that's on EBook::EPUB(3). slay. 💅🦋🌸

📦 where this page comes from