Author: jeremias
Date: Fri Apr 17 14:31:37 2009
New Revision: 766030
URL: http://svn.apache.org/viewvc?rev=766030&view=rev
Log:
Bugzilla #46705:
End-user documentation on the new accessibility features and PDF/A-1a.
Based on work by: Jost Klopfstein <jost.klopfstein.at.gmail.com>
Added:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
(with props)
Modified:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/site.xml
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/pdfa.xml
Modified:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewvc/xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/site.xml?rev=766030&r1=766029&r2=766030&view=diff
==============================================================================
---
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/site.xml
(original)
+++
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/site.xml
Fri Apr 17 14:31:37 2009
@@ -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>
Added:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
URL:
http://svn.apache.org/viewvc/xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml?rev=766030&view=auto
==============================================================================
---
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
(added)
+++
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
Fri Apr 17 14:31:37 2009
@@ -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>
Propchange:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
------------------------------------------------------------------------------
svn:keywords = Id
Modified:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/pdfa.xml
URL:
http://svn.apache.org/viewvc/xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/pdfa.xml?rev=766030&r1=766029&r2=766030&view=diff
==============================================================================
---
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/pdfa.xml
(original)
+++
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/pdfa.xml
Fri Apr 17 14:31:37 2009
@@ -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 @@
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 @@
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">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
