Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
EBOOK(1)	      User Contributed Perl Documentation	      EBOOK(1)

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

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

       o   "debug"

	   Sets	the default debugging level when no verbosity is specified.
	   Note	that verbosity can only	be increased, not decreased, with the
	   "-v"	option.

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

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

       o   "infile"

	   The first non-option	argument is taken to be	the input file.	 If
	   not specified, the program exits with an error.

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

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

       o   "--input filename.imp"

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

       o   "--output modified.imp"

       o   "-o modified.imp"

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

       o   "--identifier"

	   Specify the identifier metadata.

       o   "--category"

       o   "--cat"

	   Specify the category	metadata.

       o   "--subcategory"

       o   "--subcat"

	   Specify the subcategory metadata.

       o   "--title"

	   Specify the title metadata.

       o   "--lastname"

	   Specify the author last name	metadata.

       o   "--middlename"

	   Specify the author middle name metadata.

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

       o   "--opffile"

       o   "--opf"

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

       o   "--identifier"

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

       o   "--opffile" =item * "--opf"

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

       o   "--delete"

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

       o   "--fileas"

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

       o   "--identifier"

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

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

       o   Documentation is incomplete

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

perl v5.24.1			  2017-07-08			      EBOOK(1)

NAME | SYNOPSIS | COMMANDS | EXAMPLES | BUGS/TODO | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ebook&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help