Provided by: libebook-tools-perl_0.5.4-1.3_amd64 bug

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

   "bisac"
       Search for a BISAC code matching a case-insensitive regular expression.

       Options

       "regexp"
           The first argument is taken as a regular expression to use for the search.  If this is
           either '.' or not specified, the entire list of valid codes is printed.

           This requires that the BISAC codes be downloaded ahead of time.  (See "dlbisac".)

   "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'

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

       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.

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

       "--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.  This can also be specified as the
           first non-option argument, which will override 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.

           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

   "genncx"
       Given an OPF file, creates a NCX-format table of contents from the package unique-
       identifier, the dc:title, dc:creator, and spine elements, and then add the NCX entry to
       the manifest if it is not already referenced.

       The OPF file will be cleaned to OPF20 format before this happens.

       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.

   "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'

   "setcover"
       Sets the cover image

       Takes as a single argument the href of the file to use.

       Options

       •   "--opffile"

       •   "--opf"

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

       •   "--identifier"

       •   "--id"

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

       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
       date
       description
       publisher
       rights
       series
       subject
       title
       type

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

       The 'subject' elements can be added multiple times (including in a single command-line,
       though --id will only set the ID on the first one specified).  Other entries will be
       overwritten.

       The element argument can be shortened to the minimum number of letters necessary to
       uniquely identify it.

       Options

       •   "--opffile" =item * "--opf"

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

       •   "--delete"

           Allows the deletion of subject and series metadata.  Has no effect on other elements.

       •   "--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 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"
       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_ebook"
       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 "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, 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.