src/documentation/content/xdocs/trunk/accessibility.xml - xmlgraphics-fop - Git at Google

 <?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.setAccessibility(true);</code>
         </li>
         <li>
           <strong>Optional setting in fop.xconf file:</strong>
           <pre>
           &lt;fop version="1.0"&gt;
               &lt;accessibility&gt;true&lt;/accessibility&gt;
               ...
           &lt;/fop&gt;
           </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>
	<?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.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>
	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>