| <?xml version="1.0" standalone="no"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!-- $Id$ --> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> |
| <document> |
| <header> |
| <title>Accessibility</title> |
| </header> |
| <body> |
| <section id="overview"> |
| <title>Overview</title> |
| <p> |
| This page describes the |
| <a href="http://en.wikipedia.org/wiki/Accessibility">accessibility</a> |
| features of Apache FOP. |
| <a href="http://www.section508.gov/">Section 508</a> defines accessibility in the context |
| of electronic documents for the USA but other countries have similar requirements. |
| </p> |
| <p> |
| Accessibility features are available only for the PDF output format and there are some |
| implementation limitations. Also, certain actions must be undertaken by the content creator |
| to ensure that FOP can create a truly accessible document. |
| </p> |
| </section> |
| <section> |
| <title>Enabling accessibility</title> |
| <p>There are 3 ways to enable accessibility:</p> |
| <ol> |
| <li> |
| <strong>Command line:</strong> The command line option -a turns on accessibility: |
| <code>fop -a -fo mydocument.fo -pdf mydocument.pdf</code> |
| </li> |
| <li> |
| <strong>Embedding:</strong> <code>userAgent.setAccessibility(true);</code> |
| </li> |
| <li> |
| <strong>Optional setting in fop.xconf file:</strong> |
| <pre> |
| <fop version="1.0"> |
| <accessibility>true</accessibility> |
| ... |
| </fop> |
| </pre> |
| </li> |
| </ol> |
| <p> |
| When accessibility is enabled, additional information relating to the logical structure of |
| the document is added to the PDF. That information allows the PDF viewer (or a |
| text-to-speech application) to retrieve the natural reading order of the document. |
| </p> |
| <note>The processing of the logical structure is memory-hungry. You may need to adjust the |
| Java heap size in order to process larger files.</note> |
| </section> |
| <section id="source"> |
| <title>Changes to your XSL-FO input files</title> |
| <p> |
| Apache FOP cannot automatically generate accessible PDFs. Some of the work can only be |
| performed by the content provider. Following are some changes that may be necessary to |
| your XSL-FO content in order to generate really accessible documents: |
| </p> |
| <ul> |
| <li>Table cells must have a table row as their parent.</li> |
| <li> |
| Images must have an alternate text: use the <code>fox:alt-text</code> extension attribute |
| (in the <a href="extensions.html#fox-namespace">fox namespace</a>) on |
| <code>fo:external-graphic</code> and <code>fo:instream-foreign-object</code> to specify a |
| short text describing the image. |
| </li> |
| <li> |
| Ensure that the order of <code>fo:block-container</code> elements in a page corresponds to |
| the reading order. |
| </li> |
| <li> |
| Specify the natural language of the document using the language and country properties |
| (or via the <code>xml:lang</code> shorthand property). |
| </li> |
| </ul> |
| </section> |
| <section id="testing"> |
| <title>Testing</title> |
| <p> |
| Accessible PDFs can be tested, for example, using Adobe Acrobat Professional. Its |
| Accessibility Check feature creates a report indicating any deficiencies with a PDF |
| document. Alternatively, you can just let a screen reader read the document aloud. |
| </p> |
| </section> |
| <section id="limitations"> |
| <title>Limitations</title> |
| <p> |
| Accessibility support in Apache FOP is relatively new, so there are certain |
| limitations. Please help us identify and close any gaps. |
| </p> |
| <ul> |
| <li> |
| The natural language can currently only be specified at the page-sequence level. The |
| document language is derived from the language of the first page-sequence. It is |
| currently not possible to override the language inside the content below the |
| page-sequence level. |
| </li> |
| <li> |
| It's currently not possible to specify the expanded form of an abbreviation or acronym. |
| </li> |
| <li> |
| SVG graphics (or images in general) are treated as a single figure. Text contained in |
| SVGs is not accessible. It's only possible to work with <code>fox:alt-text</code>. |
| </li> |
| <li> |
| XSL-FO's role property is currently not supported. It could theoretically be used to |
| differentiate between headings and normal text. At the moment, the two are simply |
| identified as paragraphs. |
| </li> |
| <li> |
| The side regions (region-before, region-after etc.) are currently not specially |
| identified. Screen readers may read their content at page changes. |
| </li> |
| </ul> |
| </section> |
| <section id="links"> |
| <title>Related Links</title> |
| <p> |
| Many resources providing guidance about creating accessible documents can be found on the |
| web. Here are a few links, along with additional resources around the topic: |
| </p> |
| <ul> |
| <li><a href="http://www.section508.gov/">US Government - Website on Section 508</a></li> |
| <li><a href="http://en.wikipedia.org/wiki/Accessibility">Wikipedia on Accessibility in general</a></li> |
| <li><a href="http://en.wikipedia.org/wiki/Portable_Document_Format#Accessibility">Wikipedia on Accessibility in PDF</a></li> |
| <li> |
| <a href="http://partners.adobe.com/public/developer/en/pdf/PDFReference.pdf">PDF |
| Reference 1.4</a> (look up chapters 9.7 "Tagged PDF" and 9.8 "Accessibility Support") |
| </li> |
| <li><a href="pdfa.html">PDF/A support in Apache FOP</a></li> |
| <li><a href="http://wiki.apache.org/xmlgraphics-fop/PDF_Accessibility">Developer-oriented details on the accessibility features (on the Wiki)</a></li> |
| </ul> |
| </section> |
| </body> |
| </document> |