Quote:
Originally Posted by kovidgoyal
ebook-convert -h
|
Quote:
Originally Posted by pepak
In that case it makes sense to allow ebook-convert --help which would display only those universal options.
I hope that will work, but I am afraid that I will have to use format-specific options to get a nice output.
|
Quote:
Originally Posted by kovidgoyal
Contributions of documentation and/or screencasts are most welcome. th eless time I have to spend doing that, the more time I have to spend on new features and bug fixing.
|
Ok, some minimal
ebook-convert documentation for command line junkies, using the -h option in beta 2 for .oeb and then showing the differences for .lit, .mobi, .epub, .lrf and .pdb output formats, namely:
ebook-convert-oeb.txt:
Code:
Usage: ebook-convert.exe input_file output_file [options]
Convert an ebook from one format to another.
input_file is the input and output_file is the output. Both must be specified as the first two arguments to the command.
The output ebook format is guessed from the file extension of output_file. output_file can also be of the special format .EXT where EXT is the output file extension. In this case, the name of the output file is derived the name of the input file. Note that the filenames must not start with a hyphen. Finally, if output_file has no extension, then it is treated as a directory and an "open ebook" (OEB) consisting of HTML files is written to that directory. These files are the files that would normally have been passed to the output plugin.
After specifying the input and output file you can customize the conversion by specifying various options. the available options depend on the input and output file types. To get help on them specify the input and output file and then use the -h option.
For full documentation of the conversion system see
http://calibre.kovidgoyal.net/user_manual/conversion.html
Whenever you pass arguments to ebook-convert.exe that have spaces in them, enclose the arguments in quotation marks.
Options:
--version show program's version number and exit
-h, --help show this help message and exit
--input-profile=INPUT_PROFILE
Specify the input profile. The input profile gives the
conversion system information on how to interpret
various information in the input document. For example
resolution dependent lengths (i.e. lengths in pixels).
Choices are:default, sony, msreader, mobipocket,
hanlinv3, cybookg3, kindle
--output-profile=OUTPUT_PROFILE
Specify the output profile. The output profile tells
the conversion system how to optimize the created
document for the specified device. In some cases, an
output profile is required to produce documents that
will work on a device. For example EPUB on the SONY
reader. Choices are:default, sony, msreader,
mobipocket, hanlinv3, cybookg3, kindle, sony-
landscape, kindle_dx
--list-recipes List available recipes.
INPUT OPTIONS:
Options to control the processing of the input htm file
--breadth-first Traverse links in HTML files breadth first. Normally,
they are traversed depth first.
--max-levels=MAX_LEVELS
Maximum levels of recursion when following links in
HTML files. Must be non-negative. 0 implies that no
links in the root HTML file are followed. Default is
5.
--dont-package Normally this input plugin re-arranges all the input
files into a standard folder hierarchy. Only use this
option if you know what you are doing as it can result
in various nasty side effects in the rest of of the
conversion pipeline.
--debug-input=DEBUG_INPUT
Save the output from the input plugin to the specified
directory. Useful if you are unsure at which stage of
the conversion process a bug is occurring. WARNING:
This completely deletes the contents of the specified
directory.
--input-encoding=INPUT_ENCODING
Specify the character encoding of the input document.
If set this option will override any encoding declared
by the document itself. Particularly useful for
documents that do not declare an encoding or that have
erroneous encoding declarations.
OUTPUT OPTIONS:
Options to control the processing of the output oeb
--pretty-print If specified, the output plugin will try to create
output that is as human readable as possible. May not
have any effect for some output plugins.
LOOK AND FEEL:
Options to control the look and feel of the output
--base-font-size=BASE_FONT_SIZE
The base font size in pts. All font sizes in the
produced book will be rescaled based on this size. By
choosing a larger size you can make the fonts in the
output bigger and vice versa. By default, the base
font size is chosen based on the output profile you
chose.
--disable-font-rescaling
Disable all rescaling of font sizes.
--font-size-mapping=FONT_SIZE_MAPPING
Mapping from CSS font names to font sizes in pts. An
example setting is 12,12,14,16,18,20,22,24. These are
the mappings for the sizes xx-small to xx-large, with
the final size being for huge fonts. The font
rescaling algorithm uses these sizes to intelligently
rescale fonts. The default is to use a mapping based
on the output profile you chose.
--line-height=LINE_HEIGHT
The line height in pts. Controls spacing between
consecutive lines of text. By default no line height
manipulation is performed.
--linearize-tables Some badly designed documents use tables to control
the layout of text on the page. When converted these
documents often have text that runs off the page and
other artifacts. This option will extract the content
from the tables and present it in a linear fashion.
--extra-css=EXTRA_CSS
Either the path to a CSS stylesheet or raw CSS. This
CSS will be appended to the style rules from the
source file, so it can be used to override those
rules.
--margin-top=MARGIN_TOP
Set the top margin in pts. Default is 5.0. Note: 72
pts equals 1 inch
--margin-left=MARGIN_LEFT
Set the left margin in pts. Default is 5.0. Note: 72
pts equals 1 inch
--margin-right=MARGIN_RIGHT
Set the right margin in pts. Default is 5.0. Note: 72
pts equals 1 inch
--margin-bottom=MARGIN_BOTTOM
Set the bottom margin in pts. Default is 5.0. Note: 72
pts equals 1 inch
--dont-justify Do not force text to be justified in output. Whether
text is actually displayed justified or not depends on
whether the ebook format and reading device support
justification.
--insert-blank-line
Insert a blank line between paragraphs. Will not work
if the source file does not use paragraphs (<p> or
<div> tags).
--remove-paragraph-spacing
Remove spacing between paragraphs. Also sets an indent
on paragraphs of 1.5em. Spacing removal will not work
if the source file does not use paragraphs (<p> or
<div> tags).
STRUCTURE DETECTION:
Control auto-detection of document structure.
--chapter=CHAPTER An XPath expression to detect chapter titles. The
default is to consider <h1> or <h2> tags that contain
the words "chapter","book","section" or "part" as
chapter titles as well as any tags that have
class="chapter". The expression used must evaluate to
a list of elements. To disable chapter detection, use
the expression "/". See the XPath Tutorial in the
calibre User Manual for further help on using this
feature.
--chapter-mark=CHAPTER_MARK
Specify how to mark detected chapters. A value of
"pagebreak" will insert page breaks before chapters. A
value of "rule" will insert a line before chapters. A
value of "none" will disable chapter marking and a
value of "both" will use both page breaks and lines to
mark chapters.
--prefer-metadata-cover
Use the cover detected from the source file in
preference to the specified cover.
--remove-first-image
Remove the first image from the input ebook. Useful if
the first image in the source file is a cover and you
are specifying an external cover.
--insert-metadata Insert the book metadata at the start of the book.
This is useful if your ebook reader does not support
displaying/searching metadata directly.
--page-breaks-before=PAGE_BREAKS_BEFORE
An XPath expression. Page breaks are inserted before
the specified elements.
--preprocess-html Attempt to detect and correct hard line breaks and
other problems in the source file. This may make
things worse, so use with care.
TABLE OF CONTENTS:
Control the automatic generation of a Table of Contents. By default,
if the source file has a Table of Contents, it will be used in
preference to the automatically generated one.
--level1-toc=LEVEL1_TOC
XPath expression that specifies all tags that should
be added to the Table of Contents at level one. If
this is specified, it takes precedence over other
forms of auto-detection.
--level2-toc=LEVEL2_TOC
XPath expression that specifies all tags that should
be added to the Table of Contents at level two. Each
entry is added under the previous level one entry.
--level3-toc=LEVEL3_TOC
XPath expression that specifies all tags that should
be added to the Table of Contents at level three. Each
entry is added under the previous level two entry.
--toc-threshold=TOC_THRESHOLD
If fewer than this number of chapters is detected,
then links are added to the Table of Contents.
Default: 6
--max-toc-links=MAX_TOC_LINKS
Maximum number of links to insert into the TOC. Set to
0 to disable. Default is: 50. Links are only added to
the TOC if less than the threshold number of chapters
were detected.
--no-chapters-in-toc
Don't add auto-detected chapters to the Table of
Contents.
--use-auto-toc Normally, if the source file already has a Table of
Contents, it is used in preference to the auto-
generated one. With this option, the auto-generated
one is always used.
--toc-filter=TOC_FILTER
Remove entries from the Table of Contents whose titles
match the specified regular expression. Matching
entries and all their children are removed.
METADATA:
Options to set metadata in the output
--title=TITLE Set the title.
--authors=AUTHORS Set the authors. Multiple authors should be separated
by ampersands.
--title-sort=TITLE_SORT
The version of the title to be used for sorting.
--author-sort=AUTHOR_SORT
String to be used when sorting by author.
--cover=COVER Set the cover to the specified file.
--comments=COMMENTS
Set the ebook description.
--publisher=PUBLISHER
Set the ebook publisher.
--series=SERIES Set the series this ebook belongs to.
--series-index=SERIES_INDEX
Set the index of the book in this series.
--rating=RATING Set the rating. Should be a number between 1 and 5.
--isbn=ISBN Set the ISBN of the book.
--tags=TAGS Set the tags for the book. Should be a comma separated
list.
--book-producer=BOOK_PRODUCER
Set the book producer.
--language=LANGUAGE
Set the language.
DEBUG:
Options to help with debugging the conversion
-v VERBOSE, --verbose=VERBOSE
Level of verbosity. Specify multiple times for greater
verbosity.
Created by Kovid Goyal <kovid@kovidgoyal.net>
ebook-convert-diffs.txt:
Code:
calibre-0.6.0b2.exe (beta)
C:\> ebook-convert.exe abc.htm abc.oeb -h >ebook-convert-oeb.txt
Compare: (<)C:\ebook-convert-oeb.txt
with: (>)C:\ebook-convert-lit.txt ( and also with .mobi .epub .lrf .pdb)
76c76
< Options to control the processing of the output oeb
---
> Options to control the processing of the output lit
76c76,91
---
> Options to control the processing of the output mobi
>
> --prefer-author-sort
> When present, use author sort field as author.
>
> --mobi-periodical When present, generate a periodical rather than a
> book.
>
> --no-mobi-index Disable generation of MOBI index.
>
> --dont-compress Disable compression of the file contents.
>
> --toc-title=TOC_TITLE
> Title for any generated in-line table of contents.
>
> --rescale-images Modify images to meet Palm device size limitations.
139,143d154
< --dont-justify Do not force text to be justified in output. Whether
< text is actually displayed justified or not depends on
< whether the ebook format and reading device support
< justification.
<
76c76,96
---
> Options to control the processing of the output epub
>
> --extract-to=EXTRACT_TO
> Extract the contents of the generated EPUB file to the
> specified directory. The contents of the directory are
> first deleted, so be careful.
>
> --dont-split-on-page-breaks
> Turn off splitting at page breaks. Normally, input
> files are automatically split at every page break into
> two files. This gives an output ebook that can be
> parsed faster and with less resources. However,
> splitting is slow and if your source file contains a
> very large number of page breaks, you should turn off
> splitting on page breaks.
>
> --flow-size=FLOW_SIZE
> Split all HTML files larger than this size (in KB).
> This is necessary as most EPUB readers cannot handle
> large file sizes. The default of 260KB is the size
> required for Adobe Digital Editions.
76c76,100
---
> Options to control the processing of the output lrf
>
> --serif-family=SERIF_FAMILY
> The serif family of fonts to embed
>
> --header Add a header to all the pages with title and author.
>
> --header-format=HEADER_FORMAT
> Set the format of the header. %a is replaced by the
> author and %t by the title. Default is %t by %a
>
> --header-separation=HEADER_SEPARATION
> Add extra spacing below the header. Default is 0 pt.
>
> --minimum-indent=MINIMUM_INDENT
> Minimum paragraph indent (the indent of the first line
> of a paragraph) in pts. Default: 0
>
> --render-tables-as-images
> Render tables in the HTML as images (useful if the
> document has large or complex tables)
>
> --text-size-multiplier-for-rendered-tables=TEXT_SIZE_MULTIPLIER_FOR_RENDERED_TABLES
> Multiply the size of text in rendered tables by this
> factor. Default is 1.0
82a106,118
> --wordspace=WORDSPACE
> Set the space between words in pts. Default is 2.5
>
> --sans-family=SANS_FAMILY
> The sans-serif family of fonts to embed
>
> --mono-family=MONO_FAMILY
> The monospace family of fonts to embed
>
> --enable-autorotation
> Enable autorotation of images that are wider than the
> screen width.
>
139,143d176
< --dont-justify Do not force text to be justified in output. Whether
< text is actually displayed justified or not depends on
< whether the ebook format and reading device support
< justification.
<
76,85c76
---
> Options to control the processing of the output pdb
>
> -f FORMAT, --format=FORMAT
> Format to use inside the pdb container. Choices are:
> ['doc', 'ztxt', 'ereader']
>
> --output-encoding=OUTPUT_ENCODING
> Specify the character encoding of the output document.
> The default is cp1252. Note: This option is not
> honored by all formats.