Transforms a EPUB 3 publication into a PEF.
You may alternatively use the EPUB package document (the OPF-file) if your input is a unzipped/”exploded” version of an EPUB.
Makes the variable $include-line-groups
available in style sheets and includes the following rule
by default:
.linegroup .line {
display: if($include-line-groups, block, inline);
}
true
or false
true
true
or false
true
A table of contents will be generated from the heading elements present in the document: from h1
elements if the specified value for the depth is 1, from h1
and h2
elements if the specified
value is 2, etc. The resulting table of contents has the following nested structure:
<ol id="generated-document-toc">
<li>
<a href="#ch_1" title="Chapter 1">Chapter 1</a>
<ol>
<li>
<a href="#ch_1_1" title="1.1">1.1</a>
...
</li>
<li>
<a href="#ch_1_2" title="1.2">1.2</a>
...
</li>
...
</ol>
</li>
...
</ol>
Another one of these is generated but with ID generated-volume-toc
. ch_1
, ch_1_2
etc. are the
IDs of the heading elements from which the list was constructed, and the content of the links are
exact copies of the content of the heading elements. By default the lists are not rendered. The
lists should be styled and positioned with CSS. The following rules are included by default:
#generated-document-toc {
flow: document-toc;
display: -obfl-toc;
-obfl-toc-range: document;
list-style-type: none;
}
#generated-volume-toc {
flow: volume-toc;
display: -obfl-toc;
-obfl-toc-range: volume;
list-style-type: none;
}
This means that a document range table of contents is added to the named flow called “document-toc”,
and a volume range table of contents is added to the named flow called “volume-toc”. In order to
consume these named flows use the function flow()
. For example, to position the document range
table of contents at the beginning of the first volume, and to repeat the volume range table of
content at the beginning of every other volume, include the following additional rules:
@volume {
@begin {
content: flow(volume-toc, document);
}
}
@volume:first {
@begin {
content: flow(document-toc, document);
}
}
By default, the table of contents is styled as a normal unordered list, only including the text of
the headings. Including the braille page numbers of the headings can be done using the
target-counter
function. For example, to place the page number after the heading title, with a
space in between:
#generated-document-toc li > a,
#generated-volume-toc li > a {
content: ' ' target-counter(attr(href), page);
}
Note that there is only a single “depth” setting for both lists. If you wish to include less levels
of headings in the document TOC, you have to achieve it through CSS styling. For example, to get
only one level of headings in the document TOC, make all nested ol
elements invisible:
#generated-document-toc > li > ol {
display: none;
}
See the CSS specification for more info:
display:
-obfl-toc
valueflow
propertyflow()
function@volume
rule@begin
ruletarget-counter()
functionpage
counter0
If left blank, the locale information in the input document will be used to select a suitable table.
The syntax is as follows (described in terms of CSS grammar):
query
: feature*
;
feature
: '(' S* IDENT S* [ ':' S* value ]? ')' S*
;
value
: string | integer | IDENT
;
Makes the variable $hyphenation
available in style sheets and includes the following rule by
default:
: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
propertyauto
manual
none
auto
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
;
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)
If set, braille transcription is done with the selected braille code. If left empty, the braille code is determined by the document language and the “Transformer features” option.
true
or false
false
Makes the variable $capital-letters
available in style sheets and includes the following rule by
default:
@if $capital-letters != true {
:root {
text-transform: lowercase;
}
}
true
or false
true
Makes the variable $show-print-page-numbers
available in style sheets and includes the following
rule by default:
@if $show-print-page-numbers {
.page-front,
.page-normal,
.page-special,
[epub|type='pagebreak'] {
string-set: print-page attr(title);
}
}
In order to use the print-page
string include a rule like the following in your custom style
sheet:
@page {
@bottom-right {
content: string(print-page);
}
}
See the CSS specification for more info:
string-set
property@page
rulestring()
functiontrue
or false
true
Makes the variable $show-braille-page-numbers
available in style sheets. In order to use the
variable include a rule like the following in your custom style sheet:
@if $show-braille-page-numbers {
@page {
@top-right {
content: counter(page);
}
}
}
This will create a page number in the top right corner of every braille page.
See the CSS specification for more info:
true
or false
true
Makes the variable $include-production-notes
available in style sheets and includes the following
rule by default:
.prodnote,
[epub|type~='z3998:production'] {
display: if($include-production-notes, block, none);
}
true
or false
false
Makes the variable $include-captions
available in style sheets and includes the following rule by
default:
caption {
display: if($include-captions, block, none);
}
true
or false
true
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
The value can range from 1 to 10. The lower the value, the more preference is given to volume breaks
right before section
elements. The higher the value, the more equal the volumes will be in
size.
10
Sets the default page height (this can be overwritten with @page
rules), affects media queries
that use the ‘height’ feature, and makes the variable $page-height
available in style sheets.
See the CSS specification for more info:
@page
rulesize
property25
Makes the variable $levels-in-footer
available in style sheets and includes the following rule by
default:
@for $level from 1 through 6 {
@if $levels-in-footer >= $level {
h#{$level} {
string-set: footer content();
}
}
}
In other words, the footer
string is updated each time a heading with a level smaller than or
equal to levels-in-footer
is encountered. In order to use the footer
string include a rule like
the following in your custom style sheet:
@page {
@bottom-center {
content: string(footer);
}
}
See the CSS specification for more info:
string-set
property@page
rulestring()
function6
Makes the variable $maximum-number-of-sheets
available in style sheets and includes the following
rule by default:
@volume {
max-length: $maximum-number-of-sheets;
}
See the CSS specification for more info:
@volume
rulemax-length
property70
true
or false
false
Style sheets, whether they’re specified with the “stylesheets” option or associated with the source, may have parameters (variables in case of Sass). The “stylesheet-parameters” option can be used to set these parameters.
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. elements that are referenced by an element with epub:type
“noteref”, can be rendered
either at 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. Elements with epub:type
“note”, “footnote”, “endnote” or “rearnote” that are not referenced
by a noteref are not rendered.
Note references can be styled using a a[epub|type~='noteref']
rule. Notes that are placed at the
end of the block can be styled with a [epub|type~='notes'], [epub|type~='footnotes'],
[epub|type~='endnotes'], [epub|type~='rearnotes']
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
a[epub|type~='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 (section
) 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
Makes the variable $line-spacing
available in style sheets and includes the following rule by
default:
@if $line-spacing == double {
:root {
line-height: 2;
}
}
See the CSS specification for more info:
line-height
propertysingle
double
single
If specified, heading elements with this class name are excluded from the generated tables of contents.
The input EPUB may already contain CSS that applies to embossed media. Such document-specific CSS takes precedence over any CSS attached when running this script.
For instance, if the EPUB already contains the rule p { padding-left: 2; }
,
and using this script the rule p#docauthor { padding-left: 4; }
is provided, then the
padding-left
property will get the value 2
because that’s what was defined in the EPUB,
even though the provided CSS is more specific.
true
or false
false
Makes the variable $force-braille-page-break
available in style sheets and includes the following
rule by default:
@if $force-braille-page-break {
.page-front,
.page-normal,
.page-special,
[epub|type='pagebreak'] {
page-break-before: always;
}
}
See the CSS specification for more info:
page-break-before
propertytrue
or false
false
Sets the default page width (this can be overwritten with @page
rules), affects media queries that
use the ‘width’ feature, and makes the variable $page-width
available in style sheets.
See the CSS specification for more info:
@page
rulesize
property40
Makes the variable $include-images
available in style sheets and includes the following rule by
default:
@if $include-images {
img::after {
content: attr(alt);
}
}
true
or false
true
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
true
or false
false
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).
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 (first user style sheets, then author style sheets) has an influence on the cascading order.
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:
Usage: dp2 [GLOBAL_OPTIONS] epub3-to-pef [OPTIONS] Options:
--preamble preamble | An HTML file to be prepended to the EPUB spine. |
--epub epub | The EPUB you want to convert to braille. |
--include-line-groups [include-line-groups] | Include line groups (default: true ) |
--duplex [duplex] | Duplex (default: true ) |
--toc-depth [toc-depth] | Table of contents depth (default: 0 ) |
--preview-table [preview-table] | ASCII braille table for HTML preview (default: ) |
--hyphenation [hyphenation] | Hyphenation (default: auto ) |
--output-file-format [output-file-format] | Output file format (default: ) |
--transform [transform] | Transformer features (default: (translator:liblouis)(formatter:dotify) ) |
--braille-code [braille-code] | Braille code (default: ) |
--include-obfl [include-obfl] | Include OBFL (default: false ) |
--capital-letters [capital-letters] | Capital letters (default: true ) |
--show-print-page-numbers [show-print-page-numbers] | Show print page numbers (default: true ) |
--show-braille-page-numbers [show-braille-page-numbers] | Show braille page numbers (default: true ) |
--include-production-notes [include-production-notes] | Include production notes (default: false ) |
--include-captions [include-captions] | Include captions (default: true ) |
--prefer-volume-break-before-higher-level-factor [prefer-volume-break-before-higher-level-factor] | Prefer breaks at higher level sections. (default: 0 ) |
--allow-volume-break-inside-leaf-section-factor [allow-volume-break-inside-leaf-section-factor] | Allow breaks within sections. (default: 10 ) |
--page-height [page-height] | Page height (default: 25 ) |
--levels-in-footer [levels-in-footer] | Levels in footer (default: 6 ) |
--maximum-number-of-sheets [maximum-number-of-sheets] | Maximum number of sheets (default: 70 ) |
--include-preview [include-preview] | Include preview (default: false ) |
--stylesheet-parameters [stylesheet-parameters] | Style sheet parameters (default: ) |
--notes-placement [notes-placement] | Notes placement (default: end-of-book ) |
--line-spacing [line-spacing] | Line spacing (default: single ) |
--toc-exclude-class [toc-exclude-class] | Exclude headings (default: ) |
--apply-document-specific-stylesheets [apply-document-specific-stylesheets] | Apply document-specific CSS (default: false ) |
--force-braille-page-break [force-braille-page-break] | Force braille page break (default: false ) |
--page-width [page-width] | Page width (default: 40 ) |
--include-images [include-images] | Include images (default: true ) |
--hyphenation-at-page-breaks [hyphenation-at-page-breaks] | Hyphenation at page boundaries (default: false ) |
--include-pef [include-pef] | Include PEF (default: false ) |
--stylesheet [stylesheet] | Style sheets (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 |