EPUB 3 to PEF

Transforms a EPUB 3 publication into a PEF.

Synopsis

Inputs

Preamble HTML

An HTML file to be prepended to the EPUB spine.
Media-type:
- application/xhtml+xml
- text/html
Sequence: no
Input EPUB 3

The EPUB you want to convert to braille.

The EPUB you want to convert to braille.
You may alternatively use the EPUB package document (the OPF-file) if your input is a unzipped/”exploded” version of an EPUB.
Media-type:
- application/epub+zip
- application/oebps-package+xml
Sequence: no

Outputs

PEF

The intermediary PEF file.
Media-type:
- application/x-pef+xml
OBFL

The intermediary OBFL file.
Media-type:
- application/x-obfl+xml
Preview

An HTML preview of the braille result.
Media-type:
- text/html
Output file

The output braille file.
Media-type:
- text

Options

Hyphenation at page boundaries

Whether hyphenation of words at page boundaries is allowed or not.

Whether hyphenation of words at page boundaries is allowed or not.
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.

Possible values: One of the following:

false

Never hyphenate words at page boundaries

except-at-volume-breaks

Allow hyphenation at page boundaries except when it's a volume boundary

true

Allow hyphenation at page boundaries

Default value: false
Style sheet parameters
A list of parameters passed to the style sheets.
A list of parameters passed to the style sheets.
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 comma-separated list of key-value pairs enclosed in parenthesis, 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).
Possible values: <stylesheet-parameters>

Default value: ()
Transformer features

Features of the braille transformer.

Features of the braille transformer.
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.
Possible values: A query
The syntax is as follows (described in terms of CSS grammar):
```
query
 : feature*
 ;
feature
 : '(' S* IDENT S* [ ':' S* value ]? ')' S*
 ;
value
 : string | integer | IDENT
 ;
```
Default value: (translator:liblouis)(formatter:dotify)
Trimming of overflowing text

Allow trimming of overflowing text.

Allow trimming of overflowing text.
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.

Possible values: true or false

Default value: false
Include PEF

Whether or not to keep the intermediary PEF file (for debugging).

Possible values: true or false

Default value: false
Include OBFL

Whether or not the keep the intermediary OBFL file (for debugging).

Possible values: true or false

Default value: false
Include preview

Whether or not to include a HTML preview of the braille result.

Possible values: true or false

Default value: false
ASCII braille table for HTML preview

The ASCII braille table used to render the HTML and PDF previews.

The ASCII braille table used to render the HTML and PDF previews.
If left blank, the locale information in the input document will be used to select a suitable table.

Possible values: <preview-table>

Default value:
Duplex

When enabled, will print on both sides of the paper.

Possible values: true or false

Default value: true
Apply document-specific CSS

If this option is enabled, any pre-existing CSS in the EPUB with media "embossed" (or "all") will be used.

If this option is enabled, any pre-existing CSS in the EPUB with media "embossed" (or "all") will be used.
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.

Possible values: true or false

Default value: false
Output file format

The file format in which to store the braille result.

The file format in which to store the braille result.
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.
Possible values: A query
The syntax is as follows (described in terms of CSS grammar):
```
query
 : feature*
 ;
feature
 : '(' S* IDENT S* [ ':' S* value ]? ')' S*
 ;
value
 : string | integer | IDENT
 ;
```
Default value:
Page height
The number of rows available for printing.
The number of rows available for printing.
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:
- the @page rule
- the size property
- the page dimensions media features
Possible values: Any <integer>

Default value: 25
Braille code

Braille code to be used for braille transcription.

Braille code to be used for braille transcription.
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.

Possible values: <liblouis-table-query>

Default value:
Page width
The number of columns available for printing.
The number of columns available for printing.
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:
- the @page rule
- the size property
- the page dimensions media features
Possible values: Any <integer>

Default value: 40
Style sheets
A list of CSS/Sass style sheets to take into account.
A list of CSS/Sass style sheets to take into account.
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.

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

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:
- http://www.daisy.org/pipeline/modules/braille/html-to-pef/_generate-toc.scss: for generating a table of content
- http://www.daisy.org/pipeline/modules/braille/html-to-pef/_tables.scss: for styling tables
- http://www.daisy.org/pipeline/modules/braille/html-to-pef/_definition-lists.scss: for styling definition lists
- http://www.daisy.org/pipeline/modules/braille/html-to-pef/_legacy.scss: collection of styles that used to be included by default
Possible values: <anyURI>

Default value:

Usage: dp2 [GLOBAL_OPTIONS] epub3-to-pef [OPTIONS]

Options:

--preamble preamble	An HTML file to be prepended to the EPUB spine.
--source source	The EPUB you want to convert to braille.
--hyphenation-at-page-breaks [hyphenation-at-page-breaks]	Hyphenation at page boundaries (default: `false`)
--stylesheet-parameters [stylesheet-parameters]	Style sheet parameters (default: `()`)
--transform [transform]	Transformer features (default: `(translator:liblouis)(formatter:dotify)`)
--allow-text-overflow-trimming [allow-text-overflow-trimming]	Trimming of overflowing text (default: `false`)
--include-pef [include-pef]	Include PEF (default: `false`)
--include-obfl [include-obfl]	Include OBFL (default: `false`)
--include-preview [include-preview]	Include preview (default: `false`)
--preview-table [preview-table]	ASCII braille table for HTML preview (default: )
--duplex [duplex]	Duplex (default: `true`)
--apply-document-specific-stylesheets [apply-document-specific-stylesheets]	Apply document-specific CSS (default: `false`)
--output-file-format [output-file-format]	Output file format (default: )
--page-height [page-height]	Page height (default: `25`)
--braille-code [braille-code]	Braille code (default: )
--page-width [page-width]	Page width (default: `40`)
--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