xml.xproc.__processed__dtbook-to-pef.xpl Maven / Gradle / Ivy
DTBook to braille
Transforms a DTBook (DAISY 3 XML) document into an embosser ready braille document.
Online documentation
Authors:
- Name:
- Bert Frees
- E-mail:
- [email protected]
- Organization:
- SBS
- Name:
- Jostein Austvik Jacobsen
- E-mail:
- [email protected]
- Organization:
- NLB
Input DTBook
Style sheets
A list of CSS/Sass style sheets to apply.
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/)).
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](https://www.w3.org/TR/CSS2/cascade.html#cascading-order).
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/dtbook-to-pef/_tables.scss](http://daisy.github.io/pipeline/modules/braille/dtbook-to-pef/src/main/resources/css/tables):
for styling tables
- [http://www.daisy.org/pipeline/modules/braille/dtbook-to-pef/_definition-lists.scss](http://daisy.github.io/pipeline/modules/braille/dtbook-to-pef/src/main/resources/css/definition-lists):
for styling definition lists
Style sheet parameters
A list of parameters passed to the style sheets.
Style sheets, whether they're specified with the "stylesheet" option or 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)`.
Braille code
Braille code to be used for braille transcription.
If set, [braille transcription](http://daisy.github.io/pipeline/Get-Help/User-Guide/Braille/) is
done with the selected braille code. If left empty, the braille code is determined by the document
language and the "Transformer features" option.
Transformer features
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.
Include preview
Whether or not to include a HTML preview of the braille result.
Include PEF
Whether or not to keep the intermediary PEF file (for debugging).
Include OBFL
Whether or not the keep the intermediary OBFL file (for debugging).
Output file format
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.
ASCII braille table for HTML preview
The ASCII braille table used to render the HTML preview.
If left blank, the locale information in the input document will be used to select a suitable table.
Page layout: Page width
The number of columns available for printing.
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:
- 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)
Page layout: Page height
The number of rows available for printing.
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:
- 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)
Page layout: Duplex
When enabled, will print on both sides of the paper.
Headers/footers: Levels in footer
Specify which headings are rendered in the footer.
Makes the variable `$levels-in-footer` available in style sheets and includes the following rule by
default:
~~~sass
@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:
~~~css
@page {
@bottom-center {
content: string(footer);
}
}
~~~
See the CSS specification for more info:
- the [`string-set`](http://braillespecs.github.io/braille-css/#h4_the-string-set-property) property
- the [`@page`](http://braillespecs.github.io/braille-css/#h4_the-page-rule) rule
- the [`string()`](http://braillespecs.github.io/braille-css/#h4_the-string-function) function
Translation/formatting of text: Hyphenation
Hyphenation policy.
Makes the variable `$hyphenation` available in style sheets and includes the following rule by
default:
~~~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
In addition, special rules may apply at page boundaries, see the "Hyphenation at page boundaries"
option.
Translation/formatting of text: Hyphenation at page boundaries
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.
Translation/formatting of text: Line spacing
Single or double line spacing.
Makes the variable `$line-spacing` available in style sheets and includes the following rule by
default:
~~~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
Translation/formatting of text: Capital letters
When enabled, will indicate capital letters.
Makes the variable `$capital-letters` available in style sheets and includes the following rule by
default:
~~~sass
@if $capital-letters != true {
:root {
text-transform: lowercase;
}
}
~~~
Block elements: Include captions
When enabled, will include captions for images, tables, and so on.
Makes the variable `$include-captions` available in style sheets and includes the following rule by
default:
~~~sass
caption {
display: if($include-captions, block, none);
}
~~~
Block elements: Include images
When enabled, will include the alt text of the images. When disabled, the images will be completely removed.
Makes the variable `$include-images` available in style sheets and includes the following rule by
default:
~~~sass
@if $include-images {
img::after {
content: attr(alt);
}
}
~~~
Block elements: Include line groups
When disabled, lines in a linegroup are joined together to form one block.
Makes the variable `$include-line-groups` available in style sheets and includes the following rule
by default:
~~~sass
linegroup line {
display: if($include-line-groups, block, inline);
}
~~~
Inline elements: Include production notes
When enabled, production notes are included in the content.
Makes the variable `$include-production-notes` available in style sheets and includes the following
rule by default:
~~~sass
prodnote {
display: if($include-production-notes, block, none);
}
~~~
Page numbers: Show braille page numbers
When enabled, will number braille pages.
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:
~~~sass
@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:
- the [`@page`](http://braillespecs.github.io/braille-css/#h4_the-page-rule) rule
- the
[`counter()`](http://braillespecs.github.io/braille-css/#printing-counters-the-counter-function)
function
Page numbers: Show print page numbers
When enabled, will indicate original page numbers.
Makes the variable `$show-print-page-numbers` available in style sheets and includes the following
rule by default:
~~~sass
@if $show-print-page-numbers {
pagenum {
string-set: print-page content();
}
}
~~~
In order to use the `print-page` string include a rule like the following in your custom style
sheet:
~~~css
@page {
@bottom-right {
content: string(print-page);
}
}
~~~
See the CSS specification for more info:
- the [`string-set`](http://braillespecs.github.io/braille-css/#h4_the-string-set-property) property
- the [`@page`](http://braillespecs.github.io/braille-css/#h4_the-page-rule) rule
- the [`string()`](http://braillespecs.github.io/braille-css/#h4_the-string-function) function
Page numbers: Force braille page break
Force braille page breaks at print page breaks.
Makes the variable `$force-braille-page-break` available in style sheets and includes the following
rule by default:
~~~sass
@if $force-braille-page-break {
pagenum {
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
Table of contents: Table of contents depth
The depth of the table of contents hierarchy to include. '0' means no table of contents.
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:
~~~xml
<list id="generated-document-toc">
<li>
<a href="#ch_1" title="Chapter 1">Chapter 1</a>
<list>
<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>
...
</list>
</li>
...
</list>
~~~
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:
~~~css
#generated-document-toc {
flow: document-toc;
display: -obfl-toc;
-obfl-toc-range: document;
}
#generated-volume-toc {
flow: volume-toc;
display: -obfl-toc;
-obfl-toc-range: volume;
}
~~~
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:
~~~css
@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:
~~~css
#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 `list` elements invisible:
~~~css
#generated-document-toc > li > list {
display: none;
}
~~~
See the CSS specification for more info:
- the [`display:
-obfl-toc`](http://braillespecs.github.io/braille-css/obfl#extending-the-display-property-with--obfl-toc)
value
- the [`flow`](http://braillespecs.github.io/braille-css/#the-flow-property) property
- the [`flow()`](http://braillespecs.github.io/braille-css/#h4_the-flow-function) function
- the [`@volume`](http://braillespecs.github.io/braille-css/#h3_the-volume-rule) rule
- the [`@begin`](http://braillespecs.github.io/braille-css/#h3_the-begin-and-end-rules) rule
- the [`target-counter()`](http://braillespecs.github.io/braille-css/#h4_the-target-counter-function) function
- the [`page`](http://braillespecs.github.io/braille-css/#h4_creating-and-inheriting-counters) counter
Table of contents: Exclude headings
Class name for excluding headings from the table of contents.
If specified, heading elements with this class name are excluded from the generated tables of contents.
Volumes: Maximum number of sheets
The maximum number of sheets in a volume.
Makes the variable `$maximum-number-of-sheets` available in style sheets and includes the following
rule by default:
~~~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
Volumes: Allow breaks within sections.
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 or after elements `level1` to `level6`. The higher the value, the more equal the volumes
will be in size.
Volumes: Prefer breaks at higher level sections.
Amount with which preference is given to volume breaks before higher level sections.
`level1` is the highest level. 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.
Placement of content: Notes placement
Placement of notes
Notes, i.e. `note` elements that are referenced by a `noteref` element, can be rendered either at
the 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. `note`
elements that are not referenced by a `noteref` are not rendered.
Note references can be styled using a `noteref` rule. Notes that are placed at the end of the block
can be styled with a `note` 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 `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;
}
~~~
Output file
The output braille file.
PEF
The intermediary PEF file.
Preview
An HTML preview of the braille result.
OBFL
The intermediary OBFL file.
px:dtbook-to-pef
px:dtbook-to-pef.store
px:delete-parameters
px:parse-query
px:dtbook-load