Transforms a DTBook (DAISY 3 XML) document into a PEF.
The value can range from 1 to 10. The lower the value, the more preference is given to volume breaks
right before or after elements level1
to level6
. The higher the value, the more equal the volumes
will be in size.
10
This option only determines whether hyphenation is allowed at page boundaries. The “Hyphenation” option and the CSS determine how the hyphenation is done, when allowed.
false
except-at-volume-breaks
true
false
If left blank, the locale information in the input document will be used to select a suitable table.
DEPRECATION WARNING: XSLT style sheets are also supported, but this feature might be removed in the future. It is recommended to apply any XSLT style sheets during pre-processing of the document.
Must be a space separated list of URIs, absolute or relative to the input.
Style sheets specified through this option are called “user style sheets”. Style sheets can also be attached to the source document. These are referred to as “author style sheets”. They can be linked (using an ‘xml-stylesheet’ processing instruction or a ‘link’ element), embedded (using a ‘style’ element) and/or inlined (using ‘style’ attributes). Only author styles that apply to “embossed” media are taken into account.
Style sheets are applied to the document in the following way: XSLT style sheets are applied before CSS/Sass style sheets. XSLT style sheets are applied one by one, first the user style sheets, then the author style sheets, in the order in which they are specified.
All CSS/Sass style sheets are applied at once, but the order in which they are specified has an influence on the cascading order. Author styles take precedence over user styles.
CSS/Sass style sheets are interpreted according to braille CSS rules.
For info on how to use Sass (Syntactically Awesome StyleSheets) see the Sass manual.
A number of partials (helper style sheet modules) are available for use in Sass style sheets:
The following CSS rule is included by default (where $hyphenation
is the value of this option):
:root {
hyphens: $hyphenation;
}
This means that words are hyphenated according to the specified policy, except where overridden by more specific CSS rules. See the CSS specification for more info:
hyphens
propertyIn addition, special rules may apply at page boundaries, see the “Hyphenation at page boundaries” option.
auto
manual
none
auto
true
or false
false
true
or false
false
Sets the default page height (this can be overwritten with @page
rules) and affects media queries
that use the ‘height’ feature. The variable $page-height
is available in Sass style sheets.
See the CSS specification for more info:
@page
rulesize
property25
By default, text that overflows its containing box will result in an error. By selecting this option, overflowing text will be truncated and generate a warning instead whenever possible. Notably, this will happen with text within page margins (top, right, bottom and left) that is too long to fit the space.
true
or false
false
The following CSS rule is included by default (where $force-braille-page-break
is the value of
this option):
@if $force-braille-page-break {
pagenum {
page-break-before: always;
}
}
See the CSS specification for more info:
page-break-before
propertytrue
or false
false
Style sheets, whether they’re user style sheets (specified with the “stylesheet” option) or author style sheets (associated with the source), may have parameters (Sass variables). The “stylesheet-parameters” option, which takes a list of parenthesis enclosed key-value pairs, can be used to set these variables.
For example, if a style sheet uses the Sass variable “foo”:
@if $foo {
/* some style that should only be enabled when "foo" is truthy */
}
you can control that variable with the following parameters list: (foo:true)
.
The syntax is as follows (described in terms of CSS grammar):
query
: feature*
;
feature
: '(' S* IDENT S* [ ':' S* value ]? ')' S*
;
value
: string | integer | IDENT
;
Notes, i.e. note
elements that are referenced by a noteref
element, can be rendered either at
the bottom of the page on which they occur (on which they are referenced), at the end of the block
in which they occur, at the end of the volume in which they occur, or at the end of the book. note
elements that are not referenced by a noteref
are not rendered.
Note references can be styled using a noteref
rule. Notes that are placed at the end of the block
can be styled with a note
rule. Notes that are placed at the bottom of the page or at the end of a
chapter, volume or the end of the book can be styled with a noteref::alternate
rule. A title can
be inserted at the beginning of an endnotes section using a
.endnotes-section::-obfl-on-collection-start
rule. Example:
.endnotes-section::-obfl-on-collection-start {
content: "Notes in this volume";
text-align: center;
margin-bottom: 1;
}
bottom-of-page
Notes are rendered in the @footnotes
area of the page on which they occur.
There is a built-in fallback mechanism: if a note does not fit on a page, e.g. because it is too big, or there are too many other notes on that page, all notes in the whole book will be rendered at the end of the volume in which they occur.
The footnotes area can be styled using a @footnotes
rule. Example:
@page {
@footnotes {
border-top: ⠤;
max-height: 20;
}
}
end-of-block
Notes are rendered after the block (e.g. paragraph) in which they occur.
end-of-chapter
Notes are rendered at the end of the chapter (level1
, level2
, level3
, level4
, level5
,
level6
,) in which they occur.
end-of-volume
Notes are rendered in the @end
area of
the volume in which they occur.
end-of-book
Notes are rendered in the @end
area of
the last volume.
Notes can be grouped by volume using a
.endnotes-section::-obfl-on-volume-start
rule. Example:
.endnotes-section::-obfl-on-volume-start {
content: "Notes in volume " -obfl-evaluate("$started-volume-number");
margin: 1 0;
}
custom
Special handling of notes is disabled. Notes are rendered as specified in custom style sheets.
end-of-book
If set, braille transcription is
done using the selected braille code. If left empty, the braille code is determined by the document
language. Note that braille transcription can also be controlled through CSS @text-transform
rules.
true
or false
true
Features of the braille transformer to be used for creating the paginated braille document from the CSS styled input document. Together with the “Braille code” option this determines the transformer that is selected.
The syntax is as follows (described in terms of CSS grammar):
query
: feature*
;
feature
: '(' S* IDENT S* [ ':' S* value ]? ')' S*
;
value
: string | integer | IDENT
;
(translator:liblouis)(formatter:dotify)
level1
is the highest level. The value must be greater or equal to 0. It can be a non-integer. A
value of 0 means no preference is given. A higher value results in volumes that are less equal in
size.
0
Sets the default page width (this can be overwritten with @page
rules) and affects media queries
that use the ‘width’ feature. The variable $page-width
is available in Sass style sheets.
See the CSS specification for more info:
@page
rulesize
property40
true
or false
false
The following CSS rule is included by default (where $line-spacing
is the value of this option):
@if $line-spacing == double {
:root {
line-height: 2;
}
}
See the CSS specification for more info:
line-height
propertysingle
double
single
The following CSS rule is included by default (where $maximum-number-of-sheets
is the value of
this option):
@volume {
max-length: $maximum-number-of-sheets;
}
See the CSS specification for more info:
@volume
rulemax-length
property70
true
or false
false
The file format must be expressed as a list of parenthesis enclosed key-value pairs. For example, to
select a file format suited for the U.S., set the option to (locale:en-US)
. To use the braille
character set used in the Netherlands and store to a file with extension “.brl”, set the option to
(locale:nl)(file-extension:'.brl')
.
If left blank, the braille will be stored in PEF format.
The syntax is as follows (described in terms of CSS grammar):
query
: feature*
;
feature
: '(' S* IDENT S* [ ':' S* value ]? ')' S*
;
value
: string | integer | IDENT
;
Usage: dp2 [GLOBAL_OPTIONS] dtbook-to-pef [OPTIONS] Options:
--source source | |
--allow-volume-break-inside-leaf-section-factor [allow-volume-break-inside-leaf-section-factor] | Allow breaks within sections. (default: 10 ) |
--hyphenation-at-page-breaks [hyphenation-at-page-breaks] | Hyphenation at page boundaries (default: false ) |
--preview-table [preview-table] | ASCII braille table for HTML preview (default: ) |
--stylesheet [stylesheet] | Style sheets (default: ) |
--hyphenation [hyphenation] | Hyphenation (default: auto ) |
--include-obfl [include-obfl] | Include OBFL (default: false ) |
--include-pef [include-pef] | Include PEF (default: false ) |
--page-height [page-height] | Page height (default: 25 ) |
--allow-text-overflow-trimming [allow-text-overflow-trimming] | Trimming of overflowing text (default: false ) |
--force-braille-page-break [force-braille-page-break] | Force braille page break (default: false ) |
--stylesheet-parameters [stylesheet-parameters] | Style sheet parameters (default: ) |
--notes-placement [notes-placement] | Notes placement (default: end-of-book ) |
--braille-code [braille-code] | Braille code (default: ) |
--duplex [duplex] | Duplex (default: true ) |
--transform [transform] | Transformer features (default: (translator:liblouis)(formatter:dotify) ) |
--prefer-volume-break-before-higher-level-factor [prefer-volume-break-before-higher-level-factor] | Prefer breaks at higher level sections. (default: 0 ) |
--page-width [page-width] | Page width (default: 40 ) |
--include-preview [include-preview] | Include preview (default: false ) |
--line-spacing [line-spacing] | Line spacing (default: single ) |
--maximum-number-of-sheets [maximum-number-of-sheets] | Maximum number of sheets (default: 70 ) |
--include-css [include-css] | Include DTBook with inline CSS (default: false ) |
--output-file-format [output-file-format] | Output file format (default: ) |
-o,--output [OUTPUT] | Path where to store the results. This option is mandatory when the job is not executed in the background |
-z,--zip | Write the output to a zip file rather than to a folder |
-n,--nicename [NICENAME] | Set job's nice name |
-r,--priority [PRIORITY] | Set job's priority (high|medium|low) |
-q,--quiet | Do not print the job's messages |
-p,--persistent | Delete the job after it is executed |
-b,--background | Sends the job and exits |