diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/documentation/content/xdocs/site.xml | 1 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/trunk/accessibility.xml | 158 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/trunk/pdfa.xml | 20 |
3 files changed, 175 insertions, 4 deletions
diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml index d87b68aab..f65b7fa65 100644 --- a/src/documentation/content/xdocs/site.xml +++ b/src/documentation/content/xdocs/site.xml @@ -159,6 +159,7 @@ <extensions label="Extensions" href="extensions.html"/> <events label="Events" href="events.html"/> <metadata label="Metadata" href="metadata.html"/> + <accessibility label="Accessibility" href="accessibility.html"/> </features> </trunk> diff --git a/src/documentation/content/xdocs/trunk/accessibility.xml b/src/documentation/content/xdocs/trunk/accessibility.xml new file mode 100644 index 000000000..d9fbbff1f --- /dev/null +++ b/src/documentation/content/xdocs/trunk/accessibility.xml @@ -0,0 +1,158 @@ +<?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 US but it impacts also other countries. + </p> + <p> + These features are concentrated exclusively on PDF output + (Tagged PDF). There are certain implementation limitations that need to be observed + and certain actions are necessary 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.getRendererOptions().put("accessibility", Boolean.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> + As mentioned, enabling accessibility currently only changes the way PDFs are generated. + Internally, FOP maintains a reduced structure tree of the document so the target format + viewer can ultimately reconstruct the natural reading order of the document. This is + important for document readers that produce an aural representation of the content. + </p> + <p> + Hint: You may need to adjust the Java heap size in order to process larger files. + </p> + </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 so the generate documents that are truly accessible. + </p> + <ul> + <li>Table cells require a table row as the parent.</li> + <li> + Ensure that the order of <code>fo:block-container</code> in a page corresponds to + the reading order. + </li> + <li> + Alternate text for images: The attribute <code>fox:alt-text</code> has been added + for <code>fo:external-graphic</code> and <code>fo:instream-foreign-object</code>. + </li> + <li> + Specify the natural language of the document using the language and country properties + (or via the xml:lang 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 creates a report indicating any deficiencies with a PDF document. + Alternatively, you can just let a screen reader read the document out aloud. + </p> + </section> + <section id="limitations"> + <title>Limitations</title> + <p> + Accessibility support in Apache FOP is relatively new, so naturally, there are certain + limitations. Please help us identify and close any gaps. + </p> + <ul> + <li> + The natural language can currently only be specified on 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 fox:alt-text. + </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> + <li> + The accessibility features are only available with PDF output and only if the + new output implementation based on the intermediate format (PDFDocumentHandler) is used. + Accessibility (Tagged PDF) is not supported by the legacy PDFRenderer. + </li> + </ul> + </section> + <section id="links"> + <title>Related Links</title> + <p> + We don't provide a comprehensive guide to create accessible documents. Below are some + links with additional resources around the topic. + </p> + <ul> + <li><a href="pdfa.html">PDF/A support in Apache FOP</a></li> + <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> + (lookup chapters 9.7 "Tagged PDF" and 9.8 "Accessibility Support") + </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> diff --git a/src/documentation/content/xdocs/trunk/pdfa.xml b/src/documentation/content/xdocs/trunk/pdfa.xml index bfa1ae33e..db5f56482 100644 --- a/src/documentation/content/xdocs/trunk/pdfa.xml +++ b/src/documentation/content/xdocs/trunk/pdfa.xml @@ -53,8 +53,9 @@ lack of a full license to get a detailed error protocol. </p> <p> - <strong>PDF/A-1a</strong> is not implemented, yet. This is mostly because of the requirement - for tagged PDF which is not available in FOP, yet. + <strong>PDF/A-1a</strong> is based on PDF-A-1b and adds accessibility features + (such as Tagged PDF). This format is available within the limitation described on + the <a href="accessibility.html">Accessibility page</a>. </p> </section> <section id="command-line"> @@ -64,6 +65,9 @@ as a parameter. If there is a violation of one of the validation rules for PDF/A, an error message is presented and the processing stops. </p> + <p> + PDF/A-1a is enabled by specifying "-pdfprofile PDF/A-1a". + </p> </section> <section id="embedded"> <title>Usage (embedded)</title> @@ -80,6 +84,9 @@ Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent); If one of the validation rules of PDF/A is violated, an PDFConformanceException (descendant of RuntimeException) is thrown. </p> + <p> + For PDF/A-1a, just use the string "PDF/A-1a" instead of "PDF/A-1b". + </p> </section> <section id="rules"> <title>PDF/A in Action</title> @@ -118,12 +125,17 @@ Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent); embedded in clear text so non-PDF-aware applications can extract the XMP metadata. </li> </ul> + <note> + There are additional requirements if you want to enabled PDF/A-1a (Tagged PDF). This is + particularly the specification of the natural language and alternative descriptions for + images. Please refer to the <a href="accessibility.html">Accessibility page</a> for details. + </note> </section> <section id="profile-compatibility"> <title>PDF profile compatibility</title> <p> - The PDF profiles "PDF/X-3:2003" and "PDF/A-1b" are compatible and can both be - activated at the same time. + The PDF profiles "PDF/X-3:2003" and "PDF/A-1b" (or "PDF/A-1a") are compatible and can + both be activated at the same time. </p> </section> <section id="interoperability"> |