xml.epub3-to-epub3.xpl Maven / Gradle / Ivy
EPUB 3 Enhancer
Transforms an EPUB 3 publication into an EPUB 3 publication with audio and/or a braille rendition.
- Name:
- Bert Frees
- E-mail:
- [email protected]
Input EPUB 3
The EPUB you want to convert.
You may alternatively use the "mimetype" document if your input is a unzipped/"exploded" version of an EPUB.
Metadata
Metadata to be included in the EPUB.
If specified, the document must be a single
[`metadata`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-metadata-elem) or
[`package`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-package-elem) element. A
[`prefix`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-prefix-attr) attribute is
allowed on the root element. The metadata will be injected in the EPUB's package document, possibly
overwriting existing metadata. This works as follows:
- All (valid) fields in the provided metadata document end up in the output EPUB. More than one
field with the same property is allowed. `meta` elements with a `refines` attribute must refine
elements within the metadata document itself. Elements that refine elements in the EPUB's package
document will be dropped.
- Any metadata fields in the input EPUB that have matching fields (same property in case of `meta`
fields, same element name in case of `dc:*` fields) in the provided metadata document are omitted,
together with any `meta` elements that refine them.
- Metadata fields in the input that do not have any matching fields in the provided metadata
document are preserved in the output.
There are a number of fields that result in addional changes in the EPUB (apart from an updated
`metadata` section in the package document):
- If the provided metadata document contains one or more
[`dc:identifier`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dcidentifier)
fields, the first one without a `refines` attribute will be used to update the
[`unique-identifier`](https://www.w3.org/publishing/epub3/epub-packages.html#attrdef-package-unique-identifier)
attribute on the package document. The `dc:identifier` metadata in the content documents can also be
aligned with it. This behavior can be enabled or disabled with the "Update <meta
name='dc:identifier'> elements based on EPUB metadata" option.
- If the provided metadata document contains one or more
[`dc:title`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dctitle) fields, the
first one can also be used as the `title` element in the content documents. This behavior can be
enabled or disabled with the "Update <title> elements based on EPUB metadata" option.
- If the provided metadata document contains exactly one
[`dc:language`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dclanguage) field,
it can be used to update the `xml:lang` and `lang` attributes of the content documents. This
behavior can be enabled or disabled with the "Update 'lang' attributes based on metadata" option.
Some fields are ignored:
- The [`dcterms:modified`](https://www.w3.org/publishing/epub3/epub-packages.html#last-modified-date)
field gets updated whenever Pipeline produces an EPUB. As a consequence, any `dcterms:modified`
fields in the provided metadata document are ignored.
Update 'lang' attributes based on metadata
Whether to update 'lang' and 'xml:lang' attributes of content documents based on metadata in the package document.
If there is exactly one
[`dc:language`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dclanguage) element,
use its value to create `xml:lang` and `lang` attributes on the root elements of all content
documents (overwriting any existing attributes)
If the "Metadata" option is used to inject new metadata into the EPUB, the resulting metadata is
used to generate the attributes.
Update <meta name='dc:identifier'> elements based on EPUB metadata
Whether to update <meta name='dc:identifier'> elements of content documents based on metadata in the package document.
Use the primary identifier (provided by the
[`dc:identifier`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dcidentifier)
element identified by the
[`unique-identifier`](https://www.w3.org/publishing/epub3/epub-packages.html#attrdef-package-unique-identifier)
attribute) to create a `<meta name='dc:identifier'>` element in all content documents
(overwriting any existing elements with the same name).
If the "Metadata" option is used to inject new metadata into the EPUB, the resulting metadata is
used to generate the attributes.
Update <title> elements based on EPUB metadata
Whether to update <title> elements of content documents based on metadata in the package document.
If there is one or more
[`dc:title`](https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf-dctitle) element, use
the value of the first one to create a `<title>` element in all content documents (overwriting
any existing elements with the same name).
If the "Metadata" option is used to inject new metadata into the EPUB, the resulting metadata is
used to generate the attributes.
true
Yes
false
No
hidden
Yes, but not visible
Ensure text content for page numbers
Whether to fix empty page number elements.
Page number elements (elements with a `doc-pagebreak` `role` or `pagebreak` `epub:type`) that have
no child text node can be given one. The text can be generated based on
- the element's `aria-label` attribute,
- the element's `title` attribute, or
- the text used by the corresponding page link in the navigation document.
These options are tried in the listed order. If none of the attributes exist, and the page is linked
from the navigation document, no text is generated.
Ensure headings for all sections
Whether to generate a heading element for sections that don't have one.
For sectioning elements that don't have a heading element, one can be created. The headings are
generated based on the section element's [`aria-label`](https://www.w3.org/TR/wai-aria/#aria-label)
attribute. If the `aria-label` attribute is not present, no heading element is generated. When an
`aria-label` is used to generate a heading, it is replaced with a
[`aria-labelledby`](https://www.w3.org/TR/wai-aria/#aria-labelledby) attribute that points to the
new heading. The rank of the generated heading matches the depth of the corresponding TOC item in
the navigation document.
Translate to braille
Whether to produce a braille rendition.
true
Yes
false
No
default
If publication has no media overlays yet
Perform text-to-speech
Whether to use a speech synthesizer to produce media overlays.
This will remove any existing media overlays in the EPUB.
Perform sentence detection
Whether to add markup (span elements) for sentences.
This setting has no effect when text-to-speech is also enabled. In that case sentences are always
marked up.
Braille translator query
Style sheets
CSS style sheets to apply. A space separated list of URIs, absolute or relative to source.
All CSS style sheets are applied at once, but the order in which they are specified has an influence
on the cascading order.
If the "Apply document-specific CSS" option is enabled, the document-specific style sheets will be
applied before the ones specified through this option (see below).
Apply document-specific CSS
If this option is enabled, any pre-existing CSS in the EPUB for medium "embossed" will be taken into account for the translation, or preserved in the result EPUB.
The HTML files inside the source EPUB may already contain CSS that applies to embossed media. Style
sheets can be associated with an HTML file in several ways: linked (using an 'xml-stylesheet'
processing instruction or a 'link' element), embedded (using a 'style' element) and/or inlined
(using 'style' attributes).
Document-specific CSS takes precedence over any CSS provided through the "Style sheets" option. 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.
Set default rendition to braille.
Make the generated braille rendition the default rendition.
Sentence class
Class attribute to mark sentences with.
When sentence detection is enabled, this option may be used to add a class attribute to the `span`
elements that represent the sentences.
Output EPUB 3
Temporary directory
Directory used for temporary files.
px:epub-load
px:epub3-to-epub3
px:fileset-store
px:fileset-delete