Author: vhennebert
Date: Mon Oct 26 12:35:44 2009
New Revision: 829769
URL: http://svn.apache.org/viewvc?rev=829769&view=rev
Log:
Improved and updated documentation about accessibility
Modified:
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
Modified:
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=829769&r1=829768&r2=829769&view=diff
==============================================================================
---
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
(original)
+++
xmlgraphics/fop/branches/Temp_Accessibility/src/documentation/content/xdocs/trunk/accessibility.xml
Mon Oct 26 12:35:44 2009
@@ -29,13 +29,12 @@
<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.
+ of electronic documents for the USA but other countries have similar
requirements.
</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.
+ 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>
@@ -43,7 +42,7 @@
<p>There are 3 ways to enable accessibility:</p>
<ol>
<li>
- <strong>Command line:</strong> The command line option -a turns on
accessibility.
+ <strong>Command line:</strong> The command line option -a turns on
accessibility:
<code>fop -a -fo mydocument.fo -pdf mydocument.pdf</code>
</li>
<li>
@@ -60,55 +59,55 @@
</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.
+ 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>
- <p>
- Hint: You may need to adjust the Java heap size in order to process
larger files.
- </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 so the generate documents that are truly
accessible.
+ your XSL-FO content in order to generate really accessible documents:
</p>
<ul>
- <li>Table cells require a table row as the parent.</li>
+ <li>Table cells must have a table row as their parent.</li>
<li>
- Ensure that the order of <code>fo:block-container</code> in a page
corresponds to
- the reading order.
+ 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>
- 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>.
+ 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 xml:lang shorthand property).
+ (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 creates a report indicating any deficiencies with
a PDF document.
- Alternatively, you can just let a screen reader read the document out
aloud.
+ 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 naturally,
there are certain
+ 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 on the
page-sequence level. The
+ 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.
@@ -118,7 +117,7 @@
</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.
+ 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
@@ -129,28 +128,23 @@
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.
+ 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="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")
+ <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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
