EBOOK(1p)

📦
version 0.5.4 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

ebook — create and manipulate e-books from the command line ✨

okay bestie, so this whole thing lives in the manual page EBOOK(1p), which is a User Contributed Perl Documentation situation 🫶 and it's literally your entire toolkit for building and messing with e-books straight from the terminal. no cap.

📜 SYNOPSIS 📜

 ebook COMMAND arg1 arg2 --opt1 --opt2

also go peek at "EXAMPLES", k? it's giving helpful 💅

🎀 COMMANDS 🎀

🌸 adddoc 🌸

Adds a documents to both the book manifest and the spine. (yes, both. it's the whole point, bestie 💖)

Options

  • --opffile, --opf — the OPF file you wanna modify. if you don't say which one, it'll go searching for one in the current directory 🔍
  • --identifier, --id — the ID attribute to use for the added manifest item. this one is required — ebook will straight up abort if you don't give it one 😭
  • --mimetype, --mtype — the mime type string for the added manifest item. skip it and it gets autodetected via File::Mimeinfo::Magic. heads up: that may not result in an optimal string 🙈

Example

 ebook adddoc --opf mybook.opf --id 'text-ch1' chapter1.html

🌸 additem 🌸

Add an item to the book manifest, but not the spine. manifest-only era, she's doing her own thing 💅

little note bestie: the "fix" command will automatically insert manifest items for any local files referenced by existing manifest items 👑

Options

  • --opffile, --opf — the OPF file to modify. if you don't specify one, one will be searched for in the current directory 🔍
  • --identifier, --id — the ID attribute for the added manifest item. required — ebook will abort if you don't hand it over 😤
  • --mimetype, --mtype — the mime type string for the added manifest item. not specified? it gets autodetected via File::Mimeinfo::Magic. and again: this may not result in an optimal string 🙈

Example

 ebook additem --opf mybook.opf --id 'illus-ch1' chapter1-illus.jpg

🌸 bisac 🌸

Search for a BISAC code matching a case-insensitive regular expression. detective mode activated 🕵️‍♀️✨

Options

  • regexp — the first argument gets taken as the regular expression to search with. if it's either . or you don't specify it at all, the entire list of valid codes gets printed 📋
psst: this requires that the BISAC codes be downloaded ahead of time. (go see "dlbisac" for that 👀)

🌸 blank 🌸

Create a blank e-book structure. fresh start, clean slate, main character energy 👑

Options

  • --opffile filename.opf, --opf filename.opf — use the specified OPF file. you can also hand it over as the first non-option argument, and if you do, that overrides this option. if no file is specified at all, the program will abort with an error 💀
  • --author "Author Name" — the author of the book. if you don't say, it defaults to "Unknown Author" 🫠
  • --title "Title Name" — the title of the book. if you don't say, it defaults to "Unknown Title" 🫠
  • --dir directory, -d directory — output the OPF file in this directory, creating it if necessary 🗂️
ok ngl, the original page has a stray =item directive wedged in right before the --author entry (a lil pod-formatting oopsie, it happens to the best of us 🙈). that's all it is, bestie — the --author option underneath it is the real deal, and we're keeping her exactly as written 💖

Example

 ebook blank newfile.opf --author "Me Myself" --title "New File"
 ebook blank --opffile newfile.opf --author "Me Myself" --title "New File"

Both of those commands have the same effect. twin flames fr fr 👯‍♀️

🌸 config 🌸

Make changes to the EBook::Tools configuration file. glow-up time for your settings ✨

The configuration file itself is located as either $ENV{HOME}/.ebooktools/config.ini or as $ENV{USERPROFILE}\Application Data\EBook-Tools, depending on platform and which directory is found first. see "userconfigdir()" in EBook::Tools for the deets 👀

Arguments / Subcommands

Configuration is always handled in the format of:

 ebook config subcommand value
  • default — replace any existing configuration file with a default template. creates the file if it doesn't exist. you should do this once before any other configuration manipulation, unless you already manually created a config file ahead of time 🎀
  • debug — sets the default debugging level when no verbosity is specified. note that verbosity can only be increased, not decreased, with the -v option ⬆️
  • tidysafety — sets the default safety level when tidy is used. valid values are from 0-4. see "unpack" for what each value actually means 📖
  • mobipids — a comma-separated list of Mobipocket PIDs to try to use to decrypt e-books. this value is only used if the appropriate plug-in modules or helper applications are available, as DRM is not supported natively by EBook::Tools. and heads up: if the PID includes a $ character, the entire PID string has to be enclosed in single quotes ⚠️

Examples

 ebook config default
 ebook config debug 2
 ebook config mobipids '1234567890,2345678$90'

🌸 convert 🌸

Unpacks the ebook specified as the first argument, runs standard fixes on the contents, and repacks it into a new format in the output file specified as the second argument. currently the only supported output format is epub — which is the format you will get irrespective of the extension you actually give the output file. she does what she wants 💅

Options

all options from "unpack" and "fix" are technically valid here as well, though of course some options are nonsensical in this context and will likely break the conversion (e.g. --nosave) 💀

Example

 ebook convert MyBook.prc MyBook.epub
 ebook convert --name MyBook.lit /home/myname/MyBook.epub

🌸 dlbisac 🌸

Downloads and caches the Book Industry Study Group BISAC codes into a local database. ⚠️ this will destroy the existing contents of that table if this has been done previously. so like, be aware bestie 😭

🌸 downconvert 🌸

🌸 dc 🌸

If the appropriate helpers or plugins are available, write a copy of the input file with the DRM restrictions removed.

NOTE: no actual DRM-removal code is present in this package. this just presents a unified interface to other programs that have that capability. she's the middleman, not the magician 🧚

Arguments

  • infile — the first non-option argument is taken to be the input file. if not specified, the program exits with an error 💀
  • outfile — the second non-option argument is the output file. if you don't specify one, the program uses a name based on the input file, appending -nodrm to the basename and keeping the extension. in the special case of Mobipocket files ending in -sm, the -sm portion of the basename is simply removed, and nothing else is appended ✂️
  • key — the third non-option argument is taken to be either the decryption key/PID, or in the case of Microsoft Reader (.lit) files, the keys.txt file containing the decryption keys 🔑

if not specified, this gets looked up from the configuration file. Convertlit keyfiles will be looked for in standard locations. if no key is found, the command aborts and exits with an error 💀

Example

 ebook downconvert NewBook.lit NewBook-readable.lit mykeys.txt
 ebook dc MyBook-sm.prc

🌸 fix 🌸

Find and fix problems with an e-book, including enforcing a standard specification and ensuring that all linked objects are present in the manifest. she's the responsible one 🫶✨

Options

  • --opffile filename.opf, --opf filename.opf — use the specified OPF file. you can also pass it as the first non-option argument, which will override this option if it exists. if no file is specified, one will be searched for 🔍
  • --oeb12 — force the OPF to conform to the OEB 1.2 standard. this is the default 👑
  • --opf20 — force the OPF to conform to the OPF 2.0 standard. if both this and --oeb12 are specified, the program will abort with an error 💀
  • --mobi — correct Mobipocket-specific elements, creating an output element to force UTF-8 output if one does not yet exist 🔤
  • --erotic or --sex — enable special handling for erotic fiction (most notably special subject normalization rules) 🫣
  • --names — normalize names to standard capitalization and format (primary name display is "First Middle Last", but file-as is "Last, First Middle").

this is not done by default as it can damage unusual but correct names ⚠️

🌸 genepub 🌸

Generate a .epub book from existing OPF data. ✨

Options

  • --input filename.opf, --i filename.opf, --opffile filename.opf, --opf filename.opf — use the specified OPF file. if no file is specified, one will be searched for 🔍
  • --output bookname.epub, -o bookname.epub — use the specified name for the final output file. you can also pass it as the first non-option argument, which overrides this option if it exists. if not specified, the book will have the same filename as the OPF file, with the extension changed to .epub 🎀
  • --dir directory, -d directory — output the final .epub book into the specified directory. the default is to use the current working directory 🗂️

Example

 ebook genepub mybook.opf -o my_special_book.epub -d ../epubbooks

or in the simplest case:

 ebook genepub

🌸 genimp 🌸

Generate a eBookwise .imp book from a .RES directory 💖

Options

  • --input DIRNAME.RES, -i DIRNAME.RES — specifies the resource directory to use for input. a valid resource directory will contain at least a RSRC.INF file, a DATA.FRK file, and several other files with four-capital-letter filenames 🔤

you can also pass it as the first non-option argument, which will override this option if it exists. if not specified, the current directory will be used 📁

  • --output bookname.epub, -o bookname.epub — use the specified name for the final output file. if not specified, the book will have the same filename as the input, with the extension changed to .imp ✨

Examples

 ebook genimp MyUnpackedBook.RES MyBook.imp
 ebook genimp --resdir ../MyUnpackedBook.RES -f imp/MyBook.imp

🌸 genmobi 🌸

Generate a Mobipocket .mobi/.prc book from OPF, HTML, or ePub input. she's versatile, she contains multitudes 💅

Options

  • --input filename, --i filename — use the specified file for input. valid formats are OPF, HTML, and ePub. you can also pass it as the first non-option argument, which will override this option if it exists. if no file is specified, an OPF file in the current directory will be searched for 🔍
  • --output bookname.prc, -o bookname.prc — use the specified name for the final output file. if not specified, the book will have the same filename as the input file, with the extension changed to .mobi (this file is always created by mobigen — specifying a different filename only causes it to be renamed afterwards 👀).

you can also pass it as the second non-option argument, which will override this option if it exists 💖

  • --dir directory, -d directory — drop the finished book into the directory you name here. Default is the current working directory, because that's where mobigen always puts it first anyway; if you pass this, all it really does is force the file to be moved after it's generated. 💅
  • --compression x, -c x — pick your compression level x, bestie. 0 = no compression at all, 1 = PalmDoc compression, 2 = HUFF/CDIC compression. Skip it and you get 1 (PalmDoc compression), no thoughts, just vibes.

✨ Example ✨

ebook genmobi mybook.opf -o my_special_book.prc -d ../mobibooks
ebook genmobi mybook.html mybook.prc -c2

or if you're feeling minimalist queen, the simplest case:

ebook genmobi

🦋 genncx 🦋

Hand it an OPF file and it builds you an NCX-format table of contents out of the package unique-identifier, the dc:title, dc:creator, and spine elements — and then it adds the NCX entry to the manifest if it isn't already referenced. Very "I did it myself" of it. 💖

Heads up though: the OPF file gets cleaned to OPF20 format before any of that happens. That's just the process, no cap.

Options

  • --opffile filename.opf, --opf filename.opf — use the OPF file you name. You can also just hand it over as the first non-option argument, and that will override this option if it exists. Don't specify anything at all and it'll go searching for one on its own. 🕵️‍♀️

🌸 impmeta 🌸

Sets specific metadata values inside an ETI .imp file. Glow-up for your metadata, basically.

Options

  • --input filename.imp, -i filename.imp — name the input file. Can also be given as the first argument, and in that case the -i option just gets ignored. 🙈
  • --output modified.imp, -o modified.imp — name the output file. Leave it out and the input file gets overwritten. You've been warned, bestie.
  • --identifier — set the identifier metadata.
  • --category, --cat — set the category metadata.
  • --subcategory, --subcat — set the subcategory metadata.
  • --title — set the title metadata.
  • --lastname — set the author last name metadata.
  • --middlename — set the author middle name metadata.
  • --firstname — set the author first name metadata. Little lore drop: IMP files commonly stuff the full name into this component and leave the middlename and lastname entries blank. iykyk.

Examples

ebook impmeta mybook.imp --title 'Fixed Title' --lastname 'John Q. Brandy'
ebook impmeta -i mybook.imp -o fixed.imp --title 'Fixed Title'

🎀 setcover 🎀

Sets the cover image. It takes, as a single argument, the href of the file to use. One argument, that's it, that's the whole thing. 💅

Options

  • --opffile, --opf — the OPF file to modify. If you don't specify one, the script will attempt to find one. It's giving resourceful.
  • --identifier, --id — the ID to assign to the associated manifest item.

⭐ setmeta ⭐

Set specific metadata values on an OPF file, creating a new entry if none exists. Main character energy for your metadata block.

Both the element to set and the value are given as additional arguments — not as options. Okay? Okay.

The elements you can set right now are:

  • author
  • date
  • description
  • publisher
  • rights
  • series
  • subject
  • title
  • type

The 'series' values can take an extra argument containing the series index position. Cute.

The 'subject' elements can be added multiple times, including in a single command line — though fair warning, --id will only set the ID on the first one you specified. Every other entry gets overwritten. 💀

And the element argument can be shortened to the minimum number of letters necessary to uniquely identify it. Lazy typing rights, we love to see it.

Options

  • --opffile, --opf — the OPF file to modify. If you don't specify one, the script will attempt to find one in the current directory.
  • --delete — lets you delete subject and series metadata. Has no effect on other elements. Sorry.
  • --fileas — specifies the 'file-as' attribute when setting an author. Has no effect on other elements either.
  • --identifier, --id — the ID to assign to the element.

Examples

ebook setmeta series 'Some Other Series' 03
ebook setmeta title 'My Great Title'
ebook setmeta t 'My Great Title'
ebook --opf newfile.opf setmeta author 'John Smith' --fileas 'Smith, John' --id mainauthor

🧚 splitmeta 🧚

Splits the <metadata>...</metadata> block out of a pseudo-HTML file that contains one. Extraction, but make it fashion. ✨

🍓 splitpre 🍓

Splits <pre>...</pre> blocks out of an existing HTML file, wrapping each one it finds into a separate HTML file. Every <pre> gets its own little apartment. 🏠

The first non-option argument is taken to be the input file. The second non-option argument is taken to be the basename of the output files.

💀 stripscript 💀

Strips <script>...</script> blocks out of an HTML file. Yeet. 🗑️

The first non-option argument is taken to be the input file. The second non-option argument is taken to be the output file. If you don't give the second one, the input file gets overwritten.

Options

  • --noscript — strips <noscript>...</noscript> blocks as well. Double yeet.

💜 tidyxhtml 💜

Runs tidy on an HTML file to enforce valid XHTML output (required by the OPF 2.0 specification). Not optional in the spec's eyes, so. ✋

🌈 tidyxml 🌈

Runs tidy on an XML file — for neatness. Purely for the aesthetic. 🧼

👑 unpack_ebook 👑

Unpacks an ebook into its component parts, creating an OPF for them if necessary. Unboxing video, but for files. 📦

Options

  • --input, -i — the filename of the ebook to unpack. Can also be given as the first non-option argument, in which case it will override the option if it exists.
  • --dir, -d — the directory to unpack into. It'll be created if it doesn't exist, and it defaults to the filename with the extension removed. Can also be given as the second non-option argument, in which case it will override the option if it exists.
  • --format — the unpacking routines should autodetect the type of book under normal conditions. If autodetection fails, you can force a format here. See EBook::Tools::Unpack for a list of available formats.
  • --htmlconvert — attempt to convert the extracted text to HTML. Which is obviously only of value if the format doesn't use HTML normally. Common sense, bestie.
  • --raw — this causes a lot of raw, unparsed, unmodified data to be dumped into the directory along with everything else. It's useful for debugging exactly what was in the file being unpacked, but not for much else. It's giving data hoard.
  • --author — set the primary author of the unpacked e-book, overriding whatever gets detected. Not all e-book formats contain author metadata, and if none is found and this isn't specified, the primary author will be set to 'Unknown Author'. Sad but true. 😭
  • --title — set the title of the unpacked e-book, overriding what's detected. A title will always be detected in some form from the e-book, but the exact text can be overridden here.
  • --opffile, --opf — the filename of the OPF metadata file that will be generated. If not specified, defaults to "content.opf".
  • --tidy — run tidy on any HTML output files to convert them to valid XHTML. Be warned that this can occasionally change the formatting, because Tidy isn't very forgiving on certain common tricks (such as empty <pre> elements with style elements) that abuse the standard. Tidy said no. 🙅‍♀️
  • --tidycmd — the tidy executable name. This has to be a fully qualified pathname if tidy isn't on the path. Defaults to 'tidy'.
  • --tidysafety — the safety level to use when running tidy (default is 1). Potential values are:
    • "$tidysafety < 1" — no checks performed, no error files kept, works like a clean tidy -m.
This setting is DANGEROUS! 🚨 Like, actually. Bestie. Please.
  • "$tidysafety == 1" — overwrites the original file if there were no errors, but even if there were warnings. Keeps a log of errors, but not warnings.
  • "$tidysafety == 2" — overwrites the original file if there were no errors, but even if there were warnings. Keeps a log of both errors and warnings.
  • "$tidysafety == 3" — overwrites the original file only if there were no errors or warnings. Keeps a log of both errors and warnings.
  • "$tidysafety = 4>" — never overwrites the original file. Keeps a log of both errors and warnings.

Examples

ebook unpack mybook.pdb My_Book --author "By Me"
ebook unpack -i mybook.pdb -d My_Book --author "By Me"

Both of the above commands do the same thing. Twinning! 👯‍♀️

🔥 EXAMPLES 🔥

ebook splitmeta book.html mybook.opf
ebook tidyxhtml book.html
ebook tidyxml mybook.opf
ebook fix mybook.opf --oeb12 --mobi
ebook genepub

ebook blank newbook.opf --title "My Title" --author "My Name"
ebook adddoc myfile.html
ebook fix newbook.opf --opf20 -v
ebook genepub

ebook unpack mybook.pdb my_book
cd my_book
ebook addoc new_document.html
ebook fix
ebook genepub

💀 BUGS/TODO 💀

  • Need to implement a one-pass conversion from one format to another. This will wait until more formats are supported by the underlying modules, however. Patiently waiting. ⏳
  • Documentation is incomplete
  • Not all configuration file options are actually used

Copyright 2008 Zed Pobre

📜 LICENSE 📜

Licensed to the public under the terms of the GNU GPL, version 2.

okay bestie that's the whole page, you made it to the end, I'm so proud 🫶 this lil edition is running on perl v5.40.0 and it's dated 2025-01-10 — so EBOOK(1p) is officially not new but still iconic. now go unpack something. 💖✨

📦 where this page comes from