NAME

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

SYNOPSIS

 ebook COMMAND arg1 arg2 --opt1 --opt2

See also "EXAMPLES".

COMMANDS

adddoc

Adds a documents to both the book manifest and spine.

Options

--opffile

--opf

The OPF file to modify. If not specified one will be searched for in the current directory.

--identifier

--id

The ID attribute to use for the added manifest item. This is required, and ebook will abort if it is not specified.

--mimetype

--mtype

The mime type string to use for the added manifest item. If not specified, it will be autodetected via File::Mimeinfo::Magic. This 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.

Note that 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 not specified one will be searched for in the current directory.

--identifier

--id

The ID attribute to use for the added manifest item. This is required, and ebook will abort if it is not specified.

--mimetype

--mtype

The mime type string to use for the added manifest item. If not specified, it will be autodetected via File::Mimeinfo::Magic. This may not result in an optimal string.

Example

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

blank

Create a blank e-book structure.

Options

--opffile filename.opf

--opf filename.opf

Use the specified OPF file. This can also be specified as the first non-option argument, which will override this option if it exists. If no file is specified, the program will abort with an error. =item --author "Author Name"

The author of the book. If not specified, defaults to "Unknown Author".

--title "Title Name"

The title of the book. If not specified, defaults to "Unknown Title".

--dir directory

-d directory

Output the OPF file in this directory, creating it if necessary.

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.

config

Make changes to the EBook::Tools configuration file.

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

Arguments / Subcommands

Configuration is always handled in the format of:

 ebook config subcommand value

• default

  Replace any existing configuration file with a default template. This creates the file if it does not exist. This should be done once before any other configuration manipulation is done, unless a configuration file has been manually created 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 details on what each value 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. Note that 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'

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 is just presents a unified interface to other programs that have that capability.

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 taken to be the output file. If not specified, the program will use 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 will be 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.

Options

--opffile filename.opf

--opf filename.opf

Use the specified OPF file. This can also be specified 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.

--dir directory

-d directory

Save the fixed output into the specified directory. The default is to write all output in the current working directory. Note that this only affects the output, and not where the OPF file is found.

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. This can also be specified as the first non-option argument, which will override this option if it exists. 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. If not specified, the bok 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 -f 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.

This can also be specified 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.

Options

--input filename

--i filename

Use the specified file for input. Valid formats are OPF, HTML, and ePub. This can also be specified 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).

This can also be specified as the second non-option argument, which will override this option if it exists.

--dir directory

-d directory

Output the final book into the specified directory. The default is to use the current working directory, which is where mobigen will always place it initially; if specified this only forces the file to be moved after generation.

--compression x

-c x

Use the specified compression level x, where 0 is no compression, 1 is PalmDoc compression, and 2 is HUFF/CDIC compression. If not specified, defaults to 1 (PalmDoc compression).

Example

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

or in the simplest case:

 ebook genmobi

impmeta

Set specific metadata values in an ETI .imp file.

Options

• --input filename.imp
• -i filename.imp

  Specify the input filename. This can also be specified as the first argument, in which case the -i option will be ignored.

• --output modified.imp
• -o modified.imp

  Specify the output filename. If not specified, the input file will be overwritten.

• --identifier

  Specify the identifier metadata.

• --category
• --cat

  Specify the category metadata.

• --subcategory
• --subcat

  Specify the subcategory metadata.

• --title

  Specify the title metadata.

• --lastname

  Specify the author last name metadata.

• --middlename

  Specify the author middle name metadata.

• --firstname

  Specify the author first name metadata. Note that IMP files commonly place the full name in this component, and leave the middlename and lastname entries blank.

Examples

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

setmeta

Set specific metadata values on an OPF file, creating a new entry only if none exists.

Both the element to set and the value are specified as additional arguments, not as options.

The elements that can be set are currently 'author', 'title', 'publisher', and 'rights'.

Options

• --opffile =item * --opf

  Specifies the OPF file to modify. If not specified, the script will attempt to find one in the current directory.

• --fileas

  Specifies the 'file-as' attribute when setting an author. Has no effect on other elements.

• --identifier
• --id

  Specifies the ID to assign to the element.

Examples

 ebook setmeta title 'My Great Title'
 ebook --opf newfile.opf setmeta author 'John Smith' --fileas 'Smith, John' --id mainauthor

splitmeta

Split the <metadata>...</metadata> block out of a pseudo-HTML file that contains one.

splitpre

Split <pre>...</pre> blocks out of an existing HTML file, wrapping each one found into a separate HTML file.

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 a HTML file.

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 the latter is not specified, the input file will be overwritten.

Options

• --noscript

  Strips <noscript>...</noscript> blocks as well.

tidyxhtml

Run tidy on a HTML file to enforce valid XHTML output (required by the OPF 2.0 specification).

tidyxml

Run tidy an a XML file (for neatness).

unpack

Unpacks an ebook into its component parts, creating an OPF for them if necessary.

Options

--input =item -i

The filename of the ebook to unpack. This can also be specified as the first non-option argument, in which case it will override the option if it exists.

--dir =item -d

The directory to unpack into, which will be created if it does not exist, defaulting to the filename with the extension removed. This can also be specified 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, a format can be forced here. See EBook::Tools::Unpack for a list of available formats.

--htmlconvert

Attempt to convert the extracted text to HTML. This is obviously only of value if the format doesn't use HTML normally.

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

--author

Set the primary author of the unpacked e-book, overriding what is detected. Not all e-book formats contain author metadata, and if none is found and this is not specified the primary author will be set to 'Unknown Author'.

--title

Set the title of the unpacked e-book, overriding what is 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 the title with a .opf extension.

--tidy

Run tidy on any HTML output files to convert them to valid XHTML. Be warned that this can occasionally change the formatting, as Tidy isn't very forgiving on certain common tricks (such as empty <pre> elements with style elements) that abuse the standard.

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

$tidysafety == 1:

Overwrites original file if there were no errors, but even if there were warnings. Keeps a log of errors, but not warnings.

$tidysafety == 2:

Overwrites original file if there were no errors, but even if there were warnings. Keeps a log of both errors and warnings.

$tidysafety == 3:

Overwrites original file only if there were no errors or warnings. Keeps a log of both errors and warnings.

$tidysafety = 4>:

Never overwrites 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

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.
• Documentation is incomplete
• Not all configuration file options are actually used

COPYRIGHT

Copyright 2008 Zed Pobre

LICENSE

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