<p:declare-stepxmlns:p="http://www.w3.org/ns/xproc"xmlns:px="http://www.daisy.org/ns/pipeline/xproc"xmlns:c="http://www.w3.org/ns/xproc-step"xmlns:pef="http://www.daisy.org/ns/2008/pef"xmlns:ocf="urn:oasis:names:tc:opendocument:xmlns:container"xmlns:dc="http://purl.org/dc/elements/1.1/"xmlns:opf="http://www.idpf.org/2007/opf"type="px:epub3-to-pef.script"version="1.0"exclude-inline-prefixes="#all"name="main">
<p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h1px:role="name">EPUB 3 to braille</h1><ppx:role="desc"xml:space="preserve">Transforms a EPUB 3 publication into an embosser ready braille document.</p>
<apx:role="homepage"href="http://daisy.github.io/pipeline/Get-Help/User-Guide/Scripts/epub3-to-pef/">
Online documentation
</a>
</p:documentation>
<p:optionname="source"required="true"px:type="anyFileURI"px:sequence="false"px:media-type="application/epub+zip application/oebps-package+xml">
<p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Input EPUB 3</h2><ppx:role="desc"xml:space="preserve">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.</p>
</p:documentation>
</p:option><p:optionname="preamble"required="false"select="''"px:type="anyFileURI"px:sequence="false"px:media-type="application/xhtml+xml text/html">
<p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Preamble HTML</h2><ppx:role="desc">An HTML file to be prepended to the EPUB spine.</p>
</p:documentation>
</p:option><p:outputport="validation-status"px:media-type="application/vnd.pipeline.status+xml">
<p:pipestep="convert"port="status"/>
</p:output><p:optionname="stylesheet"required="false"px:type="anyURI"select="''"px:sequence="true"px:separator=" "px:media-type="text/css text/x-scss application/xslt+xml">
<p:documentationxmlns="http://www.w3.org/1999/xhtml"><h2px:role="name">Style sheets</h2><ppx:role="desc"xml:space="preserve">A list of CSS/Sass style sheets to take into account.
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](https://www.w3.org/TR/CSS2/cascade.html#cascade)". Style sheets can also be attached to the
source document. These are referred to as "[author style
sheets](https://www.w3.org/TR/CSS2/cascade.html#cascade)". They can be linked (using an
['xml-stylesheet' processing instruction](https://www.w3.org/TR/xml-stylesheet) or a ['link'
element](https://www.w3.org/Style/styling-XML#External)), embedded (using a ['style'
element](https://www.w3.org/Style/styling-XML#Embedded)) and/or inlined (using '[style'
attributes](https://www.w3.org/TR/css-style-attr/)). 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](https://www.w3.org/TR/CSS2/cascade.html#cascading-order). Author
styles take precedence over user styles.
CSS/Sass style sheets are interpreted according to [braille
CSS](http://braillespecs.github.io/braille-css) rules.
For info on how to use Sass (Syntactically Awesome StyleSheets) see the [Sass
manual](http://sass-lang.com/documentation/file.SASS_REFERENCE.html).
A number of [partials](https://sass-lang.com/documentation/at-rules/import#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](http://daisy.github.io/pipeline/modules/braille/html-to-pef/src/main/resources/css/_generate-toc.scss/):
for generating a table of content
- [http://www.daisy.org/pipeline/modules/braille/html-to-pef/_tables.scss](http://daisy.github.io/pipeline/modules/braille/html-to-pef/src/main/resources/css/tables):
for styling tables
- [http://www.daisy.org/pipeline/modules/braille/html-to-pef/_definition-lists.scss](http://daisy.github.io/pipeline/modules/braille/html-to-pef/src/main/resources/css/definition-lists):
for styling definition lists
- [http://www.daisy.org/pipeline/modules/braille/html-to-pef/_legacy.scss](http://daisy.github.io/pipeline/modules/braille/html-to-pef/src/main/resources/css/_legacy.scss/):
collection of styles that used to be included by default
</p>
</p:documentation>
</p:option><p:optionname="apply-document-specific-stylesheets"px:type="boolean"select="'false'">
<p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Apply document-specific CSS</h2><ppx:role="desc"xml:space="preserve">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.
</p>
</p:documentation>
</p:option><p:optionname="stylesheet-parameters"required="false"px:type="transform-query"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Style sheet parameters</h2><ppx:role="desc"xml:space="preserve">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 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":
~~~sass
@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)`.</p>
</p:documentation></p:option><p:optionname="braille-code"px:type="liblouis-table-query"required="false"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Braille code</h2><ppx:role="desc"xml:space="preserve">Braille code to be used for braille transcription.
If set, [braille transcription](http://daisy.github.io/pipeline/Get-Help/User-Guide/Braille/) 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.</p>
</p:documentation></p:option><p:optionname="transform"required="false"px:type="transform-query"select="'(translator:liblouis)(formatter:dotify)'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Transformer features</h2><ppx:role="desc"xml:space="preserve">Features of the braille transformer.
Features of the [braille transformer](http://daisy.github.io/pipeline/Get-Help/User-Guide/Braille/)
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.</p>
</p:documentation></p:option><p:optionname="include-preview"required="false"px:type="boolean"select="'false'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Include preview</h2><ppx:role="desc"xml:space="preserve">Whether or not to include a HTML preview of the braille result.</p>
</p:documentation></p:option><p:optionname="include-pef"required="false"px:type="boolean"select="'false'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Include PEF</h2><ppx:role="desc"xml:space="preserve">Whether or not to keep the intermediary PEF file (for debugging).</p>
</p:documentation></p:option><p:optionname="include-obfl"required="false"px:type="boolean"select="'false'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Include OBFL</h2><ppx:role="desc"xml:space="preserve">Whether or not the keep the intermediary OBFL file (for debugging).</p>
</p:documentation></p:option><p:optionname="output-file-format"required="false"px:type="transform-query"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Output file format</h2><ppx:role="desc"xml:space="preserve">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.</p>
</p:documentation></p:option><p:optionname="preview-table"required="false"px:type="preview-table"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">ASCII braille table for HTML preview</h2><ppx:role="desc"xml:space="preserve">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.</p>
</p:documentation></p:option><p:optionname="page-width"required="false"px:type="integer"select="'40'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Page width</h2><ppx:role="desc"xml:space="preserve">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`](http://braillespecs.github.io/braille-css/#h4_the-page-rule) rule
- the [`size`](http://braillespecs.github.io/braille-css/#the-size-property) property
- the [page dimensions media features](https://www.w3.org/TR/mediaqueries-4/#mf-dimensions)
</p>
</p:documentation></p:option><p:optionname="page-height"required="false"px:type="integer"select="'25'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Page height</h2><ppx:role="desc"xml:space="preserve">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`](http://braillespecs.github.io/braille-css/#h4_the-page-rule) rule
- the [`size`](http://braillespecs.github.io/braille-css/#the-size-property) property
- the [page dimensions media features](https://www.w3.org/TR/mediaqueries-4/#mf-dimensions)
</p>
</p:documentation></p:option><p:optionname="duplex"required="false"px:type="boolean"select="'true'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Duplex</h2><ppx:role="desc"xml:space="preserve">When enabled, will print on both sides of the paper.</p>
</p:documentation></p:option><p:optionname="hyphenation"required="false"select="'auto'"><p:pipeinfo><px:type>
<choicexmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0">
<value>auto</value>
<a:documentationxml:lang="en">Hyphenate words</a:documentation>
<value>manual</value>
<a:documentationxml:lang="en">Only hyphenate words where there are soft hyphens (U+00AD)</a:documentation>
<value>none</value>
<a:documentationxml:lang="en">Never hyphenate words</a:documentation>
</choice>
</px:type></p:pipeinfo><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Hyphenation</h2><ppx:role="desc"xml:space="preserve">Hyphenation policy.
The following CSS rule is included by default (where `$hyphenation` is the value of this option):
~~~sass
: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:
- the [`hyphens`](http://braillespecs.github.io/braille-css/#the-hyphens-property) property
</p>
</p:documentation></p:option><p:optionname="line-spacing"required="false"select="'single'"><p:pipeinfo><px:type>
<choice>
<value>single</value>
<documentationxml:lang="en">Single</documentation>
<value>double</value>
<documentationxml:lang="en">Double</documentation>
</choice>
</px:type></p:pipeinfo><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Line spacing</h2><ppx:role="desc"xml:space="preserve">Single or double line spacing.
The following CSS rule is included by default (where `$line-spacing` is the value of this option):
~~~sass
@if $line-spacing == double {
:root {
line-height: 2;
}
}
~~~
See the CSS specification for more info:
- the [`line-height`](http://braillespecs.github.io/braille-css/#h3_the-line-height-property)
property
</p>
</p:documentation></p:option><p:optionname="hyphenation-at-page-breaks"/><p:optionname="allow-text-overflow-trimming"/><p:optionname="force-braille-page-break"required="false"px:type="boolean"select="'false'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Force braille page break</h2><ppx:role="desc"xml:space="preserve">Force braille page breaks at print page breaks.
The following CSS rule is included by default (where `$force-braille-page-break` is the value of
this option):
~~~sass
@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:
- the [`page-break-before`](http://braillespecs.github.io/braille-css/#h4_controlling-page-breaks)
property
</p>
</p:documentation></p:option><p:optionname="maximum-number-of-sheets"required="false"px:type="integer"select="'70'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Maximum number of sheets</h2><ppx:role="desc"xml:space="preserve">The maximum number of sheets in a volume.
The following CSS rule is included by default (where `$maximum-number-of-sheets` is the value of
this option):
~~~sass
@volume {
max-length: $maximum-number-of-sheets;
}
~~~
See the CSS specification for more info:
- the [`@volume`](http://braillespecs.github.io/braille-css/#h3_the-volume-rule) rule
- the [`max-length`](http://braillespecs.github.io/braille-css/#h3_the-length-properties) property
</p>
</p:documentation></p:option><p:optionname="allow-volume-break-inside-leaf-section-factor"required="false"px:type="integer"select="'10'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Allow breaks within sections.</h2><ppx:role="desc"xml:space="preserve">Amount with which volume breaks are allowed within sections.
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.</p>
</p:documentation></p:option><p:optionname="prefer-volume-break-before-higher-level-factor"required="false"select="'0'"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Prefer breaks at higher level sections.</h2><ppx:role="desc"xml:space="preserve">Amount with which preference is given to volume breaks before higher level sections.
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.</p>
</p:documentation></p:option><p:optionname="notes-placement"required="false"select="'end-of-book'"><p:pipeinfo><px:type>
<choice>
<value>bottom-of-page</value>
<documentationxml:lang="en"xml:space="preserve">At the bottom of the page
Notes are rendered in the [`@footnotes`](http://braillespecs.github.io/braille-css/#the-footnotes-area)
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:
~~~css
@page {
@footnotes {
border-top: ⠤;
max-height: 20;
}
}
~~~
</documentation>
<value>end-of-block</value>
<documentationxml:lang="en"xml:space="preserve">At the end of the block
Notes are rendered after the block (e.g. paragraph) in which they occur.
</documentation>
<value>end-of-chapter</value>
<documentationxml:lang="en"xml:space="preserve">At the end of the chapter
Notes are rendered at the end of the chapter (`section`) in which they occur.
</documentation>
<value>end-of-volume</value>
<documentationxml:lang="en"xml:space="preserve">At the end of the volume
Notes are rendered in the [`@end`](http://braillespecs.github.io/braille-css/#the-footnotes-area) area of
the volume in which they occur.
</documentation>
<value>end-of-book</value>
<documentationxml:lang="en"xml:space="preserve">At the end of the book
Notes are rendered in the [`@end`](http://braillespecs.github.io/braille-css/#the-footnotes-area) area of
the last volume.
Notes can be grouped by volume using a
[`.endnotes-section::-obfl-on-volume-start`](http://braillespecs.github.io/braille-css/obfl#extending-the-display-property-with--obfl-list-of-references)
rule. Example:
~~~css
.endnotes-section::-obfl-on-volume-start {
content: "Notes in volume " -obfl-evaluate("$started-volume-number");
margin: 1 0;
}
~~~
</documentation>
<value>custom</value>
<documentationxml:lang="en"xml:space="preserve">Custom handling
Special handling of notes is disabled. Notes are rendered as specified in custom style sheets.
</documentation>
</choice>
</px:type></p:pipeinfo><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Notes placement</h2><ppx:role="desc"xml:space="preserve">Placement of notes
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:
~~~css
.endnotes-section::-obfl-on-collection-start {
content: "Notes in this volume";
text-align: center;
margin-bottom: 1;
}
~~~
</p>
</p:documentation></p:option><p:optionname="result"required="true"px:output="result"px:type="anyDirURI"px:media-type="text"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Output file</h2><ppx:role="desc">The output braille file.</p>
</p:documentation></p:option><p:optionname="pef"required="false"px:output="result"px:type="anyDirURI"px:media-type="application/x-pef+xml"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">PEF</h2><ppx:role="desc">The intermediary PEF file.</p>
</p:documentation></p:option><p:optionname="preview"required="false"px:output="result"px:type="anyDirURI"px:media-type="text/html"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">Preview</h2><ppx:role="desc">An HTML preview of the braille result.</p>
</p:documentation></p:option><p:optionname="obfl"required="false"px:output="result"px:type="anyDirURI"px:media-type="application/x-obfl+xml"select="''"><p:documentationxmlns="http://www.w3.org/1999/xhtml">
<h2px:role="name">OBFL</h2><ppx:role="desc">The intermediary OBFL file.</p>
</p:documentation></p:option>
<p:importhref="http://www.daisy.org/pipeline/modules/braille/epub3-to-pef/library.xpl">
<p:documentation>
px:epub3-to-pef.load
px:epub3-to-pef
px:epub3-to-pef.store
</p:documentation>
</p:import>
<p:importhref="http://www.daisy.org/pipeline/modules/braille/common-utils/library.xpl">
<p:documentation>
px:delete-parameters
px:parse-query
</p:documentation>
</p:import>
<p:importhref="http://www.daisy.org/pipeline/modules/fileset-utils/library.xpl">
<p:documentation>
px:fileset-load
</p:documentation>
</p:import>
<p:in-scope-namesname="in-scope-names"/>
<px:delete-parametersname="input-options"px:message="Collecting parameters"px:progress=".01"parameter-names="epub preamble stylesheet stylesheet-parameters apply-document-specific-stylesheets transform braille-code output-file-format include-pef include-preview include-obfl result pef preview obfl temp-dir">
<p:inputport="source">
<p:pipeport="result"step="in-scope-names"/>
</p:input>
</px:delete-parameters>
<p:sink/>
<px:parse-queryname="stylesheet-parameters">
<p:with-optionname="query"select="$stylesheet-parameters"/>
</px:parse-query>
<p:sink/>
<px:epub3-to-pef.loadname="load"px:message="Loading EPUB"px:progress=".04">
<p:with-optionname="epub"select="$source"/>
<p:with-optionname="preamble"select="$preamble"/>
<p:with-optionname="temp-dir"select="concat($temp-dir,'load/')"/>
</px:epub3-to-pef.load>
<px:fileset-loadname="opf"media-types="application/oebps-package+xml">
<p:inputport="in-memory">
<p:pipestep="load"port="in-memory.out"/>
</p:input>
</px:fileset-load>
<p:sink/>
<p:identity>
<p:inputport="source">
<p:pipeport="fileset.out"step="load"/>
</p:input>
</p:identity>
<px:epub3-to-pefname="convert"px:message="Converting from EPUB to PEF"px:progress=".90">
<p:with-optionname="epub"select="$source"/>
<p:inputport="in-memory.in">
<p:pipeport="in-memory.out"step="load"/>
</p:input>
<p:with-optionname="temp-dir"select="concat($temp-dir,'convert/')"/>
<p:with-optionname="stylesheet"select="$stylesheet"/>
<p:with-optionname="apply-document-specific-stylesheets"select="$apply-document-specific-stylesheets"/>
<p:with-optionname="transform"select="concat($braille-code,($transform,'(translator:liblouis)(formatter:dotify)')[not(.='')][1])"/>
<p:with-optionname="include-obfl"select="$include-obfl"/>
<p:inputport="parameters">
<p:pipeport="result"step="input-options"/>
<p:pipeport="result"step="stylesheet-parameters"/>
</p:input>
</px:epub3-to-pef>
<p:sink/>
<p:identity>
<p:inputport="source">
<p:pipestep="convert"port="in-memory.out"/>
</p:input>
</p:identity>
<p:deletematch="/*/@xml:base"/>
<px:epub3-to-pef.storepx:message="Storing results"px:progress=".05">
<p:with-optionname="epub"select="$source"/>
<p:inputport="opf">
<p:pipestep="opf"port="result"/>
</p:input>
<p:inputport="obfl">
<p:pipestep="convert"port="obfl"/>
</p:input>
<p:with-optionname="include-pef"select="$include-pef"/>
<p:with-optionname="include-preview"select="$include-preview"/>
<p:with-optionname="output-file-format"select="$output-file-format"/>
<p:with-optionname="preview-table"select="$preview-table"/>
<p:with-optionname="output-dir"select="$result"/>
<p:with-optionname="pef-output-dir"select="$pef"/>
<p:with-optionname="preview-output-dir"select="$preview"/>
<p:with-optionname="obfl-output-dir"select="$obfl"/>
</px:epub3-to-pef.store>
</p:declare-step>