PDF options - triplecanopy/b-ber GitHub Wiki
Please note: this is an experimental feature and has not been fully tested.
b-ber uses Calibre to generate PDFs. In the config.yml file the following options can be passed in:
OUTPUT OPTIONS:
Options to control the processing of the output pdf
--custom-size=CUSTOM_SIZE
Custom size of the document. Use the form widthxheight
e.g. `123x321` to specify the width and height. This
overrides any specified paper-size.
--pdf-standard-font=PDF_STANDARD_FONT
The font family used to render monospace fonts
--pdf-mark-links Surround all links with a red box, useful for
debugging.
--preserve-cover-aspect-ratio
Preserve the aspect ratio of the cover, instead of
stretching it to fill the full first page of the
generated pdf.
--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.
--pdf-page-margin-top=PDF_PAGE_MARGIN_TOP
The size of the top page margin, in pts. Default is
72pt. Overrides the common top page margin setting,
unless set to zero.
--pdf-page-margin-right=PDF_PAGE_MARGIN_RIGHT
The size of the right page margin, in pts. Default is
72pt. Overrides the common right page margin setting,
unless set to zero.
--toc-title=TOC_TITLE
Title for generated table of contents.
--uncompressed-pdf Generate an uncompressed PDF, useful for debugging,
only works with the new PDF engine.
--pdf-serif-family=PDF_SERIF_FAMILY
The font family used to render serif fonts
--pdf-mono-font-size=PDF_MONO_FONT_SIZE
The default font size for monospaced text
--pdf-page-margin-left=PDF_PAGE_MARGIN_LEFT
The size of the left page margin, in pts. Default is
72pt. Overrides the common left page margin setting.
--pdf-page-margin-bottom=PDF_PAGE_MARGIN_BOTTOM
The size of the bottom page margin, in pts. Default is
72pt. Overrides the common bottom page margin setting,
unless set to zero.
--pdf-page-numbers Add page numbers to the bottom of every page in the
generated PDF file. If you specify a footer template,
it will take precedence over this option.
--pdf-add-toc Add a Table of Contents at the end of the PDF that
lists page numbers. Useful if you want to print out
the PDF. If this PDF is intended for electronic use,
use the PDF Outline instead.
--use-profile-size Instead of using the paper size specified in the PDF
Output options, use a paper size corresponding to the
current output profile. Useful if you want to generate
a PDF for viewing on a specific device.
--pdf-footer-template=PDF_FOOTER_TEMPLATE
An HTML template used to generate footers on every
page. The strings _PAGENUM_, _TITLE_, _AUTHOR_ and
_SECTION_ will be replaced by their current values.
--pdf-default-font-size=PDF_DEFAULT_FONT_SIZE
The default font size
--pdf-sans-family=PDF_SANS_FAMILY
The font family used to render sans-serif fonts
--pdf-mono-family=PDF_MONO_FAMILY
The font family used to render monospace fonts
-u UNIT, --unit=UNIT
The unit of measure for page sizes. Default is inch.
Choices are ['millimeter', 'centimeter', 'point',
'inch', 'pica', 'didot', 'cicero', 'devicepixel']
Note: This does not override the unit for margins!
--paper-size=PAPER_SIZE
The size of the paper. This size will be overridden
when a non default output profile is used. Default is
letter. Choices are [u'a0', u'a1', u'a2', u'a3',
u'a4', u'a5', u'a6', u'b0', u'b1', u'b2', u'b3',
u'b4', u'b5', u'b6', u'legal', u'letter']
--pdf-header-template=PDF_HEADER_TEMPLATE
An HTML template used to generate headers on every
page. The strings _PAGENUM_, _TITLE_, _AUTHOR_ and
_SECTION_ will be replaced by their current values.
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.
--embed-font-family=EMBED_FONT_FAMILY
Embed the specified font family into the book. This
specifies the "base" font used for the book. If the
input document specifies its own fonts, they may
override this base font. You can use the filter style
information option to remove fonts from the input
document. Note that font embedding only works with
some output formats, principally EPUB, AZW3 and DOCX.
--subset-embedded-fonts
Subset all embedded fonts. Every embedded font is
reduced to contain only the glyphs used in this
document. This decreases the size of the font files.
Useful if you are embedding a particularly large font
with lots of unused glyphs.
--embed-all-fonts Embed every font that is referenced in the input
document but not already embedded. This will search
your system for the fonts, and if found, they will be
embedded. Embedding will only work if the format you
are converting to supports embedded fonts, such as
EPUB, AZW3, DOCX or PDF. Please ensure that you have
the proper license for embedding the fonts used in
this document.
--line-height=LINE_HEIGHT
The line height in pts. Controls spacing between
consecutive lines of text. Only applies to elements
that do not define their own line height. In most
cases, the minimum line height option is more useful.
By default no line height manipulation is performed.
--minimum-line-height=MINIMUM_LINE_HEIGHT
The minimum line height, as a percentage of the
element's calculated font size. calibre will ensure
that every element has a line height of at least this
setting, irrespective of what the input document
specifies. Set to zero to disable. Default is 120%.
Use this setting in preference to the direct line
height specification, unless you know what you are
doing. For example, you can achieve "double spaced"
text by setting this to 240.
--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.
--filter-css=FILTER_CSS
A comma separated list of CSS properties that will be
removed from all CSS style rules. This is useful if
the presence of some style information prevents it
from being overridden on your device. For example:
font-family,color,margin-left,margin-right
--transform-css-rules=TRANSFORM_CSS_RULES
Path to a file containing rules to transform the CSS
styles in this book. The easiest way to create such a
file is to use the wizard for creating rules in the
calibre GUI. Access it in the "Look & feel->Transform
styles" section of the conversion dialog. Once you
create the rules, you can use the "Export" button to
save them to a file.
--expand-css By default, calibre will use the shorthand form for
various CSS properties such as margin, padding,
border, etc. This option will cause it to use the full
expanded form instead. Note that CSS is always
expanded when generating EPUB files with the output
profile set to one of the Nook profiles as the Nook
cannot handle shorthand CSS.
--smarten-punctuation
Convert plain quotes, dashes and ellipsis to their
typographically correct equivalents. For details, see
https://daringfireball.net/projects/smartypants
--unsmarten-punctuation
Convert fancy quotes, dashes and ellipsis to their
plain equivalents.
--margin-top=MARGIN_TOP
Set the top margin in pts. Default is 5.0. Setting
this to less than zero will cause no margin to be set
(the margin setting in the original document will be
preserved). Note: Page oriented formats such as PDF
and DOCX have their own margin settings that take
precedence.
--margin-left=MARGIN_LEFT
Set the left margin in pts. Default is 5.0. Setting
this to less than zero will cause no margin to be set
(the margin setting in the original document will be
preserved). Note: Page oriented formats such as PDF
and DOCX have their own margin settings that take
precedence.
--margin-right=MARGIN_RIGHT
Set the right margin in pts. Default is 5.0. Setting
this to less than zero will cause no margin to be set
(the margin setting in the original document will be
preserved). Note: Page oriented formats such as PDF
and DOCX have their own margin settings that take
precedence.
--margin-bottom=MARGIN_BOTTOM
Set the bottom margin in pts. Default is 5.0. Setting
this to less than zero will cause no margin to be set
(the margin setting in the original document will be
preserved). Note: Page oriented formats such as PDF
and DOCX have their own margin settings that take
precedence.
--change-justification=CHANGE_JUSTIFICATION
Change text justification. A value of "left" converts
all justified text in the source to left aligned (i.e.
unjustified) text. A value of "justify" converts all
unjustified text to justified. A value of "original"
(the default) does not change justification in the
source file. Note that only some output formats
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).
--insert-blank-line-size=INSERT_BLANK_LINE_SIZE
Set the height of the inserted blank lines (in em).
The height of the lines between paragraphs will be
twice the value set here.
--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).
--remove-paragraph-spacing-indent-size=REMOVE_PARAGRAPH_SPACING_INDENT_SIZE
When calibre removes blank lines between paragraphs,
it automatically sets a paragraph indent, to ensure
that paragraphs can be easily distinguished. This
option controls the width of that indent (in em). If
you set this value negative, then the indent specified
in the input document is used, that is, calibre does
not change the indentation.
--asciiize Transliterate unicode characters to an ASCII
representation. Use with care because this will
replace unicode characters with ASCII. For instance it
will replace "Михаил Горбачёв" with "Mikhail
Gorbachiov". Also, note that in cases where there are
multiple representations of a character (characters
shared by Chinese and Japanese for instance) the
representation based on the current calibre interface
language will be used.
--keep-ligatures Preserve ligatures present in the input document. A
ligature is a special rendering of a pair of
characters like ff, fi, fl et cetera. Most readers do
not have support for ligatures in their default fonts,
so they are unlikely to render correctly. By default,
calibre will turn a ligature into the corresponding
pair of normal characters. This option will preserve
them instead.
HEURISTIC PROCESSING:
Modify the document text and structure using common patterns. Disabled
by default. Use --enable-heuristics to enable. Individual actions can
be disabled with the --disable-* options.
--enable-heuristics
Enable heuristic processing. This option must be set
for any heuristic processing to take place.
--disable-markup-chapter-headings
Detect unformatted chapter headings and sub headings.
Change them to h2 and h3 tags. This setting will not
create a TOC, but can be used in conjunction with
structure detection to create one.
--disable-italicize-common-cases
Look for common words and patterns that denote italics
and italicize them.
--disable-fix-indents
Turn indentation created from multiple non-breaking
space entities into CSS indents.
--html-unwrap-factor=HTML_UNWRAP_FACTOR
Scale used to determine the length at which a line
should be unwrapped. Valid values are a decimal
between 0 and 1. The default is 0.4, just below the
median line length. If only a few lines in the
document require unwrapping this value should be
reduced
--disable-unwrap-lines
Unwrap lines using punctuation and other formatting
clues.
--disable-delete-blank-paragraphs
Remove empty paragraphs from the document when they
exist between every other paragraph
--disable-format-scene-breaks
Left aligned scene break markers are center aligned.
Replace soft scene breaks that use multiple blank
lines with horizontal rules.
--disable-dehyphenate
Analyze hyphenated words throughout the document. The
document itself is used as a dictionary to determine
whether hyphens should be retained or removed.
--disable-renumber-headings
Looks for occurrences of sequential <h1> or <h2> tags.
The tags are renumbered to prevent splitting in the
middle of chapter headings.
--replace-scene-breaks=REPLACE_SCENE_BREAKS
Replace scene breaks with the specified text. By
default, the text from the input document is used.
SEARCH AND REPLACE:
Modify the document text and structure using user defined patterns.
--sr1-search=SR1_SEARCH
Search pattern (regular expression) to be replaced
with sr1-replace.
--sr1-replace=SR1_REPLACE
Replacement to replace the text found with sr1-search.
--sr2-search=SR2_SEARCH
Search pattern (regular expression) to be replaced
with sr2-replace.
--sr2-replace=SR2_REPLACE
Replacement to replace the text found with sr2-search.
--sr3-search=SR3_SEARCH
Search pattern (regular expression) to be replaced
with sr3-replace.
--sr3-replace=SR3_REPLACE
Replacement to replace the text found with sr3-search.
--search-replace=SEARCH_REPLACE
Path to a file containing search and replace regular
expressions. The file must contain alternating lines
of regular expression followed by replacement pattern
(which can be an empty line). The regular expression
must be in the Python regex syntax and the file must
be UTF-8 encoded.
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", "prologue",
"epilogue" 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 e-book. Useful
if the input document has a cover image that is not
identified as a cover. In this case, if you set a
cover in calibre, the output document will end up with
two cover images if you do not specify this option.
--insert-metadata Insert the book metadata at the start of the book.
This is useful if your e-book 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. To disable use the expression:
/
--disable-remove-fake-margins
Some documents specify page margins by specifying a
left and right margin on each individual paragraph.
calibre will try to detect and remove these margins.
Sometimes, this can cause the removal of margins that
should not have been removed. In this case you can
disable the removal.
--start-reading-at=START_READING_AT
An XPath expression to detect the location in the
document at which to start reading. Some e-book
reading programs (most prominently the Kindle) use
this location as the position at which to open the
book. See the XPath tutorial in the calibre User
Manual for further help using this feature.
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. See the XPath Tutorial in the
calibre User Manual for examples.
--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. See
the XPath Tutorial in the calibre User Manual for
examples.
--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. See
the XPath Tutorial in the calibre User Manual for
examples.
--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.
--duplicate-links-in-toc
When creating a TOC from links in the input document,
allow duplicate entries, i.e. allow more than one
entry with the same text, provided that they point to
a different location.
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 or URL
--comments=COMMENTS
Set the e-book description.
--publisher=PUBLISHER
Set the e-book publisher.
--series=SERIES Set the series this e-book 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.
--pubdate=PUBDATE Set the publication date (assumed to be in the local
timezone, unless the timezone is explicitly specified)
--timestamp=TIMESTAMP
Set the book timestamp (no longer used anywhere)
-m READ_METADATA_FROM_OPF, --read-metadata-from-opf=READ_METADATA_FROM_OPF, --from-opf=READ_METADATA_FROM_OPF
Read metadata from the specified OPF file. Metadata
read from this file will override any metadata in the
source file.
For example, to generate a PDF with an a5 paper size, page numbers, and a 25pt margin, the following would be included in the config.yml file:
pdf_options:
paper_size: a5
pdf_page_numbers: true
pdf_page_margin_top: 25
pdf_page_margin_right: 25
pdf_page_margin_bottom: 25
pdf_page_margin_left: 25
Calibre uses Qt 5.x to create the web views that are rendered as PDFs. A list of the supported CSS properties can be found in the CSS properties supported by Qt's rich text engine table.
Styles can be scoped to the PDF build.