DTBook to PEF

Inputs

• Input DTBook
  Media-type:

  • application/x-dtbook+xml
  Sequence: no

Outputs

• Output file
  The output braille file.
  Media-type:

  • text
• Preview
  An HTML preview of the braille result.
  Media-type:

  • text/html
• OBFL
  The intermediary OBFL file.
  Media-type:

  • application/x-obfl+xml
• PEF
  The intermediary PEF file.
  Media-type:

  • application/x-pef+xml

Options

• Braille code
  Braille code to be used for braille transcription.

  Braille code to be used for braille transcription.

  If set, braille transcription is done with the selected braille code. If left empty, the braille code is determined by the document language and the “Transformer features” option.

  Possible values: <liblouis-table-query>
  Default value:
• Include production notes
  When enabled, production notes are included in the content.

  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:

  prodnote {
    display: if($include-production-notes, block, none);
  }
  

  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: 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:
• Include images
  When enabled, will include the alt text of the images. When disabled, the images will be completely removed.

  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:

  @if $include-images {
    img::after {
      content: attr(alt);
    }
  }
  

  Possible values: true or false
  Default value: true
• Include PEF
  Whether or not to keep the intermediary PEF file (for debugging).
  Possible values: true or false
  Default value: false
• Line spacing
  Single or double line spacing.

  Single or double line spacing.

  Makes the variable $line-spacing available in style sheets and includes the following rule by default:

  @if $line-spacing == double {
    :root {
      line-height: 2;
    }
  }
  

  See the CSS specification for more info:

  • the line-height property
  Possible values: One of the following:

  single

  Single

  double

  Double

  Default value: single
• Force braille page break
  Force braille page breaks at print page breaks.

  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:

  @if $force-braille-page-break {
    pagenum {
      page-break-before: always;
    }
  }
  

  See the CSS specification for more info:

  • the page-break-before property
  Possible values: true or false
  Default value: false
• 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), 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 rule
  • the size property
  • the page dimensions media features
  Possible values: Any <integer>
  Default value: 40
• Show print page numbers
  When enabled, will indicate original 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:

  @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:

  @page {
    @bottom-right {
      content: string(print-page);
    }
  }
  

  See the CSS specification for more info:

  • the string-set property
  • the @page rule
  • the string() function
  Possible values: true or false
  Default value: true
• Levels in footer
  Specify which headings are rendered in the 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:

  @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:

  @page {
    @bottom-center {
      content: string(footer);
    }
  }
  

  See the CSS specification for more info:

  • the string-set property
  • the @page rule
  • the string() function
  Possible values: Any <integer>
  Default value: 0
• Prefer breaks at higher level sections.
  Amount with which preference is given to volume breaks before 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.

  Possible values: Any <string>
  Default value: 0
• Style sheets
  A list of CSS/Sass style sheets to take into account.

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

  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. Author styles take precedence over user styles.

  CSS/Sass 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/dtbook-to-pef/_tables.scss: for styling tables
  • http://www.daisy.org/pipeline/modules/braille/dtbook-to-pef/_definition-lists.scss: for styling definition lists
  Possible values: <anyURI>
  Default value:
• Include captions
  When enabled, will include captions for images, tables, and so on.

  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:

  caption {
    display: if($include-captions, block, none);
  }
  

  Possible values: true or false
  Default value: true
• Capital letters
  When enabled, will indicate capital letters.

  When enabled, will indicate capital letters.

  Makes the variable $capital-letters available in style sheets and includes the following rule by default:

  @if $capital-letters != true {
    :root {
      text-transform: lowercase;
    }
  }
  

  Possible values: true or false
  Default value: true
• Maximum number of sheets
  The maximum number of sheets in a volume.

  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:

  @volume {
    max-length: $maximum-number-of-sheets;
  }
  

  See the CSS specification for more info:

  • the @volume rule
  • the max-length property
  Possible values: Any <integer>
  Default value: 70
• Table of contents depth
  The depth of the table of contents hierarchy to include. '0' means no table of contents.

  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:

  <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:

  #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:

  @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:

  #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:

  #generated-document-toc > li > list {
    display: none;
  }
  

  See the CSS specification for more info:

  • the display: -obfl-toc value
  • the flow property
  • the flow() function
  • the @volume rule
  • the @begin rule
  • the target-counter() function
  • the page counter
  Possible values: <nonNegativeInteger>
  Default value: 0
• Include OBFL
  Whether or not the keep the intermediary OBFL file (for debugging).
  Possible values: true or false
  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 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”:

  @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: 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:
• 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:
• 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)
• 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), 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 rule
  • the size property
  • the page dimensions media features
  Possible values: Any <integer>
  Default value: 25
• Hyphenation
  Hyphenation policy.

  Hyphenation policy.

  Makes the variable $hyphenation available in style sheets and includes the following rule by default:

  :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 property

  In addition, special rules may apply at page boundaries, see the “Hyphenation at page boundaries” option.

  Possible values: One of the following:

  auto

  Hyphenate words

  manual

  Only hyphenate words where there are soft hyphens (U+00AD)

  none

  Never hyphenate words

  Default value: auto
• Notes placement
  Placement of notes

  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:

  .endnotes-section::-obfl-on-collection-start {
     content: "Notes in this volume";
     text-align: center;
     margin-bottom: 1;
  }
  

  Possible values: One of the following:

  bottom-of-page

  At the bottom of the page

  Notes are rendered in the @footnotes 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:

  @page {
     @footnotes {
        border-top: ⠤;
        max-height: 20;
     }
  }
  

  end-of-block

  At the end of the block

  Notes are rendered after the block (e.g. paragraph) in which they occur.

  end-of-chapter

  At the end of the chapter

  Notes are rendered at the end of the chapter (level1, level2, level3, level4, level5, level6,) in which they occur.

  end-of-volume

  At the end of the volume

  Notes are rendered in the @end area of the volume in which they occur.

  end-of-book

  At the end of the book

  Notes are rendered in the @end area of the last volume.

  Notes can be grouped by volume using a .endnotes-section::-obfl-on-volume-start rule. Example:

  .endnotes-section::-obfl-on-volume-start {
     content: "Notes in volume " -obfl-evaluate("$started-volume-number");
     margin: 1 0;
  }
  

  custom

  Custom handling

  Special handling of notes is disabled. Notes are rendered as specified in custom style sheets.

  Default value: end-of-book
• 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
• Include line groups
  When disabled, lines in a linegroup are joined together to form one block.

  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:

  linegroup line {
    display: if($include-line-groups, block, inline);
  }
  

  Possible values: true or false
  Default value: true
• Duplex
  When enabled, will print on both sides of the paper.
  Possible values: true or false
  Default value: true
• Show braille page numbers
  When enabled, will number braille pages.

  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:

  @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 rule
  • the counter() function
  Possible values: true or false
  Default value: true
• Exclude headings
  Class name for excluding headings from the table of contents.

  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.

  Possible values: Any <string>
  Default value:
• Allow breaks within sections.
  Amount with which volume breaks are allowed 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.

  Possible values: Any <integer>
  Default value: 10