<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:px="http://www.daisy.org/ns/pipeline/xproc" xmlns:pf="http://www.daisy.org/ns/pipeline/functions" xmlns:c="http://www.w3.org/ns/xproc-step" xmlns:cx="http://xmlcalabash.com/ns/extensions" 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" xmlns:map="http://www.w3.org/2005/xpath-functions/map" type="px:epub3-to-pef.script" version="1.0" exclude-inline-prefixes="#all" name="main" px:input-filesets="epub2 epub3" px:output-filesets="pef"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h1 px:role="name">EPUB to braille</h1> <p px:role="desc" xml:space="preserve">Transforms a EPUB publication into an embosser ready braille document.</p> <a px:role="homepage" href="http://daisy.github.io/pipeline/Get-Help/User-Guide/Scripts/epub3-to-pef/"> Online documentation </a> </p:documentation> <p:option name="source" required="true" px:type="anyFileURI" px:sequence="false" px:media-type="application/epub+zip application/oebps-package+xml"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Input EPUB</h2> <p px: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:option name="preamble" required="false" select="''" px:type="anyFileURI" px:sequence="false" px:media-type="application/xhtml+xml text/html" px:reusable="true"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Preamble HTML</h2> <p px:role="desc">An HTML file to be prepended to the EPUB spine.</p> </p:documentation> </p:option> <p:output port="validation-status" px:media-type="application/vnd.pipeline.status+xml"> <p:pipe step="convert-and-store" port="status"/> </p:output> <p:option name="braille-code" px:type="liblouis-table-query" required="false" select="''" px:reusable="false"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Braille code</h2> <p px: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:option name="formatting-standard" select="''" px:reusable="false"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Formatting standard</h2> <p px:role="desc" xml:space="preserve">Standard to be used for braille formatting. If set, [braille formatting](http://daisy.github.io/pipeline/Get-Help/User-Guide/Braille/) is done using the selected formatting standard. If left empty, the formatting of the document is determined entirely by custom styles. It is important to understand that when no formatting standard or custom style sheets are specified, the output will not be formatted (meaning everything will be aligned to the left, without blank lines, pages will be filled completely, and there will be no page numbering). Custom formatting rules may be specified using the "Custom style sheets" option, or in style sheets attached to the source document.</p> </p:documentation> <p:pipeinfo> <px:type> <choice xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"> <value/> <a:documentation xml:lang="en">-</a:documentation> <value>https://raw.githubusercontent.com/daisy/braille-stylesheets/refs/heads/main/bana/bana.scss</value> <a:documentation xml:lang="en" xml:space="preserve">United States and Canada (BANA) The document is formatted according to the rules of the [Braille Authority of North America (BANA)](https://www.brailleauthority.org/). [UEB](https://iceb.org/) is used as the braille code for all text. Equivalent to specifying the value `https://raw.githubusercontent.com/daisy/braille-stylesheets/refs/heads/main/bana/bana.scss` for the "Custom style sheets" option. See the [online documentation](https://daisy.github.io/braille-stylesheets/bana/) for more information. </a:documentation> </choice> </px:type> </p:pipeinfo> </p:option> <p:option xmlns:_="embossed" name="_:stylesheet" required="false" px:type="anyURI" select="''" px:sequence="true" px:separator=" " px:reusable="true" px:media-type="text/css text/x-scss"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"><h2 px:role="name">Style sheets</h2> <p px:role="desc" xml:space="preserve">CSS/Sass style sheets to take into account. Each style sheet must be specified as a URI, absolute or relative to the input. Style sheets specified through this option or through the "Formatting standard" 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. All 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, and user style sheets specified through this option take precedence over the selected formatting standard. 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:option name="apply-document-specific-stylesheets" px:type="boolean" select="'false'"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Apply document-specific CSS</h2> <p px: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:option name="stylesheet-parameters" required="false" px:type="stylesheet-parameters" select="'()'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Style sheet parameters</h2> <p px:role="desc" xml:space="preserve">A list of parameters passed to the style sheets. Style sheets, whether they're user style sheets (specified through options) or author style sheets (associated with the source), may have parameters (Sass variables). This 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": ~~~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:option name="transform" required="false" px:type="transform-query" select="'(translator:liblouis)(formatter:dotify)'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Transformer features</h2> <p px: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:option name="include-preview" required="false" px:type="boolean" select="'false'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Include preview</h2> <p px:role="desc" xml:space="preserve">Whether or not to include a HTML preview of the braille result.</p> </p:documentation></p:option> <p:option name="include-pef" required="false" px:type="boolean" select="'false'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Include PEF</h2> <p px:role="desc" xml:space="preserve">Whether or not to keep the intermediary PEF file (for debugging). [PEF (Portable Embosser Format)](https://braillespecs.github.io/pef/pef-specification.html) is an internal data format used by DAISY Pipeline to represent the final formatted braille document, before it is converted to another embosser-ready format.</p> </p:documentation></p:option> <p:option name="include-obfl" required="false" px:type="boolean" select="'false'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Include OBFL</h2> <p px:role="desc" xml:space="preserve">Whether or not the keep the intermediary OBFL file (for debugging). [OBFL (Open Braille Formatting Language)](https://mtmse.github.io/obfl/obfl-specification.html) is an internal data format used by DAISY Pipeline to represent an intermediary stage of the document being transformed (before it is formatted). The OBFL file may be used for debugging, or it may also be edited and re-transformed to the final braille document using the "OBFL to braille" script.</p> </p:documentation></p:option> <p:option name="include-css" px:type="boolean" select="'false'"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Include HTML with inline CSS</h2> <p px:role="desc" xml:space="preserve">Whether or not the include the intermediary HTML with all CSS styles inlined (for debugging).</p> </p:documentation> </p:option> <p:option name="output-file-format" required="false" px:type="medium" select="''"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Output file format</h2> <p px:role="desc" xml:space="preserve">The file format in which to store the braille result. The file format must be expressed in the media query syntax. For example, to select a file format suited for the U.S., set the option to `(-daisy-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 `(-daisy-locale: nl) AND (-daisy-file-extension: \.brl)`. If left blank, the braille will be stored in [PEF](https://braillespecs.github.io/pef/pef-specification.html) (Portable Embosser Format).</p> </p:documentation></p:option> <p:option name="preview-table" required="false" px:type="preview-table" select="''"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">ASCII braille table for HTML preview</h2> <p px: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:option xmlns:xs="http://www.w3.org/2001/XMLSchema" name="page-width" required="false" select="()" cx:as="xs:string?" px:role="media-feature"><p:pipeinfo> <px:type> <data xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" type="string"> <a:documentation xml:lang="en" xml:space="preserve">A length The syntax is as follows (described in terms of [CSS grammar](https://www.w3.org/TR/CSS21/grammar.html)): length : number unit? ; unit : 'mm' | 'cm' | 'in' | 'px' | 'ch' ; </a:documentation> <param name="pattern">^+?([0-9]*\\.)?[0-9]+([eE][+-]?[0-9]+)?(mm|cm|in|px|ch)?$</param> </data> </px:type></p:pipeinfo><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Page width</h2> <p px:role="desc" xml:space="preserve">The width of the targeted medium. Sets the default page width, and affects media queries that use the 'width' and 'device-width' media features. The 'width' media feature describes the width of the targeted display area, i.e. the printable area of the page. The 'device-width' media feature describes the total width of the rendering surface, i.e. the page width. Note that the default page width may be overwritten with `@page` rules, but this does not affect media queries. The width may be specified in an absolute (`mm`, `cm`, `in`, ...) or cell-relative (`ch`) length. A dimension without a unit is interpreted as a multiple of the braille cell width. 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:option xmlns:xs="http://www.w3.org/2001/XMLSchema" name="page-height" required="false" select="()" cx:as="xs:string?" px:role="media-feature"><p:pipeinfo> <px:type> <data xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" type="string"> <a:documentation xml:lang="en" xml:space="preserve">A length The syntax is as follows (described in terms of [CSS grammar](https://www.w3.org/TR/CSS21/grammar.html)): length : number unit? ; unit : 'mm' | 'cm' | 'in' | 'px' | 'em' ; </a:documentation> <param name="pattern">^+?([0-9]*\.)?[0-9]+([eE][+-]?[0-9]+)?(mm|cm|in|px|em)?$</param> </data> </px:type></p:pipeinfo><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Page height</h2> <p px:role="desc" xml:space="preserve">The height of the targeted medium. Sets the default page height, and affects media queries that use the 'height' and 'device-height' media features. The 'height' media feature describes the height of the targeted display area, i.e. the printable area of the page. The 'device-height' media feature describes the total height of the rendering surface, i.e. the page height. The height may be specified in an absolute (`mm`, `cm`, `in`, ...) or cell-relative (`em`) length. A dimension without a unit is interpreted as a multiple of the braille cell height. 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:option xmlns:xs="http://www.w3.org/2001/XMLSchema" name="duplex" required="false" select="()" cx:as="xs:boolean?" px:role="media-feature"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Duplex</h2> <p px:role="desc" xml:space="preserve">Whether to print on both sides of the leaves. Sets the number of printed sides per leaf, and affects media queries that use the '-daisy-duplex' media feature.</p> </p:documentation></p:option> <p:option xmlns:xs="http://www.w3.org/2001/XMLSchema" name="saddle-stitch" required="false" select="()" cx:as="xs:boolean?" px:role="media-feature"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Saddle stitch (folio binding)</h2> <p px:role="desc" xml:space="preserve">Whether the targeted medium is bound in folios. In this mode, sheets of paper are folded once to produce two leaves (four pages). This option affects media queries that use the '-daisy-saddle-stitch' media feature.</p> </p:documentation></p:option> <p:option name="hyphenation-at-page-breaks" required="false" select="'false'"><p:pipeinfo> <px:type> <choice xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"> <value>false</value> <a:documentation xml:lang="en">Never hyphenate words at page boundaries</a:documentation> <value>except-at-volume-breaks</value> <a:documentation xml:lang="en">Allow hyphenation at page boundaries except when it's a volume boundary</a:documentation> <value>true</value> <a:documentation xml:lang="en">Allow hyphenation at page boundaries</a:documentation> </choice> </px:type></p:pipeinfo><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Hyphenation at page boundaries</h2> <p px:role="desc" xml:space="preserve">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. </p> </p:documentation></p:option> <p:option name="allow-text-overflow-trimming" px:type="boolean" required="false" select="'false'"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Trimming of overflowing text</h2> <p px:role="desc" xml:space="preserve">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. </p> </p:documentation></p:option> <p:option name="result" required="true" px:output="result" px:type="anyDirURI" px:media-type="text"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Output file</h2> <p px:role="desc">The output braille file.</p> </p:documentation></p:option> <p:option name="pef" required="false" px:output="result" px:type="anyDirURI" px:media-type="application/x-pef+xml" select="''"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">PEF</h2> <p px:role="desc">The intermediary PEF file.</p> </p:documentation></p:option> <p:option name="preview" required="false" px:output="result" px:type="anyDirURI" px:media-type="text/html" select="''"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">Preview</h2> <p px:role="desc">An HTML preview of the braille result.</p> </p:documentation></p:option> <p:option name="obfl" required="false" px:output="result" px:type="anyDirURI" px:media-type="application/x-obfl+xml" select="''"><p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">OBFL</h2> <p px:role="desc">The intermediary OBFL file.</p> </p:documentation></p:option> <p:option name="html-with-css" px:output="result" px:type="anyDirURI" px:media-type="application/xhtml+xml" select="''"> <p:documentation xmlns="http://www.w3.org/1999/xhtml"> <h2 px:role="name">HTML with inline CSS</h2> <p px:role="desc">The intermediary HTML file with inline CSS.</p> </p:documentation> </p:option> <p:import href="library.xpl"> <p:documentation> px:epub3-to-pef.load px:epub3-to-pef px:epub3-to-pef.store </p:documentation> </p:import> <p:import href="http://www.daisy.org/pipeline/modules/fileset-utils/library.xpl"> <p:documentation> px:fileset-load </p:documentation> </p:import> <cx:import href="http://www.daisy.org/pipeline/modules/css-utils/library.xsl" type="application/xslt+xml"> <p:documentation> pf:css-parse-medium </p:documentation> </cx:import> <cx:import href="http://www.daisy.org/pipeline/modules/braille/pef-utils/library.xsl" type="application/xslt+xml"> <p:documentation> pf:pef-assert-embossable </p:documentation> </cx:import> <px:epub3-to-pef.load name="load" px:message="Loading EPUB" px:progress=".04"> <p:with-option name="epub" select="$source"/> <p:with-option name="preamble" select="$preamble"/> <p:with-option name="temp-dir" select="concat($temp-dir,'load/')"/> </px:epub3-to-pef.load> <px:fileset-load name="opf" media-types="application/oebps-package+xml"> <p:input port="in-memory"> <p:pipe step="load" port="in-memory.out"/> </p:input> </px:fileset-load> <p:sink/> <p:group name="convert-and-store" px:progress=".96"> <p:output port="status"> <p:pipe step="convert" port="status"/> </p:output> <p:variable name="medium" select="pf:pef-assert-embossable( pf:css-parse-medium(( ($output-file-format,'embossed AND (-daisy-format:pef)')[not(.='')][1], map:merge(( for $page-width in $page-width return map:entry('device-width',$page-width), for $page-height in $page-height return map:entry('device-height',$page-height), for $duplex in $duplex return map:entry('duplex',$duplex), for $saddle-stitch in $saddle-stitch return map:entry('saddle-stitch',$saddle-stitch), map:entry('-daisy-document-locale',(/*/opf:metadata/dc:language[not(@refines)])[1]/string(text())))))))"> <p:pipe port="result" step="opf"/> </p:variable> <p:identity> <p:input port="source"> <p:pipe port="fileset.out" step="load"/> </p:input> </p:identity> <px:epub3-to-pef name="convert" px:message="Converting from EPUB to PEF" px:progress="90/95"> <p:with-option name="epub" select="$source"/> <p:input port="in-memory.in"> <p:pipe port="in-memory.out" step="load"/> </p:input> <p:with-option name="temp-dir" select="concat($temp-dir,'convert/')"/> <p:with-option xmlns:_="embossed" name="stylesheet" select="string-join(($formatting-standard,$_:stylesheet),' ')"/> <p:with-option name="parameters" select="($stylesheet-parameters, map:merge(( for $page-width in $page-width return map:entry('page-width',$page-width), for $page-height in $page-width return map:entry('page-height',$page-height), for $duplex in $duplex return map:entry('duplex',$duplex), for $saddle-stitch in $saddle-stitch return map:entry('saddle-stitch',$saddle-stitch), map:entry('hyphenation-at-page-breaks',$hyphenation-at-page-breaks), map:entry('allow-text-overflow-trimming',$allow-text-overflow-trimming))))"/> <p:with-option name="apply-document-specific-stylesheets" select="$apply-document-specific-stylesheets"/> <p:with-option name="transform" select="concat($braille-code,($transform,'(translator:liblouis)(formatter:dotify)')[not(.='')][1])"/> <p:with-option name="medium" select="$medium"/> <p:with-option name="include-obfl" select="$include-obfl"/> </px:epub3-to-pef> <p:sink/> <p:identity> <p:input port="source"> <p:pipe step="convert" port="in-memory.out"/> </p:input> </p:identity> <p:for-each> <p:delete match="/*/@xml:base"/> </p:for-each> <px:epub3-to-pef.store px:message="Storing results" px:progress="5/95"> <p:with-option name="epub" select="$source"/> <p:input port="opf"> <p:pipe step="opf" port="result"/> </p:input> <p:input port="obfl"> <p:pipe step="convert" port="obfl"/> </p:input> <p:input port="css"> <p:pipe step="convert" port="css"/> </p:input> <p:with-option name="include-pef" select="$include-pef"/> <p:with-option name="include-preview" select="$include-preview"/> <p:with-option name="include-css" select="$include-css"/> <p:with-option name="medium" select="$medium"/> <p:with-option name="preview-table" select="$preview-table"/> <p:with-option name="output-dir" select="$result"/> <p:with-option name="pef-output-dir" select="$pef"/> <p:with-option name="preview-output-dir" select="$preview"/> <p:with-option name="obfl-output-dir" select="$obfl"/> <p:with-option name="css-output-dir" select="$html-with-css"/> </px:epub3-to-pef.store> </p:group> </p:declare-step>