diff options
Diffstat (limited to 'src/documentation/content/xdocs/1.1rc1/accessibility.xml')
| -rw-r--r-- | src/documentation/content/xdocs/1.1rc1/accessibility.xml | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/1.1rc1/accessibility.xml b/src/documentation/content/xdocs/1.1rc1/accessibility.xml new file mode 100644 index 000000000..412519d8b --- /dev/null +++ b/src/documentation/content/xdocs/1.1rc1/accessibility.xml @@ -0,0 +1,167 @@ +<?xml version="1.0" encoding="UTF-8" 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>Apache™ FOP: 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="customTags"> + <title>Customized Tagging</title> + <p>The <a href="#PDFReference">PDF Reference</a> defines a set of standard Structure Types to + tag content. For example, ‘P’ is used for identifying paragraphs, ‘H1’ to ‘H6’ for headers, + ‘L’ for lists, ‘Div’ for block-level groups of elements, etc. This standard set is aimed at + improving interoperability between applications producing or consuming PDF. </p> + <p>FOP provides a default mapping of Formatting Objects to elements from that standard set. + For example, <code>fo:page-sequence</code> is mapped to ‘Part’, <code>fo:block</code> is + mapped to ‘P’, <code>fo:list-block</code> to ‘L’, etc.</p> + <p>You may want to customize that mapping to improve the accuracy of the tagging or deal with + particular FO constructs. For example, you may want to make use of the ‘H1’ to ‘H6’ tags to + make the hierarchical structure of the document appear in the PDF. This is achieved by using + the <code>role</code> XSL-FO property:</p> + <source>... +<fo:block role="H1" font-weight="bold">I. A Level 1 Heading</fo:block> +<fo:block>This is the first paragraph of the first section...</fo:block> +...</source> + <p>If a non-standard structure type is specified, FOP will issue a warning and fall back to + the default tag associated to the Formatting Object.</p> + </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> + 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 id="PDFReference"> + <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>
\ No newline at end of file |