[daisy-pipeline.wiki] push by bertfrees - Update zedai-to-pef documentation to next version (1.10)... on 2015-03-20 18:44 GMT
0 views
Skip to first unread message
daisy-p...@googlecode.com
Mar 20, 2015, 2:44:39 PM3/20/15
to daisy-pipel...@googlegroups.com
Revision: 96da38472265
Branch: default
Author: Bert Frees <bert...@gmail.com>
Date: Fri Mar 20 18:43:15 2015 UTC
Log: Update zedai-to-pef documentation to next version (1.10)
also removed the section "Extending the script" as it doesn't really belong
to user documentation
https://code.google.com/p/daisy-pipeline/source/detail?r=96da38472265&repo=wiki
Deleted:
/ZedAIToPEFInstallation.wiki
/ZedAIToPEFUsage.wiki
Modified:
/ZedAIToPEFDoc.wiki
=======================================
--- /ZedAIToPEFInstallation.wiki Thu Sep 6 13:59:57 2012 UTC
+++ /dev/null
@@ -1,34 +0,0 @@
-#summary Instructions on how to install the ZedAI to PEF script.
-#labels Phase-Deploy
-#sidebar UserGuideToc
-
-= ZedAI to PEF Installation Instructions =
-
-The ZedAI script is not included in the default DAISY Pipeline
distribution. Some additional steps are required to install the script.
-
-== Prerequisites ==
-
- * Obviously, you need to [Installation install the Pipeline 2] first.
- * You need to know [CommandLine how to use the command line tool].
- * If you prefer a graphical interface over the command line, find out
[WebUI how to install the web UI].
-
-== Automated Installation ==
-
-An installer that automatically installs the required files into the right
folders, is available from the
[https://code.google.com/p/daisy-pipeline/downloads/list downloads page].
The installer is an executable JAR file that you can run by double-clicking
it or by using the `java -jar` command. In the first step, you are asked to
select the installation path. Choose the same directory where you installed
the DAISY Pipeline. You will get a warning: "The directory already exists!
Are you sure you want to install here and possibly overwrite existing
files?". Ignore this. In the next step you'll get an overview of the
packages that will be installed. Press "Next" a few times and then "Done"
to finish the installation.
-
-== Manual Installation ==
-
-The Braille components are also packaged in a ZIP archive. The ZIP
contains two folders:
-
- * `modules`
- * `system/framework`
-
-Copy the contents of these folders into the corresponding folders of your
DAISY Pipeline installation. The `modules` folder contains multiple
versions of `liblouis-native.jar`, one for each operating system. Copy only
the version that applies to you.
-
-== Note when running on OS X ==
-
-When running the zedai-to-pef script on OS X, you may notice that the
Pipeline daemon process starts appearing as a regular application with the
default Java icon appearing on the Dock. To remove this behavior, you can
add the following line to the `etc/system.properties` file in your Pipeline
installation directory:
-
-{{{java.awt.headless=true}}}
-
-Next: [ZedAIToPEFUsage Using the ZedAI to PEF script]
=======================================
--- /ZedAIToPEFUsage.wiki Thu Oct 2 13:56:28 2014 UTC
+++ /dev/null
@@ -1,430 +0,0 @@
-#summary A guide on how to use the ZedAI to PEF script.
-#labels Phase-Support
-#sidebar UserGuideToc
-
-= ZedAI to PEF User Guide =
-
-<wiki:toc/>
-
-== Synopsis ==
-
-=== Input ===
-
-|| *name* || *description* ||
-|| source || A valid ZedAI document. ||
-
-=== Options ===
-
-|| *name* ||
*default* || *description* ||
-|| include-preview (optional) ||
`false` || Whether or not to include a preview of
the PEF in HTML (true or false). ||
-|| include-brf (optional) ||
`false` || Whether or not to include an ASCII
version of the PEF (true or false). ||
-|| output-dir (required in local mode only) |
| || Directory for storing result files. ||
-|| temp-dir (optional) |
| || Directory for storing temporary
files. ||
-|| default-stylesheet (optional) ||
`default.css` || The default CSS stylesheet to apply. ||
-|| translator (optional, advanced) ||
`generic-liblouis-translate.xsl` || The translator(s) (XSLT/XProc step or
liblouis/libhyphen table) to be used. Can be a comma separated list. ||
-
-
-== Example running from command line ==
-
-{{{
-$ ./dp2 zedai-to-pef \
- --i-source samples/zedai/alice.xml \
- --x-include-preview true \
- --x-include-brf true \
- --x-output-dir ~/Desktop/out
-}}}
-
-output:
-
-{{{
-$ ls ~/Desktop/out
-alice.pef
-alice.pef.html
-alice.brf
-}}}
-
-More advanded example:
-
-{{{
-$ ./dp2 zedai-to-pef \
- --i-source samples/zedai/alice.xml \
- --x-include-preview true \
- --x-translator hyph_en_US.dic,unicode.dis,en-us-g1.ctb \
- --x-default-stylesheet bana.css \
- --x-output-dir ~/Desktop/out
-}}}
-
-== Getting a preview ==
-
-To emboss a PEF file or display it on screen you need special software
(such as the [http://code.google.com/p/e2u/ Easy Embosser Utility]
developed at TPB). Opening a PEF with an XML editor is not very useful
because you only get to see Unicode braille (dot patterns). If you don't
have access to a special PEF tool, or you just want to quickly review the
document first, you should set the `include-preview` option to `true`. In
addition to the actual PEF file, an HTML page will then be generated that
you can open in your browser. You will be able to quickly navigate pages,
and switch between a 'dot patterns' view and a more readable ASCII view. To
properly render this HTML page, you need the
[http://sourceforge.net/projects/odt2braille/files/ttf/odt2braille-6dot-v1.1.ttf
odt2braille font].
-
-== Advanced Configuration ==
-
-=== Translation ===
-
-By default, text is translated to braille with a simple generic
[http://code.google.com/p/liblouis/ liblouis] based translator. All the
translation tables distributed by liblouis (about 80 languages) are
included in the DAISY Pipeline as well. The translator will automatically
look for the table that matches the `xml:lang` attribute best. If you need
more control over the translation, you can specify an alternative
translator or a list of translators with the `translator` option. For
example:
-
-{{{
---x-translator generic-liblouis-translate-with-emphasis.xsl
-}}}
-
-looks for emphasised text and tries to mark it up in braille (through
liblouis). Or, you might want to select a specific liblouis table, for
example US English Grade 1:
-
-{{{
---x-translator unicode.dis,en-us-g1.ctb
-}}}
-
-Or, if you are running Pipeline 2 in local mode, and you have your own
liblouis tables installed somewhere, you can use them by specifying the
full path:
-
-{{{
---x-translator file:/home/me/liblouis-tables/unicode.dis,my_en-us.ctb
-}}}
-
-Liblouis is the main translation engine used in DAISY Pipeline 2, but no
one stops you from using another library. The following translator is
backed by [https://code.google.com/p/dotify/ Dotify], a braille translation
library developed at TPB:
-
-{{{
---x-translator generic-dotify-translate.xsl
-}}}
-
-More examples are provided below (see [ZedAIToPEFUsage#Hyphenation
Hyphenation] and [ZedAIToPEFUsage#Math Math]). If your use case requires
non-trivial features and the supplied generic translators won't do, you can
write your own translator, which might be a combination of existing and new
components. Read [ZedAIToPEFUsage#Extending_the_Script Extending the
Script] for more details. If you have idea's about features that should be
supported by default, please share them with us.
-
-
-=== Hyphenation ===
-
-To enable hyphenation, a translator step needs to be inserted _before_ the
actual braille translation. [http://hunspell.sourceforge.net/ Hyphen], the
main hyphenation engine used in [http://www.openoffice.org/ OpenOffice] and
[http://www.libreoffice.org/ LibreOffice], is also the main hyphenator in
DAISY Pipeline 2:
-
-{{{
---x-translator
generic-libhyphen-hyphenate.xsl,generic-liblouis-translate.xsl
-}}}
-
-This translator will find the right hyphenation dictionary based on the
`xml:lang` attribute. As with liblouis, you can also select a specific
Hyphen dictionary:
-
-{{{
---x-translator hyph_en_US.dic,generic-liblouis-translate.xsl
-}}}
-
-Windows users should use the TeX implementation (until a certain issue is
fixed):
-
-{{{
---x-translator generic-tex-hyphenate.xsl,generic-liblouis-translate.xsl
-}}}
-
-
-=== Math ===
-
-Liblouis is capable of translating math as [http://www.w3.org/Math/
MathML] to braille. The supported braille math codes are _Nemeth_ (used in
the US), _Marburg_ (Germany), _Woluwe_ (Belgium) and _UKMaths_ (Great
Britain). To enable math translation, insert the following step:
-
-{{{
---x-translator
generic-liblouis-translate-mathml.xpl,generic-liblouis-translate.xsl
-}}}
-
-
-=== Styling with Braille CSS ===
-
-The formatting of documents into a paged braille layout is done entirely
based on CSS (Cascading Style Sheets). We use a flavor of CSS specially
designed for this use case. For people that already know CSS, it will feel
very natural. In fact, it is almost a subset of CSS3, but with some
restrictions and a few braille specific features. The most obvious
difference is that margins are expressed in units of cell width and line
height instead of pixels, ems and percentages. A complete overview of
braille CSS can be found on [http://snaekobbi.github.io/braille-css-spec
this page].
-
-The actual formatting of documents based on CSS is done with
[http://code.google.com/p/liblouisutdml/ liblouisutdml] under the hood. In
the future other implementations may be added. Note that, when the
_formatting_ begins, the braille _translation_ has already been performed.
Translation and formatting are completely separated steps, and their
implementations can be changed independently.
-
-Attaching style information to a document can be done either by linking to
an external CSS stylesheet, by including an internal stylesheet, by
inserting inline styles, or a hibrid of these three.
-
-1. External stylesheet:
-
-{{{
-<document>
- <head>
- <link rel="stylesheet" media="embossed" type="text/css"
href="external_stylesheet.css" />
- ...
-}}}
-
-2. Internal stylesheet:
-
-{{{
-<document>
- <head>
- <style media="embossed" type="text/css">
- head {
- display: none;
- }
- h {
- display: block;
- text-align: center;
- }
- ...
- </style>
- ...
-}}}
-
-3. Inline styles:
-
-{{{
-<document>
- <head style="display:none">
- ...
- </head>
- <body>
- <frontmatter>
- <section>
- <h style="display:block;text-align:center">...</h>
- ...
-}}}
-
-Keep in mind that a simple default stylesheet (`default.css`) is always
applied first. If you don't want this default CSS, include `reset.css` in
your stylesheet:
-
-{{{
-@import
url('http://www.daisy.org/pipeline/modules/braille/zedai-to-pef/css/reset.css');
-}}}
-
-To change which default CSS is applied, use the `default-stylesheet`
option as in the [ZedAIToPEFUsage#Example_running_from_command_line
advanced example] above. Valid choices are
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/bana.css
bana.css] and
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/ueb.css
ueb.css]. This is not meant to be a complete list, the idea is to
eventually have stylesheets for each braille formatting standard. In fact,
`bana.css` and `ueb.css` are currently only stubs, we are hoping for
contributions from people who are more familiar with these standards.
-
-==== Example 1: Sections and headings ====
-
-{{{
-section {
- display: block;
- page-break-before: always;
-}
-}}}
-
-By putting this code in your stylesheet, each section will be guaranteed
to start on a new braille page.
-
-{{{
-h {
- display:block;
- text-align:center;
- margin-top: 1;
- margin-bottom: 1;
- margin-left: 4;
- margin-right: 4;
- page-break-after: avoid;
-}
-h + * {
- orphans: 2;
-}
-}}}
-
-Headings are centered on the page, with at least one line left blank both
above and below. The left and right margins are increased enough so that
long headings can not be confused with normal paragraphs. To make sure
headings are not rendered at the bottom of a page, no page breaks are
allowed right after a heading, and any element immediately following a
heading must have at least two lines (orphans) on the current page.
-
-
-==== Example 2: Ordered and unordered lists ====
-
-{{{
-list {
- display: block;
-}
-list > item {
- display: list-item;
-}
-list[type="unordered"] {
- list-style-type: ⠶;
-}
-list[type="ordered"].decimal {
- list-style-type: decimal;
-}
-list[type="ordered"].alpha {
- list-style-type: lower-alpha;
-}
-list[type="ordered"].roman {
- list-style-type: lower-roman;
-}
-}}}
-
-This will format lists of type "unordered" as bulleted lists, with each
item preceded by the braille character (bullet) '⠶'. Lists of
type "ordered" will be numbered: "1. 2. 3. ..." for class "decimal", "a. b.
c. ..." for class "alpha" and "i. ii. iii. ..." for class "roman".
-
-
-==== Example 3: Tables in linear vs. stairstep format ====
-
-{{{
-table {
- display: block;
- border-top: ⠶;
- border-bottom: ⠛;
-}
-thead {
- display: block;
- border-bottom: ⠒;
-}
-tr {
- display: block;
- page-break-inside: avoid;
-}
-}}}
-
-This code will give tables an upper and lower border (lines of
characters '⠶' and '⠛' respectively). If there is a table header, a '⠒'
border is printed between the header and the body. Table rows are protected
from being split across braille pages.
-
-{{{
-.linear th::after,
-.linear td::after {
- content: "⠰ "
-}
-}}}
-
-Tables of class "linear" (`<table class="linear">`) will have table cells
separated by the character '⠰' and a space.
-
-{{{
-table.stairstep td,
-table.stairstep th {
- display: block;
-}
-table.stairstep th:first-child,
-table.stairstep td:first-child {
- margin-left: 0;
-}
-table.stairstep th:nth-child(2),
-table.stairstep td:nth-child(2) {
- margin-left: 3;
-}
-table.stairstep th:nth-child(3),
-table.stairstep td:nth-child(3) {
- margin-left: 6;
-}
-...
-}}}
-
-In tables of class "stairstep" (`<table class="stairstep">`), each table
cell will start on a new line, with a left margin that is the same for
cells in the same column.
-
-
-==== Example 4: Print page numbers ====
-
-{{{
-pagebreak {
- display: none;
- string-set: print-page attr(value);
-}
-}}}
-
-This snippet will update the print page number whenever a `<pagebreak
value="..."/>` is encountered. In order to render print page numbers, the
`@page` rule must be used (see [ZedAIToPEFUsage#Example_6:_Page_layout
example 6] below).
-
-When `display:none` is changed to `display:page-break`, a _page break
indicator_ (a line of braille dots '36') is generated wherever a print page
break occurs:
-
-{{{
-pagebreak {
- display: page-break;
- string-set: print-page attr(value);
-}
-}}}
-
-Note that in the current implementation, `display:page-break` only works
in combination with `string-set:print-page`, and won't have any effect
unless it is used for *all* print pages.
-
-==== Example 5: Table of contents ====
-
-{{{
-<toc>
- <h>Contents</h>
- <entry><ref ref="chapter_1">I. Down the Rabbit-Hole</ref></entry>
- <entry><ref ref="chapter_2">II. The Pool of Tears</ref></entry>
- <entry><ref ref="chapter_3">III. A Caucus-Race and a Long
Tale</ref></entry>
-</toc>
-...
- <h xml:id="chapter_1">Chapter I. Down the Rabbit-Hole</h>
-...
-}}}
-
-A table of contents can be rendered in a typical layout with page numbers
on the right and leaders between entries and page numbers. A precondition
is that headings in the text are referenced within the table of contents
(e.g. with an attribute). If print page numbers and/or braille page numbers
are present in the braille output, they can be included in the table of
contents too. The pattern of leaders can be configured. Let's look at the
CSS:
-
-{{{
-toc > h {
- display: block;
- text-align: center;
- margin-top: 1;
- margin-bottom: 1;
-}
-toc > entry > ref {
- display: block;
- margin-left: 2;
- text-indent: -2;
- content: target-text(attr(ref))
- leader('⠤')
- target-string(attr(ref), print-page)
- target-counter(attr(ref), braille-page)
-}
-}}}
-
-With the `content` property we are dropping the original text of the
_referencing_ elements and copying the text of the _referenced_ elements.
-
-The use is not limited to tables of contents; any kind of list that
references page numbers is a candidate. Think of indices, lists of figures,
list of tables, etc.
-
-
-==== Example 6: Page layout ====
-
-The dimensions of the page, the position of page numbers, and the running
header and/or footer (see [ZedAIToPEFUsage#Example_7:_Running_header/footer
example 7]), can be configured with the `@page` rule:
-
-{{{
-@page {
- size: 40 25;
- @top-right {
- content: string(print-page);
- }
- @bottom-right {
- content: counter(braille-page);
- }
- @bottom-center {
- content: string(running-footer);
- }
-}
-}}}
-
-The only valid positions for page numbers are currently `@top-right` and
`@bottom-right`. It is also possible to put both page numbers at the top or
at the bottom, like this: `@top-right{content:string(print-page)
counter(braille-page);}`
-
-As showed in the next example, pages can be named. This can be useful to
switch page layout in the middle of a document. The following example will
start a new page with double width for each wide table, so that it can be
printed across facing pages.
-
-{{{
-@page double {
- size: 80 25;
-}
-
-table.wide {
- page: double;
-}
-}}}
-
-
-==== Example 7: Running header/footer ====
-
-As seen in [ZedAIToPEFUsage#Example_6:_Page_layout example 6] above, pages
can have running headers and/or footers. To update the value of the footer
whenever a new heading appears, include the following:
-
-{{{
-h {
- string-set: running-footer content();
-}
-}}}
-
-
-==== Example 8: Braille page numbers ====
-
-CSS also has some tools to customized the braille page numbering. For
example, to distinguished the frontmatter from the bodymatter, they often
have different page numbering formats. This snippet gives the frontmatter
lowercase Roman page numbers, and restarts the numbering after the
frontmatter:
-
-{{{
-@page front {
- @bottom-right {
- content: counter(braille-page, lower-roman);
- }
-}
-
-frontmatter {
- page: front;
-}
-
-bodymatter {
- counter-reset: braille-page 1;
-}
-}}}
-
-
-=== Extending the Script ===
-
-The simple generic liblouis based translator that is used by default is
not very likely to fit everyone's needs. Braille translation requirements
are very specific and diverse. This is the main reason why we need such a
modular and extensible design. Custom translators, which are either XSLT or
XProc steps, liblouis tables or libhyphen dictionaries, can be 'plugged in'
using the XML Catalog mechanism. Basically this means you write an XSLT or
XProc step or a liblouis table, map it to a URL, and provide this URL (or a
list of URLs) to the script with the `translator` option (more details
below).
-
-An example of a custom translator can be found
[https://github.com/sbsdev/sbs-pipeline/blob/master/dtbook-to-pef/src/main/resources/xml/xslt/zedai-translator.xsl
here].
-
-Translation can happen on the 'document level' or on the 'block level'.
Performing block-level translation greatly simplifies the contract for a
translator and supports the idea of separating formatting and translation.
You can create a block-level translator by extending
`block-translator-template.xsl`. (Definition: a CSS block is defined as the
largest group of adjacent text nodes and inline elements, i.e. elements
with "display:inline", that only have other text nodes and inline elements
as their descendants.)
-
-The next sections explain a bit more in detail how to create custom
translators.
-
-
-=== Custom liblouis tables ===
-
-*_TBD_*
-
-=== Custom translators ===
-
-*_TBD_*
=======================================
--- /ZedAIToPEFDoc.wiki Wed Nov 28 11:08:23 2012 UTC
+++ /ZedAIToPEFDoc.wiki Fri Mar 20 18:43:15 2015 UTC
@@ -2,17 +2,403 @@
#labels Type-Doc,Compoment-UserGuide,Component-Module,Component-Script
#sidebar UserGuideToc
-= ZedAI to PEF =
+The "ZedAI to PEF" script will convert a ZedAI document (NISO Z39.98-2012
- Authoring and Interchange Framework for Adaptive XML Publishing) into a
PEF (Portable Embosser Format) file. PEF is a format for representing paged
braille documents in an unambiguous way. It builds on XML, Unicode and
Dublin Core. Tools are available for embossing PEF files or converting them
into other braille formats. See also [http://pef-format.org/ the PEF Format
website].
-The "ZedAI to PEF" script will convert a ZedAI document (NISO Z39.98-2012
- Authoring and Interchange Framework for Adaptive XML Publishing) into a
PEF (Portable Embosser Format) file. PEF is a format for representing paged
Braille documents in an unambiguous way. It builds on XML, Unicode and
Dublin Core. Tools are available for embossing PEF files or converting them
into other Braille formats. See also [http://pef-format.org/ the PEF Format
website].
+<wiki:toc/>
-== [ZedAIToPEFInstallation Installation] ==
+== Synopsis ==
-This script is not included in the default DAISY Pipeline distribution.
Some additional steps are required to install the script.
+=== Input ===
+|| *name* || *description* ||
+|| source || A valid ZedAI document. ||
-== [ZedAIToPEFUsage User Guide] ==
+=== Options ===
-This page gives you and overview of the basic functionality and explains
how you can extend the script to fit your needs.
+|| *name* ||
*default* || *description* ||
+|| include-preview (optional) ||
`false` || Whether or not to include a
preview of the PEF in HTML (true or false). ||
+|| include-brf (optional) ||
`false` || Whether or not to include an
ASCII version of the PEF (true or false). ||
+|| default-stylesheet (optional) ||
`default.css` || The default CSS stylesheet
to apply. ||
+|| transform (optional, advanced) ||
`(formatter:liblouis)(translator:liblouis)` || A transformer query. ||
+== Example running from command line ==
+{{{
+$ ./dp2 zedai-to-pef \
+ --i-source samples/zedai/alice.xml \
+ --x-include-preview true \
+ --x-include-brf true \
+ --x-output ~/Desktop/out
+}}}
+
+output:
+
+{{{
+$ ls ~/Desktop/out
+alice.pef
+alice.pef.html
+alice.brf
+}}}
+
+More advanded example:
+
+{{{
+$ ./dp2 zedai-to-pef \
+ --i-source samples/zedai/alice.xml \
+ --x-include-preview true \
+ --x-default-stylesheet bana.css \
+ --x-transform "(formatter:dotify)" \
+ --x-output ~/Desktop/out
+}}}
+
+== Getting a preview ==
+
+To emboss a PEF file or display it on screen you need special software
(such as the [http://code.google.com/p/e2u/ Easy Embosser Utility]
developed at TPB). Opening a PEF with an XML editor is not very useful
because you only get to see Unicode braille (dot patterns). If you don't
have access to a special PEF tool, or you just want to quickly review the
document first, you should set the `include-preview` option to `true`. In
addition to the actual PEF file, an HTML page will then be generated that
you can open in your browser. You will be able to quickly navigate pages,
and switch between a 'dot patterns' view and a more readable ASCII view. To
properly render this HTML page, you need the
[http://sourceforge.net/projects/odt2braille/files/ttf/odt2braille-6dot-v1.1.ttf
odt2braille font].
+
+== Advanced Configuration ==
+
+=== Translation ===
+
+By default, text is translated to braille with a simple generic
[http://code.google.com/p/liblouis/ liblouis] based translator. All the
translation tables distributed by liblouis (about 80 languages) are
included in the DAISY Pipeline. The translator will automatically look for
the table that matches the `xml:lang` attribute best. The `transform`
option gives you more control over translator selection. For example:
+
+{{{
+--x-transform "(locale:fr)"
+}}}
+
+will force the document to be translated to French braille. Or, you might
want to select a specific liblouis table, for example US English Grade 1:
+
+{{{
+--x-transform "(liblouis-table:'en-us-g1.ctb')"
+}}}
+
+If you are running DAISY Pipeline 2 in local mode, and you have your own
liblouis tables installed somewhere, you can use them by specifying the
full path:
+
+{{{
+--x-transform "(liblouis-table:'file:/home/me/liblouis-tables/my_en-us.ctb')"
+}}}
+
+Liblouis is the main translation engine used in DAISY Pipeline 2, but
other libraries are available. The following translator is backed by
[https://code.google.com/p/dotify/ Dotify], the braille translation library
developed at MTM:
+
+{{{
+--x-transform "(translator:dotify)"
+}}}
+
+More examples are provided below. If your use case requires non-trivial
features and the supplied generic translators won't do, you can write your
own translator, which might be a combination of existing and new
components. If you have idea's about features that should be supported by
default, please share them with us.
+
+
+=== Hyphenation ===
+
+The default transformer automatically hyphenates text with CSS property
“`hyphens:auto`” (see [ZedAIToPEFDoc#Styling_with_Braille_CSS Styling with
Braille CSS] below). A hyphenator will be selected based on the `xml:lang`
attribute. If liblouis isn't able to hyphenate the text itself, then
[http://hunspell.sourceforge.net/ Hyphen], the hyphenation engine from
[http://www.openoffice.org/ OpenOffice] and [http://www.libreoffice.org/
LibreOffice], is used. To force the use of Hyphen, specify:
+
+{{{
+--x-transform "(hyphenator:hyphen)"
+}}}
+
+and to select a specific Hyphen table, specify:
+
+{{{
+--x-transform "(libhyphen-table:'hyph_en_US.dic')"
+}}}
+
+
+=== Text Emphasis ===
+
+In case the input document has styling attached for media 'print', the
default translator uses this information to mark emphasised text
(`font-style`, `font-weight`, etc.) with braille indicators.
+
+
+=== Math ===
+
+Translation of [http://www.w3.org/Math/ MathML] is supported by default.
The supported braille math codes are _Nemeth_ (used in the US), _Marburg_
(Germany), _Woluwe_ (Belgium) and _UKMaths_ (Great Britain). The right
translator is selected based on the `xml:lang` attribute.
+
+
+=== Styling with Braille CSS ===
+
+The formatting of documents into a paged braille layout is specified with
CSS (Cascading Style Sheets). We use a flavor of CSS specially designed for
this use case. For people that already know CSS, it will feel very natural.
In fact, it is almost a subset of CSS3, but with certain restrictions and
some braille specific features. The most obvious difference is that margins
are expressed in units of cell width and line height instead of pixels, ems
and percentages. Extensive documentation of braille CSS can be found in
[http://snaekobbi.github.io/braille-css-spec the Braille CSS specification
draft].
+
+In addition to braille CSS, which is normative, certain parts of 'print'
CSS can be taken into account as well. An example is
[ZedAIToPEFDoc#Text_Emphasis text emphasis]. (See also
[http://snaekobbi.github.io/braille-css-spec/#h2_media-types Braille CSS -
Media Types].)
+
+The actual rendering of documents based on CSS is done with
[http://code.google.com/p/liblouisutdml/ liblouisutdml] under the hood. A
second implementation is based on Dotify (experimental). Note that, when
the _formatting_ begins, the braille _translation_ has already been
performed. Translation and formatting are completely separated steps, and
their implementations can be changed independently.
+
+Attaching style information to a document can be done either by linking to
an external CSS stylesheet, by including an internal stylesheet, by
inserting inline styles, or a hibrid of these three.
+
+1. External stylesheet:
+
+{{{
+<document>
+ <head>
+ <link rel="stylesheet" media="embossed" type="text/css"
href="external_stylesheet.css" />
+ ...
+}}}
+
+2. Internal stylesheet:
+
+{{{
+<document>
+ <head>
+ <style media="embossed" type="text/css">
+ head {
+ display: none;
+ }
+ h {
+ display: block;
+ text-align: center;
+ }
+ ...
+ </style>
+ ...
+}}}
+
+3. Inline styles:
+
+{{{
+<document>
+ <head style="display:none">
+ ...
+ </head>
+ <body>
+ <frontmatter>
+ <section>
+ <h style="display:block;text-align:center">...</h>
+ ...
+}}}
+
+Keep in mind that a simple default stylesheet (`default.css`) is always
applied first. If you don't want this default CSS, include `reset.css` in
your stylesheet:
+
+{{{
+@import
url('http://www.daisy.org/pipeline/modules/braille/zedai-to-pef/css/reset.css');
+}}}
+
+To change which default CSS is applied, use the `default-stylesheet`
option as in the [ZedAIToPEFDoc#Example_running_from_command_line advanced
example] above. Valid choices are
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/bana.css
bana.css] and
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/ueb.css
ueb.css]. This is not meant to be a complete list, the idea is to
eventually have stylesheets for each braille formatting standard. In fact,
`bana.css` and `ueb.css` are currently only stubs, we are hoping for
contributions from people who are more familiar with these standards.
+
+==== Example 1: Sections and headings ====
+
+{{{
+section {
+ display: block;
+ page-break-before: always;
+}
+}}}
+
+By putting this code in your stylesheet, each section will be guaranteed
to start on a new braille page.
+
+{{{
+h {
+ display:block;
+ text-align:center;
+ margin-top: 1;
+ margin-bottom: 1;
+ margin-left: 4;
+ margin-right: 4;
+ page-break-after: avoid;
+}
+h + * {
+ orphans: 2;
+}
+}}}
+
+Headings are centered on the page, with at least one line left blank both
above and below. The left and right margins are increased enough so that
long headings can not be confused with normal paragraphs. To make sure
headings are not rendered at the bottom of a page, no page breaks are
allowed right after a heading, and any element immediately following a
heading must have at least two lines (orphans) on the current page.
+
+
+==== Example 2: Ordered and unordered lists ====
+
+{{{
+list {
+ display: block;
+}
+list > item {
+ display: list-item;
+}
+list[type="unordered"] {
+ list-style-type: ⠶;
+}
+list[type="ordered"].decimal {
+ list-style-type: decimal;
+}
+list[type="ordered"].alpha {
+ list-style-type: lower-alpha;
+}
+list[type="ordered"].roman {
+ list-style-type: lower-roman;
+}
+}}}
+
+This will format lists of type "unordered" as bulleted lists, with each
item preceded by the braille character (bullet) '⠶'. Lists of
type "ordered" will be numbered: "1. 2. 3. ..." for class "decimal", "a. b.
c. ..." for class "alpha" and "i. ii. iii. ..." for class "roman".
+
+
+==== Example 3: Tables in linear versus stairstep format ====
+
+{{{
+table {
+ display: block;
+ border-top: ⠶;
+ border-bottom: ⠛;
+}
+thead {
+ display: block;
+ border-bottom: ⠒;
+}
+tr {
+ display: block;
+ page-break-inside: avoid;
+}
+}}}
+
+This code will give tables an upper and lower border (lines of
characters '⠶' and '⠛' respectively). If there is a table header, a '⠒'
border is printed between the header and the body. Table rows are protected
from being split across braille pages.
+
+{{{
+.linear th::after,
+.linear td::after {
+ content: "⠰ "
+}
+}}}
+
+Tables of class "linear" (`<table class="linear">`) will have table cells
separated by the character '⠰' and a space.
+
+{{{
+table.stairstep td,
+table.stairstep th {
+ display: block;
+}
+table.stairstep th:first-child,
+table.stairstep td:first-child {
+ margin-left: 0;
+}
+table.stairstep th:nth-child(2),
+table.stairstep td:nth-child(2) {
+ margin-left: 3;
+}
+table.stairstep th:nth-child(3),
+table.stairstep td:nth-child(3) {
+ margin-left: 6;
+}
+...
+}}}
+
+In tables of class "stairstep" (`<table class="stairstep">`), each table
cell will start on a new line, with a left margin that is the same for
cells in the same column.
+
+
+==== Example 4: Print page numbers ====
+
+{{{
+pagebreak {
+ display: none;
+ string-set: print-page attr(value);
+}
+}}}
+
+This snippet will update the print page number whenever a `<pagebreak
value="..."/>` is encountered. In order to render print page numbers, the
`@page` rule must be used (see [ZedAIToPEFDoc#Example_6:_Page_layout
example 6] below).
+
+When `display:none` is changed to `display:page-break`, a _page break
indicator_ (a line of braille dots '36') is generated wherever a print page
break occurs:
+
+{{{
+pagebreak {
+ display: page-break;
+ string-set: print-page attr(value);
+}
+}}}
+
+Note that in the current implementation, `display:page-break` only works
in combination with `string-set:print-page`, and won't have any effect
unless it is used for *all* print pages.
+
+==== Example 5: Table of contents ====
+
+{{{
+<toc>
+ <h>Contents</h>
+ <entry><ref ref="chapter_1">I. Down the Rabbit-Hole</ref></entry>
+ <entry><ref ref="chapter_2">II. The Pool of Tears</ref></entry>
+ <entry><ref ref="chapter_3">III. A Caucus-Race and a Long
Tale</ref></entry>
+</toc>
+...
+ <h xml:id="chapter_1">Chapter I. Down the Rabbit-Hole</h>
+...
+}}}
+
+A table of contents can be rendered in a typical layout with page numbers
on the right and leaders between entries and page numbers. A precondition
is that headings in the text are referenced within the table of contents
(e.g. with an attribute). If print page numbers and/or braille page numbers
are present in the braille output, they can be included in the table of
contents too. The pattern of leaders can be configured. Let's look at the
CSS:
+
+{{{
+toc > h {
+ display: block;
+ text-align: center;
+ margin-top: 1;
+ margin-bottom: 1;
+}
+toc > entry > ref {
+ display: block;
+ margin-left: 2;
+ text-indent: -2;
+ content: target-text(attr(ref))
+ leader('⠤')
+ target-string(attr(ref), print-page)
+ target-counter(attr(ref), page)
+}
+}}}
+
+With the `content` property we are dropping the original text of the
_referencing_ elements and copying the text of the _referenced_ elements.
+
+The use is not limited to tables of contents; any kind of list that
references page numbers is a candidate. Think of indices, lists of figures,
list of tables, etc.
+
+
+==== Example 6: Page layout ====
+
+The dimensions of the page, the position of page numbers, and the running
header and/or footer (see [ZedAIToPEFDoc#Example_7:_Running_header/footer
example 7]), can be configured with the `@page` rule:
+
+{{{
+@page {
+ size: 40 25;
+ @top-right {
+ content: string(print-page);
+ }
+ @bottom-right {
+ content: counter(page);
+ }
+ @bottom-center {
+ content: string(running-footer);
+ }
+}
+}}}
+
+The only valid positions for page numbers are currently `@top-right` and
`@bottom-right`. It is also possible to put both page numbers at the top or
at the bottom, like this: `@top-right{content:string(print-page)
counter(page);}`
+
+As showed in the next example, pages can be named. This can be useful to
switch page layout in the middle of a document. The following example will
start a new page with double width for each wide table, so that it can be
printed across facing pages.
+
+{{{
+@page double {
+ size: 80 25;
+}
+
+table.wide {
+ page: double;
+}
+}}}
+
+
+==== Example 7: Running header/footer ====
+
+As seen in [ZedAIToPEFDoc#Example_6:_Page_layout example 6] above, pages
can have running headers and/or footers. To update the value of the footer
whenever a new heading appears, include the following:
+
+{{{
+h {
+ string-set: running-footer content();
+}
+}}}
+
+
+==== Example 8: Braille page numbers ====
+
+CSS also has some tools to customized the braille page numbering. For
example, to distinguished the frontmatter from the bodymatter, they often
have different page numbering formats. This snippet gives the frontmatter
lowercase Roman page numbers, and restarts the numbering after the
frontmatter:
+
+{{{
+@page front {
+ @bottom-right {
+ content: counter(page, lower-roman);
+ }
+}
+
+frontmatter {
+ page: front;
+}
+
+bodymatter {
+ counter-reset: page 1;
+}
+}}}
Branch: default
Author: Bert Frees <bert...@gmail.com>
Date: Fri Mar 20 18:43:15 2015 UTC
Log: Update zedai-to-pef documentation to next version (1.10)
also removed the section "Extending the script" as it doesn't really belong
to user documentation
https://code.google.com/p/daisy-pipeline/source/detail?r=96da38472265&repo=wiki
Deleted:
/ZedAIToPEFInstallation.wiki
/ZedAIToPEFUsage.wiki
Modified:
/ZedAIToPEFDoc.wiki
=======================================
--- /ZedAIToPEFInstallation.wiki Thu Sep 6 13:59:57 2012 UTC
+++ /dev/null
@@ -1,34 +0,0 @@
-#summary Instructions on how to install the ZedAI to PEF script.
-#labels Phase-Deploy
-#sidebar UserGuideToc
-
-= ZedAI to PEF Installation Instructions =
-
-The ZedAI script is not included in the default DAISY Pipeline
distribution. Some additional steps are required to install the script.
-
-== Prerequisites ==
-
- * Obviously, you need to [Installation install the Pipeline 2] first.
- * You need to know [CommandLine how to use the command line tool].
- * If you prefer a graphical interface over the command line, find out
[WebUI how to install the web UI].
-
-== Automated Installation ==
-
-An installer that automatically installs the required files into the right
folders, is available from the
[https://code.google.com/p/daisy-pipeline/downloads/list downloads page].
The installer is an executable JAR file that you can run by double-clicking
it or by using the `java -jar` command. In the first step, you are asked to
select the installation path. Choose the same directory where you installed
the DAISY Pipeline. You will get a warning: "The directory already exists!
Are you sure you want to install here and possibly overwrite existing
files?". Ignore this. In the next step you'll get an overview of the
packages that will be installed. Press "Next" a few times and then "Done"
to finish the installation.
-
-== Manual Installation ==
-
-The Braille components are also packaged in a ZIP archive. The ZIP
contains two folders:
-
- * `modules`
- * `system/framework`
-
-Copy the contents of these folders into the corresponding folders of your
DAISY Pipeline installation. The `modules` folder contains multiple
versions of `liblouis-native.jar`, one for each operating system. Copy only
the version that applies to you.
-
-== Note when running on OS X ==
-
-When running the zedai-to-pef script on OS X, you may notice that the
Pipeline daemon process starts appearing as a regular application with the
default Java icon appearing on the Dock. To remove this behavior, you can
add the following line to the `etc/system.properties` file in your Pipeline
installation directory:
-
-{{{java.awt.headless=true}}}
-
-Next: [ZedAIToPEFUsage Using the ZedAI to PEF script]
=======================================
--- /ZedAIToPEFUsage.wiki Thu Oct 2 13:56:28 2014 UTC
+++ /dev/null
@@ -1,430 +0,0 @@
-#summary A guide on how to use the ZedAI to PEF script.
-#labels Phase-Support
-#sidebar UserGuideToc
-
-= ZedAI to PEF User Guide =
-
-<wiki:toc/>
-
-== Synopsis ==
-
-=== Input ===
-
-|| *name* || *description* ||
-|| source || A valid ZedAI document. ||
-
-=== Options ===
-
-|| *name* ||
*default* || *description* ||
-|| include-preview (optional) ||
`false` || Whether or not to include a preview of
the PEF in HTML (true or false). ||
-|| include-brf (optional) ||
`false` || Whether or not to include an ASCII
version of the PEF (true or false). ||
-|| output-dir (required in local mode only) |
| || Directory for storing result files. ||
-|| temp-dir (optional) |
| || Directory for storing temporary
files. ||
-|| default-stylesheet (optional) ||
`default.css` || The default CSS stylesheet to apply. ||
-|| translator (optional, advanced) ||
`generic-liblouis-translate.xsl` || The translator(s) (XSLT/XProc step or
liblouis/libhyphen table) to be used. Can be a comma separated list. ||
-
-
-== Example running from command line ==
-
-{{{
-$ ./dp2 zedai-to-pef \
- --i-source samples/zedai/alice.xml \
- --x-include-preview true \
- --x-include-brf true \
- --x-output-dir ~/Desktop/out
-}}}
-
-output:
-
-{{{
-$ ls ~/Desktop/out
-alice.pef
-alice.pef.html
-alice.brf
-}}}
-
-More advanded example:
-
-{{{
-$ ./dp2 zedai-to-pef \
- --i-source samples/zedai/alice.xml \
- --x-include-preview true \
- --x-translator hyph_en_US.dic,unicode.dis,en-us-g1.ctb \
- --x-default-stylesheet bana.css \
- --x-output-dir ~/Desktop/out
-}}}
-
-== Getting a preview ==
-
-To emboss a PEF file or display it on screen you need special software
(such as the [http://code.google.com/p/e2u/ Easy Embosser Utility]
developed at TPB). Opening a PEF with an XML editor is not very useful
because you only get to see Unicode braille (dot patterns). If you don't
have access to a special PEF tool, or you just want to quickly review the
document first, you should set the `include-preview` option to `true`. In
addition to the actual PEF file, an HTML page will then be generated that
you can open in your browser. You will be able to quickly navigate pages,
and switch between a 'dot patterns' view and a more readable ASCII view. To
properly render this HTML page, you need the
[http://sourceforge.net/projects/odt2braille/files/ttf/odt2braille-6dot-v1.1.ttf
odt2braille font].
-
-== Advanced Configuration ==
-
-=== Translation ===
-
-By default, text is translated to braille with a simple generic
[http://code.google.com/p/liblouis/ liblouis] based translator. All the
translation tables distributed by liblouis (about 80 languages) are
included in the DAISY Pipeline as well. The translator will automatically
look for the table that matches the `xml:lang` attribute best. If you need
more control over the translation, you can specify an alternative
translator or a list of translators with the `translator` option. For
example:
-
-{{{
---x-translator generic-liblouis-translate-with-emphasis.xsl
-}}}
-
-looks for emphasised text and tries to mark it up in braille (through
liblouis). Or, you might want to select a specific liblouis table, for
example US English Grade 1:
-
-{{{
---x-translator unicode.dis,en-us-g1.ctb
-}}}
-
-Or, if you are running Pipeline 2 in local mode, and you have your own
liblouis tables installed somewhere, you can use them by specifying the
full path:
-
-{{{
---x-translator file:/home/me/liblouis-tables/unicode.dis,my_en-us.ctb
-}}}
-
-Liblouis is the main translation engine used in DAISY Pipeline 2, but no
one stops you from using another library. The following translator is
backed by [https://code.google.com/p/dotify/ Dotify], a braille translation
library developed at TPB:
-
-{{{
---x-translator generic-dotify-translate.xsl
-}}}
-
-More examples are provided below (see [ZedAIToPEFUsage#Hyphenation
Hyphenation] and [ZedAIToPEFUsage#Math Math]). If your use case requires
non-trivial features and the supplied generic translators won't do, you can
write your own translator, which might be a combination of existing and new
components. Read [ZedAIToPEFUsage#Extending_the_Script Extending the
Script] for more details. If you have idea's about features that should be
supported by default, please share them with us.
-
-
-=== Hyphenation ===
-
-To enable hyphenation, a translator step needs to be inserted _before_ the
actual braille translation. [http://hunspell.sourceforge.net/ Hyphen], the
main hyphenation engine used in [http://www.openoffice.org/ OpenOffice] and
[http://www.libreoffice.org/ LibreOffice], is also the main hyphenator in
DAISY Pipeline 2:
-
-{{{
---x-translator
generic-libhyphen-hyphenate.xsl,generic-liblouis-translate.xsl
-}}}
-
-This translator will find the right hyphenation dictionary based on the
`xml:lang` attribute. As with liblouis, you can also select a specific
Hyphen dictionary:
-
-{{{
---x-translator hyph_en_US.dic,generic-liblouis-translate.xsl
-}}}
-
-Windows users should use the TeX implementation (until a certain issue is
fixed):
-
-{{{
---x-translator generic-tex-hyphenate.xsl,generic-liblouis-translate.xsl
-}}}
-
-
-=== Math ===
-
-Liblouis is capable of translating math as [http://www.w3.org/Math/
MathML] to braille. The supported braille math codes are _Nemeth_ (used in
the US), _Marburg_ (Germany), _Woluwe_ (Belgium) and _UKMaths_ (Great
Britain). To enable math translation, insert the following step:
-
-{{{
---x-translator
generic-liblouis-translate-mathml.xpl,generic-liblouis-translate.xsl
-}}}
-
-
-=== Styling with Braille CSS ===
-
-The formatting of documents into a paged braille layout is done entirely
based on CSS (Cascading Style Sheets). We use a flavor of CSS specially
designed for this use case. For people that already know CSS, it will feel
very natural. In fact, it is almost a subset of CSS3, but with some
restrictions and a few braille specific features. The most obvious
difference is that margins are expressed in units of cell width and line
height instead of pixels, ems and percentages. A complete overview of
braille CSS can be found on [http://snaekobbi.github.io/braille-css-spec
this page].
-
-The actual formatting of documents based on CSS is done with
[http://code.google.com/p/liblouisutdml/ liblouisutdml] under the hood. In
the future other implementations may be added. Note that, when the
_formatting_ begins, the braille _translation_ has already been performed.
Translation and formatting are completely separated steps, and their
implementations can be changed independently.
-
-Attaching style information to a document can be done either by linking to
an external CSS stylesheet, by including an internal stylesheet, by
inserting inline styles, or a hibrid of these three.
-
-1. External stylesheet:
-
-{{{
-<document>
- <head>
- <link rel="stylesheet" media="embossed" type="text/css"
href="external_stylesheet.css" />
- ...
-}}}
-
-2. Internal stylesheet:
-
-{{{
-<document>
- <head>
- <style media="embossed" type="text/css">
- head {
- display: none;
- }
- h {
- display: block;
- text-align: center;
- }
- ...
- </style>
- ...
-}}}
-
-3. Inline styles:
-
-{{{
-<document>
- <head style="display:none">
- ...
- </head>
- <body>
- <frontmatter>
- <section>
- <h style="display:block;text-align:center">...</h>
- ...
-}}}
-
-Keep in mind that a simple default stylesheet (`default.css`) is always
applied first. If you don't want this default CSS, include `reset.css` in
your stylesheet:
-
-{{{
-@import
url('http://www.daisy.org/pipeline/modules/braille/zedai-to-pef/css/reset.css');
-}}}
-
-To change which default CSS is applied, use the `default-stylesheet`
option as in the [ZedAIToPEFUsage#Example_running_from_command_line
advanced example] above. Valid choices are
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/bana.css
bana.css] and
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/ueb.css
ueb.css]. This is not meant to be a complete list, the idea is to
eventually have stylesheets for each braille formatting standard. In fact,
`bana.css` and `ueb.css` are currently only stubs, we are hoping for
contributions from people who are more familiar with these standards.
-
-==== Example 1: Sections and headings ====
-
-{{{
-section {
- display: block;
- page-break-before: always;
-}
-}}}
-
-By putting this code in your stylesheet, each section will be guaranteed
to start on a new braille page.
-
-{{{
-h {
- display:block;
- text-align:center;
- margin-top: 1;
- margin-bottom: 1;
- margin-left: 4;
- margin-right: 4;
- page-break-after: avoid;
-}
-h + * {
- orphans: 2;
-}
-}}}
-
-Headings are centered on the page, with at least one line left blank both
above and below. The left and right margins are increased enough so that
long headings can not be confused with normal paragraphs. To make sure
headings are not rendered at the bottom of a page, no page breaks are
allowed right after a heading, and any element immediately following a
heading must have at least two lines (orphans) on the current page.
-
-
-==== Example 2: Ordered and unordered lists ====
-
-{{{
-list {
- display: block;
-}
-list > item {
- display: list-item;
-}
-list[type="unordered"] {
- list-style-type: ⠶;
-}
-list[type="ordered"].decimal {
- list-style-type: decimal;
-}
-list[type="ordered"].alpha {
- list-style-type: lower-alpha;
-}
-list[type="ordered"].roman {
- list-style-type: lower-roman;
-}
-}}}
-
-This will format lists of type "unordered" as bulleted lists, with each
item preceded by the braille character (bullet) '⠶'. Lists of
type "ordered" will be numbered: "1. 2. 3. ..." for class "decimal", "a. b.
c. ..." for class "alpha" and "i. ii. iii. ..." for class "roman".
-
-
-==== Example 3: Tables in linear vs. stairstep format ====
-
-{{{
-table {
- display: block;
- border-top: ⠶;
- border-bottom: ⠛;
-}
-thead {
- display: block;
- border-bottom: ⠒;
-}
-tr {
- display: block;
- page-break-inside: avoid;
-}
-}}}
-
-This code will give tables an upper and lower border (lines of
characters '⠶' and '⠛' respectively). If there is a table header, a '⠒'
border is printed between the header and the body. Table rows are protected
from being split across braille pages.
-
-{{{
-.linear th::after,
-.linear td::after {
- content: "⠰ "
-}
-}}}
-
-Tables of class "linear" (`<table class="linear">`) will have table cells
separated by the character '⠰' and a space.
-
-{{{
-table.stairstep td,
-table.stairstep th {
- display: block;
-}
-table.stairstep th:first-child,
-table.stairstep td:first-child {
- margin-left: 0;
-}
-table.stairstep th:nth-child(2),
-table.stairstep td:nth-child(2) {
- margin-left: 3;
-}
-table.stairstep th:nth-child(3),
-table.stairstep td:nth-child(3) {
- margin-left: 6;
-}
-...
-}}}
-
-In tables of class "stairstep" (`<table class="stairstep">`), each table
cell will start on a new line, with a left margin that is the same for
cells in the same column.
-
-
-==== Example 4: Print page numbers ====
-
-{{{
-pagebreak {
- display: none;
- string-set: print-page attr(value);
-}
-}}}
-
-This snippet will update the print page number whenever a `<pagebreak
value="..."/>` is encountered. In order to render print page numbers, the
`@page` rule must be used (see [ZedAIToPEFUsage#Example_6:_Page_layout
example 6] below).
-
-When `display:none` is changed to `display:page-break`, a _page break
indicator_ (a line of braille dots '36') is generated wherever a print page
break occurs:
-
-{{{
-pagebreak {
- display: page-break;
- string-set: print-page attr(value);
-}
-}}}
-
-Note that in the current implementation, `display:page-break` only works
in combination with `string-set:print-page`, and won't have any effect
unless it is used for *all* print pages.
-
-==== Example 5: Table of contents ====
-
-{{{
-<toc>
- <h>Contents</h>
- <entry><ref ref="chapter_1">I. Down the Rabbit-Hole</ref></entry>
- <entry><ref ref="chapter_2">II. The Pool of Tears</ref></entry>
- <entry><ref ref="chapter_3">III. A Caucus-Race and a Long
Tale</ref></entry>
-</toc>
-...
- <h xml:id="chapter_1">Chapter I. Down the Rabbit-Hole</h>
-...
-}}}
-
-A table of contents can be rendered in a typical layout with page numbers
on the right and leaders between entries and page numbers. A precondition
is that headings in the text are referenced within the table of contents
(e.g. with an attribute). If print page numbers and/or braille page numbers
are present in the braille output, they can be included in the table of
contents too. The pattern of leaders can be configured. Let's look at the
CSS:
-
-{{{
-toc > h {
- display: block;
- text-align: center;
- margin-top: 1;
- margin-bottom: 1;
-}
-toc > entry > ref {
- display: block;
- margin-left: 2;
- text-indent: -2;
- content: target-text(attr(ref))
- leader('⠤')
- target-string(attr(ref), print-page)
- target-counter(attr(ref), braille-page)
-}
-}}}
-
-With the `content` property we are dropping the original text of the
_referencing_ elements and copying the text of the _referenced_ elements.
-
-The use is not limited to tables of contents; any kind of list that
references page numbers is a candidate. Think of indices, lists of figures,
list of tables, etc.
-
-
-==== Example 6: Page layout ====
-
-The dimensions of the page, the position of page numbers, and the running
header and/or footer (see [ZedAIToPEFUsage#Example_7:_Running_header/footer
example 7]), can be configured with the `@page` rule:
-
-{{{
-@page {
- size: 40 25;
- @top-right {
- content: string(print-page);
- }
- @bottom-right {
- content: counter(braille-page);
- }
- @bottom-center {
- content: string(running-footer);
- }
-}
-}}}
-
-The only valid positions for page numbers are currently `@top-right` and
`@bottom-right`. It is also possible to put both page numbers at the top or
at the bottom, like this: `@top-right{content:string(print-page)
counter(braille-page);}`
-
-As showed in the next example, pages can be named. This can be useful to
switch page layout in the middle of a document. The following example will
start a new page with double width for each wide table, so that it can be
printed across facing pages.
-
-{{{
-@page double {
- size: 80 25;
-}
-
-table.wide {
- page: double;
-}
-}}}
-
-
-==== Example 7: Running header/footer ====
-
-As seen in [ZedAIToPEFUsage#Example_6:_Page_layout example 6] above, pages
can have running headers and/or footers. To update the value of the footer
whenever a new heading appears, include the following:
-
-{{{
-h {
- string-set: running-footer content();
-}
-}}}
-
-
-==== Example 8: Braille page numbers ====
-
-CSS also has some tools to customized the braille page numbering. For
example, to distinguished the frontmatter from the bodymatter, they often
have different page numbering formats. This snippet gives the frontmatter
lowercase Roman page numbers, and restarts the numbering after the
frontmatter:
-
-{{{
-@page front {
- @bottom-right {
- content: counter(braille-page, lower-roman);
- }
-}
-
-frontmatter {
- page: front;
-}
-
-bodymatter {
- counter-reset: braille-page 1;
-}
-}}}
-
-
-=== Extending the Script ===
-
-The simple generic liblouis based translator that is used by default is
not very likely to fit everyone's needs. Braille translation requirements
are very specific and diverse. This is the main reason why we need such a
modular and extensible design. Custom translators, which are either XSLT or
XProc steps, liblouis tables or libhyphen dictionaries, can be 'plugged in'
using the XML Catalog mechanism. Basically this means you write an XSLT or
XProc step or a liblouis table, map it to a URL, and provide this URL (or a
list of URLs) to the script with the `translator` option (more details
below).
-
-An example of a custom translator can be found
[https://github.com/sbsdev/sbs-pipeline/blob/master/dtbook-to-pef/src/main/resources/xml/xslt/zedai-translator.xsl
here].
-
-Translation can happen on the 'document level' or on the 'block level'.
Performing block-level translation greatly simplifies the contract for a
translator and supports the idea of separating formatting and translation.
You can create a block-level translator by extending
`block-translator-template.xsl`. (Definition: a CSS block is defined as the
largest group of adjacent text nodes and inline elements, i.e. elements
with "display:inline", that only have other text nodes and inline elements
as their descendants.)
-
-The next sections explain a bit more in detail how to create custom
translators.
-
-
-=== Custom liblouis tables ===
-
-*_TBD_*
-
-=== Custom translators ===
-
-*_TBD_*
=======================================
--- /ZedAIToPEFDoc.wiki Wed Nov 28 11:08:23 2012 UTC
+++ /ZedAIToPEFDoc.wiki Fri Mar 20 18:43:15 2015 UTC
@@ -2,17 +2,403 @@
#labels Type-Doc,Compoment-UserGuide,Component-Module,Component-Script
#sidebar UserGuideToc
-= ZedAI to PEF =
+The "ZedAI to PEF" script will convert a ZedAI document (NISO Z39.98-2012
- Authoring and Interchange Framework for Adaptive XML Publishing) into a
PEF (Portable Embosser Format) file. PEF is a format for representing paged
braille documents in an unambiguous way. It builds on XML, Unicode and
Dublin Core. Tools are available for embossing PEF files or converting them
into other braille formats. See also [http://pef-format.org/ the PEF Format
website].
-The "ZedAI to PEF" script will convert a ZedAI document (NISO Z39.98-2012
- Authoring and Interchange Framework for Adaptive XML Publishing) into a
PEF (Portable Embosser Format) file. PEF is a format for representing paged
Braille documents in an unambiguous way. It builds on XML, Unicode and
Dublin Core. Tools are available for embossing PEF files or converting them
into other Braille formats. See also [http://pef-format.org/ the PEF Format
website].
+<wiki:toc/>
-== [ZedAIToPEFInstallation Installation] ==
+== Synopsis ==
-This script is not included in the default DAISY Pipeline distribution.
Some additional steps are required to install the script.
+=== Input ===
+|| *name* || *description* ||
+|| source || A valid ZedAI document. ||
-== [ZedAIToPEFUsage User Guide] ==
+=== Options ===
-This page gives you and overview of the basic functionality and explains
how you can extend the script to fit your needs.
+|| *name* ||
*default* || *description* ||
+|| include-preview (optional) ||
`false` || Whether or not to include a
preview of the PEF in HTML (true or false). ||
+|| include-brf (optional) ||
`false` || Whether or not to include an
ASCII version of the PEF (true or false). ||
+|| default-stylesheet (optional) ||
`default.css` || The default CSS stylesheet
to apply. ||
+|| transform (optional, advanced) ||
`(formatter:liblouis)(translator:liblouis)` || A transformer query. ||
+== Example running from command line ==
+{{{
+$ ./dp2 zedai-to-pef \
+ --i-source samples/zedai/alice.xml \
+ --x-include-preview true \
+ --x-include-brf true \
+ --x-output ~/Desktop/out
+}}}
+
+output:
+
+{{{
+$ ls ~/Desktop/out
+alice.pef
+alice.pef.html
+alice.brf
+}}}
+
+More advanded example:
+
+{{{
+$ ./dp2 zedai-to-pef \
+ --i-source samples/zedai/alice.xml \
+ --x-include-preview true \
+ --x-default-stylesheet bana.css \
+ --x-transform "(formatter:dotify)" \
+ --x-output ~/Desktop/out
+}}}
+
+== Getting a preview ==
+
+To emboss a PEF file or display it on screen you need special software
(such as the [http://code.google.com/p/e2u/ Easy Embosser Utility]
developed at TPB). Opening a PEF with an XML editor is not very useful
because you only get to see Unicode braille (dot patterns). If you don't
have access to a special PEF tool, or you just want to quickly review the
document first, you should set the `include-preview` option to `true`. In
addition to the actual PEF file, an HTML page will then be generated that
you can open in your browser. You will be able to quickly navigate pages,
and switch between a 'dot patterns' view and a more readable ASCII view. To
properly render this HTML page, you need the
[http://sourceforge.net/projects/odt2braille/files/ttf/odt2braille-6dot-v1.1.ttf
odt2braille font].
+
+== Advanced Configuration ==
+
+=== Translation ===
+
+By default, text is translated to braille with a simple generic
[http://code.google.com/p/liblouis/ liblouis] based translator. All the
translation tables distributed by liblouis (about 80 languages) are
included in the DAISY Pipeline. The translator will automatically look for
the table that matches the `xml:lang` attribute best. The `transform`
option gives you more control over translator selection. For example:
+
+{{{
+--x-transform "(locale:fr)"
+}}}
+
+will force the document to be translated to French braille. Or, you might
want to select a specific liblouis table, for example US English Grade 1:
+
+{{{
+--x-transform "(liblouis-table:'en-us-g1.ctb')"
+}}}
+
+If you are running DAISY Pipeline 2 in local mode, and you have your own
liblouis tables installed somewhere, you can use them by specifying the
full path:
+
+{{{
+--x-transform "(liblouis-table:'file:/home/me/liblouis-tables/my_en-us.ctb')"
+}}}
+
+Liblouis is the main translation engine used in DAISY Pipeline 2, but
other libraries are available. The following translator is backed by
[https://code.google.com/p/dotify/ Dotify], the braille translation library
developed at MTM:
+
+{{{
+--x-transform "(translator:dotify)"
+}}}
+
+More examples are provided below. If your use case requires non-trivial
features and the supplied generic translators won't do, you can write your
own translator, which might be a combination of existing and new
components. If you have idea's about features that should be supported by
default, please share them with us.
+
+
+=== Hyphenation ===
+
+The default transformer automatically hyphenates text with CSS property
“`hyphens:auto`” (see [ZedAIToPEFDoc#Styling_with_Braille_CSS Styling with
Braille CSS] below). A hyphenator will be selected based on the `xml:lang`
attribute. If liblouis isn't able to hyphenate the text itself, then
[http://hunspell.sourceforge.net/ Hyphen], the hyphenation engine from
[http://www.openoffice.org/ OpenOffice] and [http://www.libreoffice.org/
LibreOffice], is used. To force the use of Hyphen, specify:
+
+{{{
+--x-transform "(hyphenator:hyphen)"
+}}}
+
+and to select a specific Hyphen table, specify:
+
+{{{
+--x-transform "(libhyphen-table:'hyph_en_US.dic')"
+}}}
+
+
+=== Text Emphasis ===
+
+In case the input document has styling attached for media 'print', the
default translator uses this information to mark emphasised text
(`font-style`, `font-weight`, etc.) with braille indicators.
+
+
+=== Math ===
+
+Translation of [http://www.w3.org/Math/ MathML] is supported by default.
The supported braille math codes are _Nemeth_ (used in the US), _Marburg_
(Germany), _Woluwe_ (Belgium) and _UKMaths_ (Great Britain). The right
translator is selected based on the `xml:lang` attribute.
+
+
+=== Styling with Braille CSS ===
+
+The formatting of documents into a paged braille layout is specified with
CSS (Cascading Style Sheets). We use a flavor of CSS specially designed for
this use case. For people that already know CSS, it will feel very natural.
In fact, it is almost a subset of CSS3, but with certain restrictions and
some braille specific features. The most obvious difference is that margins
are expressed in units of cell width and line height instead of pixels, ems
and percentages. Extensive documentation of braille CSS can be found in
[http://snaekobbi.github.io/braille-css-spec the Braille CSS specification
draft].
+
+In addition to braille CSS, which is normative, certain parts of 'print'
CSS can be taken into account as well. An example is
[ZedAIToPEFDoc#Text_Emphasis text emphasis]. (See also
[http://snaekobbi.github.io/braille-css-spec/#h2_media-types Braille CSS -
Media Types].)
+
+The actual rendering of documents based on CSS is done with
[http://code.google.com/p/liblouisutdml/ liblouisutdml] under the hood. A
second implementation is based on Dotify (experimental). Note that, when
the _formatting_ begins, the braille _translation_ has already been
performed. Translation and formatting are completely separated steps, and
their implementations can be changed independently.
+
+Attaching style information to a document can be done either by linking to
an external CSS stylesheet, by including an internal stylesheet, by
inserting inline styles, or a hibrid of these three.
+
+1. External stylesheet:
+
+{{{
+<document>
+ <head>
+ <link rel="stylesheet" media="embossed" type="text/css"
href="external_stylesheet.css" />
+ ...
+}}}
+
+2. Internal stylesheet:
+
+{{{
+<document>
+ <head>
+ <style media="embossed" type="text/css">
+ head {
+ display: none;
+ }
+ h {
+ display: block;
+ text-align: center;
+ }
+ ...
+ </style>
+ ...
+}}}
+
+3. Inline styles:
+
+{{{
+<document>
+ <head style="display:none">
+ ...
+ </head>
+ <body>
+ <frontmatter>
+ <section>
+ <h style="display:block;text-align:center">...</h>
+ ...
+}}}
+
+Keep in mind that a simple default stylesheet (`default.css`) is always
applied first. If you don't want this default CSS, include `reset.css` in
your stylesheet:
+
+{{{
+@import
url('http://www.daisy.org/pipeline/modules/braille/zedai-to-pef/css/reset.css');
+}}}
+
+To change which default CSS is applied, use the `default-stylesheet`
option as in the [ZedAIToPEFDoc#Example_running_from_command_line advanced
example] above. Valid choices are
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/bana.css
bana.css] and
[https://github.com/daisy-consortium/pipeline-mod-braille/blob/master/zedai-to-pef/src/main/resources/css/ueb.css
ueb.css]. This is not meant to be a complete list, the idea is to
eventually have stylesheets for each braille formatting standard. In fact,
`bana.css` and `ueb.css` are currently only stubs, we are hoping for
contributions from people who are more familiar with these standards.
+
+==== Example 1: Sections and headings ====
+
+{{{
+section {
+ display: block;
+ page-break-before: always;
+}
+}}}
+
+By putting this code in your stylesheet, each section will be guaranteed
to start on a new braille page.
+
+{{{
+h {
+ display:block;
+ text-align:center;
+ margin-top: 1;
+ margin-bottom: 1;
+ margin-left: 4;
+ margin-right: 4;
+ page-break-after: avoid;
+}
+h + * {
+ orphans: 2;
+}
+}}}
+
+Headings are centered on the page, with at least one line left blank both
above and below. The left and right margins are increased enough so that
long headings can not be confused with normal paragraphs. To make sure
headings are not rendered at the bottom of a page, no page breaks are
allowed right after a heading, and any element immediately following a
heading must have at least two lines (orphans) on the current page.
+
+
+==== Example 2: Ordered and unordered lists ====
+
+{{{
+list {
+ display: block;
+}
+list > item {
+ display: list-item;
+}
+list[type="unordered"] {
+ list-style-type: ⠶;
+}
+list[type="ordered"].decimal {
+ list-style-type: decimal;
+}
+list[type="ordered"].alpha {
+ list-style-type: lower-alpha;
+}
+list[type="ordered"].roman {
+ list-style-type: lower-roman;
+}
+}}}
+
+This will format lists of type "unordered" as bulleted lists, with each
item preceded by the braille character (bullet) '⠶'. Lists of
type "ordered" will be numbered: "1. 2. 3. ..." for class "decimal", "a. b.
c. ..." for class "alpha" and "i. ii. iii. ..." for class "roman".
+
+
+==== Example 3: Tables in linear versus stairstep format ====
+
+{{{
+table {
+ display: block;
+ border-top: ⠶;
+ border-bottom: ⠛;
+}
+thead {
+ display: block;
+ border-bottom: ⠒;
+}
+tr {
+ display: block;
+ page-break-inside: avoid;
+}
+}}}
+
+This code will give tables an upper and lower border (lines of
characters '⠶' and '⠛' respectively). If there is a table header, a '⠒'
border is printed between the header and the body. Table rows are protected
from being split across braille pages.
+
+{{{
+.linear th::after,
+.linear td::after {
+ content: "⠰ "
+}
+}}}
+
+Tables of class "linear" (`<table class="linear">`) will have table cells
separated by the character '⠰' and a space.
+
+{{{
+table.stairstep td,
+table.stairstep th {
+ display: block;
+}
+table.stairstep th:first-child,
+table.stairstep td:first-child {
+ margin-left: 0;
+}
+table.stairstep th:nth-child(2),
+table.stairstep td:nth-child(2) {
+ margin-left: 3;
+}
+table.stairstep th:nth-child(3),
+table.stairstep td:nth-child(3) {
+ margin-left: 6;
+}
+...
+}}}
+
+In tables of class "stairstep" (`<table class="stairstep">`), each table
cell will start on a new line, with a left margin that is the same for
cells in the same column.
+
+
+==== Example 4: Print page numbers ====
+
+{{{
+pagebreak {
+ display: none;
+ string-set: print-page attr(value);
+}
+}}}
+
+This snippet will update the print page number whenever a `<pagebreak
value="..."/>` is encountered. In order to render print page numbers, the
`@page` rule must be used (see [ZedAIToPEFDoc#Example_6:_Page_layout
example 6] below).
+
+When `display:none` is changed to `display:page-break`, a _page break
indicator_ (a line of braille dots '36') is generated wherever a print page
break occurs:
+
+{{{
+pagebreak {
+ display: page-break;
+ string-set: print-page attr(value);
+}
+}}}
+
+Note that in the current implementation, `display:page-break` only works
in combination with `string-set:print-page`, and won't have any effect
unless it is used for *all* print pages.
+
+==== Example 5: Table of contents ====
+
+{{{
+<toc>
+ <h>Contents</h>
+ <entry><ref ref="chapter_1">I. Down the Rabbit-Hole</ref></entry>
+ <entry><ref ref="chapter_2">II. The Pool of Tears</ref></entry>
+ <entry><ref ref="chapter_3">III. A Caucus-Race and a Long
Tale</ref></entry>
+</toc>
+...
+ <h xml:id="chapter_1">Chapter I. Down the Rabbit-Hole</h>
+...
+}}}
+
+A table of contents can be rendered in a typical layout with page numbers
on the right and leaders between entries and page numbers. A precondition
is that headings in the text are referenced within the table of contents
(e.g. with an attribute). If print page numbers and/or braille page numbers
are present in the braille output, they can be included in the table of
contents too. The pattern of leaders can be configured. Let's look at the
CSS:
+
+{{{
+toc > h {
+ display: block;
+ text-align: center;
+ margin-top: 1;
+ margin-bottom: 1;
+}
+toc > entry > ref {
+ display: block;
+ margin-left: 2;
+ text-indent: -2;
+ content: target-text(attr(ref))
+ leader('⠤')
+ target-string(attr(ref), print-page)
+ target-counter(attr(ref), page)
+}
+}}}
+
+With the `content` property we are dropping the original text of the
_referencing_ elements and copying the text of the _referenced_ elements.
+
+The use is not limited to tables of contents; any kind of list that
references page numbers is a candidate. Think of indices, lists of figures,
list of tables, etc.
+
+
+==== Example 6: Page layout ====
+
+The dimensions of the page, the position of page numbers, and the running
header and/or footer (see [ZedAIToPEFDoc#Example_7:_Running_header/footer
example 7]), can be configured with the `@page` rule:
+
+{{{
+@page {
+ size: 40 25;
+ @top-right {
+ content: string(print-page);
+ }
+ @bottom-right {
+ content: counter(page);
+ }
+ @bottom-center {
+ content: string(running-footer);
+ }
+}
+}}}
+
+The only valid positions for page numbers are currently `@top-right` and
`@bottom-right`. It is also possible to put both page numbers at the top or
at the bottom, like this: `@top-right{content:string(print-page)
counter(page);}`
+
+As showed in the next example, pages can be named. This can be useful to
switch page layout in the middle of a document. The following example will
start a new page with double width for each wide table, so that it can be
printed across facing pages.
+
+{{{
+@page double {
+ size: 80 25;
+}
+
+table.wide {
+ page: double;
+}
+}}}
+
+
+==== Example 7: Running header/footer ====
+
+As seen in [ZedAIToPEFDoc#Example_6:_Page_layout example 6] above, pages
can have running headers and/or footers. To update the value of the footer
whenever a new heading appears, include the following:
+
+{{{
+h {
+ string-set: running-footer content();
+}
+}}}
+
+
+==== Example 8: Braille page numbers ====
+
+CSS also has some tools to customized the braille page numbering. For
example, to distinguished the frontmatter from the bodymatter, they often
have different page numbering formats. This snippet gives the frontmatter
lowercase Roman page numbers, and restarts the numbering after the
frontmatter:
+
+{{{
+@page front {
+ @bottom-right {
+ content: counter(page, lower-roman);
+ }
+}
+
+frontmatter {
+ page: front;
+}
+
+bodymatter {
+ counter-reset: page 1;
+}
+}}}
Reply all
Reply to author
Forward
0 new messages